build: migrate to pyproject.toml

.github/workflows/framework-tests.yaml

@@ -93,20 +93,27 @@ jobs:
           PEBBLE: /tmp/pebble
 
   pip-install:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
       - uses: actions/checkout@v3
       - name: Set up Python 3
         uses: actions/setup-python@v2
         with:
-          python-version: '3.11'
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build dependencies
+        run: pip install wheel build
 
       - name: Build
-        run: python setup.py sdist
+        run: python -m build
 
       # Test that a pip install of the source dist .tar.gz will work
       - name: Test 'pip install'
         # Shouldn't happen, but pip install will fail if ls returns multiple lines
         run: pip install $(ls dist/ops*.gz)
-

.github/workflows/publish.yml

@@ -19,12 +19,10 @@ jobs:
       - uses: actions/checkout@v3
       - name: Setup Python
         uses: actions/setup-python@v1
-        with:
-          python-version: "3.10"
-      - name: Install wheel
-        run: pip install wheel
+      - name: Install build dependencies
+        run: pip install wheel build
       - name: Build
-        run: python setup.py sdist bdist_wheel
+        run: python -m build
       - name: Publish
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

.gitignore

@@ -1,10 +1,7 @@
 __pycache__
 /sandbox
-/build
-/dist
 /ops.egg-info
 .idea
-/docs/_build
 *~
 .venv
 venv
@@ -13,6 +10,11 @@ venv
 .coverage
 /.tox
 
+# Build artifacts
+/dist
+/build
+/docs/_build
+
 # Smoke test artifacts
 *.tar.gz
 *.charm

HACKING.md

@@ -180,26 +180,71 @@ next to the relevant content (e.g. headings, etc.).
 
 Noteworthy changes should also get a new entry in [CHANGES.md](CHANGES.md).
 
+To update the requirements list for the documentation, ensure that
+[pip-tools](https://pypi.org/project/pip-tools/) is installed and run, in the
+root project folder:
 
-## Dependencies
+```sh
+pip-compile --extra=docs -o docs/requirements.txt pyproject.toml
+```
+
+# Dependencies
 
 The Python dependencies of `ops` are kept as minimal as possible, to avoid
 bloat and to minimise conflict with the charm's dependencies. The dependencies
-are listed in [requirements.txt](requirements.txt).
+are listed in [pyproject.toml](pyproject.toml) in the `[project] dependencies` section.
+
+If the dependencies change, use [pip-tools](https://pypi.org/project/pip-tools/)
+to update the generated dependency lockfiles:
+
+```sh
+pip-compile -o requirements.txt pyproject.toml
+pip-compile --extra=dev -o requirements-dev.txt pyproject.toml
+```
 
+# Dev Tools
+
+## Formatting and Checking
+
+Test environments are managed with [tox](https://tox.wiki/) and executed with
+[pytest](https://pytest.org), with coverage measured by
+[coverage](https://coverage.readthedocs.io/en/7.3.2/).
+Static type checking is done using [pyright](https://github.com/microsoft/pyright),
+and extends the Python 3.8 type hinting support through the
+[typing_extensions](https://pypi.org/project/typing-extensions/) package.
+
+Formatting uses [isort](https://pypi.org/project/isort/) and
+[autopep8](https://pypi.org/project/autopep8/), with linting also using
+[flake8](https://github.com/PyCQA/flake8), including the
+[docstrings](https://pypi.org/project/flake8-docstrings/),
+[builtins](https://pypi.org/project/flake8-builtins/) and
+[pep8-naming](https://pypi.org/project/pep8-naming/) extensions.
+
+All tool configuration is kept in [project.toml](pyproject.toml).
+
+## Building
+
+The build backend is [setuptools](https://pypi.org/project/setuptools/), and
+the build frontend is [build](https://pypi.org/project/build/).
 
 # Publishing a Release
 
 To make a release of the ops library, do the following:
 
-1. Visit the [releases page on GitHub](https://github.com/canonical/operator/releases).
-2. Click "Draft a new release"
-3. The "Release Title" is simply the full version number, in the form <major>.<minor>.<patch>
-   E.g. 2.3.12
-4. Drop notes and a changelog in the description.
-5. When you are ready, click "Publish". (If you are not ready, click "Save as Draft".)
-
-This will trigger an automatic build for the Python package and publish it to PyPI (the API token/secret is already set up in the repository settings).
+1. Open a PR to change [version.py][ops/version.py]'s `version` to the
+   [appropriate string](https://semver.org/), and get that merged to main.
+2. Visit the [releases page on GitHub](https://github.com/canonical/operator/releases).
+3. Click "Draft a new release"
+4. The "Release Title" is simply the full version number, in the form <major>.<minor>.<patch>
+   and a brief summary of the main changes in the release
+   E.g. 2.3.12 Bug fixes for the Juju foobar feature when using Python 3.12
+5. Drop notes and a changelog in the description.
+6. When you are ready, click "Publish". (If you are not ready, click "Save as Draft".)
+7. Open a PR to change [version.py][ops/version.py]'s `version` to the expected
+   next version, with "+dev" appended (for example, if 3.14.1 is the next expected version, use
+   `'3.14.1.dev0'`).
+
+This will trigger an automatic build for the Python package and publish it to PyPI (authorization is handled via a [Trusted Publisher](https://docs.pypi.org/trusted-publishers/) relationship).
 
 See [.github/workflows/publish.yml](.github/workflows/publish.yml) for details. (Note that the versions in publish.yml refer to versions of the GitHub actions, not the versions of the ops library.)
 

MANIFEST.in

@@ -0,0 +1,18 @@
+recursive-exclude .github/
+recursive-exclude docs/
+exclude .readthedocs.yaml
+exclude .gitignore
+
+recursive-include test/
+recursive-include ops/
+
+include .pyproject.toml
+include CHANGES.md
+include HACKING.md
+include README.md
+include CODE_OF_CONDUCT.md
+include LICENSE.txt
+include MANIFEST.in
+include requirements.txt
+include requirements-dev.txt
+include tox.ini