Skip to content

A spry little configuration reader

License

Notifications You must be signed in to change notification settings

bryant-finney/pyspry

Repository files navigation

A Springy Little Configuration Reader

latest release pipeline status coverage report Maintainability pylint PyPI version Downloads Code style: black docs: pdoc Checked with mypy pre-commit.ci status

Influenced by Spring Boot's YAML configuration features, this library reads system configuration settings from environment variables and YAML files.

Installation

To install using pip:

pip install pyspry

Usage

By default, a file named config.yml in the current directory will be loaded and parsed for configuration settings. These can be accessed through the pyspry.settings module.

For example, consider the following config.yml file:

DATABASES:
  default:
    AUTOCOMMIT: true
    NAME: db.sqlite3
DEBUG: true
DEFAULT_CHARSET: utf-8

These configuration settings can be accessed as follows:

>>> from pyspry import settings
>>> settings.DEBUG
True

>>> settings.DEFAULT_CHARSET
'utf-8'

Specifying Alternate Config Files

Set the environment variable PYSPRY_CONFIG_PATH to override the default path to the configuration file:

>>> import os; os.environ["PYSPRY_CONFIG_PATH"]
'sample-config.yml'

>>> from pyspry import settings
>>> settings.PYSPRY_STATICFILES_FINDERS
['django.contrib.staticfiles.finders.FileSystemFinder', 'django.contrib.staticfiles.finders.AppDirectoriesFinder']

Variable Prefixes

Set the environment variable PYSPRY_VAR_PREFIX to filter which settings are loaded:

>>> import os; os.environ["PYSPRY_VAR_PREFIX"]
'PYSPRY'

>>> from pyspry import settings
>>> "TEST_RUNNER" in settings         # the prefix is automatically inserted
True

>>> "IGNORED_SETTING" in settings     # see the last line in 'sample-config.yml'
False

Nested Structures

If the configuration includes nested data structures, each layer of nesting can be traversed using _-separated names:

>>> settings.LOGGING["version"] == settings.LOGGING_version == 1
True

>>> settings.LOGGING["loggers"]["pyspry"]["level"] == \
...   settings.LOGGING_loggers_pyspry_level == 'DEBUG'
True

Environment Variables

In many cases, it can be useful to set one-off overrides for a setting. This can be done with an environment variable:

>>> import importlib, os
>>> settings.LOGGING_loggers_pyspry_level
'DEBUG'
>>> os.environ["PYSPRY_LOGGING_loggers_pyspry_level"] = "INFO"
>>> settings = importlib.reload(settings)
>>> settings.LOGGING["loggers"]["pyspry"]["level"]
'INFO'

Django Integration

This package was originally designed for use with the Django framework. To use it:

# after installing the package, specify it as the settings module
export DJANGO_SETTINGS_MODULE=pyspry.settings

django-admin diffsettings

Development

The following system dependencies are required:

Common development commands are managed by poethepoet; run poe --help for an up-to-date list of commands:

Poe the Poet - A task runner that works well with poetry.
version 0.20.0

USAGE
  poe [-h] [-v | -q] [--root PATH] [--ansi | --no-ansi] task [task arguments]

GLOBAL OPTIONS
  -h, --help     Show this help page and exit
  --version      Print the version and exit
  -v, --verbose  Increase command output (repeatable)
  -q, --quiet    Decrease command output (repeatable)
  -d, --dry-run  Print the task contents but don't actually run it
  --root PATH    Specify where to find the pyproject.toml
  --ansi         Force enable ANSI output
  --no-ansi      Force disable ANSI output

CONFIGURED TASKS
  setup-versioning  Install the 'poetry-dynamic-versioning' plugin to the local 'poetry' installation
  docs              Generate this package's docs
  docserver         Use 'pdoc' to launch an HTTP server for this package's docs
  lab               Run Jupyter Lab
  lint              Lint this package
  test              Test this package and report coverage

Reports