workflows: add a release workflow (#308)

* workflows: add a release workflow

* Update .github/workflows/release.yml

Co-authored-by: Frost Ming <[email protected]>

* treewide: pyproject-based metadata

Removes setup.{cfg,py} in favor of pyproject.toml,
and consolidates all settings.

* pyproject: fix typo

* tox: use isolated builds

Required with PEP 517/8 metadata.

* pyproject: include `build` in dev-deps

* pyproject: include tests in sdist

Also, remove MANIFEST.in.

* meta: dedupe version, use `bump`

* Makefile, pyproject: remove bump

* CONTRIBUTING: initial contributing docs

---------

Co-authored-by: Frost Ming <[email protected]>

Author: woodruffw

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
 current_version = 0.13.0
-files = setup.py cachecontrol/__init__.py docs/conf.py
+files = cachecontrol/__init__.py docs/conf.py
 commit = True
 tag = True

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+on:
+  release:
+    types:
+      - published
+
+name: release
+
+jobs:
+  pypi:
+    name: upload release to PyPI
+    runs-on: ubuntu-latest
+
+    permissions:
+      # Used to authenticate to PyPI via OIDC.
+      # Used to sign the release's artifacts with sigstore-python.
+      id-token: write
+
+      # Used to attach signing artifacts to the published release.
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - uses: actions/setup-python@v4
+      with:
+        python-version: ">= 3.6"
+
+    - name: deps
+      run: python -m pip install -U build
+
+    - name: build
+      run: python -m build
+
+    - name: publish
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+    - name: sign
+      uses: sigstore/[email protected]
+      with:
+        inputs: ./dist/*.tar.gz ./dist/*.whl
+        release-signing-artifacts: true

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to CacheControl
+
+Thank you for your interest in contributing to `CacheControl`!
+
+The information below will help you set up a local development environment
+and perform common development tasks.
+
+## Requirements
+
+`CacheControl`'s only external development requirement is Python 3.7 or newer.
+
+## Development steps
+
+First, clone this repository:
+
+```bash
+git clone https://github.com/psf/cachecontrol
+cd cachecontrol
+```
+
+Then, bootstrap your local development environment:
+
+```bash
+make bootstrap
+# OPTIONAL: enter the new environment, if you'd like to run things directly
+source .venv/bin/activate
+```
+
+Once you've run `make bootstrap`, you can run the other `make` targets
+to perform particular tasks.
+
+Any changes you make to the `cachecontrol` source tree will take effect
+immediately in the development environment.
+
+### Linting
+
+You can run the current formatters with:
+
+```bash
+make format
+```
+
+### Testing
+
+You can run the unit tests locally with:
+
+```bash
+# run the test suite in the current environment
+make test
+
+# OPTIONAL: use `tox` to fan out across multiple interpreters
+make test-all
+```
+
+### Documentation
+
+You can build the Sphinx-based documentation with:
+
+```bash
+# puts the generated HTML in docs/_build/html/
+make doc
+```
+
+### Releasing
+
+**NOTE**: If you're a non-maintaining contributor, you don't need the steps
+here! They're documented for completeness and for onboarding future maintainers.
+
+Releases of `CacheControl` are managed by GitHub Actions.
+
+To perform a release:
+
+1. Update `CacheControl`'s `__version__` attribute. It can be found under
+   `cachecontrol/__init__.py`.
+
+1. Create a new tag corresponding to your new version, with a `v` prefix. For example:
+
+   ```bash
+   # IMPORTANT: don't forget the `v` prefix!
+   git tag v1.2.3
+   ```
+
+1. Push your changes to `master` and to the new remote tag.
+
+1. Create, save, and publish a GitHub release for your new tag, including any
+   `CHANGELOG` entries.

MANIFEST.in

@@ -7,13 +7,14 @@ VENV_CMD=python3 -m venv
 ACTIVATE = $(VENV)/bin/activate
 CHEESE=https://pypi.python.org/pypi
 BUMPTYPE=patch
+BUMPPRE=0
 
 
 $(VENV)/bin/pip3:
 	$(VENV_CMD) $(VENV)
 
 bootstrap: $(VENV)/bin/pip3
-	$(VENV)/bin/pip3 install -r dev_requirements.txt
+	$(VENV)/bin/pip3 install -e .[dev]
 
 format:
 	$(VENV)/bin/black .
@@ -49,13 +50,6 @@ test:
 coverage:
 	$(VENV)/bin/py.test --cov cachecontrol
 
-release: dist
-	$(VENV)/bin/twine upload dist/*
-
 dist: clean
-	$(VENV)/bin/python setup.py sdist bdist_wheel
+	$(VENV)/bin/python -m build
 	ls -l dist
-
-bump:
-	$(VENV)/bin/bumpversion $(BUMPTYPE)
-	git push && git push --tags

Makefile

@@ -16,6 +16,8 @@
 # serve to show the default.
 
 
+from cachecontrol import __version__
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -51,9 +53,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "0.13.0"
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = "0.13.0"
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

dev_requirements.txt

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["flit_core >=3.2,<4"]
+build-backend = "flit_core.buildapi"
+
+[tool.flit.module]
+name = "cachecontrol"
+
+[tool.flit.sdist]
+include = ["tests/"]
+
+[project]
+name = "CacheControl"
+dynamic = ["version"]
+description = "httplib2 caching for requests"
+readme = "README.rst"
+license = { file = "LICENSE.txt" }
+authors = [
+    { name = "Eric Larson", email = "[email protected]" },
+    { name = "Frost Ming", email = "[email protected]" },
+    { name = "William Woodruff", email = "[email protected]" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.6",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Internet :: WWW/HTTP",
+]
+keywords = ["requests", "http", "caching", "web"]
+dependencies = ["requests >= 2.16.0", "msgpack >= 0.5.2"]
+requires-python = ">=3.7"
+
+[project.urls]
+Homepage = "https://pypi.org/project/CacheControl/"
+Issues = "https://github.com/psf/cachecontrol/issues"
+Source = "https://github.com/psf/cachecontrol"
+
+[project.optional-dependencies]
+# End-user extras.
+filecache = ["filelock >= 3.8.0"]
+redis = ["redis>=2.10.5"]
+
+# Development extras.
+dev = [
+    "CacheControl[filecache,redis]",
+    "build",
+    "mypy",
+    "tox",
+    "pytest-cov",
+    "pytest",
+    "cherrypy",
+    "sphinx",
+    "black",
+    "types-redis",
+    "types-requests",
+]
+
+[project.scripts]
+doesitcache = "cachecontrol._cmd:main"
+
+[tool.mypy]
+show_error_codes = true
+strict = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+
+[[tool.mypy.overrides]]
+module = "msgpack"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+norecursedirs = ["bin", "lib", "include", "build"]

docs/conf.py

@@ -3,6 +3,7 @@
 ; SPDX-License-Identifier: Apache-2.0
 
 [tox]
+isolated_build = True
 envlist = py{36,37,38,39,310,311}, mypy
 
 [gh-actions]