Skip to content

Add an export formats page (1.13.81) - #21

Merged
bensynapse merged 2 commits into
mainfrom
docs/export-formats
Nov 11, 2026
Merged

bensynapse merged 2 commits into
mainfrom
docs/export-formats

Conversation

@bensynapse

@bensynapse bensynapse commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Adds docs/export-formats.html, a guide to exporting tennis data to CSV, JSON Lines or Parquet with livetennisapi-export 0.1.0. Spec version 1.13.81, with a changelog entry. Nothing on the wire changed.

What is on the page

  • When each of the three formats fits, and which file names pick it.
  • The six datasets (matches, fixtures, players, player, rankings, tournaments) with the endpoint each reads and the plan each needs. The plans are the package's, and the History wording for matches follows the spec.
  • Paging: pages of 200 rows, meta.has_more, --max-rows and --page-size. player sends one request for each id.
  • How nested fields become dotted columns, with a worked row and column names the spec documents.
  • When the file is written: nothing until every page has arrived, and a refused API key writes no file.
  • Read-back examples for pandas, DuckDB and R, and the Python API.

The page is a guide in GUIDES, built like ai-sdk.html and errors-and-rate-limits.html. It adds no new component. Two cells carry white-space:nowrap so a short code word is not split across lines.

Where the facts come from

Every statement was read from the package source (datasets.py, writers.py, cli.py) and its tests. The published 0.1.0 wheel is identical to the repository's src/.

A new check, _export_drift, stops the build in three cases. One is a dataset endpoint the spec does not define. Another is a page size that differs from the spec's limit maximum. The last is a listed column the spec's schema for that endpoint does not document.

Examples, run before publishing

I had no API key, so nothing called the live API. The package's own writers wrote sample files from its test fixtures. I then ran the code blocks taken from the built page against those files.

Example Run with Result
pandas pandas 3.1.1, pyarrow 26.0.1 reads the Parquet and CSV files, decodes score.sets
DuckDB DuckDB 2.0.0 all four queries return rows
R R 4.6.2, arrow 26.0.1, jsonlite reads the CSV and Parquet files, decodes score.sets
worked row write_csv from the package gives the six columns and values the page shows

Checks run

  • python scripts/build_reference.py --check: generated docs are current
  • sh scripts/truthcheck.sh: truthcheck OK
  • the contract script from lint.yml: OK, 48 paths, 49 operations, 66 schemas
  • npx @redocly/cli@latest lint openapi.yaml: valid
  • the builder's own gates pass: title and description budgets, JSON-LD, heading order, index links
  • every link on the page answers 200, apart from the page's own canonical URL, which is not published yet
  • at 360 px and at 1280 px the page has no horizontal overflow

The README's table of packages gains a row for the export package.

The page copy, the changelog entry and this text were linted with hw_lint.py.

After merge

The page goes live at https://docs.livetennisapi.com/export-formats.html once the docs are published again from main. PRs #15 and #16 also change scripts/build_reference.py, and #15 changes docs/index.html. Whichever merges later needs a rebase and a rebuild of the generated pages.

export-formats.html explains how to export matches, fixtures, players,
rankings and tournaments to CSV, JSON Lines or Parquet with
livetennisapi-export 0.1.0. It is a guide in the GUIDES list.

The page says when each format fits. It lists the six datasets with the
endpoint and the plan each needs, as the package states them. It also
covers paging, how nested fields become dotted columns and when the
file is written.

The pandas, DuckDB and R examples were run against files the package's
own writers produced from its test fixtures. Versions were pandas 3.1.1
with pyarrow 26.0.1, DuckDB 2.0.0, and R 4.6.2 with arrow 26.0.1.

_export_drift fails the build when the page names an endpoint the spec
does not define. It also fails when the page size differs from the
spec's limit maximum.

The docs menu, the docs home, the sitemap, llms.txt and the README link
the page.
Nothing on the wire changed.
The column table named four fixtures fields the Fixture schema does not
document. They are gone. The fixtures row now lists fields the schema
has.

_export_drift resolves every listed column against the schema of its
endpoint. A name the spec does not document at that path stops the
build.
@bensynapse
bensynapse merged commit e26cd67 into main Nov 11, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant