chore!: adopt uv and PEP 735 dependency groups

.github/workflows/docs.yaml.bkp

@@ -11,23 +11,20 @@ jobs:
       contents: read
     env:
       BUILD_PATH: .
-      PIP_DISABLE_PIP_VERSION_CHECK: 1
     steps:
       # checkout repository
       - name: Checkout repository
         uses: actions/checkout@v4
-      # set up specific python version
-      - name: Set up Python v3.12
-        uses: actions/setup-python@v5
+      # set up uv and a specific python version
+      - name: Set up uv with Python v3.12
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           python-version: "3.12"
       # building
       - name: Install 'documentation' dependencies
-        run: |
-          pip install .
-          pip install -r package/requirements.mkdocs.txt
+        run: uv sync --locked --no-editable --group docs-online --extra crypto-eth-addresses
       - name: Build documentation
-        run: python package/export doc
+        run: uv run --no-sync python package/export doc
       # set up Pages
       - name: Set up Pages
         uses: actions/configure-pages@v4

.github/workflows/package.yaml.bkp

@@ -12,30 +12,20 @@ jobs:
       contents: read
     env:
       BUILD_PATH: .
-      PIP_DISABLE_PIP_VERSION_CHECK: 1
     steps:
       # checkout repository
       - name: Checkout repository
         uses: actions/checkout@v4
-      # set up specific python version
-      - name: Set up Python v3.8
-        uses: actions/setup-python@v5
+      # set up uv and a specific python version
+      - name: Set up uv with Python v3.11
+        uses: astral-sh/setup-uv@v10.3.0
         with:
-          python-version: "3.8"
-      # install dependencies
-      - name: Install dependencies
-        run: |
-          python -m venv .venv
-          ./.venv/bin/python -m pip install --upgrade pip
-          ./.venv/bin/pip install .
-          ./.venv/bin/pip install -r package/requirements.sphinx.txt
-          ./.venv/bin/pip install build
-      # build package
+          python-version: "3.11"
+      # build package (generates the man page, then runs `uv build`)
       - name: Build package
         run: |
-          . ./.venv/bin/activate
-          python package/export pkg
-          deactivate
+          uv run --locked --no-editable --group docs-offline --extra crypto-eth-addresses \
+            python package/export pkg
       # upload package as artifact
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

.github/workflows/pycqa.yaml

@@ -9,25 +9,24 @@ on:
 jobs:
   tooling:
     runs-on: ubuntu-latest
-    env:
-      PIP_DISABLE_PIP_VERSION_CHECK: 1
     steps:
       # checkout repository
       - name: Checkout repository
         uses: actions/checkout@v6
-      # set up specific python version
-      - name: Set up Python v3.11
-        uses: actions/setup-python@v6
+      # set up uv and a specific python version
+      - name: Set up uv with Python v3.11
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           python-version: "3.11"
+          enable-cache: true
       # tooling
       - name: Install 'tooling' dependencies
-        run: pip install -r package/requirements.tooling.txt
+        run: uv sync --locked --group tooling --extra crypto-eth-addresses
       - name: Tooling
         run: |
-          ruff format .
-          ruff check .
-          pyright .
+          uv run --no-sync ruff format .
+          uv run --no-sync ruff check .
+          uv run --no-sync pyright .
   testing:
     strategy:
       fail-fast: true
@@ -40,16 +39,14 @@ jobs:
       # ref: https://github.com/actions/checkout/issues/19
       - name: Checkout repository
         uses: actions/checkout@v4
