[1.0.3] add trim query option (#1)

* [feature] add trim_query option for every API class

* [docs] add trim_query option description to readme

* [test] add test cases with query

* [CI] add test

* [CI] change python test versions

* [CI] remove python 3.10 test

* [CI] add publish workflow

* [1.0.3] update changelog and setup for version 1.0.3

Author: holamgadol

.github/workflows/python-publish.yml

@@ -0,0 +1,48 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+  workflow_run:
+    workflows: [Python package]
+    types: [completed]
+
+permissions:
+  contents: read
+
+jobs:
+  on-success:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - run: echo 'The test workflow passed'
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: '3.x'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_TOKEN }}
+
+  on-failure:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+    steps:
+      - run: echo 'The test workflow failed'

.github/workflows/python-test.yml

@@ -0,0 +1,26 @@
+name: Python package
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9"]
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip3 install .
+          pip3 install --upgrade foliantcontrib.test_framework
+      - name: Test with unittest
+        run: |
+          python3 -m unittest discover

README.md

@@ -312,6 +312,9 @@ The list of options and some default values differ for each mode.
 `endpoint_prefix`
 :   *(optional)* The endpoint prefix from the server root to API methods. If is stated — APIReferences can divide the command in the reference and search for it more accurately. Also, you could use it in templates. More info in the **Commands and Endpoint Prefixes** section. Default: `''`
 
+`trim_query`
+: *(optional)* Cut a query part after `?` character from command while searching for an API link. Default: `True`
+
 **`find_by_anchor` mode**
 
 `url`
@@ -335,6 +338,9 @@ The list of options and some default values differ for each mode.
 `password`
 :    *(optional)* Password for basic authentication if present on your API site.
 
+`trim_query`
+: *(optional)* Cut a query part after `?` character from command while searching for an API link. Default: `True`
+
 **`find_by_tag_content` mode**
 
 `url`
@@ -355,6 +361,9 @@ The list of options and some default values differ for each mode.
 `password`
 :    *(optional)* Password for basic authentication if present on your API site.
 
+`trim_query`
+: *(optional)* Cut a query part after `?` character from command while searching for an API link. Default: `True`
+
 **`find_for_swagger` mode**
 
 `url`
@@ -375,6 +384,9 @@ The list of options and some default values differ for each mode.
 `password`
 :    *(optional)* Password for basic authentication if present on your API site.
 
+`trim_query`
+: *(optional)* Cut a query part after `?` character from command while searching for an API link. Default: `True`
+
 **`find_for_redoc` mode**
 
 `url`
@@ -395,6 +407,9 @@ The list of options and some default values differ for each mode.
 `password`
 :    *(optional)* Password for basic authentication if present on your API site.
 
+`trim_query`
+: *(optional)* Cut a query part after `?` character from command while searching for an API link. Default: `True`
+
 # User guide
 
 The purpose of APIReferences is to convert *references* into Markdown links. 
@@ -899,22 +914,22 @@ preprocessors:
 
 With the default template, the reference string will be replaced by something like that:
 
