Merge pull request #2328 from Exirel/modern-python-packaging

ci, packaging, meta: modernize Python packaging for Sopel

.github/workflows/ci.yml

@@ -24,19 +24,19 @@ jobs:
           - 3.8
           - 3.9
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt -r dev-requirements.txt
+          python -m pip install --upgrade wheel
+          python -m pip install --upgrade -r dev-requirements.txt
+          python -m pip install -e .
       - name: Check code style
         run: make quality
-      - name: Install test package
-        run: python setup.py develop
       - name: Run pytest
         run: make test_norecord
       - name: Upload coverage data to coveralls.io

.github/workflows/pypi.yml

@@ -9,20 +9,19 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v3
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v4
         with:
           python-version: '3.9'
-      - name: Install dependencies
+      - name: Install PyPA/build
         run: |
           python -m pip install --upgrade pip
-          pip install setuptools wheel twine
-          pip install -r requirements.txt -r dev-requirements.txt
-      - name: Build and publish
-        env:
-          TWINE_USERNAME: __token__
-          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+          python -m pip install build --user
+      - name: Build a binary wheel and a source tarball
         run: |
-          python setup.py sdist bdist_wheel
-          twine upload dist/*
+          python -m build --sdist --wheel --outdir dist/ .
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}

CONTRIBUTING.md

@@ -8,7 +8,7 @@ that you do the following:
 1. Describe your issue clearly and concisely.
 2. Give Sopel the `.version` command, and include the output in your issue.
 3. Note the OS you're running Sopel on, and how you installed Sopel (via your
-   package manager, pip, `setup.py install`, or running straight from source)
+   package manager, pip, `pip install .` straight from source)
 4. Include relevant output from the log files in `~/.sopel/logs/`.
 
 Committing Code
@@ -45,9 +45,90 @@ include your changes.
   the name of the thing you're changing in at the beginning of the message,
   followed by a colon: the plugin name for plugins, "docs" for documentation
   files, "coretasks" for `coretasks.py`, "db" for the database feature, etc.
-* Python files should always have  `from __future__ import generator_stop`
+* Python files should always have `from __future__ import annotations`
   as the first line after the module docstring.
 
+Running from source
+-------------------
+
+Sopel is your typical Python project: you can install it from source, edit
+the code using standard tooling, and take advantage of your favorite code
+editor.
+
+Assuming you are using standard tools:
+
+* Create a virtualenv.
+  * You can use `virtualenv` (or the `venv` built-in) directly,
+    `virtualenvwrapper`, or any tool that allows you to create and manage your
+    virtualenvs.
+  * Your project manager may create the virtualenv for you; be sure to check
+    the documentation of the tools you are using.
+* Fork Sopel's repository, and clone your fork locally.
+* Activate your virtualenv, and `cd` into your clone's folder.
+* Ensure you have the latest version of `pip`, and install `wheel`.
+* Install Sopel from source as an editable install.
+  * If you don't use a project manager (like Poetry or Hatch), you can do
+    that with `pip install -e .` from within the clone's directory, where
+    there is a `pyproject.toml` file.
+* Install development tools used to run tests and linters; there is a specific
+  requirement file you can use with `pip install -U -r dev-requirements.txt`.
+* Run `make qa` to run linters and tests.
+* Run `make cleandoc` or just `make docs` to build the documentation locally.
+
+At this point, you are all set, at least for the Python environment; all that's
+left is for you to configure your code editor the way you like, and read and
+write some code and documentation.
+
+Using branches
+--------------
+
+As previously stated, you should fork Sopel's repository to implement your
+changes and commit them. Moreover, we advise you to work from your own branch.
+
+To setup your local clone, we suggest the following steps:
+
+```
+$ cd path/to/your/dev/folder
+$ git clone [email protected]:<USERNAME>/sopel.git
+$ cd sopel/
+$ git remote add upstream [email protected]:sopel-irc/sopel.git
+$ git checkout -b <your-branch-name>
+```
+
+With that workflow, you have your local clone with a link to the upstream
+repository, and a branch to work on. Once you are done with your work, you can
+commit, and push to your repository.
+
+You'll probably need, at some point, to update your repository with the new
+commits from upstream. We suggest the following steps:
+
+```
+$ git checkout master
+$ git fetch upstream
+$ git rebase upstream/master
+$ git push
+```
+
+If you never pushed on your own `master` branch, you should not need to force
+the push, which is why we recommend to work on your own branch.
+
+Said branch can be updated with rebase:
+
+```
+$ git checkout <your-branch-name>
+$ git rebase master
+```
+
+To squash your commits, you can use interactive mode with
+`git rebase -i master`.
+
+In both cases, if you configured
+[a GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification)
+to sign your commits, don't forget the `-S` option:
+
+* `git rebase -S master`
+* `git rebase -S -i master`
+
 Documenting Code
 ----------------
 

MANIFEST.in

@@ -1,4 +1,6 @@
-include *requirements.txt
 include setup.cfg
+include pyproject.toml
+recursive-exclude docs *
+recursive-exclude test *
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

conftest.py

@@ -2,9 +2,6 @@
 
 import pytest
 
-# This file lists files which should be ignored by pytest
-collect_ignore = ["setup.py", "sopel.py"]
-
 
 def pytest_addoption(parser):
     parser.addoption('--offline', action='store_true', default=False)

contrib/githooks/main-hook.sh

@@ -67,9 +67,9 @@ RUN_PYTEST=$([ "${SKIP_PYTEST}" = "1" ] && echo "0" || echo "1")
 # pytest
 [ "${RUN_PYTEST}" -eq "1" ] \
     && {
-        echo -e "\033[32mRunning \033[33mpytest_run.py \033[32mbefore ${_GIT_COMMAND}... \033[0m"
+        echo -e "\033[32mRunning \033[33mpytest \033[32mbefore ${_GIT_COMMAND}... \033[0m"
 
-        python pytest_run.py
+        python -m pytest sopel test/
         pt="${?}"
         if [ "${pt}" -ne "0" ]; then
             echo -e '\033[91mFAILED.\033[0m'

pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=63.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+platforms = ["Linux x86, x86-64"]
+
+[tool.setuptools.packages.find]
+include = ["sopel", "sopel.*"]
+namespaces = false
+
+[project]
+name = "sopel"
+version = "8.0.0.dev0"
+description = "Simple and extensible IRC bot"
+authors = [
+  { name="dgw", email="[email protected]" },
+]
+readme = "README.rst"
+license = { text="EFL-2.0" }
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: Eiffel Forum License (EFL)",
+    "License :: OSI Approved :: Eiffel Forum License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Topic :: Communications :: Chat :: Internet Relay Chat",
+]
+requires-python = ">=3.7"
+dependencies = [
+    "xmltodict==0.12",
+    "pytz",
+    "praw>=4.0.0,<8.0.0",
+    "geoip2>=4.0,<5.0",
+    "requests>=2.24.0,<3.0.0",
+    "dnspython<3.0",
+    "sqlalchemy>=1.4,<1.5",
+    "importlib_metadata>=3.6",
+    "packaging",
+]
+
+[project.urls]
+"Homepage" = "https://sopel.chat/"
+"Release notes" = "https://sopel.chat/changelog/"
+"Documentation" = "https://sopel.chat/docs/"
+"Bug Tracker" = "https://github.com/sopel-irc/sopel/issues"
+"Donate on Open Collective" = "https://opencollective.com/sopel"
+"Donate on GitHub" = "https://github.com/sponsors/sopel-irc"
+"Source" = "https://github.com/sopel-irc/sopel"
+"Coverage" = "https://coveralls.io/github/sopel-irc/sopel"
+
+
+[project.scripts]
+sopel = "sopel.cli.run:main"
+sopel-config = "sopel.cli.config:main"
+sopel-plugins = "sopel.cli.plugins:main"
+
+[project.entry-points.pytest11]
+pytest-sopel = "sopel.tests.pytest_plugin"

setup.cfg

@@ -1,39 +1,3 @@
-[metadata]
-name = sopel
-version = 8.0.0-dev
-description = Simple and extensible IRC bot
-long_description = file: README.rst
-long_description_content_type = text/x-rst
-author = dgw
-author_email = [email protected]
-url = https://sopel.chat/
-license = Eiffel Forum License, version 2
-platforms = Linux x86, x86-64
-classifiers =
-    Development Status :: 5 - Production/Stable
-    Intended Audience :: Developers
-    Intended Audience :: System Administrators
-    License :: Eiffel Forum License (EFL)
-    License :: OSI Approved :: Eiffel Forum License
-    Operating System :: POSIX :: Linux
-    Programming Language :: Python :: 3.7
-    Programming Language :: Python :: 3.8
-    Programming Language :: Python :: 3.9
-    Topic :: Communications :: Chat :: Internet Relay Chat
-
-[options]
-python_requires = >=3.7, <4
-packages = find:
-zip_safe = false
-
-[options.entry_points]
-console_scripts =
-    sopel = sopel.cli.run:main
-    sopel-config = sopel.cli.config:main
-    sopel-plugins = sopel.cli.plugins:main
-pytest11 =
-    pytest-sopel = sopel.tests.pytest_plugin
-
 [flake8]
 max-line-length = 79
 application-import-names = sopel