Metadata-Version: 2.1
Name: importspy
Version: 0.1.10
Summary: ImportSpy is a lightweight Python library that enables proactive control over how your code is used when imported by other modules or packages. It allows developers to define rules that importing modules must follow, ensuring proper use and preventing misuse or errors.
License: MIT
Author: Luca Atella
Author-email: atellaluca@outlook.it
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pydantic (>=2.9.2,<3.0.0)
Project-URL: documentation, https://importspy.readthedocs.io
Project-URL: repository, https://github.com/atellaluca/importspy
Description-Content-Type: text/x-rst

.. image:: https://static.pepy.tech/badge/importspy
   :target: https://pepy.tech/project/importspy

.. image:: https://img.shields.io/github/actions/workflow/status/atellaluca/ImportSpy/python-package.yml?style=flat-square
   :target: https://github.com/atellaluca/ImportSpy/actions/workflows/python-package.yml

.. image:: https://img.shields.io/github/license/atellaluca/ImportSpy?style=flat-square
   :target: https://github.com/atellaluca/ImportSpy/blob/master/LICENSE

   
ImportSpy
=========

.. image:: https://raw.githubusercontent.com/atellaluca/ImportSpy/refs/heads/main/assets/ImportSpy.png
   :width: 830
   :alt: ImportSpy Image

ImportSpy
=========

**ImportSpy** is the ultimate Python library for proactive import control. Designed for complex and modular environments, ImportSpy ensures that external modules adhere to precise rules, improving the stability and security of your project.

Why ImportSpy?
--------------

ImportSpy allows developers to:

- **Define clear rules**: Specify required functions, classes, and environment variables for every module importing your code.
- **Validate imports**: Ensure external modules comply with these rules before they can interact with your code.
- **Improve project quality**: Reduce bugs caused by improper imports or misconfigured environments.

Key Features
------------

🔒 **Proactive Import Validation**
- Define what an external module must include to import your code:
- Required functions and classes.
- Mandatory methods and attributes.
- Structural dependencies such as superclasses.

📋 **Environment Variable Validation**
- Ensure the environment is correctly configured:
- Check for critical environment variables.
- Validate their values against predefined expectations.
- Essential for CI/CD pipelines or distributed systems.

🧩 **Optimized for Modular Architectures**
- Supports complex systems:
- Prevents cyclic dependencies.
- Facilitates seamless integration of plugins and scalable components.

🔄 **Import Monitoring**
- Gather data on how modules interact with your code:
- Track external imports.
- Provide valuable debugging insights.

Installation
------------

You can install ImportSpy via PyPI with a single command:

.. code-block:: bash

    pip install importspy

Quick Start
-----------

Defining Validation Rules
^^^^^^^^^^^^^^^^^^^^^^^^^

Start by creating a ``SpyModel`` that defines what is expected from modules importing your code:

.. code-block:: python

    from importspy import Spy
    from importspy.models import SpyModel, ClassModel
    from typing import List, Optional

    
    class MyLibrarySpy(SpyModel):
        # Name of the expected module file
        filename: Optional[str] = "expected_module.py"
    
        # Expected version of the module
        version: Optional[str] = "1.0.0"
    
        # Required variables defined within the module (name-value pairs)
        variables: dict = {
            "default_timeout": "30",
            "max_connections": "100"
        }
    
        # Required functions
        functions: List[str] = ["process_data", "log_results"]
    
        # Required classes
        classes: List[ClassModel] = [
            ClassModel(
                name="DataProcessor",  # Class name
                class_attr=["processor_type", "status"],  # Required class-level attributes
                instance_attr=["input_data", "output_data"],  # Required instance-level attributes
                methods=["process", "save"],  # Required methods
                superclasses=["BaseProcessor"]  # Expected superclasses
            ),
            ClassModel(
                name="Logger",
                class_attr=["log_level"],
                instance_attr=["log_file"],
                methods=["log_message", "clear_logs"],
                superclasses=[]
            )
        ]
    
        # Required environment variables
        env_vars: dict = {
            "CI": "true",
            "DATA_PATH": "/data/"
        }

