xeno: The Python dependency injector from outer space.
xeno at its core is a simple Python dependency injection framework. Use it when
you need to manage complex inter-object dependencies in a clean way. For the
merits of dependency injection and IOC, see
https://en.wikipedia.org/wiki/Dependency_injection.
xeno should feel pretty familiar to users of Google Guice in Java, as it
is somewhat similar, although it is less focused on type names and more
on named resources and parameter injection.
xeno also offers xeno.build, a build automation framework built atop the core
dependency injection inspired by Invoke. It is
intended to come with batteries-included tools for making C/C++ projects,
executing shell scripts, batching, and more. It is built on the concept of
composable "recipes", which are generic instructions for building different
types of filesystem targets.
Installation is simple. With python3-pip, do the following:
$ sudo pip install -e .
Or, to install the latest version available on PyPI:
$ sudo pip install xeno
To use xeno.build to build a simple C software project, first create a file
called build.py in your repo (it can be called anything, but this is
customary). Follow this template example for guidance:
#!/usr/bin/env python3
from xeno.build import *
# TODO: Add recipes, providers, and tasks here.
build()
Then, you can import the compile recipe from xeno.recipes.c:
from xeno.recipes.c import compile, ENV
ENV here is the default environment variables that compile will use by
default. It defaults to using clang to compile C projects, you can change
that here, and you can add additional compile-time flags. The ENV object is
of type xeno.shell.Environment, which allows for some complex shlex-based
joining and recombining of flags, such that you can additively compose the
enviornment with defaults and/or what may be specified outside the build script.
You can also provide your own environment variables via the env= parameter to
compile.
ENV['CC'] = 'gcc'
ENV += dict(
LDFLAGS='-g'
)
Let's create a provider that lists all of our source files and another that
lists our headers. This will be useful for defining our tasks and using the
compile recipe.
from pathlib import Path
@provide
def source_files():
return Path.cwd().glob("src/*.c")
@provide
def header_files():
return Path.cwd().glob("include/*.h")
Next, let's define a single default task that builds our program.
@task(default=True)
def executable(source_files, header_files):
return compile(source_files, target="my_program", headers=header_files)
compile can take iterables of source files and/or combinations of strings and
lists in *args. In this case, we elected to specify a target name for the
program. If this wasn't the case, the name of the resulting target would be
based on the name of the first source file. This is ideal if there is only one
source being provided or if the main source file is always provided first and is
the desired name of the executable, but in this case it would be whatever came
first in the directory order which isn't deterministic or ideal.
Specifying the headers= parameter here links the recipe to our header files
as static file dependencies. If these files change, the recipe is acknowledged
to be outdated, and will be rebuilt the next time the build script is run even
if an executable target already exists.
That's it! Let's put it all together, and then we'll have a build script for our program.
#!/usr/bin/env python3
from xeno.build import *
from xeno.recipes.c import compile, ENV
from pathlib import Path
ENV['CC'] = 'gcc'
ENV += dict(
LDFLAGS='-g'
)
@provide
def source_files():
return Path.cwd().glob("src/*.c")
@provide
def header_files():
return Path.cwd().glob("include/*.h")
build()
Mark this script as executable and run it as ./build.py, or use python build.py. Be sure to check out ./build.py --help for a list of command line
options and running modes. xeno.build is smart and can create addressable
targets from a variety of different nested recipe construction scenarios, so
build more complex scripts and try out ./build.py -L to see them all!
Watch this space for more in-depth documentation to come in the near future.
To use xeno as a dependency injection framework, you need to create a
xeno.Injector and provide it with modules. These modules are regular
Python objects with methods marked with the @xeno.provider
annotation. This annotation tells the Injector that this method
provides a named resource, the same name as the method marked with
@provider. These methods should either take no parameters (other
than self), or take named parameters which refer to other resources
by name, i.e. the providers can also be injected with other resources in
order to build a dependency chain.
Once you have an Injector full of resources, you can use it to
inject instances, functions, or methods with resources.
To create a new object instance by injecting resources into its
constructor, use Injector.create(clazz), where clazz is the
class which you would like to instantiate. The constructor of this class
is called, and all named parameters in the constructor are treated as
resource references. Once the object is instantiated, any methods marked
with @inject are invoked with named resources provided.
Resources can be injected into normal functions, bound methods, or
existing object instances via Injector.inject(obj). If the parameter
is an object instance, it is scanned for methods marked with @inject
and these methods are invoked with named resources provided.
In this simple example, we inject an output stream into an object.
import sys
from xeno import *
class OutputStreamModule:
@provide
def output_stream(self):
return sys.stdout
class VersionWriter:
def __init__(self, output_stream):
self.output_stream = output_stream
def write_version(self):
print('The python version is %s' % sys.version_info,
file=self.output_stream)
injector = Injector(OutputStreamModule())
writer = injector.create(VersionWriter)
writer.write_version()
Checkout test.py in the git repo for more usage examples.
xeno.build targets can now receive arguments! All args after a lone '@' arg are packed into an
implicit argv resource that can be injected into targets automatically.run_as functionality in ShellRecipe.**kwargs pass-thru for xeno.shell.check() for passing args to subprocess.check_output().build.py and checks its Python AST
for references to "xeno" before trying to run "./build.py deps" if "build.py"
is present in the resulting repository.update() override to xeno.shell.Environment which takes
the same arguments as select() but updates the dictionary in-place
instead of making and returning a new one.xeno.recipes.**.xeno.cookbook is deprecated.fnmatch.@recipe factory decorator for @factory.setup recipe, which is not part
of the recipe inputs or outputs but is needed to fulfill the task.@recipe decorator to xeno.build to denote recipe functions.xeno.build module, a declarative build system driven by IOC.xeno.color offering basic ANSI color and terminal control.@injector.provide, eliminating the need for modules
in some simple usage scenarios.Injector into AsyncInjector and SyncInjector to allow injection to be performed
in context of another event loop if async providers are not used.AsyncInjector to actually support asynchronous resolution of dependencies.Injector.get_ordered_dependencies to get a breadth first list of
dependencies in the order they are built.BACKWARDS INCOMPATIBLE CHANGE
@alias on methods instead.
This was removed to allow xeno code to play nicely with PEP 484 type hinting.BACKWARDS INCOMPATIBLE CHANGE
'params' method attribute
is carried forward.Injector now adds a 'resource-name' attribute to resource methods allowing
the inspection of a resource's full canonical name at runtime.Injector.provide_async(). Note that resource are always run within an
event loop and should not use inject(), provide(), or require()
directly, instead they should use inject_async(), provide_async(), and
require_async() to dynamically modify resources.Injector.scan_resources() to allow users to scan for resource names with the given attributes.Attributes.merge() to assist with passing attributes down to functions which are wrapped in a decorator.MethodAttributes.wraps() static decorator to summarize a common use case of attribute merging.MethodAttributes.add() as a simple static decorator to add attribute values to a method's attributes.Namespace.enumerate() in favor of Namespace.get_leaves().injector.loop).Injector.get_namespace(). This is useful for users who want to list the contents of namespaces.Injector.get_dependency_graph().BACKWARDS INCOMPATIBLE CHANGE
Code using the old namespace separator can be made to work by overriding the value of xeno.Namespace.SEP:
import xeno
xeno.Namespace.SEP = '::'
:: to escape their module's namespace, e.g. ::top_level_item@const() module annotation for value-based resourcesInjector.get_dependency_tree() to fetch a tree of dependency names for a given resource name.MissingResourceError and MissingDependencyError exception types.@namespace('Name') decorator for modules to specify that all resources defined in the module should be scoped within 'Name::'.@name('alt-name') to allow resources to be named something other than the name of the function that defines them.@alias('alt-name', 'name') to allow a resource to be renamed within either the scope of a single resource or a whole module.@using('NamespaceName') to allow the contents of the given namespace
to be automatically aliases into either the scope of a single resource or
a whole module.def my_resource(name: 'Name::something-important'):xeno.MethodAttributes works: it now holds a map of attributes
and provides methods get(), put(), and check()xeno.MethodAttributes instead of named
object attributes to make attribute tagging more flexible and usable by
the outside world, e.g. for the new injectors.FAQs
The Python IOC app and build framework from outer space.
We found that xeno demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.