Simple library for parsing OpenStack microversion headers.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
niuke d8e123228d remove unicode from code 2 months ago
doc remove unicode from code 2 months ago
microversion_parse fix python version in tox file: py35 -> py37 3 years ago
releasenotes/notes adding missing releasenote for the drop of py27 support 3 years ago
.gitignore Add MicroversionMiddleware 5 years ago
.gitreview OpenDev Migration Patch 3 years ago
.pre-commit-config.yaml Move flake8 as a pre-commit local target. 2 years ago
.stestr.conf Add MicroversionMiddleware 5 years ago
.zuul.yaml Drop python3.6/3.7 support in testing runtime 5 months ago
LICENSE Initial commit 7 years ago
Makefile allow tox to skip missing interpreters 7 years ago
README.rst Allow passing a json_error_formatter to the middleware 5 years ago
requirements.txt Add MicroversionMiddleware 5 years ago
setup.cfg Drop python3.6/3.7 support in testing runtime 5 months ago Initial proof of concept of microversion_parse 7 years ago
test-requirements.txt Adding pre-commit 2 years ago
tox.ini Use py3 as the default runtime for tox 2 years ago



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.


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',

# 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.


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.


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.


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:


The next WSGI middleware or application in the stack.


The service type of the application, used to identify microversion headers.


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:


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