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.
ImportSpy allows developers to:
- Define clear rules: Specify required variables, 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.
- Define what an external module must include to import your code:
- Required environment variables, functions, variables and classes.
- Both class and instance attributes, as well as mandatory class methods.
- Structural dependencies such as superclasses.
- 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.
- Supports complex systems:
- Prevents cyclic dependencies.
- Facilitates seamless integration of plugins and scalable components.
- Gather data on how modules interact with your code:
- Track external imports.
- Provide valuable debugging insights.
You can install ImportSpy via PyPI with a single command:
pip install importspyStart by creating a SpyModel that defines what is expected from modules importing your code:
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/"
}Use ImportSpy to validate a module:
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}")Ensure the CI/CD environment has all the required variables:
env_vars: dict = {
"CI": "true",
"GITHUB_ACTIONS": "true"
}Outcome: Prevent errors caused by misconfigurations.
Ensure each plugin properly implements the required classes:
classes: List[ClassModel] = [
ClassModel(name="PluginInterface", methods=["initialize", "execute"])
]Outcome: Smooth and predictable integration.
Avoid structural errors by defining rules for essential functions and attributes:
functions: List[str] = ["init_module", "shutdown"]Outcome: Improved project stability and code quality.
- Define Rules: Use
SpyModelto specify requirements. - Module Import: When a module is imported, ImportSpy validates that the rules are met.
- Validation Outcome: - Success: The import proceeds without issues. - Failure: A descriptive error is raised.
- 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.
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.
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.
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
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. ❤️
For detailed guidance on using ImportSpy, including advanced usage, API references, and examples, visit our official documentation.
The documentation is continually updated to ensure you have access to the latest features, best practices, and integration tips. Whether you're a beginner or an experienced developer, the documentation will help you unlock the full potential of ImportSpy.
Want to contribute? Add new features, provide feedback, or report bugs.
This project is distributed under the MIT License. See the LICENSE file for details.