modguard.BoundaryA Boundary makes all internal members private by default.
Boundary accepts no arguments, and has no runtime behavior. It is detected statically by modguard.
+
__init__.pyWhen a Boundary appears in __init__.py, this marks the contents of the entire package as private by default.
+
# project/core/inner.py
+# This function will be considered private
+# due to the boundary at 'project.core'
+def private_function():
+ ...
+When a Boundary appears in a standalone Python file, this marks the contents of the file itself as private by default.
+
# project/core/other.py
+from modguard import Boundary
+
+Boundary()
+
+# This function will be considered private
+# due to the boundary at 'project.core.other'
+def other_private_function():
+ ...
+modguard.publicMarking a member as public allows it to be imported outside its boundary. This should be used to mark the intended public interface of a package or module.
public can be used as either a decorator or a bare function, and has no runtime behavior. It is detected statically by modguard.
public accepts one optional positional argument (path) and one optional keyword argument (allowlist).
When present, path identifies the object being marked as public.
+
import modguard
+
+x: int = 3
+
+# These are functionally the same
+modguard.public("x")
+modguard.public(x)
+When present, allowlist defines a list of module paths which are allowed to import the object. Modules which are descendants of the modules in the allowlist are also allowed. If any other modules import the object, they will be flagged as errors by modguard.
+
# In project/utils.py
+import modguard
+
+x: int = 3
+
+modguard.public(x, allowlist=["project.core.domain"])
+
+...
+# In project/core/other_domain/logic.py
+# This import is not allowed,
+# because the module ('project.core.other_domain.logic')
+# is not contained by any module in the allowlist
+from project.utils import x
+public can also be used as a decorator to mark functions and classes as public. Its behavior is the same as when used as a function, and it accepts the same keyword arguments (the decorated object is treated as path)
import modguard
+
+@modguard.public(allowlist=["project.core.domain"])
+def my_pub_function():
+ ...
+When public is used without a path argument, it signifies that the entire containing module is public. This means that any top-level member of the module or the module itself can be imported externally (subject to allowlist).
+
# In project/core/logic.py
+import modguard
+
+modguard.public()
+...
+# In project/cli.py
+# This import is allowed because 'project.core.logic' is public
+from project.core import logic
+__init__.pyWhen public is used without a path argument in the __init__.py of a package, the top-level module of the package is treated as public.
+
# In project/core/__init__.py
+import modguard
+
+modguard.Boundary()
+modguard.public()
+...
+# In project/cli.py
+# This import is allowed because 'project.core' is public
+from project import core
+modguard-ignoreTo ignore a particular import which should be allowed unconditionally, use the modguard-ignore comment directive.
+
modguard-ignore should match the alias as it is used in the subsequent import line, not the full module path from the project root.
+Note: Boundary violations are detected at the import layer. This means that specific nonstandard custom syntax to access modules/submodules such as getattr or dynamically generated namespaces will not be caught by modguard.
+ + + + + + + + + + + + + +