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.- config_uri – Anything that can be parsed by
-
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.
- config_uri – Anything that can be parsed by
-
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.
- config_uri – Anything that can be parsed by
-
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.- scheme – Any valid scheme. Examples would be something like
-
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
.
-
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
.-
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
.- section – The name of the section in the config file. If this is
-
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]¶ -
__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]¶ -
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.
- name – The name of the application referenced in the config.
If
-
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.
- name – The name of the application referenced in the config.
If
-
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.
- name – The name of the application referenced in the config.
If
-
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.
- name – The name of the application referenced in the config.
If
-
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.