importspy 0.4.0

ImportSpy ensures structural integrity, runtime compliance, and security for external modules, preventing inconsistencies and enforcing controlled execution.

ImportSpy

Runtime contract validation for Python imports.
Enforce structure, Block invalid usage: stay safe at runtime.

---

🔍 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 docs → importspy.readthedocs.io
• Quickstart
• Contract syntax
• Violation system
• API Reference

---

🚀 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