yardage-hub 0.1.0__tar.gz

yardage_hub-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lukhed
+
+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.

yardage_hub-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: yardage_hub
+Version: 0.1.0
+Summary: Python client for the yardage-hub golf course API
+Home-page: https://github.com/lukhed/yardage-hub-python
+Author: lukhed
+Author-email: lukhed.mail@gmail.com
+Project-URL: Homepage, https://lukeheide.com/sports/yardage-hub
+Project-URL: Documentation, https://lukeheide.com/sports/yardage-hub/docs
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# yardage-hub-python
+
+A Python client for [yardage-hub](https://lukeheide.com/sports/yardage-hub), an open,
+crowdsourced database of golf courses: where they are, and their scorecards (holes, par,
+handicaps, tees, ratings, slopes, yardages). It starts from OpenStreetMap, and golfers fill in
+the rest.
+
+This README is a quick start. The full API documentation is at
+**[lukeheide.com/sports/yardage-hub/docs](https://lukeheide.com/sports/yardage-hub/docs)**.
+
+## Install
+
+```bash
+pip install yardage-hub
+```
+
+Python 3.9+, no dependencies.
+
+## Get a key
+
+Every call needs a key. Sign in at [lukeheide.com](https://lukeheide.com), open your profile
+page, and generate one. It's shown once, so copy it somewhere safe; if you lose it, regenerate it.
+Free keys allow 1,000 calls a day and 30 a minute.
+
+```python
+from yardage_hub import YardageHub
+
+hub = YardageHub("yh_...")   # or set YARDAGE_HUB_KEY and call YardageHub()
+```
+
+## Quick start
+
+```python
+# Find a course
+found = hub.search_courses("pebble beach", state="CA")
+course = hub.get_course(found["courses"][0]["id"])
+
+print(course["course_name"], course["par"])
+for tee in course["tee_sets"]:
+    print(tee["tee_name"], tee["yardage"], [(r["gender"], r["course_rating"], r["slope"]) for r in tee["ratings"]])
+for hole in course["holes_data"]:
+    print(hole["number"], hole["par"], hole["handicap_index"], hole["yardages"])
+
+# Courses near a point (km)
+near = hub.search_courses(lat=42.28, lon=-83.74, radius_km=10)
+
+# Courses that need help from contributors near you
+help = hub.courses_needing_help(lat=42.28, lon=-83.74, radius_km=25)
+for c in help["courses"]:
+    print(c["course_name"], [n["need"] for n in c["needs"]])
+```
+
+Name search forgives abbreviations, punctuation, and typos: "st johns", "mt pleasant", and
+"pebel beach" all find what you mean.
+
+## Methods
+
+| Method | What it does |
+|---|---|
+| `search_courses(q, state, lat, lon, radius_km, kinds, page, page_size)` | Search by name, state, or distance. `kinds` defaults to `["course", "par3"]`; also `practice`, `disc`, `mini` |
+| `get_course(course_id)` | One course: holes, tees and ratings, links, completeness. `None` for an unknown id |
+| `course_edits(course_id, page_size, contributor_ref)` | A course's edit history, newest first |
+| `courses_needing_help(state, lat, lon, radius_km, needs, page, page_size)` | Courses missing something a contributor can add, by state or near a point |
+| `submit_edit(course_id, payload, note, evidence_url, contributor_ref, contributor_name)` | Propose a change (contact details, holes, tees, ratings, yardages, scorecard link) |
+| `vote_edit(edit_id, vote, reason, contributor_ref, contributor_name)` | Back (`1`) or doubt (`-1`) a pending edit, or remove your vote (`0`) |
+| `report_link(course_id, field, url, works, contributor_ref, contributor_name)` | Confirm a `website` or `scorecard_url` works, or report it dead |
+| `report_course(course_id, kind, note, evidence_url, contributor_ref, contributor_name)` | Report a scorecard as `scorecard_changed`, `numbers_wrong`, or `other` |
+
+Each method returns the API's JSON as Python dicts and lists. The fields are described in the
+[docs](https://lukeheide.com/sports/yardage-hub/docs).
+
+## Writing: apply for write access
+
+Every key can read. The last four methods send data to a review queue, and a person reviews
+every edit, so they need a key with **write access**. New keys don't have it; a key without it
+gets a 403.
+
+1. **Contribute on the site first.** Suggest edits on course pages at
+   [lukeheide.com/sports/yardage-hub](https://lukeheide.com/sports/yardage-hub).
+2. **Once 5 of your edits are approved**, apply on your profile page. Say what you'll write, e.g.
+   "building an app that lets people suggest edits".
+3. **The maintainer reviews the application.** Once it's granted, your key can call the write
+   methods.
+
+Write access can be taken back. After a denial or revocation, you can apply again in 30 days.
+
+An edit looks like this:
+
+```python
+hub.submit_edit(course_id, {
+    "course": {"phone": "(415) 561-4661", "scorecard_url": "https://example.com/scorecard.pdf"},
+    "holes": [{"number": 1, "par": 4, "handicap": 7}],
+    "tees": [{"name": "Blue", "color": "blue", "gender": "M", "rating": 70.8, "slope": 132,
+              "yardages": {"1": 512, "2": 410}}],
+}, note="From the 2026 scorecard")
+```
+
+It's validated right away (a bad payload raises a 400) and waits as `pending` until it's
+reviewed.
+
+## Errors
+
+A failed call raises `YardageHubError`, with `status`, `message`, and `retry_after` (seconds,
+after a 429):
+
+```python
+from yardage_hub import YardageHubError
+
+try:
+    hub.submit_edit(course_id, {"course": {"phone": "555-0100"}})
+except YardageHubError as e:
+    if e.status == 403:
+        print("This key is read-only: apply for write access on your profile page")
+    elif e.status == 429:
+        print(f"Over a limit; retry in {e.retry_after} s")
+    else:
+        raise
+```
+
+| Status | Meaning |
+|---|---|
+| 400 | Invalid input; the message says what |
+| 401 | Missing, wrong, or revoked key |
+| 403 | A read-only key tried to write |
+| 404 | Unknown course or edit |
+| 429 | Over the daily or per-minute limit |
+
+## Data and license
+
+The data contains information from OpenStreetMap, © OpenStreetMap contributors, and is available
+under the [ODbL](https://opendatacommons.org/licenses/odbl/1-0/). Credit it wherever you show
+it: "© OpenStreetMap contributors, yardage-hub". For the whole dataset, download the weekly
+snapshots from [lukhed/yardage-hub-data](https://github.com/lukhed/yardage-hub-data); please
+don't harvest it through the API.
+
+This client is MIT licensed.

yardage_hub-0.1.0/README.md

@@ -0,0 +1,136 @@
+# yardage-hub-python
+
+A Python client for [yardage-hub](https://lukeheide.com/sports/yardage-hub), an open,
+crowdsourced database of golf courses: where they are, and their scorecards (holes, par,
+handicaps, tees, ratings, slopes, yardages). It starts from OpenStreetMap, and golfers fill in
+the rest.
+
+This README is a quick start. The full API documentation is at
+**[lukeheide.com/sports/yardage-hub/docs](https://lukeheide.com/sports/yardage-hub/docs)**.
+
+## Install
+
+```bash
+pip install yardage-hub
+```
+
+Python 3.9+, no dependencies.
+
+## Get a key
+
+Every call needs a key. Sign in at [lukeheide.com](https://lukeheide.com), open your profile
+page, and generate one. It's shown once, so copy it somewhere safe; if you lose it, regenerate it.
+Free keys allow 1,000 calls a day and 30 a minute.
+
+```python
+from yardage_hub import YardageHub
+
+hub = YardageHub("yh_...")   # or set YARDAGE_HUB_KEY and call YardageHub()
+```
+
+## Quick start
+
+```python
+# Find a course
+found = hub.search_courses("pebble beach", state="CA")
+course = hub.get_course(found["courses"][0]["id"])
+
+print(course["course_name"], course["par"])
+for tee in course["tee_sets"]:
+    print(tee["tee_name"], tee["yardage"], [(r["gender"], r["course_rating"], r["slope"]) for r in tee["ratings"]])
+for hole in course["holes_data"]:
+    print(hole["number"], hole["par"], hole["handicap_index"], hole["yardages"])
+
+# Courses near a point (km)
+near = hub.search_courses(lat=42.28, lon=-83.74, radius_km=10)
+
+# Courses that need help from contributors near you
+help = hub.courses_needing_help(lat=42.28, lon=-83.74, radius_km=25)
+for c in help["courses"]:
+    print(c["course_name"], [n["need"] for n in c["needs"]])
+```
+
+Name search forgives abbreviations, punctuation, and typos: "st johns", "mt pleasant", and
+"pebel beach" all find what you mean.
+
+## Methods
+
+| Method | What it does |
+|---|---|
+| `search_courses(q, state, lat, lon, radius_km, kinds, page, page_size)` | Search by name, state, or distance. `kinds` defaults to `["course", "par3"]`; also `practice`, `disc`, `mini` |
+| `get_course(course_id)` | One course: holes, tees and ratings, links, completeness. `None` for an unknown id |
+| `course_edits(course_id, page_size, contributor_ref)` | A course's edit history, newest first |
+| `courses_needing_help(state, lat, lon, radius_km, needs, page, page_size)` | Courses missing something a contributor can add, by state or near a point |
+| `submit_edit(course_id, payload, note, evidence_url, contributor_ref, contributor_name)` | Propose a change (contact details, holes, tees, ratings, yardages, scorecard link) |
+| `vote_edit(edit_id, vote, reason, contributor_ref, contributor_name)` | Back (`1`) or doubt (`-1`) a pending edit, or remove your vote (`0`) |
+| `report_link(course_id, field, url, works, contributor_ref, contributor_name)` | Confirm a `website` or `scorecard_url` works, or report it dead |
+| `report_course(course_id, kind, note, evidence_url, contributor_ref, contributor_name)` | Report a scorecard as `scorecard_changed`, `numbers_wrong`, or `other` |
+
+Each method returns the API's JSON as Python dicts and lists. The fields are described in the
+[docs](https://lukeheide.com/sports/yardage-hub/docs).
+
+## Writing: apply for write access
+
+Every key can read. The last four methods send data to a review queue, and a person reviews
+every edit, so they need a key with **write access**. New keys don't have it; a key without it
+gets a 403.
+
+1. **Contribute on the site first.** Suggest edits on course pages at
+   [lukeheide.com/sports/yardage-hub](https://lukeheide.com/sports/yardage-hub).
+2. **Once 5 of your edits are approved**, apply on your profile page. Say what you'll write, e.g.
+   "building an app that lets people suggest edits".
+3. **The maintainer reviews the application.** Once it's granted, your key can call the write
+   methods.
+
+Write access can be taken back. After a denial or revocation, you can apply again in 30 days.
+
+An edit looks like this:
+
+```python
+hub.submit_edit(course_id, {
+    "course": {"phone": "(415) 561-4661", "scorecard_url": "https://example.com/scorecard.pdf"},
+    "holes": [{"number": 1, "par": 4, "handicap": 7}],
+    "tees": [{"name": "Blue", "color": "blue", "gender": "M", "rating": 70.8, "slope": 132,
+              "yardages": {"1": 512, "2": 410}}],
+}, note="From the 2026 scorecard")
+```
+
+It's validated right away (a bad payload raises a 400) and waits as `pending` until it's
+reviewed.
+
+## Errors
+
+A failed call raises `YardageHubError`, with `status`, `message`, and `retry_after` (seconds,
+after a 429):
+
+```python
+from yardage_hub import YardageHubError
+
+try:
+    hub.submit_edit(course_id, {"course": {"phone": "555-0100"}})
+except YardageHubError as e:
+    if e.status == 403:
+        print("This key is read-only: apply for write access on your profile page")
+    elif e.status == 429:
+        print(f"Over a limit; retry in {e.retry_after} s")
+    else:
+        raise
+```
+
+| Status | Meaning |
+|---|---|
+| 400 | Invalid input; the message says what |
+| 401 | Missing, wrong, or revoked key |
+| 403 | A read-only key tried to write |
+| 404 | Unknown course or edit |
+| 429 | Over the daily or per-minute limit |
+
+## Data and license
+
+The data contains information from OpenStreetMap, © OpenStreetMap contributors, and is available
+under the [ODbL](https://opendatacommons.org/licenses/odbl/1-0/). Credit it wherever you show
+it: "© OpenStreetMap contributors, yardage-hub". For the whole dataset, download the weekly
+snapshots from [lukhed/yardage-hub-data](https://github.com/lukhed/yardage-hub-data); please
+don't harvest it through the API.
+
+This client is MIT licensed.

yardage_hub-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

yardage_hub-0.1.0/setup.py

@@ -0,0 +1,25 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="yardage_hub",
+    version="0.1.0",
+    description="Python client for the yardage-hub golf course API",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="lukhed",
+    author_email="lukhed.mail@gmail.com",
+    url="https://github.com/lukhed/yardage-hub-python",
+    project_urls={
+        "Homepage": "https://lukeheide.com/sports/yardage-hub",
+        "Documentation": "https://lukeheide.com/sports/yardage-hub/docs",
+    },
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
+    python_requires=">=3.9",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    install_requires=[],
+)

yardage_hub-0.1.0/src/yardage_hub/__init__.py

@@ -0,0 +1,6 @@
+"""Python client for the yardage-hub golf course API."""
+
+from .client import BASE_URL, DOCS_URL, YardageHub, YardageHubError
+
+__all__ = ["YardageHub", "YardageHubError", "BASE_URL", "DOCS_URL"]
+__version__ = "0.1.0"

yardage_hub-0.1.0/src/yardage_hub/client.py

@@ -0,0 +1,117 @@
+"""A thin client for the yardage-hub public API: one method per route, returning the JSON."""
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+BASE_URL = "https://yardage-hub.lukhed.workers.dev/v1"
+DOCS_URL = "https://lukeheide.com/sports/yardage-hub/docs"
+
+
+class YardageHubError(Exception):
+    """An error response from the API.
+
+    `status` is the HTTP status (401 bad key, 403 read-only key, 404 unknown course, 429 over a
+    limit, ...), `message` the API's explanation, and `retry_after` the seconds to wait after a 429.
+    """
+
+    def __init__(self, status, message, retry_after=None):
+        super().__init__(f"{status}: {message}")
+        self.status = status
+        self.message = message
+        self.retry_after = int(retry_after) if retry_after and str(retry_after).isdigit() else None
+
+
+class YardageHub:
+    """Calls the yardage-hub API with your key.
+
+    `key` defaults to the YARDAGE_HUB_KEY environment variable. Get a key from your profile page at
+    lukeheide.com.
+    """
+
+    def __init__(self, key=None, base_url=BASE_URL, timeout=30):
+        self.key = key or os.environ.get("YARDAGE_HUB_KEY")
+        if not self.key:
+            raise ValueError(f"pass key= or set YARDAGE_HUB_KEY; get a key at {DOCS_URL}")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    # ── Reads ────────────────────────────────────────────────────────────────
+
+    def search_courses(self, q=None, state=None, lat=None, lon=None, radius_km=None, kinds=None,
+                       page=None, page_size=None):
+        """Search courses by name, state, or distance. Give at least one of q, state, or lat and lon.
+        Returns { total, page, page_size, courses }."""
+        return self._get("/courses", q=q, state=state, lat=lat, lon=lon, radius_km=radius_km,
+                         kinds=kinds, page=page, page_size=page_size)
+
+    def get_course(self, course_id):
+        """One course with its holes, tees, ratings, and links. None for an unknown id."""
+        return self._get(f"/courses/{course_id}")
+
+    def course_edits(self, course_id, page_size=None, contributor_ref=None):
+        """A course's edit history, newest first."""
+        return self._get(f"/courses/{course_id}/edits", page_size=page_size, contributor_ref=contributor_ref)
+
+    def courses_needing_help(self, state=None, lat=None, lon=None, radius_km=None, needs=None,
+                             page=None, page_size=None):
+        """Courses where a contributor can help, by state or near a point. With no area, a sample.
+        Returns { total, page, page_size, courses, counts } (or { sample, page_size, courses })."""
+        return self._get("/help", state=state, lat=lat, lon=lon, radius_km=radius_km, needs=needs,
+                         page=page, page_size=page_size)
+
+    # ── Writes (need a key with write access) ────────────────────────────────
+
+    def submit_edit(self, course_id, payload, note=None, evidence_url=None, contributor_ref=None,
+                    contributor_name=None):
+        """Propose a change to a course. It waits for review. Returns { id, status }."""
+        return self._post(f"/courses/{course_id}/edits", payload=payload, note=note,
+                          evidence_url=evidence_url, contributor_ref=contributor_ref,
+                          contributor_name=contributor_name)
+
+    def vote_edit(self, edit_id, vote, reason=None, contributor_ref=None, contributor_name=None):
+        """Back (1) or doubt (-1) a pending edit, or remove your vote (0). Returns { up, down, my_vote }."""
+        return self._post(f"/edits/{edit_id}/votes", vote=vote, reason=reason,
+                          contributor_ref=contributor_ref, contributor_name=contributor_name)
+
+    def report_link(self, course_id, field, url, works, contributor_ref=None, contributor_name=None):
+        """Confirm a course link works or report it dead. `field` is "scorecard_url" or "website",
+        and `url` its current value. Returns the link's status."""
+        return self._post(f"/courses/{course_id}/link-reports", field=field, url=url, works=works,
+                          contributor_ref=contributor_ref, contributor_name=contributor_name)
+
+    def report_course(self, course_id, kind, note=None, evidence_url=None, contributor_ref=None,
+                      contributor_name=None):
+        """Report a course's scorecard as wrong or out of date. `kind` is "scorecard_changed",
+        "numbers_wrong", or "other" (needs a note)."""
+        return self._post(f"/courses/{course_id}/reports", kind=kind, note=note, evidence_url=evidence_url,
+                          contributor_ref=contributor_ref, contributor_name=contributor_name)
+
+    # ── HTTP ─────────────────────────────────────────────────────────────────
+
+    def _get(self, path, **params):
+        query = {k: ",".join(v) if isinstance(v, (list, tuple)) else v
+                 for k, v in params.items() if v is not None}
+        url = self.base_url + path + ("?" + urllib.parse.urlencode(query) if query else "")
+        return self._send(urllib.request.Request(url, method="GET"))
+
+    def _post(self, path, **fields):
+        body = json.dumps({k: v for k, v in fields.items() if v is not None}).encode()
+        req = urllib.request.Request(self.base_url + path, data=body, method="POST")
+        req.add_header("Content-Type", "application/json")
+        return self._send(req)
+
+    def _send(self, req):
+        req.add_header("x-yardage-key", self.key)
+        req.add_header("User-Agent", "yardage-hub-python")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read() or b"null")
+        except urllib.error.HTTPError as e:
+            try:
+                message = json.loads(e.read() or b"{}").get("message") or e.reason
+            except ValueError:
+                message = e.reason
+            raise YardageHubError(e.code, message, e.headers.get("Retry-After")) from None

yardage_hub-0.1.0/src/yardage_hub.egg-info/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: yardage_hub
+Version: 0.1.0
+Summary: Python client for the yardage-hub golf course API
+Home-page: https://github.com/lukhed/yardage-hub-python
+Author: lukhed
+Author-email: lukhed.mail@gmail.com
+Project-URL: Homepage, https://lukeheide.com/sports/yardage-hub
+Project-URL: Documentation, https://lukeheide.com/sports/yardage-hub/docs
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+# yardage-hub-python
+
+A Python client for [yardage-hub](https://lukeheide.com/sports/yardage-hub), an open,
+crowdsourced database of golf courses: where they are, and their scorecards (holes, par,
+handicaps, tees, ratings, slopes, yardages). It starts from OpenStreetMap, and golfers fill in
+the rest.
+
+This README is a quick start. The full API documentation is at
+**[lukeheide.com/sports/yardage-hub/docs](https://lukeheide.com/sports/yardage-hub/docs)**.
+
+## Install
+
+```bash
+pip install yardage-hub
+```
+
+Python 3.9+, no dependencies.
+
+## Get a key
+
+Every call needs a key. Sign in at [lukeheide.com](https://lukeheide.com), open your profile
+page, and generate one. It's shown once, so copy it somewhere safe; if you lose it, regenerate it.
+Free keys allow 1,000 calls a day and 30 a minute.
+
+```python
+from yardage_hub import YardageHub
+
+hub = YardageHub("yh_...")   # or set YARDAGE_HUB_KEY and call YardageHub()
+```
+
+## Quick start
+
+```python
+# Find a course
+found = hub.search_courses("pebble beach", state="CA")
+course = hub.get_course(found["courses"][0]["id"])
+
+print(course["course_name"], course["par"])
+for tee in course["tee_sets"]:
+    print(tee["tee_name"], tee["yardage"], [(r["gender"], r["course_rating"], r["slope"]) for r in tee["ratings"]])
+for hole in course["holes_data"]:
+    print(hole["number"], hole["par"], hole["handicap_index"], hole["yardages"])
+
+# Courses near a point (km)
+near = hub.search_courses(lat=42.28, lon=-83.74, radius_km=10)
+
+# Courses that need help from contributors near you
+help = hub.courses_needing_help(lat=42.28, lon=-83.74, radius_km=25)
+for c in help["courses"]:
+    print(c["course_name"], [n["need"] for n in c["needs"]])
+```
+
+Name search forgives abbreviations, punctuation, and typos: "st johns", "mt pleasant", and
+"pebel beach" all find what you mean.
+
+## Methods
+
+| Method | What it does |
+|---|---|
+| `search_courses(q, state, lat, lon, radius_km, kinds, page, page_size)` | Search by name, state, or distance. `kinds` defaults to `["course", "par3"]`; also `practice`, `disc`, `mini` |
+| `get_course(course_id)` | One course: holes, tees and ratings, links, completeness. `None` for an unknown id |
+| `course_edits(course_id, page_size, contributor_ref)` | A course's edit history, newest first |
+| `courses_needing_help(state, lat, lon, radius_km, needs, page, page_size)` | Courses missing something a contributor can add, by state or near a point |
+| `submit_edit(course_id, payload, note, evidence_url, contributor_ref, contributor_name)` | Propose a change (contact details, holes, tees, ratings, yardages, scorecard link) |
+| `vote_edit(edit_id, vote, reason, contributor_ref, contributor_name)` | Back (`1`) or doubt (`-1`) a pending edit, or remove your vote (`0`) |
+| `report_link(course_id, field, url, works, contributor_ref, contributor_name)` | Confirm a `website` or `scorecard_url` works, or report it dead |
+| `report_course(course_id, kind, note, evidence_url, contributor_ref, contributor_name)` | Report a scorecard as `scorecard_changed`, `numbers_wrong`, or `other` |
+
+Each method returns the API's JSON as Python dicts and lists. The fields are described in the
+[docs](https://lukeheide.com/sports/yardage-hub/docs).
+
+## Writing: apply for write access
+
+Every key can read. The last four methods send data to a review queue, and a person reviews
+every edit, so they need a key with **write access**. New keys don't have it; a key without it
+gets a 403.
+
+1. **Contribute on the site first.** Suggest edits on course pages at
+   [lukeheide.com/sports/yardage-hub](https://lukeheide.com/sports/yardage-hub).
+2. **Once 5 of your edits are approved**, apply on your profile page. Say what you'll write, e.g.
+   "building an app that lets people suggest edits".
+3. **The maintainer reviews the application.** Once it's granted, your key can call the write
+   methods.
+
+Write access can be taken back. After a denial or revocation, you can apply again in 30 days.
+
+An edit looks like this:
+
+```python
+hub.submit_edit(course_id, {
+    "course": {"phone": "(415) 561-4661", "scorecard_url": "https://example.com/scorecard.pdf"},
+    "holes": [{"number": 1, "par": 4, "handicap": 7}],
+    "tees": [{"name": "Blue", "color": "blue", "gender": "M", "rating": 70.8, "slope": 132,
+              "yardages": {"1": 512, "2": 410}}],
+}, note="From the 2026 scorecard")
+```
+
+It's validated right away (a bad payload raises a 400) and waits as `pending` until it's
+reviewed.
+
+## Errors
+
+A failed call raises `YardageHubError`, with `status`, `message`, and `retry_after` (seconds,
+after a 429):
+
+```python
+from yardage_hub import YardageHubError
+
+try:
+    hub.submit_edit(course_id, {"course": {"phone": "555-0100"}})
+except YardageHubError as e:
+    if e.status == 403:
+        print("This key is read-only: apply for write access on your profile page")
+    elif e.status == 429:
+        print(f"Over a limit; retry in {e.retry_after} s")
+    else:
+        raise
+```
+
+| Status | Meaning |
+|---|---|
+| 400 | Invalid input; the message says what |
+| 401 | Missing, wrong, or revoked key |
+| 403 | A read-only key tried to write |
+| 404 | Unknown course or edit |
+| 429 | Over the daily or per-minute limit |
+
+## Data and license
+
+The data contains information from OpenStreetMap, © OpenStreetMap contributors, and is available
+under the [ODbL](https://opendatacommons.org/licenses/odbl/1-0/). Credit it wherever you show
+it: "© OpenStreetMap contributors, yardage-hub". For the whole dataset, download the weekly
+snapshots from [lukhed/yardage-hub-data](https://github.com/lukhed/yardage-hub-data); please
+don't harvest it through the API.
+
+This client is MIT licensed.

yardage_hub-0.1.0/src/yardage_hub.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+setup.py
+src/yardage_hub/__init__.py
+src/yardage_hub/client.py
+src/yardage_hub.egg-info/PKG-INFO
+src/yardage_hub.egg-info/SOURCES.txt
+src/yardage_hub.egg-info/dependency_links.txt
+src/yardage_hub.egg-info/top_level.txt
+tests/test_client.py

yardage_hub-0.1.0/src/yardage_hub.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

yardage_hub-0.1.0/src/yardage_hub.egg-info/top_level.txt

@@ -0,0 +1 @@
+yardage_hub

yardage_hub-0.1.0/tests/test_client.py

@@ -0,0 +1,97 @@
+"""The client builds the right request for each route and turns errors into YardageHubError.
+No network: urlopen is replaced. `python -m unittest` from the repo root."""
+
+import io
+import json
+import sys
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from yardage_hub import YardageHub, YardageHubError  # noqa: E402
+
+BASE = "https://yardage-hub.lukhed.workers.dev/v1"
+ID = "3f2c9a1e-0000-4000-8000-000000000001"
+
+
+class Response(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+class ClientTest(unittest.TestCase):
+    def setUp(self):
+        self.sent = []
+        self.reply = {"ok": True}
+
+        def urlopen(req, timeout):
+            self.sent.append(req)
+            return Response(json.dumps(self.reply).encode())
+
+        patcher = mock.patch("urllib.request.urlopen", urlopen)
+        patcher.start()
+        self.addCleanup(patcher.stop)
+        self.hub = YardageHub("yh_test")
+
+    def last(self):
+        req = self.sent[-1]
+        body = json.loads(req.data) if req.data else None
+        return req.get_method(), req.full_url, body
+
+    def test_reads_are_gets_with_a_query_string(self):
+        self.hub.search_courses("presidio", state="CA", kinds=["course", "par3"], page_size=5)
+        self.assertEqual(self.last(), ("GET", f"{BASE}/courses?q=presidio&state=CA&kinds=course%2Cpar3&page_size=5", None))
+        self.hub.get_course(ID)
+        self.assertEqual(self.last()[:2], ("GET", f"{BASE}/courses/{ID}"))
+        self.hub.course_edits(ID, page_size=10)
+        self.assertEqual(self.last()[1], f"{BASE}/courses/{ID}/edits?page_size=10")
+        self.hub.courses_needing_help(lat=42.28, lon=-83.74, radius_km=25, needs=["no_website"])
+        self.assertEqual(self.last()[1], f"{BASE}/help?lat=42.28&lon=-83.74&radius_km=25&needs=no_website")
+        self.hub.courses_needing_help()
+        self.assertEqual(self.last()[1], f"{BASE}/help")
+
+    def test_writes_post_json_without_unset_fields(self):
+        self.hub.submit_edit(ID, {"course": {"phone": "555"}}, note="from the card")
+        self.assertEqual(self.last(), ("POST", f"{BASE}/courses/{ID}/edits",
+                                       {"payload": {"course": {"phone": "555"}}, "note": "from the card"}))
+        self.hub.vote_edit(ID, 1)
+        self.assertEqual(self.last(), ("POST", f"{BASE}/edits/{ID}/votes", {"vote": 1}))
+        self.hub.report_link(ID, "website", "https://a.example/", False)
+        self.assertEqual(self.last()[2], {"field": "website", "url": "https://a.example/", "works": False})
+        self.hub.report_course(ID, "numbers_wrong", note="hole 4")
+        self.assertEqual(self.last()[1:], (f"{BASE}/courses/{ID}/reports", {"kind": "numbers_wrong", "note": "hole 4"}))
+
+    def test_every_call_carries_the_key(self):
+        self.hub.get_course(ID)
+        self.assertEqual(self.sent[-1].get_header("X-yardage-key"), "yh_test")
+
+    def test_returns_the_json(self):
+        self.reply = {"total": 1, "courses": []}
+        self.assertEqual(self.hub.search_courses("x"), {"total": 1, "courses": []})
+
+    def test_errors_carry_status_message_and_retry_after(self):
+        def refuse(req, timeout):
+            raise urllib.error.HTTPError(req.full_url, 429, "Too Many Requests", {"Retry-After": "30"},
+                                         io.BytesIO(b'{"message": "daily quota used; resets at 00:00 UTC"}'))
+
+        with mock.patch("urllib.request.urlopen", refuse):
+            with self.assertRaises(YardageHubError) as e:
+                self.hub.search_courses("x")
+        self.assertEqual((e.exception.status, e.exception.retry_after), (429, 30))
+        self.assertIn("daily quota", e.exception.message)
+
+    def test_needs_a_key(self):
+        with mock.patch.dict("os.environ", {}, clear=True):
+            self.assertRaises(ValueError, YardageHub)
+        with mock.patch.dict("os.environ", {"YARDAGE_HUB_KEY": "yh_env"}):
+            self.assertEqual(YardageHub().key, "yh_env")
+
+
+if __name__ == "__main__":
+    unittest.main()