Usage

To use tzf.pyramid_yml in your pyramid app, add a config.include directive:

config.include('tzf.pyramid_yml')

Now you need to add yaml.location into your application’s settings.ini file.

[app:main]
# ....
yaml.location = my.package:config
env = dev # default value is dev
# ....

This settings key can be a path or list of paths allowing you to keep configurations for your production environment separately.

Note

This configuration option works on the same principle as defining pyramid assets. It can be a package asset path or a pathname only.

Path can point to directory or to exact file. In the latter case, pyramid_yml will try to inject the env part into the filename, and will try to read from both the main config, and the env one, alike. So setting my.package:config/application.yaml will result in pyramid_yml trying to read configuration from both /path/to/my/package/config/application.yaml and /path/to/my/package/config/application.env.yaml.

There’s no rule here on what extensions pyramid_yml will try to read; just that these files must contain yaml syntax.

Note

You do not have to define any of these options:

• yaml.location defaults to the place you start your app from (usually the same place you keep your .ini files usually)
• env defaults to dev

Multifile configuration support

There exists multifile configuration support, meaning that configuration can be stored in several files at once and all of them will be joined.

To do that, you need to either load defaults with a list of config locations, or add other locations separated by comma in your ini file:

[app:main]
# ....
yaml.location = my.package:config, my.package:config3
# ....

Yaml configuration files

tzf.pyramid_yml will read two yaml configuration files: config.yaml and config.{env}.yaml (config.dev.yaml in this case) from yaml.location. The second one will overwrite the values from the first file, but all keys and values defined in first, and not in second, will stay the same:

# config.yaml
key:
    subkey: value
    subkey2: value2

#config.dev.yaml
key:
    subkey2: overwritten
    another:
        deep:
            subkey: 1

These two files will result in this config dictionary:

{'key': {'subkey': 'value'
        'subkey2': 'overwritten'
        'another': {'deep': {'subkey': 1}}
        }
}

Access to configuration

Configuration will be accessible from the request object under the config attribute: request.config. It’s a ConfigManager instance, meaning that all keys can be accessed as regular dictionary keys or as attributes.

Pyramid settings in yaml config

You can use yml config to define global settings for 3rd party packages, that requires configuration in one place (and not in your code), and use config inheritance, as well as structures.

Every keys placed within configuration: key in yml config, will be copied into pyramid’s setting dictionary.

configurator:
    sqlalchemy.url: 'connection:url'

or

configurator:
    sqlalchemy:
        url: 'connection:url'

will become:

config.registry.settings['sqlalchemy.url']

Warning

all pyramid.* settings should still be defined in ini settings file, as these are processed on application start

Including packages

Note

This functionality is an attempt to move more core pyramid functionality into yml configuration.

For more information see Pyramid documentation on including packages

To include other packages, and not define them in .ini settings file, add include: key into your yml config.

include:
    some.module: True           # Module, that'll be included
    prefixed.module: 'path'     # Module included with route_prefix
    not.included.module: False  # Module not included (helpful for overriding inherited global setting)

pconfig - command line tool

tzf.pyramid_yml provides a command line, pconfig which will help detect inheritance chain of your yml files. It displays properly indented and inherited config tree for given environment.

To run, type: $ pconfig development.ini

Adding more defaults

tzf.pyramid_yml allows to create more defaults, based on same location of yaml files, as defined in yaml.location, allowing to use this method by 3rd party pyramid plugins.

To do this, config_defaults method has been added to Configurator object. Using it is as simple as:

config.config_defaults('package.module:folder/subfolder')
config.config_defaults('package.module:folder/subfolder', ['my_defaults.yaml'])

It’s more detailed within the api section. tzf.pyramid_yml.config_defaults()