zensols.introspect package

Submodules

zensols.introspect.imp

A utility class to load classes from modules.

class zensols.introspect.imp.ClassImporter(class_name, reload=True)

Bases: object

Utility class that reloads a module and instantiates a class from a string class name. This is handy for prototyping code in a Python REPL.

__init__(class_name, reload=True)

Initialize with the class name.

Parameters:

• class_name (str) – the fully qualifed name of the class (including the module portion of the class name)

• reload (bool) – if True then reload the module before returning the class

static full_classname(cls)

Return a fully qualified class name string for class cls.

Return type:

str

get_class()

Return the given class in the initializer.

Return type:

Type

get_class_or_global()

Like get_class() but try globals if the class isn’t fully qualified (i.e. sans module).

Return type:

Type

static get_module(name, reload=False)

Return the module that has name.

Parameters:

name (str) – the string name, which can have dots (.) to for sub modules

Return type:

ModuleType

get_module_class(resolve_module=False)

Return the module and class as a tuple of the given class in the initializer.

Parameters:

resolve_module (bool) – if True then resolve the module from the class rather than the module portion of the class_name string

Return type:

Tuple[ModuleType, Type]

Returns:

a tuple of the module and class represented by class_name

instance(*args, **kwargs)

Create an instance of the specified class in the initializer.

Parameters:

• args – the arguments given to the initializer of the new class

• kwargs – the keyword arguments given to the initializer of the new class

classmethod is_valid_class_name(class_name)

Return whether a string represents a valid class name.

Return type:

bool

parse_module_class()

Parse the module and class name part of the fully qualifed class name.

Return type:

Sequence[str]

set_log_level(level=20)

Convenciene method to set the log level of the module given in the initializer of this class.

Parameters:

level (int) – a logging level in logging

exception zensols.introspect.imp.ClassImporterError

Bases: Exception

Raised for any run time exceptions during resolving and instantiating classes with ClassImporter.

__module__ = 'zensols.introspect.imp'

__weakref__

list of weak references to the object (if defined)

class zensols.introspect.imp.ClassResolver

Bases: ABC

Used to resolve a class from a string.

find_class(class_name)

Return a class given the name of the class.

Parameters:

class_name (str) – represents the class name, which might or might not have the module as part of that name

Return type:

Type

static full_classname(cls)

Return a fully qualified class name string for class cls.

Return type:

str

class zensols.introspect.imp.DictionaryClassResolver(instance_classes)

Bases: ClassResolver

Resolve a class name from a list of registered class names without the module part. This is used with the register method on ConfigFactory.

See:

ConfigFactory.register

__init__(instance_classes)

find_class(class_name)

Return a class given the name of the class.

Parameters:

class_name (str) – represents the class name, which might or might not have the module as part of that name

Return type:

Type

zensols.introspect.insp

Utility classes to help with dataclasses.

class zensols.introspect.insp.Class(class_type, doc, fields, methods)

Bases: object

__init__(class_type, doc, fields, methods)

class_type: type

The class that was inspected.

doc: ClassDoc

The docstring of the class.

fields: Dict[str, ClassField]

The fields of the class.

property is_dataclass: bool

Whether or not the class is a dataclasses.dataclass.

methods: Dict[str, ClassMethod]

The methods of the class.

property name: str

The fully qualified class name.

class zensols.introspect.insp.ClassDoc(text, params=None)

Bases: object

A meta data for documentation at any level of the class code (methods etc).

PARAM_REGEX = re.compile('^\\s*:param ([^:]+):\\s*(.+)$')

documentation.

Type:

Matches

Type:

param

__init__(text, params=None)

params: Dict[str, str] = None

The parsed parameter documentation.

text: str

The text of the documentation.

exception zensols.introspect.insp.ClassError

Bases: Exception

Raised by ClassInspector. when a class can not be inspected or parsed by ast.

__module__ = 'zensols.introspect.insp'

__weakref__

list of weak references to the object (if defined)

class zensols.introspect.insp.ClassField(name, dtype, doc, kwargs)

Bases: ClassParam

Represents a dataclasses.dataclass field.

__init__(name, dtype, doc, kwargs)

property default: Any

kwargs: Dict[str, Any]

The field arguments.

class zensols.introspect.insp.ClassInspector(cls, attrs=None, data_type_mapper=None, include_private=False, include_init=False, strict='y')

Bases: object

A utility class to return all dataclasses.dataclass attribute (field) documentation.

DECORATOR_META: ClassVar[str] = 'CLASS_DECORATOR'

Attribute to set which must be a builtins.dict with the following keys:

• includes: as a set of decorator names that can be set on methods to indicate inclusion on introspected method set. Otherwise the decorated method (such as @property) is omitted from the class metadata

