API Reference

API reference for public:

public.public(thing: ModuleAware) → ModuleAware
public.public(**kws: Any) → Any | tuple[Any]

Add a name or names to __all__.

There are two forms of use for this function. Most commonly it will be used as a decorator on a class or function at module scope. In this case, thing will be an object with both __module__ and __name__ attributes, and the name is added to the module’s __all__ list, creating that if necessary.

When used in its function call form, thing will be None. __all__ is looked up in the globals at the function’s call site, and each key in the keyword arguments is added to the __all__. In addition, the key will be bound to the value in the globals. This form returns the keyword argument values in order. If only a single keyword argument is given, its value is return, otherwise a tuple of the values is returned.

Only one or the other format may be used.

Parameters:

  • thing (Any | None) – None, or an object with both a __module__ and a __name__ argument.

  • kws (Any) – Keyword arguments.

Returns:

In the decorator form, the original thing object is returned. In the functional form, the keyword argument value is returned if only a single keyword argument is given, otherwise a tuple of the keyword argument values is returned.

Raises:

ValueError – When the inputs are invalid, or this function finds a non-list __all__ attribute.

Return type:

ModuleAware | Any | tuple[Any]

public.private(thing: ModuleAware) → ModuleAware

Remove names from __all__.

This decorator documents private names and ensures that the names do not appear in the module’s __all__.

Parameters:

thing (ModuleAware) – An object with both a __module__ and a __name__ argument.

Returns:

The original thing object.

Raises:

ValueError – When this function finds a non-list __all__ attribute.

Return type:

ModuleAware

public.populate_all() → None

Populate the calling module’s __all__ with all of its public names.

The criteria for what is a public name is derived from various common linter rules, although it’s not an exact science.

  • The name does not start with an underscore.

  • The name is not bound to a module object. This prevents imported modules from being added.

  • The object the name is bound to does not appear to be defined in some other module. This prevents most from-imports from being added, but note that this can be fooled if you import simple types (such as an int or a str) from another module (e.g. from sys import abiflags), because simple types don’t have a __module__ attribute.

If you find that some names are missing from the list, you can add them to __all__ explicitly by using the @public decorator. If you find some names in __all__ that should not be present, decorate them with the @private decorator.

This function respects any existing __all__ in your module.

Typical usage is to call this function at the bottom of your module.

Return type:

None