Skip to content

Naming: disambiguate the two blocking modules - #126

Merged
martinkersner merged 1 commit into
mainfrom
issue-116-naming
Jul 15, 2026
Merged

Naming: disambiguate the two blocking modules#126
martinkersner merged 1 commit into
mainfrom
issue-116-naming

Conversation

@martinkersner

Copy link
Copy Markdown
Member

Part of #116 — the "two different blocking modules" item.

Problem

pub use generated::* re-exports generated::blocking (sync endpoint wrappers) as datamaxi::blocking, sitting next to the unrelated hand-written datamaxi::api::blocking (Client/ClientBuilder/Paginator). The docs had to keep telling sync users to combine both paths, e.g. "datamaxi::blocking::CexCandle and datamaxi::api::blocking".

Approach chosen

Make datamaxi::blocking a single, unified sync entry point rather than trying to rename anything.

An explicit pub mod blocking in lib.rs re-exports, in one place:

  • Client / ClientBuilder / Paginator from api::blocking, and
  • the generated sync endpoint wrappers (pub use crate::generated::blocking::*).

The explicit module shadows the glob-imported generated::blocking (an item beats a glob binding of the same name — no conflict). This mirrors the async crate root, which already holds Client + the endpoint wrappers together, so sync users now write one import: use datamaxi::blocking::{Client, CexCandle};.

Only the hand-written side is touched. generated.rs (DO NOT EDIT) is untouched.

Why not the alternatives

  • Rename api::blocking — only the hand-written side is renameable, so a rename can't remove the other blocking name; it would just add churn/breakage without fixing the core "need both" confusion.
  • Rename generated::blocking — requires the upstream datamaxi-codegen tool; out of scope here.
  • Narrow/drop pub use generated::* — too breaking; it is the crate's canonical type surface (every datamaxi::CexCandleResponse etc.). Kept as-is. The residual "~200 names in the crate root" concern is codegen-side and filed separately (see below).

Breaking?

No. Purely additive. Every prior path still resolves:

  • datamaxi::blocking::CexCandle ✓ (now via the unified module)
  • datamaxi::api::blocking::Client ✓ (unchanged home; also newly reachable as datamaxi::blocking::Client)

api::blocking becomes the implementation home that datamaxi::blocking re-exports — exactly the api::Clientdatamaxi::Client relationship that already exists on the async side.

Version implication

New public API surface (a new re-export path) ⇒ minor bump (0.12.0 → 0.13.0) at next release. Following repo convention (additive PRs #91/#106/#108/#119 didn't bump Cargo.toml themselves), this PR does not touch the version.

Follow-up

Filed a claude-found codegen issue for the residual "~200 generated names in the crate root" concern (link added as a comment).

Test plan

  • cargo fmt --all -- --check — clean
  • cargo clippy --all-targets --all-features -- -D warnings — clean; also default-feature clippy clean
  • cargo test --all-features — 44 unit + 7 doctests pass (incl. new datamaxi::blocking doctest)
  • cargo doc --no-deps (default and --all-features) — no new warnings vs. baseline (verified by diffing warning counts; the pre-existing api.rs intra-doc-link warnings are unrelated and untouched)
  • Live tests skip without DTMX_API_KEY (expected)

Add an explicit `pub mod blocking` at the crate root that re-exports the
blocking `Client`/`ClientBuilder`/`Paginator` (from `api::blocking`)
alongside the generated sync endpoint wrappers. The explicit item shadows
the glob-imported `generated::blocking`, so this is additive: existing
paths (`datamaxi::api::blocking::*`, `datamaxi::blocking::CexCandle`) all
still resolve, but sync callers now need only one module — mirroring the
async crate root that holds `Client` + wrappers together.

Drops the "you need both modules" story from crate/README docs.
@martinkersner

Copy link
Copy Markdown
Member Author

Follow-up codegen issue for the residual "~200 generated names in the crate root" concern: #127

@martinkersner
martinkersner merged commit 6178e2d into main Jul 15, 2026
5 checks passed
@martinkersner
martinkersner deleted the issue-116-naming branch July 15, 2026 10:18
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