INSPECT_META: ClassVar[str] = 'CLASS_INSPECTOR'

Attribute to set to indicate to traverse superclasses as well. This is set as an empty dict to allow future implementations to filter on what’s traversed (i.e. include_fields).

__init__(cls, attrs=None, data_type_mapper=None, include_private=False, include_init=False, strict='y')

attrs: Tuple[str, ...] = None

The class attributes to inspect, or all found are returned when None.

cls: type

The class to inspect.

data_type_mapper: TypeMapper = None

The mapper used for narrowing a type from a string parsed from the Python AST.

get_class()

Return a dict of attribute (field) to metadata and docstring.

Return type:

Class

include_init: bool = False

Whether to include the __init__ method.

include_private: bool = False

Whether to include private methods that start with _.

strict: str = 'y'

Indicates what to do for undefined or unsupported structures.

One of:

• y: raise errors

• n: ignore

• w: log as warning

class zensols.introspect.insp.ClassMethod(name, doc, args)

Bases: object

Meta data for a method in a dataclass.

__init__(name, doc, args)

args: Tuple[ClassMethodArg, ...]

The arguments of the method.

doc: ClassDoc

The docstring of the method.

name: str

The name of the method.

class zensols.introspect.insp.ClassMethodArg(name, dtype, doc, default, is_positional)

Bases: ClassParam

Meta data for an argument in a method.

__init__(name, dtype, doc, default, is_positional)

default: str

The default if any, otherwise None.

is_positional: bool

True is the argument is positional vs. a keyword argument.

class zensols.introspect.insp.ClassParam(name, dtype, doc)

Bases: object

Represents a dataclasses.dataclass field.

__init__(name, dtype, doc)

doc: ClassDoc

The documentation of the field.

dtype: type

The data type.

name: str

The name of the field.

class zensols.introspect.insp.TypeMapper(cls, data_types=<factory>, default_type=<class 'str'>, allow_class=True)

Bases: object

A utility class to map string types parsed from ClassInspector to Python types.

DEFAULT_DATA_TYPES: ClassVar[Dict[str, Type]] = {'IntegerSelection': <class 'zensols.introspect.intsel.IntegerSelection'>, 'Path': <class 'pathlib.Path'>, 'bool': <class 'bool'>, 'dict': <class 'dict'>, 'float': <class 'float'>, 'int': <class 'int'>, 'list': <class 'list'>, 'pathlib.Path': <class 'pathlib.Path'>, 'str': <class 'str'>}

Supported data types mapped from data class fields.

__init__(cls, data_types=<factory>, default_type=<class 'str'>, allow_class=True)

allow_class: bool = True

Whether or not to allow classes acceptable types. When the mapper encouters these classes, the class is loaded from the module and returned as a type.

cls: Type

The class to map.

data_types: Dict[str, Type]

Data type mapping for this instance.

default_type

Default type for when no type is given.

alias of str

map_type(stype)

Return type:

Type

zensols.introspect.intsel

A class that parses a slice or element of an array.

class zensols.introspect.intsel.IntegerSelection(raw)

Bases: object

Parses an string that selects integers. These (kind) include:

• Kind.single: <int>: a singleton integers

• Kind.interval: <int>-<int>: all the integers in the inclusive interval

• Kind.list: <int>,<int>,...: a comma separated list (space optional)

To use, create it with from_string() and use tuple(), list(), then use as an iterable.

INTERVAL_DELIM: ClassVar[str] = ':'

__init__(raw)

Parse an integer selection from string raw.

property kind: Kind

The kind of selection (see class docs).

select(arr)

Return element(s) arr based on the selection.

property selection: int | Tuple[int, int] | Tuple[int]

The selection data based on what was parsed in the initializer (see class docs).

exception zensols.introspect.intsel.IntegerSelectionError

Bases: APIError

Raised for errors parsing or working with IntegerSelection.

__annotations__ = {}

__module__ = 'zensols.introspect.intsel'

class zensols.introspect.intsel.Kind(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

The kind of integer selection provided by IntegerSelection.

static from_class(cls)

Return type:

Kind

interval = 3

list = 2

single = 1

zensols.introspect.tester

Runs test cases from the Python REPL.

class zensols.introspect.tester.UnitTester(module_name, test_path=PosixPath('tests'))

Bases: object

A class that runs unittest unit test cases for the rapid prototyping use case. It does this by reloading the unit test case module, and then runs it for every invocation of this typing.Callable.

__init__(module_name, test_path=PosixPath('tests'))

module_name: str

The name of the module, which is the Python source file name sans extension.

run()

Run all test cases in the module identified by module_name.

Return type:

TextTestResult

test_path: Path = PosixPath('tests')

The path to the source file. This is added to sys.path if non-None.

Module contents

Contains modules for introspect and reflection.