symbol-export 1.0.1

Python package module encapsulation toolkit - Enforce public/private symbols at import time

Symbol Export

symbol-export is an advanced Python module encapsulation toolkit that enforces true public/private symbol boundaries at import time.

Unlike Python’s conventional visibility mechanisms (_, __all__), this project actively intercepts the import system to ensure that third-party code can only access what a package explicitly declares as public.

---

🚀 Installation

Available on PyPI

pip install symbol-export

🎯 Project Goal

Python does not provide real encapsulation at the module level. symbol-export introduces a strict and deterministic mechanism to:

• Define a clear public API

• Prevent accidental or unintended access to internal symbols

• Respect official __all__ semantics

• Enforce visibility rules at import time

✨ Features

• 🔒 Real module encapsulation

• 📦 Strict control of exported symbols

• 🧠 Fully respects __all__

• 🔁 Automatic handling of package submodules

• 🧩 No changes required in consumer code

• 🪝 Global __import__ hook

• ⚙️ Works with transitive imports

• 🧪 Designed for libraries, not scripts

✅ Usage

[!Warning] This package must only be imported from a package’s __init__.py.

# mypackage/__init__.py
import __symbol_export__

from mypackage import helpers

_T = "public constant"

def public_function():
    ...

def _public_function():
    ...

# mypackage/helpers.py
def _private_helper():
    ...

class PublicClass:
    pass

def public_helper():
    ...

👤 From third-party code

import mypackage

# ✅ allowed
mypackage._T
mypackage.public_function
mypackage._public_function
mypackage.helpers
mypackage.helpers.PublicClass
mypackage.helpers.public_helper

# ❌ not visible
mypackage.helpers._private_helper

🧠 How It Works Internally

[!Important] Public symbols are determined following the Library interface rules.

• Overrides builtins.__import__

• Detects which package imports symbol-export

• Registers that package as an exported package

• Submodules of the package are also encapsulated automatically

• Replaces entries in sys.modules with capsule modules

• Capsule modules expose only public symbols

⚠️ Known Limitations

• Does not encapsulate the __init__ module

• Not compatible with hot-reload systems

• Not designed for embedded Python runtimes

🔐 Security Considerations

• This is NOT a sandbox

• This is NOT a security boundary

• Does not prevent intentional reflection

• Does not block access to sys.modules or inspect

• Does not replace permission systems

✔️ Designed for:

• Clean public APIs

• Library contracts

• Preventing accidental misuse

❌ Not designed for:

• Protection against malicious code

• Runtime isolation

• DRM or code obfuscation