fictive.patterns.dynamic_load module

functions for dynamically loading objects from entry point object references

Functions

from_environment	resolves an object as specificed by an environment variable
from_file	resolves an entry point as specified in a file
from_string	resolves an object as specificed by an environment variable
from_working_set	resolves an entry point from a pkg_resources.WorkingSet

Classes

LazyDescriptor

uses pkg_resources resolution to provide lazy-loading / late-binding

class fictive.patterns.dynamic_load.LazyDescriptor(object_reference, cached=True)

Bases: object

uses pkg_resources resolution to provide lazy-loading / late-binding

''' mypackage.py '''

class MyClass(object):
    THIS_CLASS = MyClass  # NameError

Traceback (most recent call last):
    ...
NameError: name 'MyClass' is not defined

''' mypackage.py '''

from fictive.patterns.dynamic_load import LazyDescriptor

class MyClass(object):
    THIS_CLASS = LazyDescriptor('mypackage:MyClass')

>>> MyClass.THIS_CLASS is MyClass
True

__init__(object_reference, cached=True)

Initialize self. See help(type(self)) for accurate signature.

resolved

resolve (and cache) the object reference

fictive.patterns.dynamic_load.from_string(object_reference: str)

resolves an object as specificed by an environment variable

''' xyzzy.py '''

class Breakfast(object):
    toast = 'burnt'

>>> from fictive.patterns.dynamic_load import from_string
>>> from_string(object_reference='xyzzy:Breakfast.toast')
'burnt'

Parameters

object_reference (str) – an object reference string according to https://packaging.python.org/specifications/entry-points/#data-model

Raises

• ValueError – the object reference contains one or more syntax errors

• ImportError – the entry point could not be loaded

fictive.patterns.dynamic_load.from_environment(env_key: str)

resolves an object as specificed by an environment variable

''' xyzzy.py '''

class Breakfast(object):
    eggs = 'scrambled'

>>> import os
>>> object_reference = f"xyzzy:Breakfast.eggs"
>>> os.environ['FICTIVE_DYNAMIC_EGGS'] = object_reference
>>> from fictive.patterns.dynamic_load import from_environment
>>> from_environment(env_key='FICTIVE_DYNAMIC_EGGS')
'scrambled'

Parameters

env_key (str) – the key for an environment variable that contains an object reference string according to https://packaging.python.org/specifications/entry-points/#data-model

Raises

• KeyError – the environment does not contain a value for the key

• ValueError – the object reference contains one or more syntax errors

• ImportError – the entry point could not be loaded

fictive.patterns.dynamic_load.from_file(group: str, name: str, filename: str = 'entry_points.txt')

resolves an entry point as specified in a file

''' xyzzy.py '''

class Breakfast(object):
    bacon = 'crispy'

# entry_points.txt

[foo.bar]
baz = xyzzy:Breakfast.bacon

[other.group]
name = other:object.reference

>>> group = 'foo.bar'
>>> name = 'baz'
>>> from fictive.patterns.dynamic_load import from_file
>>> from_file(group=group, name=name)
'crispy'

Parameters

• group (str) – the “group” for the entry point.

• name (str) – the “name” for the entry point

• filename (str) – the name of an entry points according to https://packaging.python.org/specifications/entry-points/#file-format

Raises

• OSError – the file could not be opened

• ValueError – the entry points file contains one or more syntax errors

• KeyError – the group or entry name within the group was not found in the entry point file

• ImportError – the entry point could not be loaded

fictive.patterns.dynamic_load.from_working_set(group: str, name: str, working_set: pkg_resources.WorkingSet = None, multiple: Literal[raise, warn, silent, iter] = 'raise')

resolves an entry point from a pkg_resources.WorkingSet

''' xyzzy.py '''

class Breakfast(object):
    potatoes = 'hashed'

''' setup.py '''

from setuptools import setup

setup(
    ...,
    entry_points=(
        'foo.bar': {
            'baz': 'xyzzy:Breakfast.potatoes'
        }
    }
)

>>> group = 'foo.bar'
>>> name = 'baz'
>>> from fictive.patterns.dynamic_load import from_working_set
>>> from_working_set(group=group, name=name)
'hashed'

Parameters

• group (str) – the “group” for the entry point.

• name (str) – the “name” for the entry point

• working_set (pkg_resources.WorkingSet) – the working set to search for the entry point. If not specified, uses the default pkg_resources.working_set

• multiple –

  pkg_resources permits a working set to have multiple entry points with the same group and name. In the event that multiple entry points match the group and name values provided, the value of the multiple parameter controls the result:

  • ’raise’ (default):

    raises a pkg_resources.ResolutionError

  • ’warn’:

    a warning is issued and one of the matching entry points is arbitrarily chosen and loaded

  • ’silent’:

    one of the matching entry points is arbitrarily chosen and loaded without any warning

Raises

• ValueError – the contains invalid entry point syntax

• pkg_resources.ResolutionError – there are multiple entry points in the specified group with the specified name and multiple is 'raise'

• ImportError – the entry point could not be loaded