Codebase list python-microversion-parse / HEAD
HEAD

Tree @HEAD (Download .tar.gz) 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
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

Commit History @HEAD