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.

Common errors

```
ModuleNotFoundError: cannot import name 'private_helper' from 'your_package'
```
cause A module or symbol was imported from a package, but it was not explicitly marked for export by `namex`, making it inaccessible as part of the public API.

fix Locate the `private_helper` definition in your source code and decorate it with `@namex.export()` to include it in the public API.
```
AttributeError: module 'your_package' has no attribute 'internal_function'
```
cause An attempt was made to access an attribute directly from the package namespace, but `namex` has not exposed this symbol as part of the public interface.

fix Ensure that 'internal_function' is correctly marked with `@namex.export()` in its definition file to make it accessible through the package's public API.
```
TypeError: namex.export() takes 1 positional argument but 2 were given
```
cause The `@namex.export()` decorator or `namex.export()` function was called with an incorrect number or type of arguments.

fix Refer to the `namex` documentation for the correct usage of its API, ensuring proper arguments and placement for the export function or decorator.
```
ValueError: Code directory 'src' not found for package 'my_package' during namex.convert_codebase
```
cause The `namex.convert_codebase()` utility was executed, but the specified `code_directory` or `package` path did not match the actual project structure.

fix Verify that your project's directory structure aligns with `namex` expectations (e.g., `src` folder for code) and provide the correct `package` and `code_directory` arguments to `namex.convert_codebase()`.

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 →