Modernize scaffolding and complete type hints

Author: DavidMStraub

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      github-actions:
+        patterns:
+          - '*'

.github/workflows/pypi.yml

@@ -1,27 +1,54 @@
 name: PyPI deploy
+
 on:
   release:
     types:
-      - created
+      - published
+
+permissions:
+  contents: read
 
 jobs:
-  build-and-publish:
+  build:
+    name: build distributions
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: [3.13]
-
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v5
         with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: python -m pip install --upgrade pip setuptools wheel build
-      - name: Create the source distribution
+          # setuptools-scm needs the full history and tags to derive the version
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install build dependencies
+        run: python -m pip install --upgrade pip build twine
+      - name: Build sdist and wheel
         run: python -m build
-      - name: Publish distribution to PyPI
-        uses: pypa/gh-action-pypi-publish@master
+      - name: Check distributions
+        run: python -m twine check --strict dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
         with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gedcom7
+    permissions:
+      # required for PyPI trusted publishing (OIDC); no API token needed
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yml

@@ -1,31 +1,69 @@
-name: unit tests
+name: tests
 
 on:
   push:
     branches:
       - main
   pull_request:
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
-  build:
+  lint:
+    name: lint and type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          # setuptools-scm derives the version from tags
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          cache: pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --group dev .
+      - name: Lint
+        run: ruff check --output-format=github .
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Static type check
+        run: mypy
+
+  test:
+    name: test on Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
     steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install Python dependencies
+          cache: pip
+      - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip wheel
-          pip install pytest mypy
-          pip install .
-      - name: Static type check
-        run: |
-          mypy gedcom7
+          python -m pip install --upgrade pip
+          pip install --group dev .
       - name: Test with pytest
-        run: |
-          pytest
+        run: pytest --cov=gedcom7 --cov-report=term-missing --cov-report=xml
+      - name: Upload coverage report
+        if: matrix.python-version == '3.13'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+          if-no-files-found: error

.gitignore

@@ -127,3 +127,9 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# Ruff
+.ruff_cache/
+
+# pytest-benchmark
+.benchmarks/

README.md

@@ -1,5 +1,10 @@
 # gedcom7
 
+[![Tests](https://github.com/DavidMStraub/python-gedcom7/actions/workflows/test.yml/badge.svg)](https://github.com/DavidMStraub/python-gedcom7/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/gedcom7)](https://pypi.org/project/gedcom7/)
+[![Python versions](https://img.shields.io/pypi/pyversions/gedcom7)](https://pypi.org/project/gedcom7/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
 A [GEDCOM 7](https://gedcom.io/) parser for Python.
 
 ## Background
@@ -23,6 +28,31 @@ with open("my_gedcom.ged", "r", encoding="utf-8") as f:
 records = gedcom7.loads(string)
 ```
 
+## Development
+
+Install the package together with the development dependencies:
+
+```
+python -m pip install --group dev --editable .
+```
+
+Then run the checks:
+
+```
+pytest          # tests
+mypy            # static type check (strict)
+ruff check .    # lint
+ruff format .   # format
+```
+
+## Releasing
+
+The version is derived from git tags by
+[setuptools-scm](https://setuptools-scm.readthedocs.io/); there is no version
+string in the source tree. To release, push a `vX.Y.Z` tag and publish a GitHub
+release for it — the `PyPI deploy` workflow builds the distributions and
+uploads them via PyPI trusted publishing.
+
 ## Credits
 
 Inspiration was drawn from the [Javascript parser](https://github.com/gedcom7code/js-parser).

gedcom7/__init__.py

@@ -1,5 +1,12 @@
 """Base module for gedcom7."""
 
+from importlib.metadata import PackageNotFoundError, version
+
 from .parser import loads
 
-__version__ = "0.4.1"
+__all__ = ["loads"]
+
+try:
+    __version__ = version("gedcom7")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0.dev0"

gedcom7/cast.py

@@ -12,6 +12,7 @@
 
 
 def cast_value(text: str, type_id: str) -> types.DataType | None:
+    """Cast a payload string to the data type appropriate for its structure type."""
     if not text:
         return None
     payload = const.payloads.get(type_id)
@@ -38,16 +39,16 @@ def _cast_integer(value: str) -> int:
     """Cast a string to an integer."""
     try:
         return int(value)
-    except ValueError:
-        raise ValueError(f"Cannot interpret {value} as integer")
+    except ValueError as exc:
+        raise ValueError(f"Cannot interpret {value} as integer") from exc
 
 
 def _cast_list_text(value: str) -> list[str]:
     """Cast a string to a list of strings."""
     return [el.strip() for el in value.split(",")]
 
 
-def _match(text: str, regex: str, type_name: str) -> re.Match:
+def _match(text: str, regex: str, type_name: str) -> re.Match[str]:
     """Match a string and raise if not compatible."""
     match = re.fullmatch(regex, text)
     if not match:
@@ -70,7 +71,8 @@ def _cast_time(value: str) -> types.Time:
     """Cast a string to a Time."""
     match = _match(value, grammar.time, "Time")
     return types.Time(
-        tz=match.group("tz"),
+        # the tz group is `(?P<tz>Z)?`, so it is either "Z" or absent
+        tz="Z" if match.group("tz") else None,
         hour=int(match.group("hour")),
         minute=int(match.group("minute")),
         second=int(match.group("second")) if match.group("second") else None,

gedcom7/parser.py

@@ -2,7 +2,7 @@
 
 import re
 
-from . import cast, const, grammar
+from . import const, grammar
 from .types import GedcomStructure
 
 

gedcom7/py.typed

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Literal, Union
+from typing import Literal
 
 from . import cast, const
 
@@ -16,8 +16,8 @@ class GedcomStructure:
     pointer: str
     text: str
     xref: str
-    children: list["GedcomStructure"] = field(default_factory=list)
-    parent: "GedcomStructure | None" = None
+    children: list[GedcomStructure] = field(default_factory=list)
+    parent: GedcomStructure | None = None
 
     @property
     def type_id(self) -> str:
@@ -32,18 +32,19 @@ def type_id(self) -> str:
             return const.substructures[""][self.tag]
         return const.substructures[self.parent.type_id][self.tag]
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         """Post-init steps: set parent on children."""
         for child in self.children:
             child.parent = self
 
-    def append_child(self, child: "GedcomStructure") -> None:
+    def append_child(self, child: GedcomStructure) -> None:
         """Append a child to the structure and set the child's parent to self."""
         child.parent = self
         self.children.append(child)
 
     @property
-    def value(self) -> "DataType | None":
+    def value(self) -> DataType | None:
+        """Get the payload cast to its appropriate data type."""
         return cast.cast_value(text=self.text, type_id=self.type_id)
 
 
@@ -130,24 +131,19 @@ class DateRange:
     end: Date | None = None
 
 
-DateValue = Union[
-    Date,
-    DatePeriod,
-    DateApprox,
-    DateRange,
-]
-
-DataType = Union[
-    str,
-    int,
-    list[str],
-    PersonalName,
-    Time,
-    Age,
-    MediaType,
-    DateExact,
-    DateApprox,
-    DateRange,
-    DatePeriod,
-    DateValue,
-]
+DateValue = Date | DatePeriod | DateApprox | DateRange
+
+DataType = (
+    str
+    | int
+    | list[str]
+    | PersonalName
+    | Time
+    | Age
+    | MediaType
+    | DateExact
+    | DateApprox
+    | DateRange
+    | DatePeriod
+    | DateValue
+)