ImportSpy

Context-aware contract validation for Python imports.
Enforce runtime, environment, and code structure before execution.

---

🔍 What is ImportSpy?

ImportSpy lets your Python modules declare structured import contracts (via .yml files) to define:

• What environment they expect (OS, Python version, interpreter)
• What structure they must follow (classes, methods, variables)
• Who is allowed to import them

If the contract is not met, ImportSpy blocks the import — ensuring safe and predictable runtime behavior.

---

✨ Key Features

• ✅ Validate imports dynamically at runtime or via CLI
• ✅ Block incompatible usage of internal or critical modules
• ✅ Enforce module structure, arguments, annotations
• ✅ Context-aware: Python version, OS, architecture, interpreter
• ✅ Human-readable YAML contracts
• ✅ Clear, CI-friendly violation messages

---

📦 Installation

pip install importspy

Requires Python 3.10+

---

📐 Architecture

ImportSpy is powered by a layered introspection model (SpyModel), which captures:

• Runtime: CPU architecture
• System: OS and environment
• Python: interpreter and version
• Module: classes, functions, variables, annotations

Each layer is validated against the corresponding section of your .yml contract.

---

📜 Example Contract

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

---

🔧 Modes of Use

Embedded Mode – protect your own module

from importspy import Spy

caller = Spy().importspy(filepath="spymodel.yml")
caller.Plugin().run()

---

CLI Mode – external validation in CI

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

---

🧠 How It Works

1. You define an import contract in .yml
2. At runtime or via CLI, ImportSpy inspects:
   • Who is importing the module
   • What the system/environment looks like
   • What the module structure provides
3. If validation fails → the import is blocked
4. If valid → the module runs safely

---

✅ Tech Stack

• Pydantic 2.x – schema validation
• Typer – CLI
• ruamel.yaml – YAML support
• inspect + sys – runtime introspection
• Poetry – dependency management
• Sphinx + ReadTheDocs – documentation

---

📘 Documentation

Full documentation is available at:
👉 https://atellaluca.github.io/ImportSpy/

Here are some useful entry points:

• 🧠 How ImportSpy works
  A high-level overview of the validation lifecycle, contract structure, and runtime behavior.

• ⚙️ SpyModel architecture
  Deep dive into the declarative model that describes runtime, environment, and module contracts.

• 🧪 Violation system
  Learn how ImportSpy reports context-aware, structured errors on invalid imports.

• 🚀 CLI usage
  Run contract validation in CI/CD pipelines or pre-deploy checks with the CLI interface.

• 🛠 Embedded usage
  Use ImportSpy directly inside a module to protect it from being imported in unsupported contexts.

• 📄 Writing import contracts
  Guide to authoring .yml contracts: syntax, best practices, and validation patterns.

---

🚀 Ideal Use Cases

• Plugin-based frameworks (e.g., CMS, CLI, IDE)
• CI/CD pipelines with strict integration
• Security-regulated environments (IoT, medical, fintech)
• Package maintainers enforcing internal boundaries

---

💡 Why It Matters

Python’s flexibility comes at a cost:

• Silent runtime mismatches
• Missing methods or classes
• Platform-dependent failures
• No enforcement over module consumers

ImportSpy brings governance
to how, when, and where modules are imported.

---

❤️ Contribute & Support

• ⭐ Star on GitHub
• 🐛 File issues or feature requests
• 🤝 Contribute
• 💖 Sponsor on GitHub

---

📜 License

MIT © 2024 – Luca Atella