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

Ouverte
  • Quelque chose ne va pas ?
#597 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
5/5
Temps estimé
Plus d'une semaine
Accessibilité débutants
22/100
Type d'issue
Documentation
Clarté
Plutôt claire
Activité
Calme
Stack technique
python
Domaine
api, documentation

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Description

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
Langage dominant
Python
Étoiles
214
Forks
68
Merge moyen
51 min
PR mergées (30 j)
6

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de Backblaze/b2-sdk-python

Toutes les issues de Backblaze/b2-sdk-python

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.