finesse.script.adapter module

Interface between script and Finesse.

Adapters provide a programmatic way to retrieve useful information about KatScript directives using their corresponding Python objects, and vice versa. This is primarily used for the compiler and generator, but is also used to improve syntax suggestions and error messages.

The adapter class hierarchy is intentionally very generic. By default, an ordinary KatScript directive corresponding to an ordinary Finesse object is quite simple to specify and should “just work”. When special behaviour is required, e.g. in cases where the KatScript directive has different arguments than the corresponding Python object (e.g. tem) or where there is no corresponding Python object (e.g. modes), the methods and members of the adapter can be overridden.

class finesse.script.adapter.AnalysisDocumenter(*, item_type, **kwargs)[source]: Bases: NumpyStyleDocstringGetterMixin, FunctionalSyntaxMixin, ItemDocumenter

class finesse.script.adapter.AnalysisDump(analysis: Any, adapter: ItemAdapter, parameters: List[ArgumentDump] | List[List[ArgumentDump]], is_default: bool)[source]

Bases: object

A set of analysis parameters and metadata.

adapter: ItemAdapter

analysis: Any

is_default: bool

property item_name[source]

parameters: List[ArgumentDump] | List[List[ArgumentDump]]

class finesse.script.adapter.AnalysisDumper(*, item_type, **kwargs)[source]

Bases: SignatureAttributeParameterMixin, ItemDumper

dump(adapter, analysis)[source]

Get analysis dump object(s) for analysis.

Parameters

adapterItemAdapter: The adapter corresponding to this getter.
analysisAction: The action to dump.

Yields

AnalysisDump: Object containing a mapping of keyword argument names to ArgumentDump objects and whether they are all default values.

class finesse.script.adapter.AnalysisFactory(*, item_type)[source]: Bases: ItemFactory

class finesse.script.adapter.AnalysisSetter(*, item_type, **kwargs)[source]: Bases: SignatureAttributeParameterMixin, ItemSetter

class finesse.script.adapter.Argument(name: str, kind: ArgumentType = ArgumentType.ANY, default: Any = <class 'finesse.script.adapter._empty'>, annotation: Any = <class 'finesse.script.adapter._empty'>)[source]

Bases: object

A generic instruction argument.

This is similar but not identical to inspect.Parameter. Arguments in the Finesse sense are more general than inspect.Parameter since they can refer to KatScript arguments, and KatScript instructions may not necessarily define their supported arguments via Python class signatures.

annotation[source]: alias of _empty

default[source]: alias of _empty

property has_no_default[source]

kind: ArgumentType = _ParameterKind.POSITIONAL_OR_KEYWORD

name: str

class finesse.script.adapter.ArgumentDump(name: str, kind: ArgumentType = ArgumentType.ANY, default: Any = <class 'finesse.script.adapter._empty'>, annotation: Any = <class 'finesse.script.adapter._empty'>, value: Any = <class 'finesse.script.adapter._empty'>, other_defaults: List[Any] = None, reference: bool = False)[source]

Bases: Argument

A Finesse object argument name, its current value, default value, kind, annotation, and whether it should be dumped by value or reference.

This encapsulates an argument for a script instruction. It can represent Finesse object parameters like floats, strings and model parameters, and is primarily used to generate KatScript representations of Finesse objects.

property is_default[source]: Whether the value is the parameter’s default.

other_defaults: List[Any] = None

reference: bool = False

value[source]: alias of _empty

class finesse.script.adapter.ArgumentType(*values)[source]

Bases: Enum

Signature argument types.

While we just copy those defined by inspect, note that the definitions here are more abstract than those of inspect: these refer to the different flavours of script argument, which may or may not map directly to or from a Python type’s call signature.

ANY = _ParameterKind.POSITIONAL_OR_KEYWORD

KEYWORD_ONLY = _ParameterKind.KEYWORD_ONLY

POS_ONLY = _ParameterKind.POSITIONAL_ONLY

VAR_KEYWORD = _ParameterKind.VAR_KEYWORD

VAR_POS = _ParameterKind.VAR_POSITIONAL

class finesse.script.adapter.BoundArgument(name: str, kind: ArgumentType = ArgumentType.ANY, default: Any = <class 'finesse.script.adapter._empty'>, annotation: Any = <class 'finesse.script.adapter._empty'>, var_sequence: int = None)[source]

Bases: Argument

A concrete argument originating from a call to a setter.

