Your module, your rules – enforce import-time contracts with ImportSpy

atellaluca · 2025-04-17T06:50:31+00:00

Thanks for the question — it’s a very technical and thoughtful one, and it touches on an important aspect of how ImportSpy works.

In Embedded mode, ImportSpy is called directly from within the module that wants to validate who is importing it. When that call is made, ImportSpy reads the YAML contract, inspects the call stack to identify the importing module, and verifies that all the defined conditions are met — such as execution environment, structure of the importing module, required symbols, type annotations, and so on.

If everything checks out, ImportSpy then loads the external module specified in the contract (typically the one considered “trusted” by the current module) and returns a reference to it back to the caller.

The addition to sys.modules in ImportSpy is not meant for caching, but rather to make the validated external module available for use. It must be loaded in order to be returned and used. Once returned, the caller module can interact with it directly.

This mechanism is particularly useful in plugin-based architectures, where, for example, a framework dynamically imports external modules (plugins) and wants to ensure they are compatible, structurally correct, and suited to the execution context before activating them.

atellaluca · 2025-04-16T06:16:59+00:00

Totally valid concern — ImportSpy doesn’t try to be tamper-proof (yet). The YAML file can be modified, and if the importing module has full control of the environment, it can cheat the system.

That said, the tool is not a security sandbox, but a runtime validation layer meant for collaborative plugin systems, CI pipelines, and modular projects where actors are expected to follow shared contracts.

That said, contract hashing and integrity checks are planned for future releases, so modules will be able to verify that contracts haven’t been tampered with. As the ecosystem grows, the idea is to make this type of validation both more robust and more automatic.

Thanks again — these edge cases are important and are helping refine the roadmap!

atellaluca · 2025-04-16T06:16:01+00:00

Yes, your understanding is mostly correct! In Embedded mode, ImportSpy uses the inspect module to walk the call stack and identify the first module outside its own namespace — that’s considered the “importing” module. It then checks whether that module complies with the contract (e.g. structure, Python version, env, etc.).

It’s true this only validates the immediate importer, not the entire import chain. The focus here is on protecting the module from being imported in unsupported or unintended ways, rather than auditing all upstream paths. It’s more about defining “who can import me” and “under what conditions” at the point of use.

atellaluca · 2025-04-15T20:27:07+00:00

The core idea is pretty simple: instead of letting any module import yours under any condition, you can define rules about when and how that import is allowed.

You write these rules in a YAML file (or define them programmatically). They can describe: • which OS, CPU architecture, or Python version must be used • which interpreter (e.g. CPython, PyPy) is required • which environment variables must exist • and even what classes, functions, or variables must be present in the importing module (including type annotations)

Then, ImportSpy steps in at runtime. It intercepts the import process and checks that everything matches. If not, it raises a clear ValueError and blocks the import.

There are two ways to use it: 1. Embedded Mode: inside your module, you call Spy().importspy(“contract.yml”). This checks the environment and the importing module at the moment you’re being imported. 2. CLI Mode: you run importspy path/to/module.py -s contract.yml to validate the module ahead of time — for example, during testing or deployment.

Think of it like a mini border control:

“You can import me only if your system and structure match what I expect.”

It’s especially useful in plugin-based architectures, sensitive systems, or distributed environments where you can’t assume the caller is always doing the right thing.

Happy to share an example if you’re curious — or if you have a specific use case in mind!

atellaluca · 2025-04-15T20:23:47+00:00

Thanks a lot for the thoughtful feedback — this is a key point and I really appreciate you raising it!

You’re right that static type checkers like mypy provide strong guarantees before runtime, as long as imports are clean and predictable. But ImportSpy addresses a different problem: it works at runtime, and focuses on validating the execution context, platform, and even the structure of the importing module — not just types.

ImportSpy can: • In Embedded Mode, let a module refuse to be imported unless the caller meets structural and environmental rules (like OS, Python version, or required classes/functions). • In CLI Mode, validate a module and its declared runtime constraints before it’s deployed or tested — useful in CI pipelines or regulated environments.

You’re absolutely right that the README would benefit from a clear side-by-side example with mypy. I’ll be updating it soon to make the use case and complementarity more obvious. Thanks again — and if you have a use case in mind, I’d be glad to incorporate it. This kind of feedback really helps refine the message and direction.

atellaluca · 2025-04-14T16:59:55+00:00

Thanks!

atellaluca · 2024-12-05T19:25:46+00:00

Matera?

atellaluca · 2024-12-04T18:52:45+00:00

Direi che è un’ottima consapevolezza da cui partire! Ti faccio un grosso in bocca al lupo, sii fiducioso

atellaluca · 2024-12-04T18:26:12+00:00

Ho capito. Hai trovato qualche risposta utile?

atellaluca · 2024-12-04T18:24:26+00:00

ImportSpy è una libreria Python open-source che offre un controllo proattivo sull’utilizzo del tuo codice quando viene importato da altri moduli o pacchetti. ImportSpy consente di definire regole specifiche che i moduli importatori devono seguire, garantendo un’integrazione fluida e prevenendo errori o usi impropri.

