Modernize packaging and CI with pyproject.toml and uv

.github/workflows/sphinx-check.yml

@@ -1,12 +1,19 @@
 name: "Sphinx documentation build check"
-on: 
-- pull_request
+
+on:
+  pull_request:
 
 jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
-    - uses: ammaraskar/sphinx-action@master
-      with:
-        docs-folder: "docs/"
+      - uses: actions/checkout@v6
+      - name: Install uv and set Python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.10"
+          enable-cache: true
+      - name: Sync docs environment
+        run: uv sync --locked --no-group dev --group docs
+      - name: Build documentation
+        run: uv run --no-sync sphinx-build -W -b html docs/source docs/build/html

.github/workflows/style-check.yml

@@ -8,18 +8,16 @@ on:
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v4
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install flake8
-        python -m pip install flake8-docstrings
-    - name: Check style with script (flake8)
-      run: |
-        ./scripts/style_check.sh
+      - uses: actions/checkout@v6
+      - name: Install uv and set Python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.10"
+          enable-cache: true
+      - name: Sync lint environment
+        run: uv sync --locked --only-group lint
+      - name: Lint with Ruff
+        run: uv run --no-sync ruff check

.github/workflows/unit-tests.yml

@@ -8,23 +8,20 @@ on:
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
-      with:
-        python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        python -m pip install requests simplejson pytest pytest-mock
-    - name: Test with pytest
-      run: |
-        pytest -v tests/
+      - uses: actions/checkout@v6
+      - name: Install uv and set Python version
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Sync test environment
+        run: uv sync --locked --no-group dev --group test
+      - name: Test with pytest
+        run: uv run --no-sync pytest -v tests/

.gitignore

@@ -1,6 +1,11 @@
 docs/build
 __pycache__
 build
+dist
 carta.egg-info
 .DS_Store
 .coverage
+.coverage.*
+.pytest_cache
+.ruff_cache
+.venv

.python-version

@@ -0,0 +1 @@
+3.10

.readthedocs.yaml

@@ -14,9 +14,12 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
+  fail_on_warning: true
 
 # We recommend specifying your dependencies to enable reproducible builds:
 # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-  - requirements: docs/requirements.txt
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

README.md

@@ -3,11 +3,19 @@ carta-python
 
 This is a prototype of a scripting interface which uses a generic HTTP interface in the CARTA backend as a proxy to call actions on the CARTA frontend.
 
-This package is not yet published on PyPi, but can be installed from the local repository directory with `pip`. Ensure that you're using a Python 3 installation and its corresponding `pip`, either using a `virtualenv` or the appropriate system executable, which may be called `pip3`. Required dependencies (the `requests` library) should be installed automatically:
+This package is not yet published on PyPi, but can be installed from the local repository directory with `pip`. Requires Python 3.10 or later. Ensure that you're using the corresponding `pip`, either using a `virtualenv` or the appropriate system executable, which may be called `pip3`. Required dependencies should be installed automatically:
 
     pip install .
 
