Code & API Design

Conventions for Python code and public APIs.

14. Private modules, with the public API declared in `init.py`

Implementation lives in underscore modules: _formats.py, _models.py, _backends.py.
__init__.py re-exports the public names and declares an explicit __all__, which includes "__version__".
The rule: if a name isn’t in __all__, it isn’t public API. Great Docs uses __all__ to decide what to document, so this convention keeps the API and the documentation in sync.
In Greenwood, every module also has its own __all__. A new public symbol is added both there and in __init__.py.

Every source file in the newer packages starts with it.
Hints use X | None (never Optional), built-in generics, and Literal[...] for string-choice parameters (for example tbl_type: Literal["pandas", "polars"]).
Imports needed only for type hints go under if TYPE_CHECKING:. This avoids import cycles and avoids importing pandas or polars at runtime.

Users can pass pandas, polars or pyarrow data.
narwhals reads the input. Great Tables uses its own lazy backend layer with singledispatch instead.
pandas and polars are never imported at module top level. They are imported lazily inside functions, and a missing backend raises a helpful “install mypkg[pl]” message.
Functions that return tables take an output-format argument (tbl_type= or format=) and auto-detect a sensible default when it is None.
Expensive or optional attributes are loaded lazily through a module-level __getattr__. For example, Great Tables loads its datasets this way, so import great_tables doesn’t need pandas.

The first one or two arguments are positional (the data, the main input). Everything after * is keyword-only:

def meta(es, *, method="REML", level=0.95, ...) -> MetaResult: ...
def fit(self, surv, *, data=None, by=None, weights=None): ...

An option such as make_page: bool | None = None lets the library choose based on context, for example the rendering environment. Users override it only when they need to.

Results are frozen dataclasses with a *Result naming convention: MetaResult, BootstrapResult, RMSTResult.
They have a readable, deterministic __repr__: no memory addresses, no locale-dependent formatting.
Conversion methods (to_frame(format=...), to_gt(), plot()) let users move straight into tables and plots.
Objects that display in notebooks implement _repr_html_. Examples: GT tables and Pointblank validation reports.

Related functions share a verb-family prefix, so tab-completion works as documentation:
- Great Tables: fmt_*, cols_*, tab_*, opt_*, sub_*.
- Pointblank: col_vals_*, rows_*.
Method chaining reads like a sentence: GT(df).tab_header(...).fmt_number(...).cols_label(...). In Great Tables, each method returns a new object rather than mutating the existing one.

They name the offending argument, show the bad value, and say what is allowed:
```
raise ValueError(f"Unknown measure {measure!r}. Valid measures: {valid}.")
```
Argument checks happen once, early (for example in __post_init__), not throughout the code.
Warnings use warnings.warn(..., stacklevel=2), so they point at the user’s own line of code.

Output goes through return values, reprs and warnings. Logging is used only in the larger tools.
CLIs, where present, use Click (@click.group, @click.version_option) and are exposed through [project.scripts].

A load_dataset(name, ...) function and a way to list the available datasets are provided, so every docstring example and user-guide page runs out of the box.
The data ships as package data and is read with importlib.resources.files(...).