Simple library for parsing OpenStack microversion headers.
Go to file
Zuul 8b75af5cf5 Merge "setup.cfg: Replace dashes with underscores" 2023-09-07 11:39:03 +00:00
doc Fix warnings in doc build 2023-09-07 19:48:13 +09:00
microversion_parse fix python version in tox file: py35 -> py37 2020-02-14 16:06:54 +01:00
releasenotes/notes adding missing releasenote for the drop of py27 support 2020-02-06 12:26:58 +01:00
.gitignore Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
.gitreview OpenDev Migration Patch 2019-04-19 19:42:56 +00:00
.pre-commit-config.yaml Move flake8 as a pre-commit local target. 2021-03-23 13:13:42 +01:00
.stestr.conf Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
.zuul.yaml Drop python3.6/3.7 support in testing runtime 2022-05-09 15:10:02 +02:00
LICENSE Initial commit 2016-03-22 15:29:38 +00:00
Makefile allow tox to skip missing interpreters 2016-03-24 13:28:08 +00:00
README.rst Allow passing a json_error_formatter to the middleware 2018-03-20 17:24:56 +00:00
requirements.txt Add MicroversionMiddleware 2018-03-20 17:24:56 +00:00
setup.cfg setup.cfg: Replace dashes with underscores 2023-08-07 15:38:15 +08:00 Initial proof of concept of microversion_parse 2016-03-22 17:48:42 +00:00
test-requirements.txt Adding pre-commit 2020-09-15 15:19:35 +02:00
tox.ini Use py3 as the default runtime for tox 2021-01-21 15:42:04 +01:00



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