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,12 @@ venv
 .coverage
 /.tox
 
+# Build artifacts
+/dist
+/build
+/docs/_build
+ops/version.py
+
 # Smoke test artifacts
 *.tar.gz
 *.charm

HACKING.md

@@ -107,13 +107,74 @@ 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/).
+
+The version number is automatically generated from Git metadata using the
+[setuptools-scm package](https://pypi.org/project/setuptools-scm/). During the
+build process, an ``ops/version.py`` is automatically generated so that if you
+are running from an installed package (including an editable install), you can
+statically access the version:
+
+```python
+import ops
+print(ops.__version__)
+import ops.version
+print(ops.version.version_tuple)
+```
+
+[This is pretty awful, and it seems like this cannot be the best way to do this]: #
+
+Importing `ops` outside of an install will fail because the generated version
+module does not exist. It can be generated using:
+
+```sh
+python -c 'import setuptools_scm;conf=setuptools_scm.Configuration.from_file();setuptools_scm.dump_version(conf.root,setuptools_scm.get_version(),conf.version_file,conf.version_file_template)'
+```
 
 # Publishing a Release
 
@@ -126,7 +187,7 @@ To make a release of the ops library, do the following:
 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).
+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,5 @@
+recursive-exclude .github/
+recursive-exclude docs/
+exclude .readthedocs.yaml
+exclude .gitignore
+