3LC Python Package Version 3.0¶

3.0.0¶

3lc 3.0 is a major release with breaking changes. Please see the migration guide for details about what has changed and how to update existing code for the new version. Insofar as the migration guide covers items related to APIs whose locations have changed or that have been removed altogether, such items will not be detailed here in the release notes.

The 3lc 3.0.0 release is being made soon after the 3lc 2.23.0 release, which introduced much of the new API and provided deprecations for things removed in 3lc 3.0.0. For an existing code base making use of 3LC, it may be helpful to first install the latest 3lc 2.23 and address any deprecation warnings emitted. It may also be helpful to consult the 3lc 2.23.0 release notes, since they contain descriptions of features and improvements you may otherwise be unaware of if jumping straight to 3lc 3.0.0.

Features¶

  • [16324] Drastically reduced the footprint of the public 3LC API to make it clear what is intended to be used.

    • This effort involved privatizing or removing submodules, removing *-imports, and curating __all__ lists for each package, as well as ensuring the remaining API surface is well documented.

    • The end result is a cleaner public API that is easy to understand and maintain.

  • [16743] Replaced preference for mostly positional args in the public API with a preference for mostly keyword args, following the convention that args should be positional only when the role is obvious at the call site and everything else keyword-only. This lets new keyword arguments be added near the top of the signature where they remain visible, instead of being appended to the end of a long positional chain.

  • [13850] Standardized ordering of parameters across the API.

  • Improved load time for import tlc.

    • [15057] Deferred import for several dependencies to the point where they are actually used.

    • [17519] Made torch and pandas optional dependencies, only used if and when needed, re-raising an ImportError if not available in those places.

  • [16589] Redesigned UrlAdapter and made it pluggable to allow users to define interaction with custom storage backends. See this page for details.

  • [17259] Made Exporter pluggable to allow users to define how to export to formats other than those with built-in exporters. See this page for details.

  • [16295] Redesigned the SampleType implementation around a simpler, flatter class hierarchy that is easier to subclass.

    • Table samples are now always dictionaries, giving a simpler and more consistent mental model.

    • A SampleType can no longer be supplied in place of a Schema. A Schema is now the single way to define the structure of data.

    • Made SampleType pluggable for advanced use cases. See this page for details.

  • [16203] Added a complete set of dataclasses for working with common annotation types.

    • These plug a long-standing gap in the API: instead of assembling dictionaries with hard-to-remember keys, you now work with user-friendly, typed dataclasses.

    • Each dataclass can describe its own schema (via .schema()), convert between sample and row views (to_row() / from_row()), expose its data — bounding boxes, labels, and so on — directly as NumPy arrays, and provides convenient constructors and builders.

  • [14110] Refactored TableWriter to use a streamlined, reusable pipeline.

    • A single pipeline now handles inferring and overriding schemas, transforming to row view, relativizing URLs, and related steps.

    • TableWriter accepts inputs in either sample or row view and performs the conversion only as required.

  • [16389] Refactored the configuration system with a view toward user convenience.

    • In the tlc package, moved the Configuration class that serves as the primary user-facing interface to the configuration system to tlc.configuration, and provided a top-level shortcut in tlc.config (usage: tlc.config.logging.level = "DEBUG").

    • In the low-level tlcconfig package, replaced the legacy class-based OptionLoader with a typed registry of Option instances and a thread-safe ConfigStore with per-tier provenance.

    • Configuration options are described on this page.

Enhancements and Fixes¶

  • [16966] Standardized root parameter naming to root_url across public API.

  • [16965] Made MetricsTableWriter.finalize() automatically update the Run.

  • [16327] Changed the default table name from “table” to “initial”, which is the recommended table name for users.

  • [14723] Default to the split as dataset name for YOLO ndjson datasets.

  • [17480] Removed the PyTorch Lightning integration in favor of demonstrating usage with an example notebook.

  • [16389] Made it so that 3lc logs output to stderr instead of stdout.

  • [16589] Properly handle query parameters in Url

  • [17517] Let UrlAdapter writes redirect to a different URL. Some adapters map writes onto a versioned backend and need to tell the caller that the actual written URL differs from the requested one.

  • [17232] Made it so several errors related to TableWriter and Table usage surface in a way that better describe the problem.