Publish Python package to PyPI (#43)

* Don't use symlinks for data in the Python package, to support Windows installs

* Clean up installation instructions in README

* Revert "Clean up installation instructions in README"

This reverts commit e35d0a2.

* Add workflow for building and pushing releases to PyPI

* Temporarily enable builds of the `pypi-publish` workflow on PRs, for testing

* Tweak conditional syntax in `pypi-publish.yaml` to try to resolve parsing error

* Revert "Temporarily enable builds of the `pypi-publish` workflow on PRs, for testing"

This reverts commit f72df21.

* Factor out common kwargs for reading the vars dict in vars_funs.py

* Always use absolute path when reading vars dict from CSV

* Tweaks to README ahead of PyPI release

Author: jeancochrane

.github/workflows/pypi-publish.yaml

@@ -0,0 +1,49 @@
+on:
+  workflow_dispatch:
+  release:
+    types:
+      - released
+      - prereleased
+
+name: pypi-publish
+
+env:
+  PYTHONUNBUFFERED: "1"
+
+jobs:
+  pypi-publish:
+    name: pypi-publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build Python dist
+        working-directory: python
+        run: |
+          # Copy over any necessary data files
+          mkdir -p ccao/data/
+          cp ../data-raw/vars_dict.csv ccao/data/vars_dict.csv
+          # Build the package
+          uv build
+
+      - name: Publish package distribution to test PyPI
+        if: ${{ github.event.action == 'prereleased' }}
+        env:
+          url: https://test.pypi.org/legacy/p/ccao
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Publish package distribution to PyPI
+        if: ${{ github.event.action == 'released' }}
+        env:
+          url: https://pypi.org/p/ccao
+        uses: pypa/gh-action-pypi-publish@release/v1

python/README.md

@@ -15,11 +15,10 @@ Install the latest release of `ccao` from PyPI:
 pip install ccao
 ```
 
-You can also install the most recent code directly from GitHub:
+## Usage
 
-```bash
-pip install "git+https://github.com/ccao-data/ccao.git#egg=ccao&subdirectory=python"
-```
+See [the documentation](https://ccao-data.github.io/ccao/python/)
+for detailed API reference.
 
 ## Development
 
@@ -49,3 +48,19 @@ sphinx-autobuild docs/source _build/html
 ```
 
 Navigate to http://localhost:8000 to view the docs.
+
+### Releasing new versions
+
+We handle package releases on GitHub. The `pypi-publish` workflow watches
+for release events and pushes new releases to GitHub.
+
+The workflow watches for two types of releases:
+
+- **Pre-release**: If you mark a release as a pre-release in the GitHub UI,
+  the workflow will push the package to [the PyPI test
+  instance](https://test.pypi.org/).
+- **Release**: If you cut a normal release in the GitHub UI, the workflow will
+  publish the package to the prod PyPI instance.
+
+Make sure to put up a PR to bump the package version in `pyproject.toml` before
+you cut a release.

python/ccao/data/__init__.py

@@ -1,19 +1,40 @@
 # Functions for translating variables between different data sources
-import importlib.resources
+import os
 import typing
 
 import pandas as pd
 
-import ccao.data
-
 # Load the default variable dictionary
-_data_path = importlib.resources.files(ccao.data)
-vars_dict = pd.read_csv(
-    str(_data_path / "vars_dict.csv"),
-    dtype=str,
-    keep_default_na=False,
-    na_values=[""],
-)
+vars_dict_read_kwargs = {
+    "dtype": "str",
+    "keep_default_na": False,
+    "na_values": [""],
+}
+try:
+    # Try loading from the canonical location of the file. This file does
+    # not exist in the source code, but we copy it over prior to building the
+    # package for PyPI, so it should be available in PyPI installations
+    vars_dict = pd.read_csv(
+        os.path.join(
+            os.path.dirname(os.path.abspath(__file__)), "data", "vars_dict.csv"
+        ),
+        **vars_dict_read_kwargs,
+    )
+except FileNotFoundError:
+    # If the file does not exist at the canonical location, we are most likely
+    # in a local installation of the package, so we can reference the data
+    # file in the R project. If this also fails, we allow the error to
+    # propagate
+    vars_dict = pd.read_csv(
+        os.path.join(
+            os.path.dirname(os.path.abspath(__file__)),
+            "..",
+            "..",
+            "data-raw",
+            "vars_dict.csv",
+        ),
+        **vars_dict_read_kwargs,
+    )
 
 # Prefix we use to identify variable name columns in the variable dictionary
 VAR_NAME_PREFIX = "var_name"

python/ccao/data/vars_dict.csv

@@ -34,9 +34,3 @@ Install the latest release of ``ccao`` from PyPI:
 .. code-block:: python
 
     pip install ccao
-
-You can also install the most recent code directly from GitHub:
-
-.. code-block:: python
-
-    pip install "git+https://github.com/ccao-data/ccao.git#egg=ccao&subdirectory=python"

python/ccao/vars_funs.py

@@ -2,7 +2,7 @@
 name = "ccao"
 version = "1.3.0"
 description = "Convenience Functions and Datasets for the Cook County Assessor's Office"
-readme = "README.md"
+readme = "docs/source/index.rst"
 requires-python = ">=3.9"
 authors = [
     {name = "Jean Cochrane", email="[email protected]"},