This is the same as Argument except in its handling of variadic arguments. Where this represents a variadic argument, it contains information as to which variadic argument it represents (either the sequence number or keyword). It is used to resolve self-references and to map compilation errors back to the original script.

var_sequence: int = None

class finesse.script.adapter.CommandDump(adapter: ItemAdapter, parameters: List[ArgumentDump] | List[List[ArgumentDump]], is_default: bool)[source]

Bases: object

A set of command parameters and metadata.

adapter: ItemAdapter

is_default: bool

property item_name[source]

parameters: List[ArgumentDump] | List[List[ArgumentDump]]

class finesse.script.adapter.CommandMethodDocumenter(*, sig_ignore=('self',), **kwargs)[source]: Bases: NumpyStyleDocstringGetterMixin, FunctionalSyntaxMixin, ItemDocumenter

class finesse.script.adapter.CommandMethodSetter(*, sig_ignore=('self',), **kwargs)[source]: Bases: SignatureAttributeParameterMixin, ItemSetter

class finesse.script.adapter.CommandPropertyDocumenter(*, item_type, **kwargs)[source]: Bases: CommandMethodDocumenter

class finesse.script.adapter.CommandPropertyDumper(*, item_type, default=<class 'finesse.script.adapter._empty'>, **kwargs)[source]: Bases: SignatureAttributeParameterMixin, ItemDumper

class finesse.script.adapter.CommandPropertySetter(*, item_type, **kwargs)[source]: Bases: CommandMethodSetter

finesse.script.adapter.EMPTY_VALUE[source]: alias of _empty

class finesse.script.adapter.ElementDocumenter(*, item_type, **kwargs)[source]: Bases: NumpyStyleDocstringGetterMixin, ElementSyntaxMixin, ItemDocumenter

class finesse.script.adapter.ElementDump(element: ModelElement, adapter: ItemAdapter, parameters: List[ArgumentDump] | List[List[ArgumentDump]], is_default: bool)[source]

Bases: object

A set of element parameters and metadata.

adapter: ItemAdapter

element: ModelElement

is_default: bool

parameters: List[ArgumentDump] | List[List[ArgumentDump]]

class finesse.script.adapter.ElementDumper(*, item_type, **kwargs)[source]: Bases: SignatureAttributeParameterMixin, ItemDumper

class finesse.script.adapter.ElementFactory(last=False, **kwargs)[source]: Bases: ItemFactory

class finesse.script.adapter.ElementSetter(*, item_type, **kwargs)[source]: Bases: SignatureAttributeParameterMixin, ItemSetter

class finesse.script.adapter.ElementSyntaxMixin(*, sig_type=None, sig_ignore=None, **kwargs)[source]: Bases: SyntaxMixin

class finesse.script.adapter.FunctionalSyntaxMixin(*, sig_type=None, sig_ignore=None, **kwargs)[source]: Bases: SyntaxMixin

class finesse.script.adapter.ItemAdapter(full_name, short_name=None, other_names=None, getter=None, factory=None, setter=None, documenter=None, singular=False, build_last=False)[source]

Bases: object

Adapter defining how a script instruction maps to/from a Python type.

This encapsulates the required information to take a script instruction and generate a corresponding Python object (e.g. a Laser from a laser l1 … instruction), to add it to a Model (or in the case of commands, set some model attribute), to dump that Python object back to script, and to generate documentation.

Parameters

full_namestr: The instruction’s unabbreviated name. This must be alphanumeric and can contain underscores but no spaces.
short_namestr, optional: The instruction’s short form name, used when generating compact script. If not specified, full_name is used in cases where the short form is desired.
other_namessequence, optional: Any other supported names for this instruction.
getterItemDumper, optional: Object handling the retrieval of parameters from the Python object corresponding to this instruction.
factoryItemFactory, optional: Object handling the creation of the Python object corresponding to this instruction.
setterItemSetter, optional: Object handling the setting of parameters in the Python object corresponding to this instruction’s parameters.
documenterItemDocumenter: Object handling the retrieval of docstrings and syntax suggestions for the instruction.
singularbool, optional: Flag indicating that this instruction can be defined only once per script. Defaults to False.
build_lastbool, optional: Whether to build the Python object last, regardless of dependencies. This is useful for elements with implicit dependencies (see e.g. the cavity adapter). Be careful using this flag because statements for other adapters that depend on statements for adapters with this flag will be built first. Defaults to False.

property aliases[source]

The instruction alias(es).

Getter:: Sequence of aliases for this instruction.

