Metadata-Version: 1.1
Name: microversion-parse
Version: 0.2.1
Summary: OpenStack microversion header parser
Home-page: http://www.openstack.org/
Author: OpenStack
Author-email: openstack-dev@lists.openstack.org
License: UNKNOWN
Description: microversion_parse
        ==================
        
        A small set of functions to manage OpenStack `microversion`_ headers that can
        be used in middleware, application handlers and decorators to effectively
        manage microversions.
        
        Also included, in the ``middleware`` module, is a ``MicroversionMiddleware``
        that will process incoming microversion headers.
        
        get_version
        -----------
        
        A simple parser for OpenStack microversion headers::
        
            import microversion_parse
        
            # headers is a dict of headers with folded (comma-separated
            # values) or a list of header, value tuples
            version = microversion_parse.get_version(
                headers, service_type='compute',
                legacy_headers=['x-openstack-nova-api-version'])
        
            # If headers are not already available, a dict of headers
            # can be extracted from the WSGI environ
            headers = microversion_parse.headers_from_wsgi_environ(environ)
            version = microversion_parse.get_version(
                headers, service_type='placement')
        
        It processes microversion headers with the standard form::
        
            OpenStack-API-Version: compute 2.1
        
        In that case, the response will be '2.1'.
        
        If provided with a ``legacy_headers`` argument, this is treated as
        a list of additional headers to check for microversions. Some examples of
        headers include::
        
            OpenStack-telemetry-api-version: 2.1
            OpenStack-nova-api-version: 2.1
            X-OpenStack-nova-api-version: 2.1
        
        If a version string cannot be found, ``None`` will be returned. If
        the input is incorrect usual Python exceptions (ValueError,
        TypeError) are allowed to raise to the caller.
        
        parse_version_string
        --------------------
        
        A function to turn a version string into a ``Version``, a comparable
        ``namedtuple``::
        
            version_tuple = microversion_parse.parse_version_string('2.1')
        
        If the provided string is not a valid microversion string, ``TypeError``
        is raised.
        
        extract_version
        ---------------
        
        Combines ``get_version`` and ``parse_version_string`` to find and validate
        a microversion for a given service type in a collection of headers::
        
            version_tuple = microversion_parse.extract_version(
                headers,  # a representation of headers, as accepted by get_version
                service_type,  # service type identify to match in headers
                versions_list,  # an ordered list of strings of version numbers that
                                # are the valid versions presented by this service
            )
        
        ``latest`` will be translated to whatever the max version is in versions_list.
        
        If the found version is not in versions_list a ``ValueError`` is raised.
        
        Note that ``extract_version`` does not support ``legacy_headers``.
        
        MicroversionMiddleware
        ----------------------
        
        A WSGI middleware that can wrap an application that needs to be microversion
        aware. The application will get a WSGI environ with a
        'SERVICE_TYPE.microversion' key that has a value of the microversion found at
        an 'openstack-api-version' header that matches SERVICE_TYPE.  If no header is
        found, the minimum microversion will be set. If the special keyword 'latest' is
        used, the maximum microversion will be set.
        
        If the requested microversion is not available a 406 response is returned.
        
        If there is an error parsing a provided header, a 400 response is returned.
        
        Otherwise the application is called.
        
        The middleware is configured when it is created. Three parameters are required:
        
        app
          The next WSGI middleware or application in the stack.
        
        service_type
          The service type of the application, used to identify microversion headers.
        
        versions_list
          An ordered list of legitimate microversions (as strings) for the application.
          It's assumed that any application that is using microversions will have such
          a list for its own housekeeping and documentation.
        
        One named parameter is optional:
        
        json_error_formatter
          A Webob error formatter that can be used to structure the response when JSON
          is expected.
        
        For example::
        
            def app():
                app = middleware.MicroversionMiddleware(
                    MyWSGIApp(), 'cats', ['1.0', '1.1', '1.2'])
                return app
        
        
        .. _microversion: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html
        
        
Platform: UNKNOWN
Classifier: Environment :: OpenStack
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
