Namex: Python API Surface Management

0.1.0 · active · verified Thu Apr 09

Namex is a Python utility that helps package developers define and manage their public API surface, primarily by simplifying the construction of the `__all__` attribute in `__init__.py`. It prevents accidental exposure of internal details and ensures a consistent public interface. The current version is 0.1.0, and it is likely to see active development with potential for API evolution.

Warnings

gotcha As an early-stage library (v0.1.0), the public API of `namex` is subject to rapid evolution. Breaking changes may occur in minor releases until a stable API is established (e.g., v1.0.0).
Fix: Consult the latest documentation and release notes for updates when upgrading. Pin your version for production environments.
gotcha Namex relies on conventions (e.g., leading underscores for private members) and explicit configuration (e.g., `excludes`). Misunderstandings of these conventions can lead to unintended API exposure or hidden public components.
Fix: Thoroughly review the generated `__all__` content and adhere strictly to naming conventions and explicit configuration rules within your package.
gotcha Mixing Namex with manual `__all__` management or other API surface management tools within the same package can lead to unpredictable behavior and difficult-to-debug import errors.
Fix: Use Namex as the sole authority for managing your package's `__all__` attribute within its scope to ensure consistent and predictable API definition.

Install

pip install namex Install stable version

Imports

Config
```
from namex import Config
```
The core configuration class for defining API behavior.
get_api
```
from namex import get_api
```
Function to generate the `__all__` list based on a Config object.

Quickstart

This example demonstrates how to set up `namex` in a package's `__init__.py` to define its public API. It imports `Config` and `get_api`, then configures which modules to scan and which specific symbols to exclude. The resulting `__all__` ensures only specified public members are exposed.

# my_package/__init__.py
from namex import Config, get_api

config = Config(
    modules=["my_package.module_a", "my_package.module_b"],
    excludes=["my_package.module_a.private_func"]
)
__all__ = get_api(config)

# my_package/module_a.py
def public_func_a():
    pass
def _private_func_a(): # Excluded by convention
    pass
def private_func(x): # Explicitly excluded
    pass

# my_package/module_b.py
class PublicClassB:
    pass

view raw JSON →