Welcome to Injectify¶

Welcome to Injectify’s documentation! Get started with Installation and then get an overview with the Quickstart. More information on a specific function, class, or method can be found in the injectify package section.

User Guide¶

This part of the documentation, which is mostly prose, begins with some background information about Flask, then focuses on step-by-step instructions for getting the most out of Injectify.

Installation¶

Python Version¶

Injectify is compatible with Python 3.5 and newer.

Dependencies¶

These packages will be installed automatically with Injectify. If you don’t have pipenv, head over the Pipenv website for installation instructions.

astunparse is an AST unparser for Python.

Pipenv¶

The recommended way to install the injectify package is to simply use pipenv.

$ pipenv install injectify

Pipenv is a tool that automatically creates and manages a virtual environment for your project.

Virtual Environment¶

If you prefer, pip and virtualenv can be used separately. Python comes bundled with the venv module to create virtual environments, which you can use.

Create an Environment¶

Create a project folder and a venv folder within:

$ mkdir myproject
$ cd myproject
$ python3 -m venv venv

Activate the environment¶

Before you work on your project, activate the corresponding environment:

$ . venv/bin/activate

On Windows:

> venv\Scripts\activate

Your shell prompt will change to show the name of the activated environment.

Install Injectify¶

Within the activated environment, use the following command to install Injectify:

$ pip install Injectify

Injectify is now installed. Check out the Quickstart or go to the Documentation Overview.

Quickstart¶

Eager to get started? This page gives a good introduction to Injectify. Follow Installation to set up a project and install Injectify first.

A Minimal Application¶

Injecting code with Injectify is very simple.

from injectify import inject, HeadInjector

def foo(x):
    return x

print(foo(10))  # 10

@inject(target=foo, injector=HeadInjector())
def handler():
    x = 9000

print(foo(10))  # 9000

So what does this code do?

We begin by importing from the injectify module.
Next we defined a function foo that we will inject code into.
When we print the result of foo(10), we get 10.
We then use the inject() decorator. The first argument is the target object. This is the object that will have code injected into. The second argument is the injector. An injector is used to indicate the point at which the target object should be injected. Here we use the HeadInjector for our injector. This injector indicates that the code should be injected at the top of the target object.
Then we defined a function handler. The body of this function is the code that will be injected into foo.
Now when we print the result of foo(10), we get 9000.

Thus, after we inject the body of handler, the function foo then has the following code:

def foo(x):
    x = 9000
    return x

Injection Points¶

The first thing we need to be able to do is identify parts of the target object. Let’s decorate a function with markers which show some of the areas we are able to easily identify.

def bar():
    # HEAD

    def wrapper():  # NESTED
        pass

    x = 10  # FIELD

    if x > 10:
        # RETURN
        return True
    else:
        # RETURN
        return False

    # TAIL

The markers indicate parts of the object’s anatomy:

HEAD indicates the point at the top of the target object.
TAIL indicates the point at the bottom of the target object.
FIELD indicates the point at a field’s assignment.
RETURN indicates the point before a return statement.
NESTED indicates a nested function.

Note

Not all Python objects have all these injection points. For example, a module does not have a return statement, so a module has no RETURN marker.

Injectors¶

The injector you use tells Injectify the injection point to use when merging the code inside the target object. Each of the markers above has a corresponding injector.

For more information on injectors you can visit the injectify.injectors module documentation.

API Reference¶

If you are looking for information on a specific function, class or method, this part of the documentation is for you.

injectify package¶

Submodules¶

injectify.api module¶

injectify.injectors module¶

injectify.structures module¶

injectify.utils module¶

Module contents¶

Project Info¶

Design notes, legal information and changelog are here for the interested.

History¶

0.2.0¶

Add more tests
Add documentation
Bug fixes

0.1.1¶

Fix dill dependency version

0.1.0¶

Conception!

License¶

BSD 3-Clause License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.