The following functions and decorators provide access to PyXLL’s type conversion system.
When registering Python functions as Excel worksheet functions using xl_func, or as Excel macros
using xl_macro, type information can be supplied that informs the PyXLL add-in how to convert
between Python and Excel values.
Type information can be provided to PyXLL in a number of different ways, include Python type hints, a
function signature string, and using the xl_arg and xl_return decorators documented
below.
Custom type conversion methods can be registered using the xl_arg_type and xl_return_type
decorators.
To access PyXLL’s type converters (including any custom type converters you have registered) you can use the
get_type_converter function.
See Argument and Return Types for more details about PyXLL’s type conversion features.
Returns a function to convert objects of type src_type to dest_type.
Even if there is no function registered that converts exactly from src_type to dest_type, as long
as there is a way to convert from src_type to dest_type using one or more intermediate types this
function will create a function to do that.
src_type (string) – Signature of type to convert from.
dest_type (string) – Signature of type to convert to.
src_kwargs (dict) – Parameters for the source type (e.g. {'dtype'=float} for numpy_array).
dest_kwargs (dict) – Parameters for the destination type (e.g. {'index'=True} for dataframe).
Function to convert from src_type to dest_type.
Example usage:
from pyxll import xl_func, get_type_converter
@xl_func("var x: var")
def py_function(x):
# if x is a number, convert it to a date
if isinstance(x, float):
to_date = get_type_converter("var", "date")
x = to_date(x)
return "%s : %s" % (x, type(x))
Decorator for providing type information for a function argument.
This can be used instead of providing a function signature to xl_func and xl_macro.
_name (string) – Argument name. This should match the argument name in the function definition.
_type – Optional argument type. This should be a recognized type name or the name of a custom type.
_label –
Argument label that will be used in the Excel function wizard.
Defaults to the argument name.
@Since PyXLL 5.5.0.
_description –
Argument description that will be used in the Excel function wizard.
This can be used instead of documenting the parameter in the function’s docstring.
@Since PyXLL 5.5.0.
kwargs – Type parameters for parameterized types (eg NumPy arrays and Pandas types).
Decorator for providing type information for a function’s return value.
This can be used instead of providing a function signature to xl_func and xl_macro.
_type – Optional argument type. This should be a recognized type name or the name of a custom type.
kwargs – Type parameters for parameterized types (eg NumPy arrays and Pandas types).
Returns a decorator for registering a function for converting from a base type to a custom type.
name (string) – custom type name.
base_type (string) – base type.
allow_arrays (boolean) – custom type may be passed in an array using the standard [] notation.
macro (boolean) – If True all functions using this type will automatically be registered as a macro sheet equivalent function.
thread_safe (boolean) – If False any function using this type will never be registered as thread safe.
typing_type – An optional typing type that will be recognised as this type when used as a Python type hint.
Returns a decorator for registering a function for converting from a custom type to a base type.
name (string) – custom type name.
base_type (string) – base type.
allow_arrays (boolean) – custom type may be returned as an array using the standard [] notation.
macro (boolean) – If True all functions using this type will automatically be registered as a macro sheet equivalent function.
thread_safe (boolean) – If False any function using this type will never be registered as thread safe.
typing_type – An optional typing type that will be recognised as this type when used as a Python type hint.
