# Module Design

Design a small, stable public surface. Keep implementation modules movable behind it.

## Why

Python makes it easy to publish internals by accident:

- every file is importable
- helpers become de facto API once users depend on them
- refactors turn into breaking changes when file layout becomes the contract

Mature libraries push back on that. They usually:

- publish one obvious import surface
- re-export supported names deliberately
- keep internal modules non-authoritative
- use `__all__` when the boundary needs to be explicit

That buys two things:

- simpler imports for callers
- freedom to reorganize internals later

## The pattern

1. Decide what callers should import.
2. Re-export those names from the package boundary.
3. Keep implementation details in internal modules.
4. Use `__all__` when you want an explicit contract.
5. Treat internal file layout as private unless you intentionally publish it.

## When to use

Use this when:

- a package spans multiple modules
- internals will evolve faster than the public API
- you want callers thinking in domain concepts, not filenames
- compatibility matters across releases

## When not to use

Do not build a facade when:

- the package is tiny and direct imports are already clear
- the abstraction boundary is still moving fast
- re-exporting would turn `__init__.py` into a junk drawer

A curated surface is not the same as a flat surface. Keep structure where the concepts are meaningfully different.

## Preferred shapes

### Package facade over internal modules

```python
# mypkg/__init__.py
from ._client import Client
from ._errors import AppError
from ._models import Item

__all__ = ["Client", "AppError", "Item"]
```

Why this works:

- callers learn one stable import path
- internals can move without import churn
- the package advertises its real contract

### Explicit module contract

```python
__all__ = ["Number", "Complex", "Real", "Rational", "Integral"]
```

This says: these names are supported; everything else is implementation detail.

## Counterexamples

### File layout becomes the API by accident

```python
from mypkg.utils import helper_a
from mypkg.impl_v2 import thing
from mypkg.more_helpers import other_thing
```

Refactoring internal modules now breaks users.

### Everything dumped into `__init__.py`

If `__init__.py` exports fifty unrelated names, you did not create a clean facade. You created autocomplete noise.

### Public API mirrors the folder tree too literally

If callers need to know today’s internal layout to use the library, the boundary is still underdesigned.

## Source signals

### CPython

- `Lib/numbers.py:8-23` warns that published ABC APIs are hard to change and should be designed carefully.
- `Lib/numbers.py:35` publishes a narrow `__all__` rather than treating every helper as public.
- `Lib/operator.py:13-15` and `Lib/smtplib.py:55-58` do the same in stdlib modules with mixed public/internal names.

### Pytest

- `src/pytest/__init__.py:6-80` builds the top-level `pytest` API by importing from many `_pytest.*` internals.
- `src/pytest/__init__.py:98-186` then pins that facade with an explicit `__all__`.

### HTTPX

- `httpx/__init__.py:1-12` re-exports the package surface from internal modules such as `._client`, `._exceptions`, and `._models`.
- `httpx/__init__.py:29-100` defines the supported top-level export list explicitly.
- `httpx/__init__.py:103-106` rewrites exported objects’ `__module__` to `httpx`, reinforcing the facade instead of leaking internal filenames.

### Click

- `src/click/__init__.py:10-75` exposes the package through re-exports.
- `src/click/__init__.py:77-126` keeps compatibility shims and deprecations at the boundary instead of freezing old internal layout forever.

## Bottom line

Make the public API intentional.

Callers should depend on your concepts, not your current file tree.