plaster API

Application API

plaster.get_settings(config_uri, section=None, defaults=None)

Load the settings from a named section.

settings = plaster.get_settings(...)
print(settings['foo'])

Parameters:

• config_uri – Anything that can be parsed by plaster.parse_uri().
• section – The name of the section in the config file. If this is None then it is up to the loader to determine a sensible default usually derived from the fragment in the path#name syntax of the config_uri.
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

Returns:

A dict of settings. This should return a dictionary object even if no data is available.

plaster.setup_logging(config_uri, defaults=None)

Execute the logging configuration defined in the config file.

This function should, at least, configure the Python standard logging module. However, it may also be used to configure any other logging subsystems that serve a similar purpose.

Parameters:

• config_uri – Anything that can be parsed by plaster.parse_uri().
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

plaster.get_loader(config_uri, protocols=None)

Find a plaster.ILoader object capable of handling config_uri.

Parameters:

• config_uri – Anything that can be parsed by plaster.parse_uri().
• protocols – Zero or more loader protocol identifiers that the loader must implement to match the desired config_uri.

Returns:

A plaster.ILoader object.

Raises:

• plaster.LoaderNotFound – If no loader could be found.
• plaster.MultipleLoadersFound – If multiple loaders match the requested criteria. If this happens, you can disambiguate the lookup by appending the package name to the scheme for the loader you wish to use. For example if ini is ambiguous then specify ini+myapp to use the ini loader from the myapp package.

plaster.find_loaders(scheme, protocols=None)

Find all loaders that match the requested scheme and protocols.

Parameters:

• scheme – Any valid scheme. Examples would be something like ini or ini+pastedeploy.
• protocols – Zero or more loader protocol identifiers that the loader must implement. If None then only generic loaders will be returned.

Returns:

A list containing zero or more plaster.ILoaderInfo objects.

class plaster.ILoaderInfo

An info object describing a specific plaster.ILoader.

Variables:

• scheme – The full scheme of the loader.
• protocols – Zero or more supported loader protocol identifiers.
• factory – The plaster.ILoaderFactory.

load(config_uri)

Create and return an plaster.ILoader instance.

Parameters:config_uri – Anything that can be parsed by plaster.parse_uri().

Loader API

class plaster.ILoader

An abstraction over an source of configuration settings.

It is required to implement get_sections, get_settings and setup_logging.

Optionally, it may also implement other loader protocol interfaces to provide extra functionality. For example, plaster.protocols.IWSGIProtocol which requires get_wsgi_app, and get_wsgi_server for loading WSGI configurations. Services that depend on such functionality should document the required functionality behind a particular loader protocol which custom loaders can implement.

Variables:uri – The plaster.PlasterURL object used to find the plaster.ILoaderFactory.

get_sections()

Load the list of section names available.

get_settings(section=None, defaults=None)

Load the settings for the named section.

Parameters:

• section – The name of the section in the config file. If this is None then it is up to the loader to determine a sensible default usually derived from the fragment in the path#name syntax of the config_uri.
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

Returns:

A dict of settings. This should return a dictionary object even if the section is missing.

Raises:

ValueError – If a section name is missing and cannot be determined from the config_uri.

setup_logging(defaults=None)

Execute the logging configuration defined in the config file.

This function should, at least, configure the Python standard logging module. However, it may also be used to configure any other logging subsystems that serve a similar purpose.

Parameters:defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

class plaster.ILoaderFactory

__call__(uri)

A factory which accepts a plaster.PlasterURL and returns a plaster.ILoader object.

plaster.parse_uri(config_uri)

Parse the config_uri into a plaster.PlasterURL object.

config_uri can be a relative or absolute file path such as development.ini or /path/to/development.ini. The file must have an extension that can be handled by a plaster.ILoader registered with the system.

Alternatively, config_uri may be a RFC 1738-style string.

class plaster.PlasterURL(scheme, path='', options=None, fragment='')

Represents the components of a URL used to locate a plaster.ILoader.

Variables:

• scheme – The name of the loader backend.
• path – The loader-specific path string. This is the entirety of the config_uri passed to plaster.parse_uri() without the scheme, fragment and options. If this value is falsey it is replaced with an empty string.
• options – A dictionary of options parsed from the query string as url-encoded key=value pairs.
• fragment – A loader-specific default section name. This parameter may be used by loaders in scenarios where they provide APIs that support a default name. For example, a loader that provides get_wsgi_app may use the fragment to determine the name of the section containing the WSGI app if none was explicitly defined. If this value is falsey it is replaced with an empty string.

Protocols

class plaster.protocols.IWSGIProtocol

get_wsgi_app(name=None, defaults=None)

Create a WSGI application object.

An example application object may be:

def app(environ, start_response):
    start_response(b'200 OK', [(b'Content-Type', b'text/plain')])
    yield [b'hello world\n']

Parameters:

• name – The name of the application referenced in the config. If None then it should default to the plaster.PlasterURL.fragment, if available.
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

Raises:

LookupError – If a WSGI application cannot be found by the specified name.

get_wsgi_app_settings(name=None, defaults=None)

Create a WSGI application object.

An example application object may be:

def app(environ, start_response):
    start_response(b'200 OK', [(b'Content-Type', b'text/plain')])
    yield [b'hello world\n']

Parameters:

• name – The name of the application referenced in the config. If None then it should default to the plaster.PlasterURL.fragment, if available.
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

Raises:

LookupError – If a WSGI application cannot be found by the specified name.

get_wsgi_filter(name=None, defaults=None)

Create a composable WSGI middleware object.

An example middleware filter may be:

class Filter(object):
    def __init__(self, app):
        self.app = app

    def __call__(self, environ, start_response):
        return self.app(environ, start_response)

Parameters:

• name – The name of the application referenced in the config. If None then it should default to the plaster.PlasterURL.fragment, if available.
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

Raises:

LookupError – If a WSGI filter cannot be found by the specified name.

get_wsgi_server(name=None, defaults=None)

Create a WSGI server runner.

An example server runner may be:

def runner(app):
    from wsgiref.simple_server import make_server
    server = make_server('0.0.0.0', 8080, app)
    server.serve_forever()

Parameters:

• name – The name of the application referenced in the config. If None then it should default to the plaster.PlasterURL.fragment, if available.
• defaults – A dict of default values used to populate the settings and support variable interpolation. Any values in defaults may be overridden by the loader prior to returning the final configuration dictionary.

Raises:

LookupError – If a WSGI server cannot be found by the specified name.

Exceptions

exception plaster.PlasterError

A base exception for any error generated by plaster.

exception plaster.InvalidURI(uri, message=None)

Raised by plaster.parse_uri() when failing to parse a config_uri.

Variables:uri – The user-supplied config_uri string.

exception plaster.LoaderNotFound(scheme, protocols=None, message=None)

Raised by plaster.get_loader() when no loaders match the requested scheme.

Variables:

• scheme – The scheme being matched.
• protocols – Zero or more loader protocol identifiers that were requested when finding a loader.

exception plaster.MultipleLoadersFound(scheme, loaders, protocols=None, message=None)

Raised by plaster.get_loader() when more than one loader matches the requested scheme.

Variables:

• scheme – The scheme being matched.
• protocols – Zero or more loader protocol identifiers that were requested when finding a loader.
• loaders – A list of plaster.ILoaderInfo objects.