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


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

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.

Testing CLI Commands

When testing the CLI settings loading can be a problem if your test case loads different settings or requires changes to be applied to settings files for test cases to execute correctly.

To reset settings to allow the CLI to rebuild the settings object use the reset_settings:

>>> from pyapp.conf import settings
>>> with settings.modify() as patch:
...     patch.reset_settings()
...     assert not settings.is_configured
>>> assert settings.is_configured

Just like with any usage of settings.modify() the origional settings are restored once the with block is exited.


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

Settings container

configure(default_settings: Union[str, 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)