B2 SDK docs: inventory and classify the public names exported by b2sdk.v3

Aperta
  • Qualcosa non va?
#597 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
22/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
python
Ambito
api, documentation

Direzione di ricerca

Start by running import b2sdk.v3 and listing vars(b2sdk.v3) for non-underscored names, then check which ones appear in the .rst files under doc/source/api. Sample the low-level names the issue lists (B2Session, B2Http, RawSimulator, BucketFactory) to see how they are documented. Done means a reviewed classification of each root export and an interface-policy statement, which needs maintainer decisions on compatibility.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Description

b2sdk.v3 re-exports a large surface from _internal, including high-level APIs, low-level HTTP classes, test simulators, constants, and implementation-oriented helpers. A static inventory at f3ab7b71 found 208 non-underscored names in the v3 root; 137 were not mentioned anywhere in the Sphinx .rst sources. This count is not evidence that all 137 names should be public. It demonstrates that the repository does not currently make the boundary explicit enough to tell intentional public exports from convenient or accidental re-exports.

Steps to reproduce

import b2sdk.v3

exported = sorted(name for name in vars(b2sdk.v3) if not name.startswith('_'))
print(exported)

Compare the result with the public API pages under doc/source/api, then sample low-level names such as B2Session, B2Http, RawSimulator, BucketFactory, and transfer-manager classes to determine whether their compatibility status is documented.

Expected behavior

Produce a reviewed inventory that classifies each root export as public, advanced public, testing support, deprecated compatibility, or internal implementation. Every intentionally public symbol should be discoverable from the API reference. Anything intentionally excluded should be covered by a clear interface-policy statement so users and maintainers understand whether compatibility is promised.

Actual behavior

The versioned root exposes substantially more names than the public API reference explains. This ambiguity affects users choosing imports and maintainers deciding whether a rename or removal requires a compatibility adapter and version-specific tests.

Environment

  • Python version: Any supported version
  • b2sdk version: master at f3ab7b71
  • OS: Any
Lingua principale
Python
Stelle
214
Fork
68
Merge medio
51m
PR unite (30g)
6

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Backblaze/b2-sdk-python

Tutte le issue di Backblaze/b2-sdk-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.