Migrate to pyproject.toml; use ruff; deprecate __version__ (#877)

* Migrate to pyproject.toml; use ruff; deprecate __version__

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Address lint warnings

* Pypi release workflow

* Fix dep name

* Copy pasta

* Add issue

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/build-release.yml

@@ -34,40 +34,58 @@ jobs:
               tox: py312-marshmallowdev,
             }
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python }}
       - run: python -m pip install --upgrade pip wheel
       - run: pip install tox
       - run: tox -e${{ matrix.tox }}
+  build:
+    if: startsWith(github.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: Install pypa/build
+        run: python3 -m pip install build --user
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v3
+        with:
+          name: python-package-distributions
+          path: dist/
   # this duplicates pre-commit.ci, so only run it on tags
   # it guarantees that linting is passing prior to a release
   lint-pre-release:
-    name: lint
     if: startsWith(github.ref, 'refs/tags')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.1.0
-      - uses: actions/setup-python@v4.3.0
+      - uses: actions/checkout@v4.0.0
+      - uses: actions/setup-python@v4.7.0
         with:
           python-version: "3.11"
       - run: python -m pip install --upgrade pip
       - run: python -m pip install tox
-      - run: python -m tox -elint
-  release:
-    needs: [tests, lint-pre-release]
+      - run: python -m tox -e lint
+  publish-to-pypi:
     name: PyPI release
-    if: startsWith(github.ref, 'refs/tags')
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: [build, tests, lint-pre-release]
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/apispec
+    permissions:
+      id-token: write
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
-      - name: install requirements
-        run: python -m pip install build twine
-      - name: build dists
-        run: python -m build
-      - name: check package metadata
-        run: twine check dist/*
-      - name: publish
-        run: twine upload -u __token__ -p ${{ secrets.PYPI_API_TOKEN }} dist/*
+      - name: Download all the dists
+        uses: actions/download-artifact@v3
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -103,3 +103,6 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# ruff
+.ruff_cache/

.pre-commit-config.yaml

@@ -1,19 +1,14 @@
 repos:
-- repo: https://github.com/asottile/pyupgrade
-  rev: v3.15.0
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.1.13
   hooks:
-  - id: pyupgrade
-    args: [--py38-plus]
-- repo: https://github.com/psf/black
-  rev: 23.12.1
+    - id: ruff
+    - id: ruff-format
+- repo: https://github.com/python-jsonschema/check-jsonschema
+  rev: 0.27.3
   hooks:
-  - id: black
-    language_version: python3
-- repo: https://github.com/pycqa/flake8
-  rev: 7.0.0
-  hooks:
-  - id: flake8
-    additional_dependencies: [flake8-bugbear==22.12.6]
+    - id: check-github-workflows
+    - id: check-readthedocs
 - repo: https://github.com/asottile/blacken-docs
   rev: 1.16.0
   hooks:

CHANGELOG.rst

@@ -1,6 +1,14 @@
 Changelog
 ---------
 
+6.5.0 (unreleased)
+******************
+
+Other changes:
+
+- Deprecate the ``__version__`` attribute. Use feature detection, or
+  ``importlib.metadata.version("apispec")``, instead (:issue:`878`).
+
 6.4.0 (2024-01-09)
 ******************
 

RELEASING.md

@@ -0,0 +1,9 @@
+# Releasing
+
+1. Bump version in `pyproject.toml` and update the changelog
+   with today's date.
+2. Commit: `git commit -m "Bump version and update changelog"`
+3. Tag the commit: `git tag x.y.z`
+4. Push: `git push --tags origin dev`. CI will take care of the
+   PyPI release.
+5. Add release notes on Tidelift.

SECURITY.md

@@ -0,0 +1,5 @@
+# Security Contact Information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.

docs/conf.py

@@ -1,13 +1,10 @@
 import datetime as dt
+import importlib
 import os
-import sys
 import time
 
 import sphinx_rtd_theme
 
-sys.path.insert(0, os.path.abspath(os.path.join("..", "src")))
-import apispec  # noqa: E402
-
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -39,7 +36,7 @@
 project = "apispec"
 copyright = f"2014-{build_date:%Y}, Steven Loria and contributors"
 
-version = release = apispec.__version__
+version = release = importlib.metadata.version("apispec")
 
 exclude_patterns = ["_build"]
 

pyproject.toml

@@ -1,7 +1,92 @@
-[tool.black]
-line-length = 88
-target-version = ['py38', 'py39', 'py310', 'py311', 'py312']
+[project]
+name = "apispec"
+version = "6.4.0"
+description = "A pluggable API specification generator. Currently supports the OpenAPI Specification (f.k.a. the Swagger specification)."
+readme = "README.rst"
+license = { file = "LICENSE" }
+authors = [{ name = "Steven Loria", email = "sloria1@gmail.com" }]
+maintainers = [
+  { name = "Steven Loria", email = "sloria1@gmail.com" },
+  { name = "Jérôme Lafréchoux", email = "jerome@jolimont.fr" },
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "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",
+  "Programming Language :: Python :: 3.12",
+]
+keywords = [
+  "apispec",
+  "swagger",
+  "openapi",
+  "specification",
+  "oas",
+  "documentation",
+  "spec",
+  "rest",
+  "api",
+]
+requires-python = ">=3.8"
+dependencies = ["packaging>=21.3"]
 
-[tool.pyright]
-# Allow class Meta in marshmallow Schemas
-reportIncompatibleVariableOverride = false
+[project.urls]
+Changelog = "https://apispec.readthedocs.io/en/latest/changelog.html"
+Funding = "https://opencollective.com/marshmallow"
+Issues = "https://github.com/marshmallow-code/apispec/issues"
+Source = "https://github.com/marshmallow-code/apispec"
+Tidelift = "https://tidelift.com/subscription/pkg/pypi-apispec?utm_source=pypi-apispec&utm_medium=pypi"
+
+[project.optional-dependencies]
+docs = [
+  "marshmallow>=3.13.0",
+  "pyyaml==6.0.1",
+  "sphinx==7.2.6",
+  "sphinx-issues==3.0.1",
+  "sphinx-rtd-theme==2.0.0",
+]
+tests = ["apispec[yaml,marshmallow]", "openapi-spec-validator==0.7.1", "pytest"]
+dev = ["marshmallow[tests]", "tox", "pre-commit~=3.5"]
+
+[build-system]
+requires = ["flit_core<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.sdist]
+include = [
+  "docs/",
+  "tests/",
+  "CHANGELOG.rst",
+  "CONTRIBUTING.rst",
+  "SECURITY.md",
+  "tox.ini",
+]
+exclude = ["docs/_build/"]
+
+[tool.ruff]
+src = ["src"]
+fix = true
+show-fixes = true
+show-source = true
+
+[tool.ruff.lint]
+ignore = ["E203", "E266", "E501", "E731"]
+select = [
+  "B",  # flake8-bugbear
+  "E",  # pycodestyle error
+  "F",  # pyflakes
+  "I",  # isort
+  "UP", # pyupgrade
+  "W",  # pycodestyle warning
+]
+
+[tool.mypy]
+ignore_missing_imports = true
+warn_unreachable = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+no_implicit_optional = true