public: Python Module Visibility Decorator

Common errors

• AttributeError: module 'your_module' has no attribute 'your_private_func'

  cause You attempted to import a function, class, or variable from a module that was not explicitly marked with `@public`. The `public` library automatically manages `__all__`, only exposing decorated symbols.
  fix Decorate `your_private_func` with `@public` in `your_module.py` if it should be public, or refrain from importing it.

• TypeError: 'NoneType' object is not callable

  cause This often occurs when trying to apply `@public` directly to a variable declaration, or when calling `public` incorrectly (e.g., `public()`). The decorator needs to be applied to a callable or via specific variable exposure syntax.
  fix For variables, use `@public('variable_name')` on a dummy `def _pass(): pass` or explicitly call `public.add(variable_name=your_variable)`. Ensure `@public` is used correctly as a decorator for functions/classes.

• NameError: name 'my_variable' is not defined

  cause When using `@public('my_variable')` on a dummy function or `public.add(my_variable=my_variable)`, the variable `my_variable` must exist in the module's top-level scope and be correctly referenced by name or object.
  fix Ensure the variable `my_variable` is defined at the module level and that the `public.add` mechanism (either via decorator or direct call) is correctly implemented and executes during module import.

Warnings

• gotcha The `public` decorator actively modifies or overwrites your module's `__all__` list. If you manually define `__all__`, the decorated symbols will typically take precedence, potentially leading to unexpected exposure or hiding of symbols.
  Fix: Avoid manually defining `__all__` in modules where `public` is used, or be mindful that `public` will manage it. Ensure all desired public symbols are decorated.
• gotcha Directly decorating non-callable objects (like variables or constants) with `@public` as `@public my_var = 'value'` is not supported. You must use specific syntax to expose variables.
  Fix: To expose a variable `my_var`, either use `@public('my_var')` on a dummy function (e.g., `def _pass(): pass`) or explicitly call `public.add(my_var=my_var)` in your module's top-level scope.
• maintenance The `public` library appears to be in maintenance mode, with its last commit and release in 2020. While stable, users should be aware that active development, new features, or timely bug fixes are unlikely.
  Fix: Factor project status into your dependency choices; consider alternatives for new projects requiring active development or modern Python features.

Install

• pip install public Install stable version

Imports

• public
  wrong:

  from public import add

  correct:

  from public import public

  The `public` object itself is the primary decorator factory, which internally aliases `public.add`.

Quickstart

This example demonstrates how to use the `@public` decorator for functions and how to alias them. It also illustrates that non-decorated functions remain private and cannot be imported.

# my_module.py
from public import public

@public
def hello_world():
    """A publicly exposed function."""
    return "Hello from the public module!"

def _private_function():
    """A private function, not exposed."""
    return "You shouldn't see this!"

@public(alias='my_custom_name')
def original_function_name():
    """A public function exposed under an alias."""
    return "This function has a custom public name."

# To use this module:
# from my_module import hello_world, my_custom_name
# print(hello_world())
# print(my_custom_name())
# try:
#     from my_module import _private_function # This will raise an AttributeError
# except AttributeError as e:
#     print(f"Error trying to import private function: {e}")