# `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 `pastedeploy+ini`.

    - 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`.

  abstractmethod 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`.

  abstractmethod get_sections()

    Load the list of section names available.

  abstractmethod 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`.

  abstractmethod 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
  abstractmethod __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
  abstractmethod 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.

  abstractmethod get_wsgi_app_settings(name=None, defaults=None)

    Return the settings for a WSGI application.

    This is similar to `plaster.ILoader.get_settings()` for a WSGI application.

    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.

  abstractmethod 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.

  abstractmethod 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.