pydrake.common.cpp_template

Provides containers for tracking instantiations of C++ templates.

pydrake.common.cpp_template.get_or_init(scope, name, template_cls, *args, **kwargs)

Gets an existing template from a scope if it exists; otherwise, it will be created and registered.

If scope does not have the attribute name, then it will be created as template_cls(name, *args, **kwargs). (module_name=… is also set, but should not be important).

Parameters

scope – Scope that contains the template object (this may not necessarily be the scope of the instantiation).
name – Name of the template object.
template_cls – Class (either TemplateBase or a derivative).
args – Passed to the template class’s constructor.
kwargs – Passed to the template class’s constructor.

Returns

The existing (or newly created) template object.

class pydrake.common.cpp_template.TemplateBase(name, allow_default=True, scope=None)

Bases: object

Provides a mechanism to map parameters (types or literals) to instantiations, following C++ mechanics.

__init__(name, allow_default=True, scope=None)

Parameters

name – Name of the template object.
allow_default – Allow a default value (None) to resolve to the parameters of the instantiation that was first added.
scope – Parent scope for the template object.

add_instantiation(param, instantiation, skip_rename=False): Adds a unique instantiation.

Note

param must not have already been added.

add_instantiations(instantiation_func, param_list)

Adds a set of instantiations given a function and a list of parameter sets.

Note

This method can only be called once.

Parameters

instantiation_func – Function of the form f(template, param), where template is the current template and param is the parameter set for the current instantiation.
param_list – Ordered container of parameter sets that these
for. (instantiations should be produced) –

classmethod define(name, param_list, *args, scope=None, **kwargs)

Provides a decorator for functions that defines a template using name. The template instantiations are added using add_instantiations, where the instantiation function is the decorated function.

Parameters

name – Name of the template. This should generally match the name of the object being decorated for clarity.
param_list – Ordered container of parameter sets. For more information, see add_instantiations.

Note

The name of the inner class will not matter as it will be overwritten with the template instantiation name. In the below example, Impl will be renamed to MyTemplate[int] when param=(int,).

Example

@TemplateClass.define("MyTemplate",
                      param_list=[(int,), (float,)])
def MyTemplate(param):
    T, = param
    class Impl:
        def __init__(self):
            self.T = T
    return Impl

deprecate_instantiation(param, message, *, date=None)

Deprecates an instantiation for the given set of parameters.

Note

This method can only be called once for a given instantiation.

Parameters

param – Parameters for an instantiation that is already registered.
message – Message to be shown when issuing a deprecation warning.
date – (Optional) String of the form “YYYY-MM-DD”. If supplied, will reformat the message to add the date as is done with DRAKE_DEPRECATED and its processing in mkdoc.py. This must be present if message does not contain the date itself.

Returns

(instantiation, param), where param is the resolved parameters.

get_instantiation(param=None, throw_error=True)

Gets the instantiation for the given parameters.

Parameters: param – Can be None, a single parameter, or a tuple/list of parameters.
Returns: (instantiation, param), where param is the resolved set of parameters.

get_module_name()

Returns module name for this object’s parent scope.

Example

>>> pydrake.common.value.Value.get_module_name()
pydrake.common.value

get_param_set(instantiation)

Returns all parameters for a given instantiation.

Returns: A set of instantiations.

is_instantiation(obj): Determines if an object is an instantion of the given template.

class pydrake.common.cpp_template.TemplateClass(name, *, scope=None, **kwargs)

Bases: pydrake.common.cpp_template.TemplateBase

Extension of TemplateBase for classes.

__init__(name, *, scope=None, **kwargs)

Parameters

name – Name of the template object.
allow_default – Allow a default value (None) to resolve to the parameters of the instantiation that was first added.
scope – Parent scope for the template object.

is_subclass_of_instantiation(obj)

Determines if obj is a subclass of one of the instantiations.

Returns: The first instantiation of which obj is a subclass.

class pydrake.common.cpp_template.TemplateFunction(name, allow_default=True, scope=None)

Bases: pydrake.common.cpp_template.TemplateBase

Extension of TemplateBase for functions.

class pydrake.common.cpp_template.TemplateMethod(name, cls, scope=None, **kwargs)

Bases: pydrake.common.cpp_template.TemplateBase

Extension of TemplateBase for class methods.

__init__(name, cls, scope=None, **kwargs)

Parameters

name – Name of the template object.
allow_default – Allow a default value (None) to resolve to the parameters of the instantiation that was first added.
scope – Parent scope for the template object.