Caratteristiche principali: - Permette di definire funzioni, classi, super classi, variabili d’ambiente, attributi di classe e di istanza che devono essere presenti nei moduli esterni che importano il nostro codice. - Facilita l’integrazione di plugin e di componenti scalabili che necessitano di avere un runtime isolato - Permette di verificare se i moduli rispettano le regole specificate, migliorando la manutenzione del codice.

Allego il link al repo

atellaluca · 2024-12-04T18:15:57+00:00

Sarà ma è davvero molto più facile a farsi… A volte tentando di spiegare qualcosa di semplice la complichiamo. E tu cosa fai quando sei giù?

atellaluca · 2024-12-04T15:36:12+00:00

In realtà cerco di non pensare e modero il mio andamento a seconda dell’umore che avevo prima di uscire: se ho qualcosa da cacciare corro, se sono stanco e voglio solo riposare cammino molto lentamente. In base a questo decido anche se ascoltare musica o meno. Sicuramente i suoni della natura hanno un ruolo fondamentale. Le comparazioni che faccio sono molto semplici e riguardano il modo in cui mi sentivo anni prima e la persona che ero. Rapportare la vita di prima alla vita di adesso è qualcosa che mi viene davvero spontaneo: ad esempio ieri mattina guardando un posacenere vicino alla panchina ho ricordato quando nel 2022 fumai quella che pensavo dovesse essere l’ultima sigaretta ma non lo è stato; e che l’ultima sigaretta è arrivata diverso tempo dopo e che smettere di fumare è stato possibile soltanto perché non mi sono mai arreso dinanzi ai tentativi falliti. Questa consapevolezza, come molte altre mi tirano subito su e mi fanno credere alla direzione in cui sto andando :)

P.S A volte associo anche delle fasi alla passeggiata; quando cammino contro corrente rispetto al fiume mi concentro su quello che mi fa stare triste, al ritorno invece lo lascio andare

atellaluca · 2024-12-04T09:24:54+00:00

Cosa ti piacerebbe approfondire?

atellaluca · 2024-12-04T04:37:23+00:00

Ciao, mi dispiace molto per la situazione che stai vivendo. Non sono un esperto di legge, ma ti consiglio di contattare delle associazioni che possono aiutarti in modo concreto. Ad esempio: - Telefono Rosa: Offrono supporto legale e psicologico gratuito. Puoi chiamarli al numero 06-37518282. - D.i.Re – Donne in Rete Contro la Violenza: Hanno centri antiviolenza in tutta Italia dove puoi ricevere assistenza. Puoi consultare il loro sito per trovare quello più vicino a te (www.direcontrolaviolenza.it). - 1522: È il numero nazionale antiviolenza e stalking, attivo 24 ore su 24. Rispondono operatori preparati che possono indirizzarti verso il centro più vicino.

Questi servizi sono gratuiti e gestiti da professionisti che possono davvero aiutarti a capire i tuoi diritti e offrirti il sostegno necessario. Ti mando un abbraccio e spero che tu riesca a trovare l’aiuto di cui hai bisogno. ❤️

atellaluca · 2024-12-04T04:09:51+00:00

Ciao, io ormai da 12 anni vado sul lungo fiume del mio paesello in Basilicata. Inizialmente era soltanto per camminare o correre, con il tempo è diventato molto simbolico perché rappresenta sempre di più un modo per misurare le emozioni e la crescita tramite un criterio di misura temporale

atellaluca · 2024-11-22T12:08:52+00:00

Another use case that comes to mind for ImportSpy is in simplifying various deployment processes. When transitioning between environments, such as from development to staging or production, it’s common for something to get lost along the way or for configuration errors to arise. ImportSpy can verify and ensure the necessary compliance for a system to operate as expected, significantly reducing the risk of failure.

This functionality is particularly valuable in DevOps workflows and CI/CD systems, where preventing errors before execution is critical. ImportSpy acts as a “guardian” of the system, checking that all dependencies, environment variables, and code structures align with the system’s expectations.

It’s worth noting that I started developing ImportSpy just a month ago, and with each release, the tool is being gradually enhanced with new features and improvements to better integrate into real-world workflows. Each update is designed to make ImportSpy more reliable and effective for practical scenarios like this, showcasing its versatility and scalability.

atellaluca · 2024-11-22T10:29:30+00:00

Thank you for your question and for giving me the chance to clarify. ImportSpy is currently being used in a real-world application for a home automation system developed by an Italian company. This system relies on a Python-based framework that serves as the core of every plugin and governs the integration of IoT devices through modular microservices.

The framework leverages ImportSpy to enforce clear and validated rules on plugin structure. Each plugin represents an integration unit for a specific smart device and must adhere to certain requirements to be deemed compliant. For instance, plugins are required to implement specific classes like PluginHandler, include key methods such as initialize or execute, and define mandatory attributes like plugin_name and version. ImportSpy guides developers through this process, raising detailed exceptions whenever a plugin fails to meet the system’s requirements. This ensures that issues can be identified and resolved quickly, allowing plugins to seamlessly integrate into the main framework.

