proboscis / pinjected

Pinjected

Welcome to Pinjected, a powerful dependency injection and dependency resolver library for Python inspired by pinject.

pip install pinjected

Table of Contents

• Introduction
• Design
• Decorators
• Injected
• Running
• Async Support
• Resolver
• Miscellaneous
• Appendix
• Updates

Introduction

Pinjected makes it easy to compose multiple Python objects to create a final object. It automatically creates dependencies and composes them, providing a clean and modular approach to dependency management. To learn more about the motivation behind Pinjected and its key concepts, check out the Introduction. Design

• VSCode plugin is available at pinjected-runner

Design

The Design section covers the core concept of Pinjected. It explains how to define a collection of objects and their dependencies using the Design class. You'll learn about binding instances, providers, and classes to create a dependency graph.

Decorators

Pinjected provides two decorators, @instance and @injected, to define provider functions. The Decorators section explains the differences between these decorators and how to use them effectively in your code.

Injected

In the Injected section, you'll learn about the Injected class, which represents a variable that requires injection. This section covers how to create Injected instances, compose them, and use them as providers in your dependency graph.

Running

Pinjected supports running Injected instances from the command line and integrating with IDEs like IntelliJ IDEA. The Running section provides details on how to use the CLI and set up IDE integration for a smooth development experience.

Async Support

Pinjected offers support for asynchronous programming, allowing you to use async functions as providers. The Async Support section explains how to define and use async providers, as well as how to compose async Injected instances.

Resolver

The Resolver section dives into the object graph and resolver concepts in Pinjected. You'll learn how the resolver manages the lifecycle of injected variables and how to use it to retrieve instances from the dependency graph.

Miscellaneous

For additional information, refer to the Miscellaneous section, which covers topics like performance considerations, comparisons with other DI libraries, and troubleshooting.

Appendix

The Appendix contains supplementary information, such as a comparison with pinject and other relevant details.

Updates

Stay up to date with the latest changes and releases by checking the Updates section, which includes a changelog and migration guides. We hope you find Pinjected helpful in your projects! If you have any questions or feedback, please don't hesitate to reach out.

pinjected's Issues

Portability Improvement

Currently, our design makes the code reusable within the same project, where a design can be easily importable.
However, when it comes to porting the design to another project, it is difficult to reuse, since all the depending scripts must be importable.
The only way we can reuse our design in other projects is to use pypi's packaging system.

Proposal:
Make each Injected portable across projects

• An Injected holds the implementation and all the depending pypi installable modules.
• by accumulating these Injecteds, we can build a pyproject.toml that is portable.
• we can also gather Injecteds and accumulate implementations to a single file for distribution.
• How can we handle classes?
• • We can edit metaclass to be reusable,
• So, it seems that if we don't rely on the 'import' statement of a python, we can become happier??

Make injected variable have an overrides for a design

When using injected variable as a run configuration, we often want to override some configurations by design

Make injection key BindingKey rather than a string

Currently, we use a simple string as an injection key, and the namespace is globally shared.
This makes the design very large in terms of namespace and causes naming issues over time.
Also, we currently register @injected_function and @injected_instance implicitly to all the designs.
We plan to make this implicit bindings have a namespace and make it not injectable to everyone,
so that the injected variables within a same module can easily share the injection while far unrelated modules don't get affected by the helper injected function's namespaces

Rename package name

Currently the library is named after 'pinject'. However, we no longer rely on the implementation of pinject (mostly, except the implicit name lookup).

So, in order to disambiguate the package, I think we need to give this a new name.
Options are:

1. Injected
2. Blueprints
3. Designs

Add visualization of the whole components

Currently we only visualize the graph from a root node.
However, we might also want to see the whole structure not only emerging from the root, but the whole project.

Make create_configuration hookable to support multiple runtime configurations

Currently we have either viz/run for the options to run Injected.
viz -> show dependency graph on a browser
run -> runs it locally.

However, there are cases where a user wants to customize how an Injected should be treated.

1. Make create_configurations return generic run configuration:

• Currently, create_configurations returns a json of IdeaConfigurations

2. Make create_configurations look for hooking designs, or retrieve hooks from a design
   2.1 Use a special name such as default_design_paths
   2.2 look for a special dependency injection variable name such as runtime (this looks better)
3. Make the 'viz' feature a runtime option

Traversing Metadata in Runtime

When saving runtime metadata (such as wandb.config), we want to construct what data is used for building such object.
Since the configurations such as hyper parameters are static, we can gather such information from InjectedPures in the design.
In order to gather such data, we need to be able to tell how the data is constructed, to the provider, while running it. This means we need to tell the provider:

1. what we are building
2. trace of injected in building sequence
3. extract statically known values from injected for config saving.

IDE support for listing injectable names

Add visualization for the design edit graphc

Currently we don't store any information about where the designs are combined.
However, since we combine a lot of designs together, this forms a complex dependency graph, and it is hard to track how the design ended up as is.

Let's store where the designs are combined and make a visualization for it.

Meta files for package

We currently use meta_design variable for each module we are interested in.
However, it may be better to use something like meta.py for extracting metadata for a package.

By doing so, we can accumulate the dependencies out of this module...
The motivation for this is the modularity problem

Enhanced Binding/Resolver, Async Call Support

• We need IBindKey rather than a direct string for custom binding control
• We need a resolver that can handle such binding
• We need a resolver that can handle async instances

Add documentations

IDE supports:

• Running from green icon in Intellij

Document run_config_utils.py

• meta_design
  • overrides
  • default_design_path
  • default_design_paths
• runnable_metadata
• .pinjected.py
  • override_design
  • default_design

A validator is required for a design to prevent the user from providing unwanted stuff during runtime.

Make default_design_paths non-mandatory in __meta_design__

I realized I have not been using default_design_paths to switch experiments.

Make refactoring support using GPT4

When using this library, you end up with many small components.
To make the program maintainable, sometimes a refactoring or grouping is preferred.
To this end, we might add a gpt-4 powered refactoring scheme.

Resource Cleanup Feature

We need to be able to register deconstructors.

Make Design Composition AST to Include Validator and Metadata

• #24
• #25
• #26
• #27

For those features, I need to extract the Design interface.

A metadata is required for a design to make it possible to provide summary and tags for logging purpose, such as wandb.

Make runnable Injected be overridable with 'with' block

Add Read the Docs

Add Metadata for Visualization

Currently, the large global dependency variable such as 'logger', 'wandb', tends to make the visualization graph look like spaghetti.

We should have some way to mitigate the strength of such large dependency variable, so that we can focus on logical dependencies of the app.

To do so, we need to let an Injected have a metadata for visualization.

Then implement DesignWithSummary, DesignWithTags, etc.