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__.

The name is always added to the __all__ of the module where this call appears, creating that list if necessary. The __all__ of the module where thing happens to have been defined is never touched.

Most commonly this is used as a decorator on a class or function at module scope, in which case thing is the object being defined and its __name__ is the name that gets added.

It can also be called directly with a single positional argument, which may be an object imported from another module, or a module or submodule. The name added is the one that object is bound to in the calling module’s globals, since that’s the name from <module> import * has to find. So given from bar import Foo as Baz, public(Baz) adds 'Baz'.

That single argument may instead be a string, which is added to __all__ as-is. It must be a valid Python identifier and must not be a reserved word, since nothing can ever be bound to one of those; soft keywords such as match and type are ordinary names and are accepted. Beyond that, nothing checks a string against the module’s contents, so the name need not be bound, or even exist. This is the escape hatch for names that don’t appear in the source, such as bindings made dynamically or re-exports guarded by try/except ImportError. Reach for it last; a string is precisely the kind of thing that goes stale, which is what this library exists to prevent.

The other call form takes keyword arguments. Each key is added to __all__ and bound to its value in the calling module’s globals. This form returns the keyword argument values in order; if only a single keyword argument is given its value is returned, otherwise a tuple of the values is returned. Use it for constants and instances, which have no __name__ to infer a name from.

Only one or the other format may be used.

Parameters:

  • thing (Any | None) – None, a string, a module, or an object with a __name__.

  • kws (Any) – Keyword arguments.

Returns:

In the decorator and single argument forms, the original thing object is returned. In the keyword argument 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:

  • TypeError – When no name can be inferred from thing, or this function finds a non-list __all__ attribute.

  • ValueError – When thing is a string that can’t be used as a name, i.e. it isn’t an identifier, or it’s a reserved word.

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__.

The name is always removed from the __all__ of the module where this call appears. The __all__ of the module where thing happens to have been defined is never touched.

Unlike public(), this never creates an __all__. If the module doesn’t have one there is nothing to remove the name from, and an empty __all__ is not the same thing as no __all__ at all: the first exports nothing, while the second exports every name that doesn’t start with an underscore. The argument is still checked, so passing something no name can be inferred from raises whether or not the module has an __all__.

Like public(), this can be called directly with a single positional argument instead of used as a decorator, and the name is resolved the same way: an object imported from another module, or a module or submodule, resolves to the name it is bound to in the calling module’s globals, while a string must be a valid Python identifier that isn’t a reserved word, and is otherwise taken as given. There is no keyword argument form.

Parameters:

thing (ModuleAware) – A string, a module, or an object with a __name__.

Returns:

The original thing object.

Raises:

  • TypeError – When no name can be inferred from thing, or this function finds a non-list __all__ attribute.

  • ValueError – When thing is a string that can’t be used as a name, i.e. it isn’t an identifier, or it’s a reserved word.

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

public.install() → None

Add the @public and @private decorators to builtins.

Once installed, both decorators are available in every module without importing anything. The companion atpublic-install package calls this at interpreter startup, but you can call it yourself only if you are not using that package.

Return type:

None