Skip to content
Back to top
View this page

# 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 – None, or an object with both a __module__ and a __name__ argument.

    - kws – 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.

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