plaster
API¶
Application API¶
- plaster.get_settings(config_uri, section=None, defaults=None)[source]¶
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 thepath#name
syntax of theconfig_uri
.defaults – A
dict
of default values used to populate the settings and support variable interpolation. Any values indefaults
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)[source]¶
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 indefaults
may be overridden by the loader prior to returning the final configuration dictionary.
- plaster.get_loader(config_uri, protocols=None)[source]¶
Find a
plaster.ILoader
object capable of handlingconfig_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 specifyini+myapp
to use the ini loader from themyapp
package.
- plaster.find_loaders(scheme, protocols=None)[source]¶
Find all loaders that match the requested scheme and protocols.
- Parameters:
scheme – Any valid scheme. Examples would be something like
ini
orpastedeploy+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[source]¶
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
.
- abstract load(config_uri)[source]¶
Create and return an
plaster.ILoader
instance.- Parameters:
config_uri – Anything that can be parsed by
plaster.parse_uri()
.
Loader API¶
- class plaster.ILoader[source]¶
An abstraction over an source of configuration settings.
It is required to implement
get_sections
,get_settings
andsetup_logging
.Optionally, it may also implement other loader protocol interfaces to provide extra functionality. For example,
plaster.protocols.IWSGIProtocol
which requiresget_wsgi_app
, andget_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 theplaster.ILoaderFactory
.
- abstract get_settings(section=None, defaults=None)[source]¶
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 thepath#name
syntax of theconfig_uri
.defaults – A
dict
of default values used to populate the settings and support variable interpolation. Any values indefaults
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
.
- abstract setup_logging(defaults=None)[source]¶
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 indefaults
may be overridden by the loader prior to returning the final configuration dictionary.
- class plaster.ILoaderFactory[source]¶
- abstract __call__(uri)[source]¶
A factory which accepts a
plaster.PlasterURL
and returns aplaster.ILoader
object.
- plaster.parse_uri(config_uri)[source]¶
Parse the
config_uri
into aplaster.PlasterURL
object.config_uri
can be a relative or absolute file path such asdevelopment.ini
or/path/to/development.ini
. The file must have an extension that can be handled by aplaster.ILoader
registered with the system.Alternatively,
config_uri
may be a RFC 1738-style string.
- class plaster.PlasterURL(scheme, path='', options=None, fragment='')[source]¶
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 toplaster.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[source]¶
- abstract get_wsgi_app(name=None, defaults=None)[source]¶
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 theplaster.PlasterURL.fragment
, if available.defaults – A
dict
of default values used to populate the settings and support variable interpolation. Any values indefaults
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.
- abstract get_wsgi_app_settings(name=None, defaults=None)[source]¶
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 theplaster.PlasterURL.fragment
, if available.defaults – A
dict
of default values used to populate the settings and support variable interpolation. Any values indefaults
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.
- abstract get_wsgi_filter(name=None, defaults=None)[source]¶
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 theplaster.PlasterURL.fragment
, if available.defaults – A
dict
of default values used to populate the settings and support variable interpolation. Any values indefaults
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.
- abstract get_wsgi_server(name=None, defaults=None)[source]¶
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 theplaster.PlasterURL.fragment
, if available.defaults – A
dict
of default values used to populate the settings and support variable interpolation. Any values indefaults
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.InvalidURI(uri, message=None)[source]¶
Raised by
plaster.parse_uri()
when failing to parse aconfig_uri
.- Variables:
uri – The user-supplied
config_uri
string.
- exception plaster.LoaderNotFound(scheme, protocols=None, message=None)[source]¶
Raised by
plaster.get_loader()
when no loaders match the requestedscheme
.- 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)[source]¶
Raised by
plaster.get_loader()
when more than one loader matches the requestedscheme
.- 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.