Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Define the top-level public API and deprecate redundant exports

Đang mở
  • Có gì không ổn?
#956 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python
Lĩnh vực
api, developer-experience

Hướng nghiên cứu

Start with py/src/braintrust/__init__.py and the existing public export coverage in type_tests/test_public_exports.py; read the export definitions in workflow_eval.py and supporting modules named in the issue. Inventory retained exports, deprecated aliases with exact replacements, and implementation spillover, then establish canonical imports and compatibility warnings. Done means the explicit root API and __all__, migration guidance, runtime and type coverage, updated imports, and optional-provider behavior meet the acceptance criteria.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

python

Problem

The top-level braintrust namespace mixes primary SDK entry points, supporting types, specialized features, and implementation details. py/src/braintrust/__init__.py uses wildcard imports and has no package-level __all__. A fresh import in the inspected checkout exposed 490 non-underscore names, including imported libraries and submodules; that count describes the observed namespace, not an intentional public contract.

Examples of spillover include DiskCache, LogQueue, ProjectIdCache, global_, construct_logs3_data, os, json, Any, cast, tee, and SSEClient.

Import order also determines the meaning of several names. Project, Dataset, Experiment, and Prompt ultimately resolve to classes from logger.py, replacing earlier exports. In particular, braintrust.Project is a different class from the project returned by braintrust.projects.create().

We should define an explicit top-level API, deprecate selected existing import paths with clear replacements, and stop exposing implementation imports as part of the intended contract.

Proposed top-level API

Keep the entry points for common workflows:

Workflow Top-level exports
Evaluations Eval, EvalAsync
Resource initialization init, init_dataset, init_logger
Authentication login
Tracing traced, start_span, current_span, flush
Instrumentation auto_instrument
Prompts and parameters load_prompt, load_prompt_async, load_parameters
Hosted function invocation invoke, invoke_async
Authoring and publishing projects
Workflow evaluations define_workflow_eval, WorkflowEval, and the existing public workflow task, scorer, submission, batching, store, and result helpers

Workflow evaluations are a first-class top-level API. Keep the existing 25 names declared in workflow_eval.__all__; they are excluded from the proposed root-import deprecations. This includes the WorkflowTask*, WorkflowScorer*, WorkflowBatch*, WorkflowSubmission*, and WorkflowEval* families.

Supporting types can be imported from stable submodules. This is a focused root API, not a rule that prohibits all classes at the top level: the workflow evaluation family is intentionally retained.

A. Deprecations

Deprecate selected top-level aliases/import paths while retaining their underlying functionality:

Candidate Replacement
init_experiment braintrust.init (it is currently an alias)
Provider-specific wrap_* and setup_* helpers braintrust.integrations.<provider>
BraintrustLogHandler braintrust.logs
Span customization APIs braintrust.span_customizer
Dataset pipeline APIs braintrust.dataset_pipeline
Sandbox registration APIs braintrust.sandbox
Evaluation support types braintrust.framework
Scoring objects and types braintrust.score
Stream/chunk classes braintrust.functions.stream
Generated schemas braintrust.generated_types
Resource classes, attachments, summaries, and other supporting types Establish and document stable submodule paths before issuing deprecations

Do not assume braintrust.types already re-exports every supporting type. Choose permanent destinations before asking users to migrate, and avoid multiple successive import migrations. Resolve the Project ambiguity explicitly in migration guidance.

Treat global log and summarize as a separate decision: replacing them with methods on experiment/logger handles changes usage beyond an import-path migration. Audit their use and decide separately whether to deprecate them. Likewise, audit advanced helpers not covered by the table before making removal decisions.

Compatibility rollout:

  1. Establish and document canonical submodule imports.
  2. Update repository examples, documentation, and internal imports to use the intended API.
  3. Preserve deprecated root imports through compatibility aliases, with DeprecationWarning messages naming the exact replacement import. A module __getattr__ compatibility layer is one option; avoid eagerly binding aliases if that prevents access warnings.
  4. Remove deprecated aliases in a future breaking release under an explicit deprecation policy.

B. Export cleanup

  • Replace wildcard imports in braintrust/__init__.py with explicit re-exports.
  • Add an explicit package-level __all__ for the supported root API, including the workflow evaluation family.
  • Preserve static type-checker visibility of intended re-exports, including the explicit as aliasing pattern already covered by type_tests/test_public_exports.py where needed.
  • Stop eagerly re-exporting third-party imports, typing utilities, internal caches/queues, serialization helpers, and mutable implementation state. Audit compatibility before removing names that downstream users may have adopted.
  • Review the three explicitly imported _internal_* hooks separately; they are private compatibility hooks, not part of the public export list.
  • Preserve optional-provider lazy loading and existing supported import-time behavior.

__all__ defines the intended public contract and wildcard-import behavior; it does not hide existing attributes or prevent Python from attaching imported submodules to the package. The goal is an explicit supported API, not a guarantee that dir(braintrust) contains only those names.

Acceptance criteria

  • Check in an explicit inventory of retained exports, deprecated root aliases with exact replacements, and implementation spillover.
  • Add explicit top-level re-exports and __all__, retaining all existing public workflow evaluation exports.
  • Document canonical submodule imports and a deprecation/removal policy.
  • Add runtime coverage for intended exports, deprecated aliases/warnings, and identity/behavior preservation.
  • Extend public-export type tests to cover the retained API and supported replacement imports.
  • Update examples and internal imports; verify optional providers remain optional.
  • Run the relevant core and type-checking sessions from py/noxfile.py.

Relevant files: py/src/braintrust/__init__.py, framework.py, framework2.py, logger.py, generated_types.py, workflow_eval.py, and type_tests/test_public_exports.py.

Ngôn ngữ chính
Python
Star
22
Fork
27
Merge trung bình
14 giờ 49 phút
Pull request đã merge (30 ngày)
126

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của braintrustdata/braintrust-sdk-python

Tất cả issue của braintrustdata/braintrust-sdk-python

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.