API documentation

See also:

• inxs.contrib module
• inxs.lib module
• inxs.utils module

inxs module contents

inxs.logger = <Logger inxs (WARNING)>

Module logger, configure as you need.

exception inxs.AbortRule

Bases: inxs.FlowControl

Can be raised to abort the evaluation of all the currently processed inxs.Rule ‘s remaining tests and handlers. No further nodes will be considered for that rule. This is similar to Python’s builtin break in iterations.

exception inxs.AbortTransformation

Bases: inxs.FlowControl

Can be raised to cancel the remaining transformation steps.

exception inxs.SkipToNextNode

Bases: inxs.FlowControl

Can be raised to abort handling of the current node. This is similar to Python’s builtin continue in iterations.

exception inxs.InxsException

Bases: Exception

Base class for inxs exceptions.

inxs.Any(*conditions) → Callable

Returns a callable that evaluates the provided test functions and returns True if any of them returned that.

inxs.Not(*conditions) → Callable

Returns a callable that evaluates the provided test functions and returns True if any of them returned False.

inxs.OneOf(*conditions) → Callable

Returns a callable that evaluates the provided test functions and returns True if exactly one of them returned that.

inxs.HasNamespace

Returns a callable that tests an node for the given tag namespace.

inxs.HasLocalname

Returns a callable that tests an node for the given local tag name.

inxs.MatchesAttributes(constraints: Union[Dict[Union[str, Pattern[~AnyStr]], Union[str, Pattern[~AnyStr], None]], Callable]) → Callable

Returns a callable that tests an node’s attributes for constrains defined in a mapping. All constraints must be matched to resolve as true. Expected keys and values can be provided as string or compiled regular expression object from the re module. A None as value constraint evaluates as true if the key is in the attributes regardless its value. It also implies that at least one attribute must match the key’s constraint if this one is a regular expression object. Alternatively a callable can be passed that returns such mappings during the transformation.

inxs.MatchesXPath

Returns a callable that tests an node for the given XPath expression (whether the evaluation result on the transformation root contains it). If the xpath argument is a callable, it will be called with the current transformation as argument to obtain the expression.

inxs.If(x: Any, operator: Callable, y: Any) → Callable

Returns a callable that can be used as condition test in a Rule. The arguments x and y can be given as callables that will be used to get the operator’s input values during execution. Before you implement your own operators, mind that there are a lot available within Python’s __builtins__ and the standard library, in particular the operator module.

Examples:

>>> If(Ref('previous_result'), operator.is_not, None)  # doctest: +SKIP

inxs.Ref

Returns a callable that can be used for value resolution in a condition test or handler function that supports such. The value will be looked up during the processing of a transformation in Transformation._available_symbols by the given name. This allows to reference dynamic values in transformation steps and Rule s.

class inxs.Rule(conditions: Union[Callable, AnyStr, Dict[Union[str, Pattern[~AnyStr]], Union[str, Pattern[~AnyStr], None]], Sequence[Union[Callable, AnyStr, Dict[Union[str, Pattern[~AnyStr]], Union[str, Pattern[~AnyStr], None]]]]], handlers: Union[Callable, Sequence[Callable]], name: str = None, traversal_order: int = None)

Bases: object

Instances of this class can be used as conditional transformation steps that are evaluated against all traversed nodes.

Parameters:

• conditions (A single callable, string or mapping, or a sequence of such.) – All given conditions must evaluate as True in order for this rule to be applied. Strings and mappings can be provided as shortcuts, see Rule condition shortcuts for details. The condition test functions are always called with the currently evaluated node and the Transformation instance as arguments. There are helper functions for grouping conditions logically: Any(), Not() and OneOf().
• handlers (A single callable or a sequence of such.) – These handlers will be called if the conditions matched. They can take any argument whose name is available in Transformation._available_symbols.
• name (String.) – The optional rule’s name.
• traversal_order (Integer.) – An optional traversal order that overrides the transformation’s default Transformation.config.traversal_order, see Traversal strategies for details.

class inxs.Once(*args, **kwargs)

Bases: inxs.Rule

This is a variant of Rule that is only applied on the first match.

class inxs.Transformation(*steps, **config)

Bases: object

A transformation instance is defined by its transformation steps and configuration. It is to be called with a delb.Document or delb.TagNode instance as transformation root, only this node (or the root node of a Document) and its children will be considered during traversal.

Parameters:

• steps – The designated transformation steps of the instance are given as a sequence of positional arguments.
• config –

  The configuration values for the instance are passed as keyword arguments. Beside the following keywords, it can be populated with any key-value-pairs that will be available in inxs.Transformation._available_symbols during a transformation. The defaults are defined in config_defaults.

  • context can be provided as mapping with items that are added to the context before a (sub-)document is processed.
  • common_rule_conditions can be used to define one or more conditions that must match in all rule evaluations. E.g. a transformation could be restricted to nodes with a certain namespace without redundantly defining that per rule. Can be given as a single object (e.g. a string) or as sequence.
  • copy is a boolean that defaults to True and indicates whether to process on a copy of the document’s tree object.
  • name can be used to identify a transformation.
  • result_object sets the transformation’s attribute that is returned as result. Dot-notation lookup (e.g. context.target) is implemented. Per default the transformation root is returned.
  • traversal_order sets the default traversal order for rule evaluations and itself defaults to depth first, left to right, to to bottom. See Traversal strategies for possible values.

_available_symbols

This mapping contains items that are used for the dependency injection of handler functions. These names are included:

• All attributes of the transformation’s configuration, overridden by the following.
• All attributes of the transformation’s context, overridden by the following.
• config - The configuration namespace object.
• context - The context namespace object.
• node - The node that matched a Rule’s conditions or None in case of simple transformation steps.
• previous_result - The result that was returned by the previously evaluated handler function.
• root - The root node of the processed (sub-)document a.k.a. transformation root.
• transformation - The calling Transformation instance.

config_defaults = {'common_rule_conditions': None, 'context': {}, 'copy': True, 'name': None, 'result_object': 'root', 'traversal_order': 7}

The default configuration values. Changing members on an instance actually affects the class unless a copy of this mapping as copied and bound as instance attribute.

context

This property can be used to access the context while the transformation is processing.

name

The name member of the transformation’s configuration.

root

This property can be used to access the root node of the currently processed (sub-)document.