New in PyXLL 5.10
The decorators xl_func, xl_macro, and xl_menu take various parameters to control their behaviour.
The default parameters for these decorators can be modified through the following configuration options:
[PYXLL]
xl_func_defaults = ...
xl_macro_defaults = ...
xl_menu_defaults = ...
Each can be set to a function that returns the defaults to be used. The function is specified using its fully qualified function name, including the module or package contianing the function.
For example, to specify that the function my_xl_func_defaults from the Python module custom_defaults.py should be used to fetch
default values for the xl_func decorator the following config would be used:
[PYXLL]
xl_func_defaults = custom_defaults.my_xl_func_defaults
The specified function is called with the decorated function, and should return a dictionary of default parameter values.
Suppose we wanted to change the default value for the name parameter the xl_func. We might want to do this in order
to use an all uppercase name for the Excel function, instead of simply using the function name is it is in Excel.
The following funcition gets the function name in uppercase and returns a dictionary of the defaults to use for the xl_func
decorator:
def my_xl_func_defaults(func)
# 'func' is the Python function that will be
# called from Excel.
name = func.__name__
# We want to use the funtion name in all uppercase
# in Excel.
xl_name = name.uppercase()
# Here we return a dictionary of default values
# for the @xl_func parameters.
return {
"name": xl_name
}
We configure PyXLL to use this function for the xl_func decorator default parameters as above.
With this function configured, any function using decorated with the xl_func decorator will now have
the name parameter defaulted to the upper case function name.
The following Python function would appear in Excel with the name A_PYTHON_FUNCTION.
@xl_func
def a_python_function():
return "In Excel!"
Usually you will not want to apply the same defaults to all modules and packages. You may want to only apply your defaults to your own packages if you are using some other third-party packages that also use PyXLL, or you may want to use different defaults for your own different packages.
The defaults can be configured on a per-module or per-package basis to accomodate this.
Suppose your had two Python modules my_math_functions and my_string_functions and you wanted all the functions in my_math_functions to have the category Math and all functions in my_string_functions to have the category String.
We can write a couple of user default functions that return the default category parameter for xl_func as follows:
def math_xl_func_defaults(func)
return {
"category": "Math"
}
def string_xl_func_defaults(func)
return {
"category": "String"
}
We use the following config to configure those for the two modules my_math_functions and my_string_functions:
[PYXLL]
xl_func_defaults =
my_math_functions: custom_defaults.math_xl_func_defaults
my_string_functions: custom_defaults.string_xl_func_defaults
If you are using packages and want to include all modules and sub-packages within a package you use * as a wildcard in the module specification in the config:
[PYXLL]
xl_func_defaults =
my_math_package.*: custom_defaults.math_xl_func_defaults
my_string_package.*: custom_defaults.string_xl_func_defaults