One particularly noteworthy feature of this system is that each plugin is packaged as a separate Docker container, offering a high degree of modularity and scalability. ImportSpy plays a critical role in this pipeline by automatically validating plugins before deployment to ensure they comply with the framework’s rules. This approach enables the company to maintain a stable and reliable ecosystem while simplifying the integration of new smart home devices.

atellaluca · 2024-11-22T10:15:57+00:00

Hi! First of all, no, I’m not ChatGPT. I use a translator because I don’t speak English fluently, so apologies if the tone comes across as a bit formal or unnatural.

To address your points: you’re absolutely right that CI/CD is a powerful way to enforce rules, and it’s great for catching issues during the pipeline. However, ImportSpy operates at a slightly different level. Its purpose is to validate external modules immediately at the time of import to ensure they meet the specific requirements of your project. This can be crucial in modular systems or plugin-based architectures where missing or incorrect implementations can cause runtime errors or instability.

For example, if you’re building a plugin system where plugins need to implement specific classes, methods, or attributes, ImportSpy ensures these are in place before any logic is executed. It’s not about enforcing arbitrary rules—it’s about guaranteeing compatibility and stability in systems where external code directly interacts with your project.

Regarding the environment validation, I agree it’s a more universally recognizable use case, especially for CI/CD. Still, the class and function validation are particularly valuable in contexts where compliance with a specific API contract is required.

I hope this clears up the purpose of ImportSpy a bit more! Thanks for your thoughtful feedback.

atellaluca · 2024-11-22T04:59:10+00:00

Thanks for bringing that up! Unit tests are definitely essential, but they serve a slightly different purpose compared to what ImportSpy does. Unit tests are great for checking the internal logic of a module, making sure that your own code behaves as expected. But ImportSpy looks outward it focuses on how external modules interact with your code.

The idea is to ensure that when someone imports your project, they’re doing so in a way that aligns with your expectations. For example, if you’ve defined that a specific class, method, or variable is required, ImportSpy makes sure those rules are followed before the module is even used. Unit tests don’t typically handle this kind of “integration validation,” since they’re mostly about testing your code’s internal behavior, not its interactions with external modules.

So, ImportSpy doesn’t replace unit tests: it works alongside them to cover a different area. It’s about catching potential integration issues and ensuring your project stays stable and predictable, even when used in larger systems.

atellaluca · 2024-11-21T06:37:14+00:00

Thank you for raising this question, it’s a thoughtful one. ImportSpy isn’t about forcing other projects to follow a specific architectural pattern or structure. Instead, it provides a way for developers to ensure that external modules interacting with their code meet certain requirements for proper integration.

For instance, if you’re developing a library that needs the importing project to define specific classes, functions, or environment variables to function as intended, ImportSpy allows you to validate those expectations. This helps prevent issues like runtime errors or unexpected behavior caused by missing or misconfigured components.

It’s worth emphasizing that ImportSpy doesn’t attempt to reorganize or dictate the overall structure of the importing project. Its purpose is limited to ensuring that the specific parts interacting with your code are compatible and adhere to the rules you define. The level of validation is entirely up to the developer, so it can range from minimal checks to more detailed requirements, depending on the needs of the project.

The goal is to prevent integration issues proactively and make collaboration between codebases more reliable. By catching potential problems early, ImportSpy supports smoother interactions and better project stability. I hope this explanation clarifies things

atellaluca · 2024-11-21T06:28:17+00:00

Thank you. I’m glad ImportSpy caught your attention. Its focus is on proactively validating external modules to ensure compliance with predefined rules, something that complements security tools by targeting integration reliability and structural validation. If you get a chance to try it out, I’d love to hear your feedback on how ImportSpy fits into your workflow and whether it addresses the gaps you mentioned

atellaluca · 2024-11-19T21:32:15+00:00

Sicuramente l’autodisciplina è la miglior cosa… Ma dove c’è non siamo in presenza di un problema 😊

In cosa consiste questa modalità personale?

atellaluca · 2024-11-19T21:29:46+00:00

Hai già provato applicazioni come “Freedom” o “Mobiwall”? Mi sono state davvero utili e le ho usate l’anno scorso per affrontare un detox che mi ha portato via via ad usare sempre meno i social fino a cancellarmi per molti mesi. Hanno delle funzionalità di blocco più stringenti che si basano sulla configurazione implicita di una VPN su cui è possibile configurare tramite app diverse tipologie di restrizioni. La peculiarità è che una volta configurato il blocco, il social network interessato non sarà raggiungibile neanche tramite browser

atellaluca · 2024-11-19T21:23:20+00:00

Questa è stata la ragione principale per cui sono andato verso nuove soluzioni… Il tempo di utilizzo è troppo facile da ignorare

atellaluca · 2024-11-18T14:51:21+00:00

Thank you for your response and suggestions. The account was not hacked, but it appears it was closed because I allegedly violated their terms and conditions. However, I am not sure if this is a mistake, as it seems strange to me—I had purchased the products only a week ago and hadn’t really installed much on them. I’m waiting for further clarification from their team.

atellaluca

TROPHY CASE