Configuration Helpers

The configuration helpers are a collection of tools that simplify building configuration structures. They also provide a set of factory objects for the generation of named instances from configuration.

The root helper is the NamedConfiguration, this object provides a simple interface over configuration eg:

>>> my_values = NamedConfiguration('MY_VALUES')
>>> my_values.get('foo')
'123'

# With the following in your settings file
MY_VALUES = {
    'foo': '123',
    'bar': '456',
}

Simple factories

These factory objects come in three flavours:

  • Basic - returns an instance for each request for a named object
  • Singleton - returns the same instance (lazily created) for each named object
  • ThreadLocalSingleton - returns an instance of each named object per thread

These classes are all ABS classes that the developer must inherit from and provide an implementation of the create_instance method.

class pyapp.conf.helpers.NamedFactory(setting: str, *, defaults: Dict[str, Any] = None, required_keys: Sequence[str] = None, optional_keys: Sequence[str] = None, default_name: str = None)[source]

Factory for creating instances from a named configuration.

class pyapp.conf.helpers.NamedSingletonFactory(setting: str, *, defaults: Dict[str, Any] = None, required_keys: Sequence[str] = None, optional_keys: Sequence[str] = None, default_name: str = None)[source]

NamedFactory that provides a single instance of an object.

This instance factory type is useful for instance types that only require a single instance eg database connections, web service agents.

If your instance types are not thread safe it is recommended that the ThreadLocalNamedSingletonFactory is used.

class pyapp.conf.helpers.ThreadLocalNamedSingletonFactory(setting: str, *, defaults: Dict[str, Any] = None, required_keys: Sequence[str] = None, optional_keys: Sequence[str] = None, default_name: str = None)[source]

NamedFactory that provides a single instance of an object per thread.

This instance factory type is useful for instance types that only require a single instance eg database connections, web service agents and that are not thread safe.

Plugin factories

Similar to simple factories, plugin factories also come in the same three flavours, however they include the additional functionality of supporting the creation of object instances based off configuration. The definition is slightly more complex in your settings file.

class pyapp.conf.helpers.NamedPluginFactory(setting: str, *, abc: Type[PT] = None, default_name: str = 'default')[source]

Factory object that generates a named instance from a definition in settings. Can optionally verify an instance type against a specified ABC (Abstract Base Class). The factory will cache imported types.

Named instances are defined in settings using the following definition:

MY_TYPE = {
    'default': (
        'my.module.MyClass', {
            'param1': 123,
            'param2': 'foo',
        }
    )
}

The NamedPluginFactory is thread safe.

class pyapp.conf.helpers.NamedSingletonPluginFactory(*args, **kwargs)[source]

NamedPluginFactory that provides a single instance of an object.

This instance factory type is useful for instance types that only require a single instance eg database connections, web service agents.

If your instance types are not thread safe it is recommended that the ThreadLocalNamedSingletonPluginFactory is used.

class pyapp.conf.helpers.ThreadLocalNamedSingletonPluginFactory(*args, **kwargs)[source]

NamedPluginFactory that provides a single instance of a plugin per thread.

This instance factory type is useful for instance types that only require a single instance eg database connections, web service agents and that are not thread safe.

Provider factories

Extending from plugin factories providers provide an additional level of dynamic configuration where configuration is obtained from data storage eg a database.

class pyapp.conf.helpers.ProviderFactoryBase(setting: str, abc: Type[PT] = None)[source]

Factory to instantiate and configure a provider.