Skip to content

Latest commit

 

History

History
143 lines (95 loc) · 3.84 KB

usage.rst

File metadata and controls

143 lines (95 loc) · 3.84 KB
Raw

Usage

Piny loads your YAML configuration file. It optionally validates data loaded from config file. Piny main logic is in a loader class. You can pass arguments in the loader class to change the way YAML file is parsed and validated.

Loaders

YamlLoader loader class is dedicated for use in Python applications. Based on PyYAML, it parses YAML files, (arguably) the most beautiful file format for configuration files!

Basic loader usage is the following.

  1. Set your environment variables
  2. Mark up your YAML configuration file with these env names:
.. literalinclude:: code/config.yaml
   :language: yaml
  1. In your app load config with Piny:
.. literalinclude:: code/simple_yaml_loader.py

YamlStreamLoader class primary use is Piny CLI tool (see :ref:`usage-cli-docs`). But it also can be used interchargably with YamlLoader whenever IO streams are used instead of file paths.

.. automodule:: piny.loaders
    :members:
    :undoc-members:
    :show-inheritance:

Matchers

In the :ref:`usage-loaders-docs` section we used Bash-style environment variables with defaults. You may want to discourage such envs in your project. This is where matchers come in handy. They apply a regular expression when parsing your YAML file that matches environment variables we want to interpolate.

By default MatcherWithDefaults is used. StrictMatcher is another matcher class used for plain vanilla envs with no default values support.

Both strict and default matchers return None value if environment variable matched is not set in the system.

Basic usage example is the following:

.. literalinclude:: code/strict_matcher.py


.. automodule:: piny.matchers
    :members:
    :undoc-members:
    :show-inheritance:

Validators

Piny supports optional data validation using third-party libraries: Marshmallow, Pydantic, Trafaret.

In order to use data validation pass validator and schema arguments in the :ref:`usage-loaders-docs` class. You may also initialize loader class with optional named arguments that will be passed to the validator's schema. Additional loading arguments may be passed in load method invocation.

.. automodule:: piny.validators
    :members:
    :undoc-members:
    :show-inheritance:

Marshmallow validation example

.. literalinclude:: code/ma_validation.py

Pydantic validation example

.. literalinclude:: code/pydantic_validation.py

Trafaret validation example

.. literalinclude:: code/trafaret_validation.py

Exceptions

LoadingError is thrown when something goes wrong with reading or parsing a YAML file. ValidationError is a wrapper for exceptions raised by the libraries for optional data validation. Original exception can be accessed by origin attribute. It comes in handy when you need more than just an original exception message (e.g. a dictionary of validation errors).

Both exceptions inherit from the ConfigError.

.. automodule:: piny.errors
    :members:
    :undoc-members:
    :show-inheritance:

Command line utility

Piny comes with CLI tool that substitutes the values of environment variables in input file or stdin and write result to an output file or stdout. Piny CLI utility is somewhat similar to GNU/gettext envsubst but works with files too.

.. click:: piny.cli:cli
   :prog: piny
   :show-nested: