v1.0.7 🧰

* Fix #27, #28, improve tests

* Replace setup.py with pyproject.toml

* make flake8 happy

* Update requirements.txt

* Fix pipeline

.flake8

@@ -1,7 +1,9 @@
 [flake8]
+exclude = __pycache__,built,build,venv
 ignore = E203, E266, W503
 max-line-length = 88
 max-complexity = 18
 per-file-ignores =
     tests/test_v2.py: E501
     tests/test_v3.py: E501
+select = B,C,E,F,W,T4,B9

.github/workflows/build.yml

@@ -83,19 +83,19 @@ jobs:
           bash <(curl -s https://codecov.io/bash)
 
       - name: Install distribution dependencies
-        run: pip install --upgrade twine setuptools wheel
-        if: matrix.python-version == 3.10
+        run: pip install build
+        if: matrix.python-version == 3.11
 
       - name: Create distribution package
-        run: python setup.py sdist bdist_wheel
-        if: matrix.python-version == 3.10
+        run: python -m build
+        if: matrix.python-version == 3.11
 
       - name: Upload distribution package
         uses: actions/upload-artifact@master
         with:
-          name: dist-package-${{ matrix.python-version }}
+          name: dist
           path: dist
-        if: matrix.python-version == 3.10
+        if: matrix.python-version == 3.11
 
   publish:
     runs-on: ubuntu-latest
@@ -105,17 +105,28 @@ jobs:
       - name: Download a distribution artifact
         uses: actions/download-artifact@v2
         with:
-          name: dist-package-3.10
+          name: dist
           path: dist
-      - name: Publish distribution 📦 to Test PyPI
-        uses: pypa/gh-action-pypi-publish@master
+
+      - name: Use Python 3.11
+        uses: actions/setup-python@v1
         with:
-          skip_existing: true
-          user: __token__
-          password: ${{ secrets.test_pypi_password }}
-          repository_url: https://test.pypi.org/legacy/
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install twine
+
+      - name: Publish distribution 📦 to Test PyPI
+        run: |
+          twine upload -r testpypi dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.test_pypi_password }}
+
       - name: Publish distribution 📦 to PyPI
-        uses: pypa/gh-action-pypi-publish@master
-        with:
-          user: __token__
-          password: ${{ secrets.pypi_password }}
+        run: |
+          twine upload -r pypi dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.pypi_password }}

.gitignore

@@ -5,3 +5,5 @@ htmlcov
 __pycache__
 *.egg-info
 *.tar.gz
+_test_files/
+dist/

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.7] - 2023-05-01 :toolbox:
+- Fixes [Markdown missing a newline after simple response types](https://github.com/Neoteroi/essentials-openapi/issues/27).
+- Fixes [Empty header when operations don't have any tag.](https://github.com/Neoteroi/essentials-openapi/issues/28).
+- When operations don't have any tag, the `h2` element
+- Improves tests.
+- Adopts `pyproject.toml`.
+- Workflow maintenance.
+
 ## [1.0.6] - 2023-03-19 :snail:
 - Fixes a bug happening when trying to serialize examples in JSON, when they
   contain datetimes and are provided in YAML;

Makefile

@@ -6,19 +6,23 @@ test-debug:
 
 
 artifacts: test
-	python setup.py sdist
+	python -m build
 
 
 prepforbuild:
-	pip install --upgrade twine setuptools wheel
+	pip install build
 
 
-testrelease:
-	twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+build:
+	python -m build
 
 
-release: artifacts
-	twine upload --repository-url https://upload.pypi.org/legacy/ dist/*
+test-release:
+	twine upload --repository testpypi dist/*
+
+
+release:
+	twine upload --repository pypi dist/*
 
 
 test:
@@ -41,8 +45,25 @@ test-cov:
 	pytest --cov-report html --cov=openapidocs
 
 
+lint: check-flake8 check-isort check-black
+
+
+check-flake8:
+	@echo "$(BOLD)Checking flake8$(RESET)"
+	@flake8 . 2>&1
+
+
+check-isort:
+	@echo "$(BOLD)Checking isort$(RESET)"
+	@isort --check-only . 2>&1
+
+
+check-black:
+	@echo "$(BOLD)Checking black$(RESET)"
+	@black --check . 2>&1
+
+
 format:
-	isort openapidocs
-	isort tests
-	black openapidocs
-	black tests
+	@echo "$(BOLD)Formatting code 🧹 🧼$(RESET)"
+	@black . 2>&1
+	@isort . 2>&1

openapidocs/__init__.py

@@ -1 +1,2 @@
-VERSION = "1.0.6"
+__version__ = "1.0.7"
+VERSION = __version__

openapidocs/mk/v3/views_markdown/partial/path-items.html

@@ -1,9 +1,9 @@
 {% for tag, operations in handler.get_operations().items() %}
 
-## {{tag}}
+## {{tag or "Endpoints"}}
 
 {% for path, definition in operations %}
-{%- for http_method, operation in definition.items() -%}
+{%- for http_method, operation in definition.items() %}
 
 ### {{http_method.upper()}} {{path | safe}}
 {% if "summary" in operation -%}

openapidocs/mk/v3/views_mkdocs/partial/path-items.html

@@ -1,8 +1,8 @@
 {% for tag, operations in handler.get_operations().items() %}
-## <span class="api-tag">{{tag}}</span>
+## <span class="api-tag">{{tag or "Endpoints"}}</span>
 
 {% for path, definition in operations %}
-{%- for http_method, operation in definition.items() -%}
+{%- for http_method, operation in definition.items() %}
 <hr class="operation-separator" />
 
 ### <span class="http-{{http_method.lower()}}">{{http_method.upper()}}</span> {{path | route | safe}}

pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "essentials-openapi"
+dynamic = ["version"]
+authors = [{ name = "Roberto Prevato", email = "[email protected]" }]
+description = "Classes to generate OpenAPI Documentation v3 and v2, in JSON and YAML."
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+]
+keywords = ["openapi", "docs", "swagger", "api", "documentation", "v3", "v2", "json", "yaml", "Markdown"]
+
+dependencies = ["PyYAML>=6", "essentials>=1.1.5"]
+
+[tool.hatch.version]
+path = "openapidocs/__init__.py"
+
+[project.optional-dependencies]
+full = ["click~=8.1.3", "Jinja2~=3.1.2", "MarkupSafe==2.1.2", "rich~=12.6.0", "httpx<1"]
+
+[project.scripts]
+openapidocs = "openapidocs.main:main"
+oad = "openapidocs.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["openapidocs"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["tests"]
+
+[tool.hatch.build]
+only-packages = true
+
+[project.urls]
+"Homepage" = "https://github.com/Neoteroi/essentials-openapi"
+"Bug Tracker" = "https://github.com/Neoteroi/essentials-openapi/issues"

requirements.txt

@@ -1,6 +1,7 @@
 anyio==3.6.2
 attrs==22.1.0
 black==22.10.0
+build==0.10.0
 certifi==2022.9.24
 charset-normalizer==3.0.0
 click==8.1.3
@@ -11,14 +12,16 @@ flake8==5.0.4
 Flask==2.2.2
 h11==0.12.0
 httpcore==0.15.0
-httpx==0.23.0
+httpx==0.24.0
 idna==3.4
 iniconfig==1.1.1
 isort==5.10.1
 itsdangerous==2.1.2
 Jinja2==3.1.2
-MarkupSafe==2.1.1
+markdown-it-py==2.2.0
+MarkupSafe==2.1.2
 mccabe==0.7.0
+mdurl==0.1.2
 mypy-extensions==0.4.3
 packaging==21.3
 pathspec==0.10.1
@@ -30,12 +33,13 @@ pydantic==1.10.2
 pyflakes==2.5.0
 Pygments==2.13.0
 pyparsing==3.0.9
+pyproject_hooks==1.0.0
 pytest==7.2.0
 pytest-cov==4.0.0
 PyYAML==6.0
 regex==2022.10.31
 rfc3986==1.5.0
-rich==12.6.0
+rich==13.3.5
 sniffio==1.3.0
 toml==0.10.2
 tomli==2.0.1

tests/common.py

@@ -1,5 +1,6 @@
 import json
 import os
+import re
 from typing import Any
 
 import pkg_resources
@@ -46,3 +47,21 @@ def get_file_json(file_name) -> Any:
 
 def get_file_yaml(file_name) -> Any:
     return yaml.safe_load(get_resource_file_content(file_name))
+
+
+def normalize_str(value: str) -> str:
+    return re.sub("\r?\n{2,}", "\n", value.strip())
+
+
+def compatible_str(value_one: str, value_two: str) -> bool:
+    """
+    Compares two strings ignoring multiple carriage returns and trailing carriage
+    returns. In HTML or Markdown it does not matter if you have multiple carriage
+    returns.
+    """
+    # first check if the two strings are equals: there is no point in stripping carriage
+    # returns otherwise
+    if value_one == value_two:
+        return True
+
+    return normalize_str(value_one) == normalize_str(value_two)

tests/conftest.py

@@ -1,5 +1,8 @@
+import shutil
 from uuid import UUID
 
+from essentials.folders import ensure_folder
+
 from openapidocs.mk.v3.examples import IntegerExampleHandler, StringExampleHandler
 
 # override the UUID example generator to return the same value, so that tests can have
@@ -12,3 +15,10 @@
     "int32": lambda: 26,
     "int64": lambda: 26,
 }
+
+try:
+    shutil.rmtree("_test_files")
+except OSError:
+    pass
+
+ensure_folder("_test_files")