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
Raw data
{
"_id": null,
"home_page": "http://www.openstack.org/",
"name": "microversion-parse",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "OpenStack",
"author_email": "openstack-discuss@lists.openstack.org",
"download_url": "https://files.pythonhosted.org/packages/3d/02/7589a0b94bf5fab83417c054ad300a259775508a3cab3cb2e4d35c550cf7/microversion_parse-2.0.0.tar.gz",
"platform": null,
"description": "microversion_parse\n==================\n\nA small set of functions to manage OpenStack `microversion`_ headers that can\nbe used in middleware, application handlers and decorators to effectively\nmanage microversions.\n\nAlso included, in the ``middleware`` module, is a ``MicroversionMiddleware``\nthat will process incoming microversion headers.\n\nget_version\n-----------\n\nA simple parser for OpenStack microversion headers::\n\n import microversion_parse\n\n # headers is a dict of headers with folded (comma-separated\n # values) or a list of header, value tuples\n version = microversion_parse.get_version(\n headers, service_type='compute',\n legacy_headers=['x-openstack-nova-api-version'])\n\n # If headers are not already available, a dict of headers\n # can be extracted from the WSGI environ\n headers = microversion_parse.headers_from_wsgi_environ(environ)\n version = microversion_parse.get_version(\n headers, service_type='placement')\n\nIt processes microversion headers with the standard form::\n\n OpenStack-API-Version: compute 2.1\n\nIn that case, the response will be '2.1'.\n\nIf provided with a ``legacy_headers`` argument, this is treated as\na list of additional headers to check for microversions. Some examples of\nheaders include::\n\n OpenStack-telemetry-api-version: 2.1\n OpenStack-nova-api-version: 2.1\n X-OpenStack-nova-api-version: 2.1\n\nIf a version string cannot be found, ``None`` will be returned. If\nthe input is incorrect usual Python exceptions (ValueError,\nTypeError) are allowed to raise to the caller.\n\nparse_version_string\n--------------------\n\nA function to turn a version string into a ``Version``, a comparable\n``namedtuple``::\n\n version_tuple = microversion_parse.parse_version_string('2.1')\n\nIf the provided string is not a valid microversion string, ``TypeError``\nis raised.\n\nextract_version\n---------------\n\nCombines ``get_version`` and ``parse_version_string`` to find and validate\na microversion for a given service type in a collection of headers::\n\n version_tuple = microversion_parse.extract_version(\n headers, # a representation of headers, as accepted by get_version\n service_type, # service type identify to match in headers\n versions_list, # an ordered list of strings of version numbers that\n # are the valid versions presented by this service\n )\n\n``latest`` will be translated to whatever the max version is in versions_list.\n\nIf the found version is not in versions_list a ``ValueError`` is raised.\n\nNote that ``extract_version`` does not support ``legacy_headers``.\n\nMicroversionMiddleware\n----------------------\n\nA WSGI middleware that can wrap an application that needs to be microversion\naware. The application will get a WSGI environ with a\n'SERVICE_TYPE.microversion' key that has a value of the microversion found at\nan 'openstack-api-version' header that matches SERVICE_TYPE. If no header is\nfound, the minimum microversion will be set. If the special keyword 'latest' is\nused, the maximum microversion will be set.\n\nIf the requested microversion is not available a 406 response is returned.\n\nIf there is an error parsing a provided header, a 400 response is returned.\n\nOtherwise the application is called.\n\nThe middleware is configured when it is created. Three parameters are required:\n\napp\n The next WSGI middleware or application in the stack.\n\nservice_type\n The service type of the application, used to identify microversion headers.\n\nversions_list\n An ordered list of legitimate microversions (as strings) for the application.\n It's assumed that any application that is using microversions will have such\n a list for its own housekeeping and documentation.\n\nOne named parameter is optional:\n\njson_error_formatter\n A Webob error formatter that can be used to structure the response when JSON\n is expected.\n\nFor example::\n\n def app():\n app = middleware.MicroversionMiddleware(\n MyWSGIApp(), 'cats', ['1.0', '1.1', '1.2'])\n return app\n\n\n.. _microversion: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html\n\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "OpenStack microversion header parser",
"version": "2.0.0",
"project_urls": {
"Homepage": "http://www.openstack.org/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad235859fad50fc5a985d55adc53f629ed4ff578be2d5df9d271fbfa5929decb",
"md5": "55450148abf1571a4ba84f19f84d177c",
"sha256": "c9bf9665ad65be8da8a7321e403fbf9ada892e4b4fbbc168395fac6f1f1a17ee"
},
"downloads": -1,
"filename": "microversion_parse-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "55450148abf1571a4ba84f19f84d177c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19611,
"upload_time": "2024-08-29T15:38:34",
"upload_time_iso_8601": "2024-08-29T15:38:34.790039Z",
"url": "https://files.pythonhosted.org/packages/ad/23/5859fad50fc5a985d55adc53f629ed4ff578be2d5df9d271fbfa5929decb/microversion_parse-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d027589a0b94bf5fab83417c054ad300a259775508a3cab3cb2e4d35c550cf7",
"md5": "9037af30e555f95c2083bdbb7a0e92cf",
"sha256": "3a6528edf73f3bcb4507f4dad3dbc3116e9704815edfbdd6ff06dc5f899a71dc"
},
"downloads": -1,
"filename": "microversion_parse-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9037af30e555f95c2083bdbb7a0e92cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20779,
"upload_time": "2024-08-29T15:38:35",
"upload_time_iso_8601": "2024-08-29T15:38:35.733112Z",
"url": "https://files.pythonhosted.org/packages/3d/02/7589a0b94bf5fab83417c054ad300a259775508a3cab3cb2e4d35c550cf7/microversion_parse-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-29 15:38:35",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "microversion-parse"
}
JSON