Skip to content

feat!: settle the public surface of both clients for 0.2.0 - #34

Merged
jm-rivera merged 8 commits into
mainfrom
feat/public-surface-0.2
Nov 14, 2026
Merged

jm-rivera merged 8 commits into
mainfrom
feat/public-surface-0.2

Conversation

@jm-rivera

@jm-rivera jm-rivera commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Settles the public surface of both clients that #19 asks for, and finishes #6 by typing only the part members the TypeScript client checks. Both packages move to 0.2.0, and each CHANGELOG.md lists every breaking change under Unreleased.

Closes #6
Part of #19

Changes

  • Errors: FormatError, BundleError and every bad-input raise on a public path are DfoErrors in both clients, and dfo.load on a damaged file raises one, while a read that fails at the disk raises its own OSError. dfo.load takes any bytes-like object. Sites that raised ValueError or TypeError in 0.1.0 still do. Messages end [<code> trace=<id>]. tests/core/test_errors.py pins the builtin raises that remain.
  • Removed: *old_form in Answer.choose and the TypeScript RENAMED options map.
  • Timeouts: the client's timeout is the default bound on a whole call, a call's timeout overrides it, and attempt_timeout (attemptTimeout, default 30 s) bounds one attempt. A timeout's message names the option that ran out. CLIENT_TIMEOUT and CallTimeout are in dfo.types. python/docs/settings.md and typescript/docs/settings.md list every setting with its argument, variable, default and precedence.
  • entities= takes dcids, Entity objects and resolved Match objects from lookup.resolve. Any other match is refused before a request, with a hint naming a candidate or near match. A ref or share given entities is refused for that first, in both clients.
  • fetch has one overload per target in both clients, plus a union overload in Python. python/tests/test_typing.py and typescript/test/fetch-options.types.ts pin the arguments each target refuses.
  • Datasets: Python gains to_bytes(), load(bytes), from_cache, fetched_at and question. The cache stores each download's fetch time under fetched/. TypeScript renames bytes() to toBytes(), adds save(path) through a writer index.node.ts installs, spells licence through a client-owned CitationSource, and adds question and fetchedAt. Saved files carry dfo.question and dfo.fetched_at as top-level keys.
  • TypeScript parts: Answer.parts, answer.specs and Spec.resolved type only what the client checks, with every other member unknown. isKnownPart runs the strict-field check, and QueryOption is Option.
  • TypeScript exports: the root holds the nine names that match Python's top level. Errors and warnings move to @developmentfinance/client/errors, every other name to @developmentfinance/client/types, and test/package.test.ts pins all three lists.
  • Docs: the recipes in both READMEs and docs/ run without a warning a reader should ignore, no example silences warnings, and .github/workflows/docs-examples.yml runs every documented example against the dev website nightly. scripts/check_docs_examples.py reports each warning a Python block shows.

Notes for reviewers

  • Client(timeout=) changes meaning, from one attempt to the whole call. Code written for 0.1.0 meets a deadline_exceeded error. A slow build cannot fail quietly.
  • TypeScript has two subpaths, ./errors and ./types, mirroring Python's dfo.errors and dfo.types. Settle the public surface of both clients before releasing 0.1.0 #19 asked for one.
  • DfoError.code is nullable in TypeScript, as ErrorCode | None is in Python, because FormatError and BundleError carry no contract code.
  • TypeScript fetchedAt is the client's clock when the dataset is built, since that client keeps no disk cache. Python's fetched_at is the download time, absent for cache entries written before 0.2.0.
  • Left open on Settle the public surface of both clients before releasing 0.1.0 #19, since each needs spec-kit first: DFO_TIMEOUT and DFO_MAX_RETRIES, the without_party_totals polarity, the readerkit cache directory, the server's licence/license split, client codes for FormatError, BundleError and the refusals that now borrow invalid_argument, a scenario expect key for party_totals_left_out, and the cache's fetched/ tree. entities= takes lookup results only, so fetch makes no network call to resolve names.
  • The docs figures stay as production serves them. Dev now words the Germany-to-Nigeria reading as net disbursements and returns 96 and 111 rows for the Ethiopia recipe.