-```
+```md
 [GET user/info](http://example.com/api/#get-user-info)
 ```
 
 If you want references to be transformed into something else, create your own template. You can use placeholders from the reference regular expression along with some additional:
 
-placeholder | description | example
--------- | ----------- | -------
-source | Full original reference string | \``Client-API: GET user/info`\`
-url | Full url to the method description | `http://example.com/api/#get-user-info`
-endpoint_prefix | API endpoint prefix from API configuration | `/api/v2`
+| placeholder     | description                                | example                                 |
+|-----------------|--------------------------------------------|-----------------------------------------|
+| source          | Full original reference string             | \``Client-API: GET user/info`\`         |
+| url             | Full url to the method description         | `http://example.com/api/#get-user-info` |
+| endpoint_prefix | API endpoint prefix from API configuration | `/api/v2`                               |
 
 Placeholders from the default regex are:
 
-placeholder | description | example
--------- | ----------- | -------
-prefix | API Prefix used in the reference | `Client-API`
-verb | HTTP verb used in the reference | `GET`
-command | API command being referenced with endpoint prefix removed | `/user/info`
+| placeholder | description                                               | example      |
+|-------------|-----------------------------------------------------------|--------------|
+| prefix      | API Prefix used in the reference                          | `Client-API` |
+| verb        | HTTP verb used in the reference                           | `GET`        |
+| command     | API command being referenced with endpoint prefix removed | `/user/info` |

changelog.md

@@ -1,3 +1,7 @@
+# 1.0.3
+
+-   New: `trim_query` option (default: True) for every API class
+
 # 1.0.2
 
 -   New utils module.

foliant/preprocessors/apireferences/classes.py

@@ -131,6 +131,13 @@ def rel_command(self):
         """
         return self.command.lstrip('/')
 
+    @property
+    def trim_query(self):
+        """
+        Return command without a query.
+        """
+        return self.command.split('?')[0]
+
 
 class APIBase:
     """
@@ -187,12 +194,14 @@ def __init__(self,
                  name: str,
                  url: str,
                  content_template: str,
+                 trim_query: bool = True,
                  endpoint_prefix: str = '',
                  tags: list = DEFAULT_TAG_LIST,
                  login: str or None = None,
                  password: str or None = None):
         super().__init__(name, url)
         self.content_template = content_template
+        self.trim_query = trim_query
         self.tags = tags
         self.registry = {}
         self.endpoint_prefix = endpoint_prefix
@@ -312,8 +321,9 @@ def generate_content_by_reference(self,
         api_ref = Reference(**ref.__dict__)  # copy of original ref
         if self.endpoint_prefix:
             api_ref.endpoint_prefix = self.endpoint_prefix
-
         ref_dict = api_ref.__dict__
+        if self.trim_query:
+            ref_dict['command'] = api_ref.trim_query
         if rel_command:
             ref_dict['command'] = api_ref.rel_command
         if with_ep and self.endpoint_prefix:
@@ -336,13 +346,15 @@ def __init__(self,
                  name: str,
                  url: str,
                  anchor_template: str,
+                 trim_query: bool = True,
                  anchor_converter: str = 'pandoc',
                  endpoint_prefix: str = '',
                  tags: list = DEFAULT_TAG_LIST,
                  login: str or None = None,
                  password: str or None = None):
         super().__init__(name, url)
         self.anchor_template = anchor_template
+        self.trim_query = trim_query
         self.anchor_converter = anchor_converter
         self.tags = tags
         self.registry = {}
@@ -409,7 +421,7 @@ def get_anchor_by_reference(self, ref: Reference) -> str:
         Get anchor for the reference from self.registry. The search is performed by
         anchor formatted by self.anchor_template. First try with `command from the
         reference, then (if that fails), try removing leading slash from command,
-        then (if that fails), tryadding self.endpoint_prefix if present.
+        then (if that fails), try adding self.endpoint_prefix if present.
 
         If reference cannot be found — raise ReferenceNotFoundError.
 
@@ -470,11 +482,12 @@ def generate_anchor_by_reference(self,
             (' with endpoint_prefix' if with_ep else '') +
             (' with relative command' if rel_command else '')
         )
-        api_ref = Reference(**ref.__dict__)  # copy of original ref
+        api_ref = Reference(**ref.__dict__) # copy of original ref
         if self.endpoint_prefix:
             api_ref.endpoint_prefix = self.endpoint_prefix
-
         ref_dict = api_ref.__dict__
+        if self.trim_query:
+            ref_dict['command'] = api_ref.trim_query
         if rel_command:
             ref_dict['command'] = api_ref.rel_command
         if with_ep and self.endpoint_prefix:
@@ -501,10 +514,12 @@ def __init__(self,
                  name: str,
                  url: str,
                  anchor_template: str,
+                 trim_query: bool = True,
                  anchor_converter: str = 'pandoc',
                  endpoint_prefix: str = ''):
         super().__init__(name, url)
         self.anchor_template = anchor_template
+        self.trim_query = trim_query
         self.anchor_converter = anchor_converter
         self.endpoint_prefix = endpoint_prefix
 
@@ -550,6 +565,8 @@ def generate_anchor_by_reference(self, ref: Reference) -> str:
             api_ref.endpoint_prefix = self.endpoint_prefix
 
         ref_dict = api_ref.__dict__
+        if self.trim_query:
+            ref_dict['command'] = api_ref.trim_query
         anchor_source = self.anchor_template.format(**ref_dict)
         return to_id(anchor_source, self.anchor_converter)
 
@@ -572,13 +589,15 @@ def __init__(
         name: str,
         url: str,
         spec: str or PosixPath,
+        trim_query: bool = True,
         anchor_template: str = DEFAULT_ANCHOR_TEMPLATE,
         anchor_converter: str = 'no_transform',
         endpoint_prefix: str = '',
         login: str or None = None,
         password: str or None = None,
     ):
         super().__init__(name, url)
+        self.trim_query = trim_query
         self.anchor_template = anchor_template
         self.anchor_converter = anchor_converter
         self.endpoint_prefix = endpoint_prefix
@@ -713,8 +732,10 @@ def get_extended_reference(self, ref: Reference) -> dict:
         api_ref = Reference(**ref.__dict__)  # copy of original ref
         if self.endpoint_prefix:
             api_ref.endpoint_prefix = self.endpoint_prefix
-
-        key = self.REGISTRY_KEY_TEMPLATE.format(verb=api_ref.verb, command=api_ref.command)
+        command = api_ref.command
+        if self.trim_query:
+            command = api_ref.trim_query
+        key = self.REGISTRY_KEY_TEMPLATE.format(verb=api_ref.verb, command=command)
         logger.debug(f'Getting link for reference {ref} by key "{key}"')
         if key in self.registry:
             logger.debug(f'Found')

setup.py

@@ -16,7 +16,7 @@
     description=SHORT_DESCRIPTION,
     long_description=LONG_DESCRIPTION,
     long_description_content_type='text/markdown',
-    version='1.0.2',
+    version='1.0.3',
     author='Daniil Minukhin',
     author_email='[email protected]',
     url='https://github.com/foliant-docs/foliantcontrib.apireferences',

tests/test_api_by_anchor.py

@@ -183,6 +183,13 @@ def test_get_link_by_reference_with_extra_prefix(self):
         link = api.get_link_by_reference(ref)
         self.assertEqual(link, 'http://example.com/#user-content-get-systemrestart')
 
+    def test_get_link_by_reference_with_query(self):
+        api = self.get_basic_api()
+        api.endpoint_prefix = '/api/v2'
+        ref = Reference(verb='GET', command='/admin/status?users=guest,admin')
+        link = api.get_link_by_reference(ref)
+        self.assertEqual(link, 'http://example.com/#user-content-get-apiv2adminstatus')
+
     def test_get_nonexistant_link(self):
         api = self.get_basic_api()
         ref = Reference(verb='GET', command='/wrong/command')

tests/test_api_by_swagger.py

@@ -166,6 +166,19 @@ def test_get_anchor_by_reference(self):
         anchor = api.get_anchor_by_reference(ref)
         self.assertEqual(anchor, expected_anchor)
 
+    def test_get_anchor_by_reference_with_query(self):
+        api = APIBySwagger(
+            name='Test',
+            url='http://example.com/',
+            spec=rel_name('data/swagger.json'),
+            anchor_template='/{tag}/{operation_id}',
+        )
+
+        ref = Reference(verb='PUT', command='/pet?spieces=cat,dog')
+        expected_anchor = '/pettag/updatePet'
+        anchor = api.get_anchor_by_reference(ref)
+        self.assertEqual(anchor, expected_anchor)
+
     def test_get_anchor_by_reference_custom_template(self):
         api = APIBySwagger(
             name='Test',

tests/test_api_by_tag_content.py

@@ -180,6 +180,13 @@ def test_get_link_by_reference_with_extra_prefix(self):
         link = api.get_link_by_reference(ref)
         self.assertEqual(link, 'http://example.com/#user-content-get-systemrestart')
 
+    def test_get_link_by_reference_with_query(self):
+        api = self.get_basic_api()
+        api.endpoint_prefix = '/api/v2'
+        ref = Reference(verb='GET', command='/admin/status?users=guest,admin')
+        link = api.get_link_by_reference(ref)
+        self.assertEqual(link, 'http://example.com/#user-content-get-apiv2adminstatus')
+
     def test_get_nonexistant_link(self):
         api = self.get_basic_api()
         ref = Reference(verb='GET', command='/wrong/command')

tests/test_api_gen_anchor.py

@@ -20,6 +20,16 @@ def test_generate_anchor_by_reference(self):
         anchor = api.generate_anchor_by_reference(ref)
         self.assertEqual(anchor, 'user-content-get-userinfo')
 
+    def test_generate_anchor_by_reference_with_query(self):
+        api = APIGenAnchor(
+            name='Test',
+            url='http://example.com/',
+            anchor_template='user content {verb} {command}',
+        )
+        ref = Reference(verb='GET', command='/user/info?type=common,secret')
+        anchor = api.generate_anchor_by_reference(ref)
+        self.assertEqual(anchor, 'user-content-get-userinfo')
+
     def test_generate_anchor_by_reference_custom_field(self):
         api = APIGenAnchor(
             name='Test',