-To create a new frontend session which is controlled by the wrapper instead of connecting to an existing frontend session, you also need to install the `selenium` Python library. You also need to make sure that your desired browser is installed, together with a corresponding web driver.
+To create a new frontend session which is controlled by the wrapper instead of connecting to an existing frontend session, you also need to install the `selenium` Python library:
+
+    pip install selenium
+
+If you prefer installing the optional browser dependencies via package extras, the equivalent command is:
+
+    pip install ".[browser]"
+
+You also need to make sure that your desired browser is installed, together with a corresponding web driver.
 
 Some example usage of the client as a module is shown in the [documentation](https://carta-python.readthedocs.io).
 
@@ -17,21 +25,83 @@ Unit tests
 ----------
 
 Running the unit tests requires the installation of additional dependencies:
+
 ```
 pip install pytest
 pip install pytest-mock
 pip install pytest-cov
 ```
 
 To run all the unit tests (from the root directory of the repository):
+
 ```
-pytest tests # concise
-pytest -v tests # more verbose
+pytest tests/     # concise
+pytest -v tests/  # more verbose
 ```
 
 To view the code coverage:
+
 ```
 pytest --cov=carta tests/
 ```
 
 See the [`pytest` documentation](https://docs.pytest.org/) for more usage options.
+
+Alternative contributor setup with uv
+-------------------------------------
+
+If you prefer a synced local development environment, `uv` is also supported:
+
+```
+uv sync
+```
+
+This creates a local virtual environment, installs the package in editable mode, and syncs the default development groups.
+
+Equivalent development commands:
+
+```
+uv run pytest tests/                 # unit tests
+uv run pytest -v tests/              # verbose unit tests
+uv run pytest --cov=carta tests/     # coverage
+uv run ruff check                    # lint
+uv run ruff format --check           # formatting check
+```
+
+To auto-fix lint and formatting issues in the `uv` environment:
+
+```
+uv run ruff check --fix
+uv run ruff format
+```
+
+Documentation
+-------------
+
+If you are using the `uv` environment, build the docs locally with Sphinx:
+
+```
+uv run sphinx-build -W -b html docs/source docs/build/html
+```
+
+Or use the Makefile shortcut inside the `docs/` directory:
+
+```
+cd docs
+uv run make html
+```
+
+Then open `docs/build/html/index.html` in a browser:
+
+```
+open docs/build/html/index.html        # macOS
+xdg-open docs/build/html/index.html    # Linux
+```
+
+The published docs are hosted on [Read the Docs](https://carta-python.readthedocs.io).
+
+If you need the docs dependency export for Read the Docs after changing dependencies in `pyproject.toml`:
+
+```
+uv export --locked --only-group docs --format requirements.txt --no-hashes --output-file docs/requirements.txt
+```

docs/requirements.txt

@@ -1,5 +1,67 @@
-Sphinx>=7
+# This file was autogenerated by uv via the following command:
+#    uv export --locked --only-group docs --format requirements.txt --no-hashes --output-file docs/requirements.txt
+alabaster==0.7.16
+    # via sphinx
+babel==2.18.0
+    # via sphinx
+certifi==2026.2.25
+    # via requests
+charset-normalizer==3.4.6
+    # via requests
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via sphinx
+docutils==0.20.1
+    # via
+    #   sphinx
+    #   sphinx-rtd-theme
+    #   sphinx-tabs
+idna==3.11
+    # via requests
+imagesize==2.0.0
+    # via sphinx
+jinja2==3.1.6
+    # via sphinx
+markupsafe==3.0.3
+    # via jinja2
+packaging==26.0
+    # via sphinx
+pockets==0.9.1
+    # via sphinxcontrib-napoleon
+pygments==2.20.0
+    # via
+    #   sphinx
+    #   sphinx-tabs
+requests==2.33.1
+    # via sphinx
+six==1.17.0
+    # via
+    #   pockets
+    #   sphinxcontrib-napoleon
+snowballstemmer==3.0.1
+    # via sphinx
+sphinx==7.3.7
+    # via
+    #   sphinx-rtd-theme
+    #   sphinx-tabs
+    #   sphinxcontrib-jquery
 sphinx-rtd-theme==2.0.0
-sphinxcontrib-napoleon==0.7
-simplejson>=3.17.6
 sphinx-tabs==3.4.5
+sphinxcontrib-applehelp==2.0.0
+    # via sphinx
+sphinxcontrib-devhelp==2.0.0
+    # via sphinx
+sphinxcontrib-htmlhelp==2.1.0
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-napoleon==0.7
+sphinxcontrib-qthelp==2.0.0
+    # via sphinx
+sphinxcontrib-serializinghtml==2.0.0
+    # via sphinx
+tomli==2.4.1 ; python_full_version < '3.11'
+    # via sphinx
+urllib3==2.6.3
+    # via requests

docs/source/quickstart.rst

@@ -6,15 +6,19 @@ Installation
 
 This package is not yet published on PyPi, but can be installed from a local checkout of the repository.
 
-Ensure that you're using a Python 3 installation and its corresponding ``pip``, either using a ``virtualenv`` or the appropriate system executable, which may be called ``pip3``.
+Requires **Python 3.10** or later. Install with ``pip``:
 
 .. code-block:: shell
 
     git clone https://github.com/CARTAvis/carta-python.git
     cd carta-python
     pip install .
 
-The required Python library dependencies should be installed automatically. To create new frontend sessions which are controlled by the wrapper instead of connecting to existing frontend sessions, you also need to install the ``selenium`` Python library.
+The required Python library dependencies should be installed automatically. To create new frontend sessions which are controlled by the wrapper instead of connecting to existing frontend sessions, you also need to install the optional browser dependencies:
+
+.. code-block:: shell
+
+    pip install ".[browser]"
 
 You need access either to a CARTA backend executable, on the local host or on a remote host which you can access through SSH, or to a CARTA controller instance (a multi-user system with web-based authentication). You must be able to access the frontend served by this CARTA instance. If you are using your own backend executable, you must start it with the ``--enable_scripting`` commandline parameter to enable the scripting interface.