Provides a simple woy to add settings to your application.

Management of loading of settings from different file types and merging into a simple easy to use settings object.


>>> from pyapp.conf import settings
>>> # Configure default settings
>>> settings.configure('my_app.default_settings')

>>> settings.MY_CONFIG_VALUE

The settings object also has helper methods to simplify your testing:

>>> from pyapp.conf import settings
>>> with settings.modify() as patch:
...     patch.MY_CONFIG_VALUE = 'bar'
...     settings.MY_CONFIG_VALUE
>>> settings.MY_CONFIG_VALUE

In addition to changing values new values can be added or existing values removed using the del keyword. Once the context has been exited all changes are reverted.


All settings must be UPPER_CASE. If a setting is not upper case it will not be imported into the settings object.


class pyapp.conf.Settings(base_settings_=None)[source]

Settings container

configure(default_settings: Sequence[str], runtime_settings: Optional[str] = None, additional_loaders: Optional[Sequence[pyapp.conf.loaders.base.Loader]] = None, env_settings_key: str = 'PYAPP_SETTINGS')[source]

Configure the settings object

  • default_settings – Your applications and extensions default settings.

  • runtime_settings – Settings defined for the current runtime (eg from the command line)

  • additional_loaders – Additional loaders to execute

  • env_settings_key – Environment variable key used to override the runtime_settings.

property is_configured

Settings have been configured (or some initial settings have been loaded).

load(loader: pyapp.conf.loaders.base.Loader, apply_method=None)[source]

Load settings from a loader instance. A loader is an iterator that yields key/value pairs.

See pyapp.conf.loaders.ModuleLoader as an example.


Apply changes to settings file using a context manager that will roll back the changes on exit of a with block. Designed to simplify test cases.

This should be used with a context manager:

>>> settings = Settings()
>>> with settings.modify() as patch:
>>>     # Change a setting
>>>     patch.FOO = 'foo'
>>>     # Remove a setting
>>>     del patch.BAR
Return type



Conf Loaders

Loaders are used to load settings from an external source, eg a Python module (using ModuleLoader).

A loader provides key/value pairs to the settings container to merge into the application settings.


class pyapp.conf.loaders.ModuleLoader(module: str)[source]

Load configuration from an importable module.

Loader will load all upper case attributes from the imported module.


>>> loader = ModuleLoader("name.of.module")
>>> settings = dict(loader)


class pyapp.conf.loaders.ObjectLoader(obj: object)[source]

Load configuration variables from any object. This can be used to mirror settings from Django settings.

Loader will only read UPPERCASE attributes from the object.


>>> from django.conf import settings as django_settings
>>> from pyapp.conf import settings as pyapp_settings
>>> loader = ObjectLoader(django_settings)
>>> pyapp_settings.load(loader)

New in version 4.2.

File Loader

Loads settings from a file


class pyapp.conf.loaders.file_loader.FileLoader(path: Union[str, pathlib.Path], content_type: str, *, encoding: str = 'UTF8')[source]

Load settings from a file.


>>> loader = FileLoader('/path/to/settings.json')
>>> settings = dict(loader)

HTTP Loader

Loads settings from an HTTP endpoint (HTTPS is recommended)


class pyapp.conf.loaders.http_loader.HttpLoader(url: yarl.URL)[source]

Load settings from a file.


>>> loader = HttpLoader(URL("https://hostname/path/to/settings.json"))
>>> settings = dict(loader)