From 160a126fdd3239717ccc8e3a99a01f791e390807 Mon Sep 17 00:00:00 2001 From: Quentin Monnet Date: Tue, 2 Aug 2022 18:12:40 +0100 Subject: [PATCH 1/3] Switch from m2r to sphinx-mdinclude m2r is unmaintained [0]. It relies on mistune, but is not compatible with mistune versions >= 2.0 [1]. This makes it impossible to update mistune, even though there is a CVE in the old versions of the package [2]. Switch to sphinx-mdinclude instead. There is also m2r2, but it is not a suitable alternative because they simply force the use of an older mistune version [3]. [0] https://github.com/sphinx-contrib/openapi/issues/123 [1] https://github.com/miyakogi/m2r/issues/66 [2] https://github.com/advisories/GHSA-fw3v-x4f2-v673 [3] https://github.com/CrossNox/m2r2/pull/43 Fixes: #123 --- setup.py | 2 +- sphinxcontrib/openapi/renderers/_httpdomain.py | 7 +++++-- sphinxcontrib/openapi/utils.py | 2 +- tests/renderers/httpdomain/rendered/v2.0/uber.json.rst | 8 ++++---- tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst | 8 ++++---- 5 files changed, 15 insertions(+), 12 deletions(-) diff --git a/setup.py b/setup.py index 3d97e05..077dacd 100755 --- a/setup.py +++ b/setup.py @@ -30,7 +30,7 @@ "sphinxcontrib-httpdomain >= 1.5.0", "PyYAML >= 3.12", "jsonschema >= 2.5.1", - "m2r >= 0.2", + "sphinx-mdinclude >= 0.5.2", "picobox >= 2.2", "deepmerge >= 0.1", ], diff --git a/sphinxcontrib/openapi/renderers/_httpdomain.py b/sphinxcontrib/openapi/renderers/_httpdomain.py index 630e11a..fe511bb 100644 --- a/sphinxcontrib/openapi/renderers/_httpdomain.py +++ b/sphinxcontrib/openapi/renderers/_httpdomain.py @@ -9,7 +9,7 @@ import deepmerge import docutils.parsers.rst.directives as directives -import m2r +import sphinx_mdinclude import requests import sphinx.util.logging as logging @@ -184,7 +184,10 @@ def _get_schema_type(schema): class HttpdomainRenderer(abc.RestructuredTextRenderer): """Render OpenAPI v3 using `sphinxcontrib-httpdomain` extension.""" - _markup_converters = {"commonmark": m2r.convert, "restructuredtext": lambda x: x} + _markup_converters = { + "commonmark": sphinx_mdinclude.convert, + "restructuredtext": lambda x: x, + } _response_examples_for = {"200", "201", "202", "2XX"} _request_parameters_order = ["header", "path", "query", "cookie"] diff --git a/sphinxcontrib/openapi/utils.py b/sphinxcontrib/openapi/utils.py index 4efb038..f779828 100644 --- a/sphinxcontrib/openapi/utils.py +++ b/sphinxcontrib/openapi/utils.py @@ -17,7 +17,7 @@ import jsonschema import yaml try: - from m2r import convert as convert_markdown + from sphinx_mdinclude import convert as convert_markdown except ImportError: convert_markdown = None diff --git a/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst b/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst index dc27468..165fc28 100644 --- a/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst +++ b/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst @@ -36,11 +36,11 @@ **Price Estimates** - .. role:: raw-html-m2r(raw) + .. role:: raw-html-md(raw) :format: html - The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-m2r:`
`\ :raw-html-m2r:`
`\ The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. + The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. :queryparam start_latitude: Latitude component of start location. @@ -154,11 +154,11 @@ **User Activity** - .. role:: raw-html-m2r(raw) + .. role:: raw-html-md(raw) :format: html - The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-m2r:`
`\ :raw-html-m2r:`
`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. + The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. :queryparam offset: Offset the list of returned results by this amount. Default is zero. diff --git a/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst b/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst index 4b14064..4ec8586 100644 --- a/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst +++ b/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst @@ -36,11 +36,11 @@ **Price Estimates** - .. role:: raw-html-m2r(raw) + .. role:: raw-html-md(raw) :format: html - The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-m2r:`
`\ :raw-html-m2r:`
`\ The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. + The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. :queryparam start_latitude: Latitude component of start location. @@ -154,11 +154,11 @@ **User Activity** - .. role:: raw-html-m2r(raw) + .. role:: raw-html-md(raw) :format: html - The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-m2r:`
`\ :raw-html-m2r:`
`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. + The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. :queryparam offset: Offset the list of returned results by this amount. Default is zero. From 1d7a5d87940b68037293991e61651787d9d7c1ae Mon Sep 17 00:00:00 2001 From: Quentin Monnet Date: Tue, 29 Nov 2022 20:59:59 +0000 Subject: [PATCH 2/3] Remove handling of optional import for mdinclude Since commit 1e95ac6fc888 ("Actualize information in setup.py"), the dependency on m2r, now replaced with mdinclude, is no longer part of the "extras_require", but of the "install_requires" in setup.py. So the dependency should always be satisfied, and we don't need to handle the case where the import fails. --- sphinxcontrib/openapi/utils.py | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/sphinxcontrib/openapi/utils.py b/sphinxcontrib/openapi/utils.py index f779828..9ed2fb2 100644 --- a/sphinxcontrib/openapi/utils.py +++ b/sphinxcontrib/openapi/utils.py @@ -16,10 +16,7 @@ from contextlib import closing import jsonschema import yaml -try: - from sphinx_mdinclude import convert as convert_markdown -except ImportError: - convert_markdown = None +import sphinx_mdinclude from urllib.parse import urlsplit from urllib.request import urlopen @@ -113,12 +110,7 @@ def get_text_converter(options): """Decide on a text converter for prose.""" if 'format' in options: if options['format'] == 'markdown': - if convert_markdown is None: - raise ValueError( - "Markdown conversion isn't available, " - "install the [markdown] extra." - ) - return convert_markdown + return sphinx_mdinclude.convert # No conversion needed. return lambda s: s From b8debb401bb10b4ad8d0cb482ac9e41cba11a832 Mon Sep 17 00:00:00 2001 From: Quentin Monnet Date: Tue, 29 Nov 2022 21:04:34 +0000 Subject: [PATCH 3/3] Update tests following the switch from m2r to mdinclude Two kind of changes are required to adjust the tests after the move from m2r to mdinclude for parsing Markdown. - We need to slightly adjust the expected results for the uber.json/uber.yaml tests, because of minor differences in formatting between m2r and mdinclude (namely, spaces before/after the inserted role markers). - Alas, we also need to adjust the base JSON/YAML files themselves, because it appears that mdinclude (itself or through its mistune dependency, I'm not sure, see [0] and [1]) does not support simple HTML tags without slash (e.g. "
...
" works, "
" too, but not simply "
"). [0] https://github.com/lepture/mistune/blob/693db5c/mistune/inline_parser.py#L32 [1] https://github.com/amyreese/sphinx-mdinclude/blob/3636e33fe83cfcfea14e70fd503777ceb11f4401/sphinx_mdinclude/parse.py#L62 --- tests/renderers/httpdomain/rendered/v2.0/uber.json.rst | 4 ++-- tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst | 4 ++-- tests/testspecs/v2.0/uber.json | 4 ++-- tests/testspecs/v2.0/uber.yaml | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst b/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst index 165fc28..ff7367d 100644 --- a/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst +++ b/tests/renderers/httpdomain/rendered/v2.0/uber.json.rst @@ -40,7 +40,7 @@ :format: html - The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. + The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.:raw-html-md:`
`:raw-html-md:`
`The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. :queryparam start_latitude: Latitude component of start location. @@ -158,7 +158,7 @@ :format: html - The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. + The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.:raw-html-md:`
`:raw-html-md:`
`The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. :queryparam offset: Offset the list of returned results by this amount. Default is zero. diff --git a/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst b/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst index 4ec8586..97d838a 100644 --- a/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst +++ b/tests/renderers/httpdomain/rendered/v2.0/uber.yaml.rst @@ -40,7 +40,7 @@ :format: html - The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. + The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.:raw-html-md:`
`:raw-html-md:`
`The response also includes low and high estimates, and the `ISO 4217 `_ currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. :queryparam start_latitude: Latitude component of start location. @@ -158,7 +158,7 @@ :format: html - The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.\ :raw-html-md:`
`\ :raw-html-md:`
`\ The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. + The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.:raw-html-md:`
`:raw-html-md:`
`The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. :queryparam offset: Offset the list of returned results by this amount. Default is zero. diff --git a/tests/testspecs/v2.0/uber.json b/tests/testspecs/v2.0/uber.json index e87f4e2..9560c18 100644 --- a/tests/testspecs/v2.0/uber.json +++ b/tests/testspecs/v2.0/uber.json @@ -61,7 +61,7 @@ "/estimates/price": { "get": { "summary": "Price Estimates", - "description": "The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.", + "description": "The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.", "parameters": [ { "name": "start_latitude", @@ -201,7 +201,7 @@ "/history": { "get": { "summary": "User Activity", - "description": "The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.", + "description": "The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.", "parameters": [ { "name": "offset", diff --git a/tests/testspecs/v2.0/uber.yaml b/tests/testspecs/v2.0/uber.yaml index 1a0a070..dc6cbd2 100644 --- a/tests/testspecs/v2.0/uber.yaml +++ b/tests/testspecs/v2.0/uber.yaml @@ -55,7 +55,7 @@ paths: /estimates/price: get: summary: Price Estimates - description: The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. + description: The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217) currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier. parameters: - name: start_latitude in: query @@ -151,7 +151,7 @@ paths: /history: get: summary: User Activity - description: The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. + description: The User Activity endpoint returns data about a user's lifetime activity with Uber. The response will include pickup locations and times, dropoff locations and times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary. parameters: - name: offset in: query