Testing: the full CI recipe in both languages (Python 4,357 passed; TypeScript 2,104 passed; ruff, ty, lint-imports, the three codegen checks, eslint, tsc, build, actionlint); the live journeys against the dev website (Python 8 passed and 2 skipped for the inline long build and the crossing, which then passed alone; TypeScript 9 passed and 2 skipped); scripts/local-stack-journeys.sh both (Python 13 passed, TypeScript 7 passed, crossing passed); scripts/check_docs_examples.py against the dev website (Python 67 passed with 5 deliberate warnings; TypeScript 22 passed, with the two client.share blocks refused by dev's daily share allowance).

- typescript: trimEnd in core/text.ts trims trailing characters in one
  scan and replaces every trailing-trim regex, which ran in quadratic
  time on long runs (CodeQL js/polynomial-redos). Two tests escape
  their input in full (js/incomplete-sanitization).
- python: the transport builds its own httpcore2 pools with the
  attempt-deadline backend through public names only, reads proxies
  from urllib, and drops the <2.16 bounds on httpx2 and httpcore2.
- Both clients set answer.timed_out when any part's own reason is
  timed_out, and expose the party totals a rendering left out as
  Dataset.party_totals_left_out (partyTotalsLeftOut), saved under
  dfo.party_totals_left_out.
- typescript: Answer.facts and partFacts give the checked facts of
  each part.
- The dashboard journeys check the local-stack seed once and stop with
  one failure that names the missing readings.
- CI installs the lowest permitted versions on Python 3.12 and the
  newest on 3.14, weekly as well, and tests the apache-arrow peer at
  21.0.0 and the newest 21.x. Struct columns that differ between
  members now stack on pyarrow 15 to 20, and float16 columns compare
  on pyarrow 15 to 25. polars needs 1.3.

Closes #11
Closes #24
Both packages move to 0.2.0. Every breaking change is listed under
Unreleased in python/CHANGELOG.md and typescript/CHANGELOG.md.

- Errors: every error a public call raises is a DfoError, FormatError
  and BundleError included, and a damaged file given to dfo.load
  raises one. Calls that raised ValueError or TypeError still do.
  Messages end in [<code> trace=<id>]. The old-form shims in
  Answer.choose and the TypeScript options map are gone.
- Timeouts: the client's timeout bounds a whole call unless the call
  sets its own, and attempt_timeout (attemptTimeout) bounds one
  attempt. docs/settings.md in each package lists every setting.
- entities= takes dcids or what lookup.resolve returns.
- fetch is overloaded per target in both languages, and type tests
  pin the arguments each target refuses.
- Datasets: Python gains to_bytes() and load(bytes); TypeScript
  renames bytes() to toBytes(), gains save(path) on Node, and spells
  licence as Python does. A cache hit says so in the repr, and saved
  files record dfo.question and dfo.fetched_at.
- TypeScript: Answer.parts types only the members the client checks,
  isKnownPart checks them, QueryOption is Option, and the root
  exports the nine names that match Python's top level, with the rest
  under ./errors and ./types.
- Docs: the recipes run without warnings a reader should ignore, and
  a nightly workflow runs every documented example against dev.

Closes #6
Refs #19
@jm-rivera
jm-rivera added this pull request to stack #35 November 13, 2026 17:46
tests/test_typing.py runs ty on a forwarded fetch target, so the
python-lowest job pins ty from uv.lock beside the other test tools.
pyarrow raises a plain OSError, outside ArrowException, when a page
header fails to decode, so dfo.load let it escape DfoError. _open_saved
opens a path before parsing, so a missing file still raises
FileNotFoundError, and turns any OSError while decoding into
BundleError not_a_bundle.
@jm-rivera
jm-rivera marked this pull request as ready for review November 14, 2026 14:35
…Error

A deadline taken from the client's timeout now reads "the client's
timeout passed", for pin, cards, history, lookups and raw requests as
well as fetch. dfo.load takes any bytes-like object, and a read that
fails at the disk raises its own OSError where it was reported as a
damaged file. A TypeScript fetch of a ref or share refuses entities
before it resolves a Match, as Python does.
On pyarrow 15 to 20 the client stacked members whose struct columns
differ by round-tripping cells through Python, which cut nanoseconds
from time64[ns] fields, dropped field nullability and metadata, and
missed structs inside maps. pyarrow 21 promotes structs in
concat_tables, so the fallback and its version gate go. A float16
column is cast to float64 before its unique values are taken, which
needs no version check.
# Conflicts:
#	python/tests/datasets/test_dataset.py
Base automatically changed from feat/client-fixes to main November 14, 2026 18:05
@jm-rivera
jm-rivera merged commit fa3abb0 into main Nov 14, 2026
15 checks passed
@jm-rivera
jm-rivera deleted the feat/public-surface-0.2 branch November 14, 2026 18:07
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.

Replace the private httpx2 pool hook and type the TypeScript Part members the client does not check

1 participant