injector-api

Injector API

The Injector API is a lightweight dependency injection library designed to simplify the management of dependencies in Python projects.

Prerequisites

• Python 3.7 or higher
• A proper environment (virtualenv or conda recommended)

Installation

To install the Injector API, simply run the following pip command:

pip install injector-api

Usage

Initial Configuration

First, call configure in your main file app configuration to set up the Injector API:

import injector_api
injector_api.initializate("your_directory_name_here")

Note on Directory Structure:

If you specify "your_directory_name_here" (or any other directory name) as the directory for the Injector API to search, make sure that your main execution file is located in the same parent directory as "your_directory_name_here".

or

Configuration injectorConfig.json

Instead of directly using the initializate method, you can also configure the library by creating an injectorConfig.json at the root of your project. This file should specify the directory name:

{
    "MODULE_APPLICATION": "your_directory_name_here"
}

Replace your_directory_name_here with the name of the directory where your module.py resides.

Defining and Registering Dependencies in module.py

The module.py file plays a pivotal role in the Injector API library structure. Here, you define and register the dependencies you wish to inject into your application.

Dependency Registration

To register dependencies, first import the container from the library. Then, use the register method. This method takes the interface you wish to implement and its concrete implementation as arguments.

from injector_api.container import container
# absolute routes, DO NOT USE RELATIVE ROUTES
from application.src.interfaces import IExampleService,InterfaceWithoutOtherService
import application
Your interfaces and classes here
container.register_module(application)
container.register(IExampleService, implementation_name='ExampleServiceImpl1' ,override=True)
container.register(IExampleService,implementation_name='ExampleServiceImpl2',override=True,lifecycle=SINGLETON )
container.register(InterfaceWithoutOtherService, implementation_name='WithoutOtherService')

or

# absolute routes, DO NOT USE RELATIVE ROUTES
from application.src.interfaces import IExampleService,InterfaceWithoutOtherService
from application.src.class import ExampleServiceImpl1,ExampleServiceImpl2,WithoutOtherService
import application


container.register_module(application)
container.register(IExampleService, ExampleServiceImpl1 ,override=True)
container.register(IExampleService,ExampleServiceImpl2,override=True,lifecycle=SINGLETON )
container.register(InterfaceWithoutOtherService, WithoutOtherService)

Override Explanation

The override parameter is optional and its default value is False. If set to True, it allows a new registration to replace an existing one for the specified interface. This is useful when you want to change the implementation for an interface without removing the previous registration manually.

Injecting into Functions and Methods

With dependencies registered in module.py, you can utilize the @inject decorator to inject these dependencies into functions or methods.

from injector_api.dynamically import inject
"""
Use @inject() only when specifying the type of implementation. For correct usage, employ @inject() with the format {interface:0}, where 0 corresponds to the first registered injection. Without specifying the type of implementation, simply use @inject
"""
@inject({IExampleService: 0})
def some_function(service: IExampleService):
return service.do_something()
@inject
def some_function_two(service: InterfaceWithoutOtherService):
return service.do_something()

In the example above, the IExampleService dependency will be injected into some_function, granting access to its methods and properties.

Location of module.py

Ensure the module.py file is located in the directory you've specified in injectorConfig.json. This file will be automatically read by the library during execution to load and manage dependencies.

Usage with Django

In Django, call configure in your app configuration:

application/apps.py

from django.apps import AppConfig
import injector_api

class ApplicationConfig(AppConfig):
    name = 'application'  # Ensure to use the correct name of your app here

    def ready(self):
        """
          It should be intuited that the new_src must be in the same apps.py directory, with new_src being a dywan
        """
        injector_api.initializate("application") 

If in application/apps.py it doesn't work, try adding

application/init.py

default_app_config = 'application.apps.ApplicationConfig'

Use the common library as if it were your own project

If you're integrating the Injector API within a Django project, you have the option to use the ScopeMiddleware to manage scoped dependencies. This middleware ensures that dependencies with a "scoped" lifecycle are correctly managed within the context of a web request.

However, do note that using scoped dependencies requires your Django application to run in a server mode where each request is handled by a separate thread or process (e.g., using gunicorn with threaded workers). Using scoped dependencies in a single-threaded server (like Django's default development server) might lead to unexpected behaviors.

To use the middleware, add it to your Django project's middleware list:

MIDDLEWARE = [
    ...
    'path_to_your_library.ScopeMiddleware',
    ...
]

Security Recommendations

While the Injector API simplifies dependency management, there are potential security risks when using dynamic loading. We recommend the following precautions:

• Always validate dynamically loaded information or modules.
• Avoid loading modules from locations that can be manipulated by untrusted users.
• Use a secure, isolated environment for your application.
• Keep the library and all its dependencies up to date.
• If you're using the optional ScopeMiddleware in Django, ensure your server is configured correctly for scoped dependencies.

Recommendation for Using Injector API Library

When considering the use of the Injector API library, it's essential to weigh the benefits against potential challenges. Here's our take:

Why We Recommend It:

• Simplicity: The library provides a straightforward approach to dependency injection, making it easier for developers to manage and maintain their codebase.
• Flexibility: The ability to dynamically load modules can significantly enhance the modularity and scalability of an application.
• Improved Testability: Dependency injection inherently makes unit testing more straightforward, as dependencies can be easily mocked or stubbed out.
• Active Development: Libraries that are actively developed tend to have regular updates, which means bugs are fixed, and new features are introduced, keeping the tool relevant and up-to-date.

Potential Challenges:

• Security Risks: As with any tool that supports dynamic module loading, there's a potential risk if not handled securely. Developers need to be cautious and follow best practices to mitigate these risks.
• Learning Curve: While the library aims to simplify dependency injection, newcomers to the concept might face a learning curve.

In conclusion, we recommend the Injector API library for developers who understand the importance of dependency injection and are willing to adopt best practices to ensure security. However, as with any tool, it's crucial to understand its workings fully and be aware of potential pitfalls.

Contribute

Contributions are welcome! Please submit pull requests or open issues on our GitHub repository.

License

This library is licensed under the MIT License. See the LICENSE file for details.