Back in 2007 I started programming in python. At first, the goal was
to learn how to write programs the pythonic way, being my background a
Java Enterprise programmer, I wanted to avoid programming java-like
in python.
We started building a web application, using Pylons, SQLAlchemy andp
Mako as the base frameworks. At first we struggled with poor
documentation (we were used to have lots of books about each
framework in java), but as the time passed, we started feeling
comfortable with python and its ways.
The project became bigger and bigger, and it was at that time that we
started missing Java and its "bureaucratic" way of coding. Don't
get me wrong, bureaucracy is not a bad thing. The issue is unnecessary
bureaucracy. We started missing static types, lack of module variables,
long package names, and inversion of control to rule them all.
At that time we started using "the java way of coding" in python, in order
to make the project more maintainable. For example, we quit using the
sqlAlchemy session as a module variable, and started injecting it. We
erased every static reference to a module variable, and we also wanted
to get good package names (at first they seem to be the same as java,
but that's misguided).
So, we needed an inversion of control (IoC) library and started to look for one.
Why a new one?
When we started looking for an IoC library, we didn't find one that filled
ours needs. The exception was Spring-Python, but from our point of view,
it was a port one on one of the Java Spring framework; and we didn't want
something that complex.
What we were looking for, was something that with much of the Spring
IoC capabilities, but taking into consideration that this was python
and not Java: There are things that are simpler to do in python,
and other that are simpler to do in Java. Above all, we wanted
to say "inject this instance on that other
instance" in the simplest way possible. That was the reason we decided to do our own. I named it "ControlFreak"
How and When?
This is kind of a disclaimer, because ControlFreak was built on spare
hours, spare and sparse hours. And it's something I would like to
refactor, probably as a whole, when I found the time for it.
Enough of introducction, let's me show what is controlfreak!
ControlFreak: The library
Controlfreak is a IoC library with capabilities similar to what
spring does in Java. But there are some changes on it's design
that are worth to mention.
The source code can be found in a SVN repository
. Also, controlfreak depends on pycommons, that can be found in this
svn repo.
Components
When you code, you tend to think about interfaces and the different
implementations of them. It's like you have a contract, and several
providers of that contract.
Discussing with a colleague of mine, we thought that it would be
interesting to take that concept into the IoC configurations. So, that
you won't be working just with beans, but with components. A component
is a group of beans, that, one can think, provides (or exports) some
beans. For example, a database component, will provide a session
bean. And one could have different implementations of this database
component. In order to take advantage of this metaphor is that
components where created. A component, may require other component to
work properly. For example, the DAO components will need the database
component to function properly, no matter who or how is this other
component "implemented"
So, in controlfreak, the application is a bundle of components, wired
together and configuration files for everything that is not beans.
Python Static Beans
When considering different alternatives to inject model objects, we
arrived to a different approach to the one we would took in java.
To inject model objects with services and others beans, one would need
to intercept the model object creation, so as to let the IoC library
to create the object. The ORM is the one usually creating model
objects, so one would need to intercept the model creation there.
When making queries that return hundreds of objects, objects that
won't probably use any of their injected properties, one starts to
wonder if the overhead of creating those objects with IoC makes
sense. But that's a question I don't plan to answer here.
Our solution, doesn't involve injecting model objects, because we end
up injecting model classes. This is what we call static beans. Classes
in python are the same as instances, just objects. So it's pretty easy
to inject them with properties, not on creation, but afterwards.
There's a catch on using class injection, instead of instance
injection. The injected properties must be stateless, not dependant of
the current instance that is calling them. But that's usually the case
with services.
ControlFreak ApplicationContext
The ApplicationContext class is the same as Spring's one. That is, it
is given an application's configuration; and we can use it as a
Bean's Locator using the get() method.
The static beans are initialized at the same time as the
ApplicationContext, cause they inject already created objects such as
class o modules.
All other beans are created on demand, and they are cached for later
use.
Right now the library supports the following kind of beans:
- bean: Constructs and inject a class
- factory: Creates a bean by calling a function (callable)
- alias: An alias of another bean
- map: A map of beans
- list: a list of beans
- static: Inject on already created objects (on ApplicationContext
initialization), such as class or module objects.
Configuration
At this moment the only supported configuration format is yaml files.
There are 3 kinds of yaml files to define:
- components definition
- configuration variables for components
- application definition
Component's File
A component is defined by a name, required config keys, required
components and beans definitions. Several components can be defined
in the same file. That is, a component file is something like:
component-name:
config-keys:
- a-config-key
- another-config-key
required-components:
- other-comp-name
definitions:
# beans definitions
other-component-name:
#same as before
# ...
Inside 'definitions' goes all components beans, next I'll show how to
configure each of the bean's types.
A bean of type 'bean' can have setter or construction injection, so it
goes:
renderer:
type: bean
path: renderers.html.impl:HtmlRenderer
constructor-args:
debug_mode: config:debug_mode
renderer:
type: bean
path: renderers.rest.impl:ReStructuredTextRenderer
properties:
syntax: bean:syntax_rules
The bean's name in each case is 'renderer', one uses constructor
injection, and the other setter injection. The first has a
constructor's keyword argument named 'debug_mode' and the value to set
is the config-key of the component 'debug_mode'. The second bean, has
a property named 'syntax' set with another bean, named
'syntax_rules'. This bean, must be in the same component. If a bean
from another component is needed, first you need to declare the other
component in 'required-components' of the component, and then, when
referring to the bean, you should use it's absolute name, that is:
'comp_name::bean_name'.
A bean of type 'factory', has only constructor-args, so it goes:
syntax_rules:
type: factory
path: renderers.rest.rules:create_rules
constructor-args:
keywords: config:accepted_keywords
If instead of a keyword argument, you want to use positional
arguments, you would place a keyword the position of the argument,
beginning with 0.
A bean of type 'alias' is just a link to another bean, so it goes:
documents_generator:
type: alias
target: simple_generator
A bean of type 'map' or 'list' needs you to define 'properties' as a
dictionary or list depending the case. Examples of this are:
rules_map:
type: map
properties:
rule1: bean:some_rule
rule2: bean:some_other_rule
exceptions_list:
type: list
properties:
- bean:some_exception
- my-string-exception
A bean fo type 'static' has only setter injection, because
controlfreak is not involved in the object creation. For example:
api-accounts:
type: static
path: popserver.controllers.api.accounts:AccountsController
properties:
service_dao: bean:dao::serviceDAO
account_dao: bean:dao::accountDAO
user_dao: bean:dao::userDAO
account_service: bean:pop-services::accountService
Configuration Variables File
A configuration variables file, defines a values for component's
required configuration values. So if we have a component named
'database' that requires a config value 'database_url' the config file
would look like
database:
database_url: postgres://user:password@mydbserver:5432/dbname
In the same configuration file one can place configuration values for
several components.
Application File
An application file, is where we bundle several components files, with
their configuration files. The reason to separate the config values
from the component's bean is because the config values will probably
change more often than the bean's wiring structure. Also, I believe
that is clearer to see configuration values on a separate place
than seeing them within the beans that are, in a way,
more coupled with the programming task itself.
Another thing one can do in the application file is to redefine the
components wiring. That is, to decide witch components will fulfill
the required components of other component. For example, suppose that
we have two components that "implements" the same contract, one it's
called 'dummy-cache' and the other 'standard-cache'. Now, we also have
a component, let's say 'services' that requires a 'cache'
component. The application file would be the place to wire one of the
cache components to the services components: dummy for development,
and standard for production environment.
Another feature of the application file is to have a same component,
configured with two different config values at the same time. Think on
the component as a class definition, that we would want to instantiate
with different values each time. For example, we have a database
component, and we are using two databases, and we need to use the same
component with two different config values. To do this, we define two
aliases for 'database' in application context: 'database1' and
'database2'. In the config file, we will then set the values for 'database1' and
'database2'; and not for 'database'.
An example of an application file is:
includes: #component files to include
- "%(here)s/../../components/general/amazon-mock.yaml"
- "%(here)s/../../components/general/cache.yaml"
- "%(here)s/../../components/general/database.yaml"
- "%(here)s/../../components/general/eye-services.yaml"
- "%(here)s/../../components/general/pop-services.yaml"
- "%(here)s/../../components/general/core-model.yaml"
- "%(here)s/../../components/general/dao.yaml"
- "%(here)s/../../components/general/domains.yaml"
- "%(here)s/../../components/general/extauth-services.yaml"
customization: #aliases and rewiring as explained
cache:
required-components:
cache-customization: dummy-cache-customization
eye-services:
required-components:
item-age-customization: testing-item-age-customization
config: #config files to read
- "%(here)s/../base/config.yaml"
- "%(here)s/config.yaml"
Using the library
To load a control freak set up, one would to something like:
from controlfreak.config.yaml import createApplicationContext
appctx = createApplicationContext('my-app-file.yaml')
To use the Application Context as a bean's locator, one need to give
it the absolute path of a bean, that is, the component and the bean
name together. For example:
session = appctx.get('database::session')
...
This would result on the 'session' bean from the 'database' component.
Final Example
Here's an example of each file:
component file:
reSt-renderer:
config-keys:
- accepted_keywords
definitions:
renderer:
type: bean
path: renderers.rest.impl:ReStructuredTextRenderer
properties:
syntax: bean:syntax_rules
syntax_rules:
type: factory
path: renderers.rest.rules:create_rules
constructor-args:
keywords: config:accepted_keywords
html-renderer:
config-keys:
- debug_mode
definitions:
renderer:
type: bean
path: renderers.html.impl:HtmlRenderer
constructor-args:
debug_mode: config:debug_mode
documents-generator:
required-components:
- renderer
definitions:
documents_generator:
type: alias
target: simple_generator
simple_generator:
type: bean
path: generators.simple:SimpleGenerator
propreties:
renderer: bean:renderer:renderer
complex_generator:
type: bean
path: generators.complex:ComplexGenerator
constructor-args:
rules: bean:rules_map
exceptions: bean:exceptions_list
rules_map:
type: map
properties:
rule1: bean:some_rule
rule2: bean:some_other_rule
exceptions_list:
type: list
properties:
- bean:some_exception
- my-string-exception
some_rule:
type: bean
path: rules:SomeRule
some_other_rule:
type: bean
path: rules:SomeOtherRule
some_exception:
type: bean
path: excpetions:MyGeneratorException
config file:
reSt-renderer:
accepted_keywords:
- hey
- jo
html-renderer:
debug_mode: True
application file:
includes:
- "%(here)s/my-components.yaml"
config:
- "%(here)s/my-config.yaml"
Well, that's all, I hope you will find this IoC library useful!
and project related settings, such as the project id in the Mantis database or the Crono project unixname in Crono, which are configured in each project maven's pom like these:
Tree-map: a tool that works perfectly when comparing projects on a specific subject.
Timeline: a tool that lets you graphically see how the project evolves through time.
Posts