-      # set up specific python version
-      - name: Set up Python v${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+      # set up uv and a specific python version
+      - name: Set up uv with Python v${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v10.3.0
         with:
           python-version: ${{ matrix.python-version }}
-          cache: "pip"
+          enable-cache: true
       # testing
       - name: Install 'testing' dependencies
-        run: |
-          pip install -r package/requirements.testing.txt
-          pip install .
+        run: uv sync --locked --no-editable --group testing --extra crypto-eth-addresses
       - name: Testing
-        run: pytest .
+        run: uv run --no-sync pytest .

CONTRIBUTING.md

@@ -3,8 +3,8 @@
 Hi, to start, you need the following installed on your system.
 
 1. [Git](https://git-scm.com)
-2. [Python](https://www.python.org) v3.8 or later
-3. [PDM](https://pdm-project.org) for easy dependency management
+2. [Python](https://www.python.org) v3.11 or later
+3. [uv](https://docs.astral.sh/uv/) for dependency management
 4. (Optional/Recommended) [`NodeJS`](https://nodejs.org/en) for type checking
 5. (Optional/Recommended) [`mise`](https://github.com/jdx/mise) to manage multiple versions of Python, NodeJS and other such tools.
 
@@ -16,18 +16,18 @@ $ git clone "https://github.com/YOUR-USERNAME/validators.git"
 # change directory 
 $ cd validators
 # install development dependencies
-$ pdm install
+$ uv sync --group testing --group tooling --group runner --extra crypto-eth-addresses
 ```
 
-Activate the virtual environment and run `tox` to verify test cases.
+Run `tox` to verify test cases. (`uv run` uses the project's virtual environment, so you don't need to activate it.)
 
 ```sh
-# activate virtual environment
-$ . ./.venv/bin/activate # replace `/bin/` with `/Scripts/` if you're on Windows.
 # run tox for linting, type checking, formatting etc.
-$ tox
+$ uv run tox
 ```
 
+Development dependencies are declared as [dependency groups](https://packaging.python.org/en/latest/specifications/dependency-groups/) in `pyproject.toml` (`testing`, `tooling`, `runner`, `docs-offline`, `docs-online`, `package` and `sast`) and are locked in `uv.lock`. Run `uv lock --upgrade` to update them, and commit `uv.lock`.
+
 Create a git branch and make changes to the source code. If needed, test your changes by running `pytest`. Execute `tox` to format, lint and type-check your code before committing. Commit, push and create a pull request. If you're in doubt, feel free to start a discussion [here](https://github.com/python-validators/validators/discussions).
 
 ## Documentation
@@ -38,9 +38,10 @@ If you're adding/removing a module, you must update the `nav` key in `mkdocs.yml
 Then export documentation as follows:
 
 ```sh
-$ . ./.venv/bin/activate
+# install documentation dependencies
+$ uv sync --group docs-offline --group docs-online --extra crypto-eth-addresses
 # generate documentation
-$ python package/export TYPE # where TYPE is any of `doc`, `man` or `web`.
+$ uv run python package/export TYPE # where TYPE is any of `doc`, `man` or `web`.
 
 # doc - generates docs found here: https://nandgator.github.io/pyvalidators
 # man - generates sphinx based manpages
@@ -50,9 +51,8 @@ $ python package/export TYPE # where TYPE is any of `doc`, `man` or `web`.
 You can preview the generated documentation:
 
 ```sh
-$ . ./.venv/bin/activate
 # To preview mkdocs
-$ mkdocs serve
+$ uv run mkdocs serve
 # To preview man pages
 $ man docs/_build/man/validators.1
 # To preview sphinx webpages
@@ -82,15 +82,15 @@ $ python -m http.server -d docs/_build/web
 
 ### Versioned documentation
 
-1. To preview versioned docs, run `mike serve` (`mike` is a dev dependency).
+1. To preview versioned docs, run `uv run mike serve` (`mike` is in the `docs-online` dependency group).
 2. Then (look at <https://nandgator.github.io/pyvalidators/stable/>)
     - to publish stable docs run `mike deploy -p -u VERSION stable` after checking out to a stable tag name like `0.28.3` (note: document `VERSION = 0.29 if tag_name == 0.29.1`).
     - to publish bleeding-edge docs run `mike deploy -p -u dev master` after checking out to the `master` branch.
 3. This will deploy docs to the `gh-pages` branch (see: <https://github.com/python-validators/validators/tree/gh-pages/>)
 
 ### Packaging and releasing
 
-1. Run `./package/roll.sh` (or `./package/roll.ps1`) to generate both `sdist` and `bdist`.
+1. Run `./package/roll.sh` (or `./package/roll.ps1`) to generate the man page and both `sdist` and `bdist` (it needs [uv](https://docs.astral.sh/uv/) and uses the locked `docs-offline` dependencies).
 2. Install [`twine`](https://pypi.org/project/twine) using [`pipx`](https://pipx.pypa.io) to upload package to PyPI.
 
     ```sh

package/export/__main__.py

@@ -2,7 +2,6 @@
 
 # standard
 from ast import ImportFrom, parse
-from os import getenv
 from os.path import getsize
 from pathlib import Path
 from shutil import copy
@@ -144,10 +143,7 @@ def _generate_documentation(
 def package(source: Path):
     """Package the source code."""
     _generate_documentation(source, only_rst_man=True)
-    if getenv("CI", "false") == "true":
-        process = Popen(("./.venv/bin/python", "-m", "build"), shell=False)  # nosec
-    else:
-        process = Popen(("pdm", "build"), shell=False)  # nosec
+    process = Popen(("uv", "build"), shell=False)  # nosec
     process.communicate()
     return process.returncode