Refactor SpyModel, structured violations, and environment validation (v0.4.0) #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

atellaluca merged 40 commits into main from feat/environment-declaration

Aug 7, 2025

.gitignore

-Original file line number
+Diff line change
@@ Expand Up / @@ -9,4 +9,5 @@ venv/ @@
     ENV/
     env.bak/
     venv.bak/
-    .pytest_cache/
+    .pytest_cache/
+    /site/

CONTRIBUTING.md

-Original file line number
+Diff line change
@@ -1,33 +1,127 @@
     # Contributing to ImportSpy
-    🎉 Thank you for considering a contribution to **ImportSpy**! We value your efforts and welcome **issues, features, and documentation improvements**.
+    🎉 Thank you for considering a contribution to **ImportSpy** — a project designed to bring structure, security, and clarity to Python imports.
+    We welcome all kinds of contributions: new features, bug fixes, tests, documentation, and even thoughtful ideas. Your involvement makes the project better.
+    ---
     ## 📢 How to Contribute
-    ### 🔍 1. Issue Reporting
-    If you find a **bug** or have a **feature request**, please open an issue:
-    🔗 [GitHub Issues](https://github.com/atellaluca/ImportSpy/issues)
-    ### 🔄 2. Fork & Branching Strategy
-    - **Create a fork** and work on a separate branch before submitting a pull request.
-    - Use the following **branch naming conventions**:
-      - **For features:** `feature/nome-feature-in-breve`
-      - **For bug fixes:** `fix/bugfix-description`
-      - **For documentation:** `docs/update-section`
-    ### ✅ 3. Code Style & Commit Rules
-    - **Follow Conventional Commits**:
-      - `feat:` → For new features
-      - `fix:` → For bug fixes
-      - `docs:` → For documentation changes
-      - `test:` → For tests
-      - `refactor:` → Code improvements without changing functionality
-    Example:
+    ### 1. Open an Issue
+    If you encounter a bug, have a feature suggestion, or want to propose a change, please [open an issue](https://github.com/atellaluca/ImportSpy/issues). Use clear and descriptive titles.
+    You can use labels such as:
+    - `bug`: for broken functionality
+    - `enhancement`: for feature requests
+    - `question`: for clarification or design discussions
+    ### 2. Fork and Branch Strategy
+    - Create a **fork** of the repository.
+    - Work in a dedicated **feature branch** off `main`.
+    - Use consistent branch naming:
+    | Purpose         | Branch Name Format            |
+    |----------------|-------------------------------|
+    | Feature         | `feature/short-description`   |
+    | Bug fix         | `fix/issue-description`       |
+    | Documentation   | `docs/section-description`    |
+    | Tests           | `test/feature-or-bug-name`    |
+    > 💡 Keep pull requests focused and small. This helps reviewers and speeds up merging.
+    ---
+    ## ✅ Code Standards
+    ### Python Style Guide
+    ImportSpy follows:
+    - [PEP8](https://peps.python.org/pep-0008/)
+    - Type hints throughout the codebase
+    - `black` + `ruff` for formatting and linting
+    - `pydantic` for data models
+    ### Linting & Tests
+    To run tests and lint checks:
     ```bash
-    git commit -m "feat: add validation for OS compatibility"
+    poetry install
+    pytest
+    ruff check .
+    black --check .
     ```
-    💡 **We Appreciate Every Contribution!**
+    ---
+    ## 📄 Commit Conventions
+    We use **[Conventional Commits](https://www.conventionalcommits.org/)** for readable history and automatic changelog generation.
+    | Type     | Use For                       |
+    |----------|-------------------------------|
+    | `feat:`  | New feature                   |
+    | `fix:`   | Bug fix                       |
+    | `docs:`  | Documentation only            |
+    | `refactor:` | Code change w/o new feature or fix |
+    | `test:`  | Adding or updating tests      |
+    | `chore:` | Internal tooling or CI        |
+    **Example:**
+    ```bash
+    git commit -m "feat: support multiple Python interpreters in contract"
+    ```
+    ---
+    ## 🧪 Test Philosophy
+    Tests live in `tests/validators/` and should:
+    - Cover core logic (validators, spymodel, contract violations)
+    - Include both positive and negative cases
+    - Be fast, deterministic, and isolated
+    ---
+    ## ✍️ Docs Contributions
+    We use **MkDocs + Material** for documentation. Docs live under:
+    ```
+    docs/
+    ```
+    To preview locally:
+    ```bash
+    poetry install
+    mkdocs serve
+    ```
+    New pages should be added to `mkdocs.yml` under the right section.
+    ---
+    ## 🙌 Join the Community
+    While we don’t yet have a Discord or forum, we encourage:
+    - Sharing feedback via GitHub Issues
+    - Discussing architecture via PRs and comments
+    - Connecting with the maintainer via LinkedIn or GitHub
+    ---
+    ## 💬 Need Help?
+    Open an issue with the `question` label or ping @atellaluca in your PR.
+    ---
+    ## 📜 License
+    By contributing, you agree your work will be released under the MIT License.
+    ---
-    ImportSpy is an open-source project, and every contribution—big or small—helps make it better. 🚀
+    **Let your modules enforce their own rules — and thank you for helping ImportSpy grow!**

README.md

-Original file line number
+Diff line change
@@ -0,0 +1,178 @@
+    # ImportSpy
+    ![License](https://img.shields.io/github/license/atellaluca/importspy)
+    [![PyPI Version](https://img.shields.io/pypi/v/importspy)](https://pypi.org/project/importspy/)
+    ![Python Versions](https://img.shields.io/pypi/pyversions/importspy)
+    [![Build Status](https://img.shields.io/github/actions/workflow/status/atellaluca/ImportSpy/python-package.yml?branch=main)](https://github.com/atellaluca/ImportSpy/actions/workflows/python-package.yml)
+    [![Docs](https://img.shields.io/readthedocs/importspy)](https://importspy.readthedocs.io/)
+    ![ImportSpy banner](https://github.com/atellaluca/ImportSpy/docs/assets/importspy-banner.png)
+    **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
+    ```bash
+    pip install importspy
+    ```
+    > Requires Python 3.10+
+    ---
+    ## 📐 Architecture
+    ![SpyModel UML](https://github.com/atellaluca/ImportSpy/docs/assets/importspy-spy-model-architecture.png)
+    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
+    ```yaml
+    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
+    ```python
+    from importspy import Spy
+    caller = Spy().importspy(filepath="spymodel.yml")
+    caller.Plugin().run()
+    ```
+    ![Embedded mode](https://github.com/atellaluca/ImportSpy/docs/assets/importspy-embedded-mode.png)
+    ---
+    ### CLI Mode – external validation in CI
+    ```bash
+    importspy -s spymodel.yml -l DEBUG path/to/module.py
+    ```
+    ![CLI mode](https://github.com/atellaluca/ImportSpy/docs/assets/importspy-works.png)
+    ---
+    ## 🧠 How It Works
+. You define an import contract in `.yml`
+. At runtime or via CLI, ImportSpy inspects:
+       - Who is importing the module
+       - What the system/environment looks like
+       - What the module structure provides
+. If validation fails → the import is blocked
+. If valid → the module runs safely
+    ---
+    ## ✅ Tech Stack
+    - [Pydantic 2.x](https://docs.pydantic.dev) – schema validation
+    - [Typer](https://typer.tiangolo.com) – CLI
+    - [ruamel.yaml](https://yaml.readthedocs.io/) – YAML support
+    - `inspect` + `sys` – runtime introspection
+    - [Poetry](https://python-poetry.org) – dependency management
+    - [Sphinx](https://www.sphinx-doc.org) + ReadTheDocs – documentation
+    ---
+    ## 📘 Documentation
+    - **Full docs** → [importspy.readthedocs.io](https://importspy.readthedocs.io)
+    - [Quickstart](https://importspy.readthedocs.io/en/latest/intro/quickstart.html)
+    - [Contract syntax](https://importspy.readthedocs.io/en/latest/contracts/syntax.html)
+    - [Violation system](https://importspy.readthedocs.io/en/latest/advanced/violations.html)
+    - [API Reference](https://importspy.readthedocs.io/en/latest/api-reference.html)
+    ---
+    ## 🚀 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](https://github.com/atellaluca/ImportSpy)
+    - 🐛 [File issues or feature requests](https://github.com/atellaluca/ImportSpy/issues)
+    - 🤝 [Contribute](https://github.com/atellaluca/ImportSpy/blob/main/CONTRIBUTING.md)
+    - 💖 [Sponsor on GitHub](https://github.com/sponsors/atellaluca)
+    ---
+    ## 📜 License
+    MIT © 2024 – Luca Atella
+    ![ImportSpy logo](https://github.com/atellaluca/ImportSpy/docs/assets/importspy-logo.png)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Refactor SpyModel, structured violations, and environment validation (v0.4.0) #39

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!