metadsl

Library to help create DSLs in Python.

class metadsl.CaptureLogging(events=<factory>)

Capture all logging.

with CaputureLogging() as results:

…

# results contains a list of all log messages, formatted

Some inspiration from unittest.assertLogs

events: List[str]

old_handlers: List[logging.Handler]

class metadsl.Children(args, kwargs)

args: Tuple[Hash, ...]

kwargs: Dict[str, Hash]

class metadsl.Expression(function, args, kwargs)

Top level object. Subclass this type and provide relevent methods for your type. Do not add any fields.

Properties:

Calling the function, after replacing the typevars in it (if it is a bound method), with the args and kwargs should resualt in an equivalent expression:

replace_fn_typevars(self.function, self.typevars)(*self.args, **self.kwargs) == self

The return type of the function, inferred by replacing the typevars in and with these args and kwargs, should match the type of the expression. If the return type of the function is not subclass of expression, then this should be a PlaceholderExpression of that type.

args: List[object]

function: Callable

kwargs: Dict[str, object]

class metadsl.ExpressionReference(_graph, _optional_index)

This is a data structure that holds onto a graph of expression and has a pointer to one node, to represent it.

property children: metadsl.normalized.Children

Returns the direct children of this node if it has any.

Return type

Children

property descendents: Iterable[metadsl.normalized.ExpressionReference]

Returns all nodes of this expression reference. If any of them get their expression replaced, it will replace that sub-node of this expression.

If this is the root node, will return them in topo order, otherwise will be arbitrary

Return type

Iterable[ExpressionReference]

property expression: object

Returns the expression this references

Return type

object

classmethod from_expression(expr)

Create a new reference from an expression

Return type

ExpressionReference

property hash: Hash

Returns the Hash of the top level expression

Return type

NewType()(Hash, str)

replace(new_expression)

Replace this expression with a new one

Return type

None

metadsl.Hash(x)

class metadsl.HashableMapping(mapping)

Like a dictionary, but immutable and hashable.

class metadsl.Item(key, value)

key: metadsl.dict_tools.T

value: metadsl.dict_tools.V

class metadsl.IteratedPlaceholder(function, args, kwargs)

args: List[object]

function: Callable

kwargs: Dict[str, object]

class metadsl.PlaceholderExpression(function, args, kwargs)

An expression that represents a type of T, for example T could be int.

This is needed when a function returns a non expression type, it still has to return an expression under the covers until it has been replaced.

It is also needed when using Wildcards in expressions when doing matching.

args: List[object]

function: Callable

kwargs: Dict[str, object]

class metadsl.UnhashableMapping(*items)

Like a dictionary, but can have unhashable keys.

metadsl.clone_expression(expr)

Return type

TypeVar(T)

metadsl.create_iterated_placeholder(i)

If a placeholder is of an iterable T, calling iter on it should return an iterable placeholder of the inner type.

Used in matching with variable args.

Return type

IteratedPlaceholder[TypeVar(T)]

metadsl.export_from(module_name, *submodules, local=[])

Sets the __all__ for the module to be the union of all the __all__’s of the submodules, plus the locals.

Needed so that the modules themselves are not present in the __init__.py file, but all the exports are.

Return type

None

metadsl.expression(fn)

Creates an expresion object by wrapping a Python function and providing a function that will take in the args and return an expression of the right type.

Return type

TypeVar(T_callable, bound= Callable)

metadsl.hash_value(value)

Computes some hash for a value that should be stable. Either use the built in hash, or if we cannot (like the object is mutable) then use the id.

It’s a single dispatch function so that you can register custom hashes for objects you don’t control.

Return type

int

metadsl.safe_merge(*mappings, dict_constructor=<class 'dict'>)

Combing mappings by merging the dictionaries. It raises a ValueError if there are duplicate keys and they are not equal.

Return type

Mapping[TypeVar(T), TypeVar(V)]

metadsl.toggle_debug_logging(enabled)

Return type

None