ImportSpy

Contract-based import validation for Python modules.

Runtime-safe, structure-aware, declarative.

ImportSpy allows your Python modules to define explicit import contracts: rules about where, how, and by whom they can be safely imported — and blocks any import that doesn’t comply.

🔍 Key Benefits

• ✅ Prevent import from unsupported environments
• ✅ Enforce structural expectations (classes, attributes, arguments)
• ✅ Control who can use your module and how
• ✅ Reduce runtime surprises across CI, staging, and production
• ✅ Define everything in readable .yml contracts

💡 Why ImportSpy?

Python is flexible, but uncontrolled imports can lead to:

• 🔥 Silent runtime failures
• 🔍 Structural mismatches (wrong or missing methods/classes)
• 🌍 Inconsistent behavior across platforms
• 🚫 Unauthorized usage of internal code

ImportSpy offers you runtime import governance — clearly defined, enforced in real-time.

📐 Architecture Highlight

ImportSpy uses a layered model (SpyModel) that mirrors your execution context and module structure:

• Runtime → defines architecture and system
• System → declares OS and environment variables
• Python → specifies interpreter, version, and modules
• Module → lists classes, functions, variables (each represented as objects, not dicts)

Each element is introspected and validated dynamically, at runtime or via CLI.

📜 Contract Example

filename: plugin.py
variables:
  - name: mode
    value: production
    annotation: str
classes:
  - name: Plugin
    methods:
      - name: run
        arguments:
          - name: self
          - name: data
            annotation: dict
        return_annotation: None

📦 Installation

pip install importspy

✅ Requires Python 3.10+

🔒 Usage Modes

Embedded Mode – the module protects itself:

from importspy import Spy
importer = Spy().importspy(filepath="spymodel.yml")
importer.Plugin().run()

CLI Mode – validate externally in CI/CD:

importspy -s spymodel.yml -l DEBUG path/to/module.py

📚 Features Overview

• ✅ Runtime validation based on import contracts
• ✅ YAML-based, declarative format
• ✅ Fine-grained introspection of classes, functions, arguments
• ✅ OS, architecture, interpreter matching
• ✅ Full error messages, CI-friendly output
• ✅ Supports embedded or external enforcement
• ✅ Strong internal model (SpyModel) powered by pydantic

🚀 Ideal Use Cases

• 🛡️ Security-sensitive systems (finance, IoT, medical)
• 🧩 Plugin-based architectures (CMS, CLI, extensions)
• 🧪 CI/CD pipelines with strict integration rules
• 🧱 Frameworks with third-party extension points
• 📦 Package maintainers enforcing integration rules

🧠 How It Works

1. Define your contract in .yml or Python.
2. ImportSpy loads your module and introspects its importer.
3. Runtime environment + structure are matched against the contract.
4. If mismatch → import blocked. If valid → import continues safely.

🎯 Tech Stack

• ✅ Pydantic 2.x – contract validation engine
• ✅ Typer – CLI interface
• ✅ ruamel.yaml – YAML parsing
• ✅ inspect + sys – runtime context introspection
• ✅ Poetry – package + dependency management
• ✅ Sphinx + ReadTheDocs – full docs and architecture reference

📘 Documentation

• 🔗 Full Docs → https://importspy.readthedocs.io/
• 🧱 Model Overview → https://importspy.readthedocs.io/en/latest/advanced/architecture_index.html
• 🧪 Use Cases → https://importspy.readthedocs.io/en/latest/overview/use_cases_index.html

🌟 Contribute & Support

• ⭐ Star → https://github.com/atellaluca/ImportSpy
• 🛠 Contribute via issues or PRs
• 💖 Sponsor → https://github.com/sponsors/atellaluca

🔥 Let your modules enforce their own rules. Start importing with structure.

📜 License

MIT © 2024 – Luca Atella

ImportSpy is an open-source project maintained with ❤️ by Luca Atella.