reep 0.0.1__tar.gz

reep-0.0.1/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+
+# Environments
+.venv/
+
+# Build output
+build/
+dist/
+
+# Tool caches and reports
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Local catalogue files used during development
+*.duckdb
+*.duckdb.wal

reep-0.0.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-12
+
+### Added
+
+- Package name reservation. The `reep` command prints where to get the register today.
+
+[Unreleased]: https://github.com/withqwerty/reep-python/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/withqwerty/reep-python/releases/tag/v0.0.1

reep-0.0.1/CITATION.cff

@@ -0,0 +1,17 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using these metadata."
+title: "reep: Python SDK and CLI for the Reep football entity register"
+type: software
+authors:
+  - name: "Withqwerty Ltd"
+    email: getintouch@withqwerty.com
+    website: "https://reep.football"
+repository-code: "https://github.com/withqwerty/reep-python"
+url: "https://reep.football"
+license: MIT
+version: 0.0.1
+keywords:
+  - football
+  - soccer
+  - entity resolution
+  - sports data

reep-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Withqwerty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reep-0.0.1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: reep
+Version: 0.0.1
+Summary: Python SDK and CLI for the Reep football entity register (in development)
+Project-URL: Homepage, https://reep.football
+Project-URL: Source, https://github.com/withqwerty/reep-python
+Project-URL: Issues, https://github.com/withqwerty/reep-python/issues
+Project-URL: Changelog, https://github.com/withqwerty/reep-python/blob/main/CHANGELOG.md
+Author-email: Withqwerty Ltd <getintouch@withqwerty.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crosswalk,entity-resolution,football,reep,soccer,sports-data
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# reep
+
+[![CI](https://github.com/withqwerty/reep-python/actions/workflows/ci.yml/badge.svg)](https://github.com/withqwerty/reep-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/reep)](https://pypi.org/project/reep/)
+[![Python versions](https://img.shields.io/pypi/pyversions/reep)](https://pypi.org/project/reep/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Python SDK and command-line tool for the [Reep Register](https://reep.football), the
+open crosswalk of football provider IDs.
+
+**Status: in development.** Version 0.0.1 reserves the package name and has no SDK
+functions yet. The first working release is 0.1.0. The [development plan](docs/plan.md)
+describes what it will do and in which order.
+
+## Use the register today
+
+- Download the complete release (CSV and DuckDB, CC0): <https://reep.football/downloads>
+- Hosted lookups with an API key: <https://reep.football/api>
+
+## What 0.1.0 will do
+
+- Download and verify a dated release, and keep it current from the release changelogs.
+- Resolve a provider ID, given as the full `(provider, namespace, external_id)` triple,
+  to its Reep ID, and follow merge redirects.
+- Translate an ID from one provider to another.
+- Give AI agents a stable interface: JSON output with a fixed envelope, documented exit
+  codes, and an MCP server.
+
+Later releases add a guarded sync of Reep IDs into your own Postgres, MySQL or SQL Server
+tables, with a report of the rows it could not resolve.
+
+## Reporting a wrong ID
+
+Data corrections (a wrong ID, a bad merge, a missing entity) go to
+<https://reep.football/submit>. Issues in this repository are for the SDK and CLI code.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). This project follows the
+[Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## Licences
+
+The code in this repository is [MIT-licensed](LICENSE). The Reep Register data is
+CC0-1.0.

reep-0.0.1/README.md

@@ -0,0 +1,45 @@
+# reep
+
+[![CI](https://github.com/withqwerty/reep-python/actions/workflows/ci.yml/badge.svg)](https://github.com/withqwerty/reep-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/reep)](https://pypi.org/project/reep/)
+[![Python versions](https://img.shields.io/pypi/pyversions/reep)](https://pypi.org/project/reep/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Python SDK and command-line tool for the [Reep Register](https://reep.football), the
+open crosswalk of football provider IDs.
+
+**Status: in development.** Version 0.0.1 reserves the package name and has no SDK
+functions yet. The first working release is 0.1.0. The [development plan](docs/plan.md)
+describes what it will do and in which order.
+
+## Use the register today
+
+- Download the complete release (CSV and DuckDB, CC0): <https://reep.football/downloads>
+- Hosted lookups with an API key: <https://reep.football/api>
+
+## What 0.1.0 will do
+
+- Download and verify a dated release, and keep it current from the release changelogs.
+- Resolve a provider ID, given as the full `(provider, namespace, external_id)` triple,
+  to its Reep ID, and follow merge redirects.
+- Translate an ID from one provider to another.
+- Give AI agents a stable interface: JSON output with a fixed envelope, documented exit
+  codes, and an MCP server.
+
+Later releases add a guarded sync of Reep IDs into your own Postgres, MySQL or SQL Server
+tables, with a report of the rows it could not resolve.
+
+## Reporting a wrong ID
+
+Data corrections (a wrong ID, a bad merge, a missing entity) go to
+<https://reep.football/submit>. Issues in this repository are for the SDK and CLI code.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). This project follows the
+[Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## Licences
+
+The code in this repository is [MIT-licensed](LICENSE). The Reep Register data is
+CC0-1.0.

reep-0.0.1/pyproject.toml

@@ -0,0 +1,137 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reep"
+version = "0.0.1"
+description = "Python SDK and CLI for the Reep football entity register (in development)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Withqwerty Ltd", email = "getintouch@withqwerty.com" }]
+keywords = ["football", "soccer", "entity-resolution", "crosswalk", "sports-data", "reep"]
+classifiers = [
+    "Development Status :: 1 - Planning",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://reep.football"
+Source = "https://github.com/withqwerty/reep-python"
+Issues = "https://github.com/withqwerty/reep-python/issues"
+Changelog = "https://github.com/withqwerty/reep-python/blob/main/CHANGELOG.md"
+
+[project.scripts]
+reep = "reep.cli:main"
+
+[dependency-groups]
+dev = [
+    { include-group = "lint" },
+    { include-group = "test" },
+    { include-group = "typecheck" },
+    "pre-commit>=4.3",
+]
+lint = ["ruff>=0.17"]
+test = ["pytest>=9", "pytest-cov>=7"]
+typecheck = ["mypy>=2", { include-group = "test" }]
+
+[tool.uv]
+required-version = ">=0.12"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/CHANGELOG.md", "/CITATION.cff", "/README.md", "/LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reep"]
+
+# --- ruff -------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.format]
+# The plan's API sketch uses aligned annotation comments.
+exclude = ["docs/plan.md"]
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # isort
+    "UP",       # pyupgrade
+    "B",        # flake8-bugbear
+    "C4",       # flake8-comprehensions
+    "SIM",      # flake8-simplify
+    "RET",      # flake8-return
+    "PTH",      # flake8-use-pathlib
+    "TC",       # flake8-type-checking
+    "PT",       # flake8-pytest-style
+    "S",        # flake8-bandit
+    "T20",      # flake8-print: library code does not print
+    "N",        # pep8-naming
+    "D",        # pydocstyle
+    "RUF",      # ruff-specific rules
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "S101"]
+"src/reep/cli.py" = ["T201"]
+
+# --- mypy -------------------------------------------------------------------
+
+[tool.mypy]
+strict = true
+warn_unreachable = true
+enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
+files = ["src", "tests"]
+
+# Lets editors that use Pyright or Pylance find the project environment.
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+# --- pytest and coverage ----------------------------------------------------
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers", "--strict-config", "-m", "not network"]
+markers = [
+    "network: calls the live Reep release or API (deselected by default; run with -m network)",
+]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["reep"]
+
+[tool.coverage.paths]
+source = ["src/reep", "*/site-packages/reep"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+skip_covered = true
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    'if __name__ == "__main__":',
+]

reep-0.0.1/src/reep/__init__.py

@@ -0,0 +1,16 @@
+"""Python SDK for the Reep football entity register.
+
+The SDK is in development. Version 0.0.1 reserves the package name; see
+https://reep.football for the register itself.
+"""
+
+import logging
+from importlib.metadata import version
+
+from reep.errors import ReepError
+
+__all__ = ["ReepError", "__version__"]
+
+__version__ = version("reep")
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

reep-0.0.1/src/reep/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m reep``."""
+
+from reep.cli import main
+
+raise SystemExit(main())

reep-0.0.1/src/reep/cli.py

@@ -0,0 +1,33 @@
+"""Command-line entry point for the ``reep`` command."""
+
+import argparse
+from collections.abc import Sequence
+
+from reep import __version__
+
+MESSAGE = f"""reep {__version__}: the v1 SDK and CLI are in development.
+
+Use the register today:
+  download  https://reep.football/downloads
+  API       https://reep.football/api
+"""
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the ``reep`` command.
+
+    Args:
+        argv: Command-line arguments without the program name. ``None`` reads
+            them from ``sys.argv``.
+
+    Returns:
+        The process exit code.
+    """
+    parser = argparse.ArgumentParser(
+        prog="reep",
+        description="Python SDK and CLI for the Reep football entity register.",
+    )
+    parser.add_argument("--version", action="version", version=f"reep {__version__}")
+    parser.parse_args(argv)
+    print(MESSAGE, end="")
+    return 0

reep-0.0.1/src/reep/errors.py

@@ -0,0 +1,10 @@
+"""Exceptions raised by the reep package."""
+
+__all__ = ["ReepError"]
+
+
+class ReepError(Exception):
+    """Base class for every error that the reep package raises.
+
+    Catch this class to handle any failure from the SDK in one place.
+    """

reep-0.0.1/tests/test_package.py

@@ -0,0 +1,56 @@
+import re
+import runpy
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+
+import pytest
+
+import reep
+from reep.cli import main
+
+
+def test_version_matches_distribution_metadata() -> None:
+    assert reep.__version__ == version("reep")
+
+
+def test_citation_version_matches_package_version() -> None:
+    citation = Path(__file__).parents[1] / "CITATION.cff"
+    match = re.search(r"^version:\s*(\S+)\s*$", citation.read_text(), re.MULTILINE)
+    assert match is not None
+    assert match.group(1) == reep.__version__
+
+
+def test_package_ships_type_information() -> None:
+    assert files("reep").joinpath("py.typed").is_file()
+
+
+def test_public_api_is_declared() -> None:
+    assert set(reep.__all__) == {"ReepError", "__version__"}
+    assert issubclass(reep.ReepError, Exception)
+
+
+def test_cli_prints_where_to_get_the_register(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    assert main([]) == 0
+    out = capsys.readouterr().out
+    assert f"reep {reep.__version__}" in out
+    assert "https://reep.football/downloads" in out
+
+
+def test_cli_version_flag(capsys: pytest.CaptureFixture[str]) -> None:
+    with pytest.raises(SystemExit) as exc:
+        main(["--version"])
+    assert exc.value.code == 0
+    assert capsys.readouterr().out.strip() == f"reep {reep.__version__}"
+
+
+def test_python_dash_m_runs_the_cli(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("sys.argv", ["reep"])
+    with pytest.raises(SystemExit) as exc:
+        runpy.run_module("reep", run_name="__main__")
+    assert exc.value.code == 0
+    assert "reep.football" in capsys.readouterr().out