# Source code for plaster.interfaces

    import abc

    from .compat import add_metaclass

    @add_metaclass(abc.ABCMeta)
    class ILoader(object):
        """
        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 :term:`loader protocol` interfaces
        to provide extra functionality. For example,
        :class:`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 :term:`loader protocol` which custom loaders can
        implement.

        :ivar uri: The :class:`plaster.PlasterURL` object used to find the
            :class:`plaster.ILoaderFactory`.

        """

        @abc.abstractmethod
        def get_sections(self):
            """
            Load the list of section names available.

            """

        @abc.abstractmethod
        def get_settings(self, section=None, defaults=None):
            """
            Load the settings for the named ``section``.

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

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

            """

        @abc.abstractmethod
        def setup_logging(self, 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.

            :param 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.

            """

    @add_metaclass(abc.ABCMeta)
    class ILoaderFactory(object):

        @abc.abstractmethod
        def __call__(self, uri):
            """
            A factory which accepts a :class:`plaster.PlasterURL` and returns a
            :class:`plaster.ILoader` object.

            """

    @add_metaclass(abc.ABCMeta)
    class ILoaderInfo(object):
        """
        An info object describing a specific :class:`plaster.ILoader`.

        :ivar scheme: The full scheme of the loader.
        :ivar protocols: Zero or more supported :term:`loader protocol`
            identifiers.
        :ivar factory: The :class:`plaster.ILoaderFactory`.

        """

        @abc.abstractmethod
        def load(self, config_uri):
            """
            Create and return an :class:`plaster.ILoader` instance.

            :param config_uri: Anything that can be parsed by
                :func:`plaster.parse_uri`.

            """