Validating During Import
^^^^^^^^^^^^^^^^^^^^^^^^

Use ImportSpy to validate a module:

.. code-block:: python

    spy = Spy()

    try:
        module = spy.importspy(spymodel=MyLibrarySpy)
        print(f"Module '{module.__name__}' complies with the specified rules.")
    except ValueError as ve:
        print(f"Validation error: {ve}")

Real-World Use Cases
--------------------

✅ **CI/CD Pipelines**
^^^^^^^^^^^^^^^^^^^^^^

Ensure the CI/CD environment has all the required variables:

.. code-block:: python

    env_vars: dict = {
        "CI": "true",
        "GITHUB_ACTIONS": "true"
    }

Outcome: Prevent errors caused by misconfigurations.

✅ **Plugin-Based Systems**
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Ensure each plugin properly implements the required classes:

.. code-block:: python

    classes: List[ClassModel] = [
        ClassModel(name="PluginInterface", methods=["initialize", "execute"])
    ]

Outcome: Smooth and predictable integration.

✅ **Modular Projects**
^^^^^^^^^^^^^^^^^^^^^^^

Avoid structural errors by defining rules for essential functions and attributes:

.. code-block:: python

    functions: List[str] = ["init_module", "shutdown"]

Outcome: Improved project stability and code quality.

How It Works
------------

1. **Define Rules**: Use ``SpyModel`` to specify requirements.
2. **Module Import**: When a module is imported, ImportSpy validates that the rules are met.
3. **Validation Outcome**:
   - Success: The import proceeds without issues.
   - Failure: A descriptive error is raised.

Why Choose ImportSpy?
---------------------

- **Enhances Security**: Blocks non-compliant imports, reducing the risk of bugs and vulnerabilities.
- **Simplifies Debugging**: Easily trace incorrect imports.
- **Supports Code Evolution**: Write code that defines rules for future integrations, preventing errors before they occur.

Support the Development of ImportSpy
-------------------------------------

**ImportSpy** is an open-source project passionately developed by a single developer from **Satriano di Lucania**, a small town in the beautiful region of Lucania, Italy. This project represents a unique solution for managing Python imports, but it requires **time**, **dedication**, and **resources** to grow and improve.

Why Your Support Matters
------------------------

By sponsoring **ImportSpy**, you can help:

- **Accelerate development**: Your support allows me to dedicate more time to creating new features, fixing bugs, and improving compatibility.
- **Keep the project up to date**: Ensure ImportSpy continues to support the latest Python versions and modern development needs.
- **Provide community support**: Expand documentation, create advanced examples, and respond to user inquiries.
- **Make the project sustainable**: Promote innovation in an open-source environment.

Every contribution, big or small, makes a difference and helps keep the project free and accessible for everyone.

How to Sponsor
--------------

You can sponsor ImportSpy directly on GitHub. As a sponsor, you will:

- **Be publicly recognized** (if desired) in the documentation and GitHub repository.
- **Influence project development** by suggesting features that meet your needs.
- **Receive priority support** for integrating ImportSpy into your projects.

💡 Sponsor ImportSpy now: `GitHub Sponsors <https://github.com/sponsors/atellaluca>`_

A Small Contribution, A Big Impact
-----------------------------------

Your support is not just an investment in ImportSpy but also in the open-source philosophy, which fosters innovation and collaboration within the Python community. Even a small contribution can make a big difference!

Thank you for believing in this project and helping take ImportSpy to the next level. ❤️

Contribute to ImportSpy
-----------------------

Want to contribute? Add new features, provide feedback, or report bugs on GitHub:

https://github.com/atellaluca/ImportSpy

License
-------

This project is distributed under the MIT License. See the `LICENSE <https://github.com/atellaluca/ImportSpy/blob/main/LICENSE>`_ file for details.