class finesse.script.adapter.ItemDocumenter(*, item_type)[source]

Bases: ItemHandler

abstract property docstring[source]

syntax(spec, adapter, short_names=True, optional_as_positional=False, multiline=None)[source]

syntax_correction(user_directive, spec, optional_as_positional=False, multiline=False)[source]: Suggest syntax using the user’s directive.

class finesse.script.adapter.ItemDumper(*, item_type)[source]: Bases: ItemHandler

class finesse.script.adapter.ItemFactory(*, item_type)[source]: Bases: ItemHandler

class finesse.script.adapter.ItemHandler(*, item_type)[source]

Bases: object

Root class for all dumper, setter, factory and documenter objects.

class finesse.script.adapter.ItemSetter(*, item_type)[source]

Bases: ItemHandler

abstractmethod arguments()[source]

The supported constructor arguments for this item.

Returns

dict: Mapping of argument names to Argument objects for this setter.

bind_argument(name_or_index)[source]

Return a bound argument object for name.

Parameters

name_or_indexstr or int: The argument keyword or index.

Returns

BoundArgument: The argument metadata corresponding to name_or_index.

keyword_args(only=False)[source]

The non-positional-only arguments of the call signature.

Parameters

onlybool, optional: Only include keyword-only arguments; defaults to False.

Returns

dict: The call object’s keyword parameters.

positional_args(only=False, keyword_defaults=True)[source]

The non-keyword-only arguments of the call signature.

Parameters

onlybool, optional: Only include positional-only arguments. Defaults to False.
keyword_defaultsbool, optional: Include keyword arguments that have default values. Defaults to True.

Returns

dict: The call object’s positional parameters.

update_parameter(item, argument, value)[source]

Update the built item’s name parameter to value.

This is used to update a parameter after the item has been created and added to the model, such as when resolving self-references.

Parameters

itemobject: The item.
argumentBoundArgument: The item argument corresponding to the value to update.
valueobject: The new value.

property var_keyword_argument[source]

property var_positional_argument[source]

class finesse.script.adapter.NumpyStyleDocstringGetterMixin(*, doc_type=None, **kwargs)[source]

Bases: object

argument_descriptions()[source]

The types and descriptions for each argument as parsed from the docstring.

Returns

dict: Mapping of arguments to their type and docstrings as listed in the object’s docstring. Note that the arguments may not correspond to signature argument names; numpydoc allows arguments to share docstrings so some keys may be e.g. n, m.

property doc_type[source]

property docstring[source]

The Python API item’s docstring.

Note: unlike inspect.getdoc(), this method returns only the docstring directly defined in doc_type, rather than taking the inherited docstring if not found. If no docstring is defined, None is returned.

extended_summary()[source]: The item’s extended summary, parsed from the docstring.

summary()[source]: The item’s summary, parsed from the docstring.

class finesse.script.adapter.SignatureArgumentMixin(*, sig_type=None, sig_ignore=None, **kwargs)[source]

Bases: object

Mixin providing ability to retrieve signature arguments from a Python function.

Parameters

sig_typetype, optional: The signature type to retrieve arguments from. Defaults to item_type.
sig_ignoresequence, optional: Signature argument names to ignore.

arguments()[source]

property sig_type[source]

class finesse.script.adapter.SignatureAttributeParameterMixin(ref_args=None, var_pos_attr=None, var_keyword_attr=None, **kwargs)[source]

Bases: SignatureArgumentMixin

Mixin providing the ability to get and set item parameters by inspecting its constructor signature arguments matching equivalently named object attributes.

Parameters

ref_argssequence, optional: Names of arguments that should be considered to be references. Corresponding ArgumentDump objects produced by this class will have their reference flags set to True to indicate to the generator that these should be treated as references instead of values.
var_pos_attrstr or callable, optional: The name of the field containing a sequence of variadic positional argument values, or a callable that returns the name of the field to set given the sequence number of the variadic argument, if the signature supports variadic positional arguments. Defaults to “args”.
var_keyword_attrstr or callable, optional: The name of the field containing a mapping of variadic keyword arguments to values, or a callable that returns the name of the field to set given the name of the keyword argument, if the signature supports variadic positional arguments. Defaults to the identity function.

dump_parameters(adapter, item)[source]: Build parameter mapping by retrieving object attributes using the signature.

update_parameter(item, argument, value)[source]

class finesse.script.adapter.SyntaxMixin(*, sig_type=None, sig_ignore=None, **kwargs)[source]: Bases: SignatureArgumentMixin