Register a new entity with parameters

Now, since we have one entity. Let’s spice things up with more complicate entity by creating a Report class at app/

class Report(object):
    def __init__(self,
        self.calculator        = calculator
        self.assignment_scores = assignment_scores  # max score = 10
        self.final_exam_score  = final_exam_score   # max score = 100

    def grade(self):
        total_scores     = sum(self.assignment_scores)
        total_max_scores = (10 * len(self.assignment_scores))
        assignment_part  = total_scores / total_max_scores
        final_exam_part  = final_exam_score / 100

        grade_ratio = self.calculator.add(
            assignment_part * 0.7,
            final_exam_part * 0.3

        return grade_ratio * 100

At this point, again, Imagination does not know about the report. To do so, let’s register an entity of an instance of in containers.xml:

    <!-- ... (omitted) ... -->
    <entity id="report.bob" class="">

        <!-- Pass [2, 0, 1, 8, 6, 9, 7, 5] (list of integers)
             as "assignment_scores" -->
        <param type="list" name="assignment_scores">
            <item type="int">2</item>
            <item type="int">0</item>
            <item type="int">1</item>
            <item type="int">8</item>
            <item type="int">6</item>
            <item type="int">9</item>
            <item type="int">7</item>
            <item type="int">5</item>

        <!-- Pass 89 (integer)
             as "final_exam_score" -->
        <param type="int" name="final_exam_score">89</param>

        <!-- Pass the reference of the "calc" entity
             as "calculator" -->
        <param type="entity" name="calculator">calc</param>

where report.bob is the entity ID.


In case you are confused, here is the equivalent code.

# From the previous page...
from app.util import Calculator

calc = Calculator()

# Now, to work with the report class.
from import Report

report = Report(calc, [2, 0, 1, 8, 6, 9, 7, 5], 89)

The key differences at this point are:

  • neither the calc entity and the report.bob entity are not instantiated immediately until the report.bob entity is requested/activated,
  • the calc is always activated before the report.bob entity as calc is a dependency of report.bob.
  • the objects are still living only in the scope of the container.

How to work with the report entity

To refer the report entity, for example, in, simply use report_bob = assembler.core.get('report.bob')

Now, to actually use the entity, let’s add something to the end of

# Omitted the code for already shown above
report_bob = assembler.core.get('report.bob')
print(report_bob.grade())  # STDOUT: 59.94999...

So, as you can see, the entity works pretty much like a normal object, except the key differences mentioned earlier.

What can you define as parameters or items?

Type Name Data Type Example PCDATA, child nodes
str Unicode (default) bamboo
bool Boolean (bool) [1] true, false
float Float (float) 1.2, 2.0
int Integer (int) 123
class Class reference [2] argparser.ArgumentParser
entity An Imagination entity [3] report.bob (Entity ID)
list Python’s List (list) (See an example below)
dict Python’s Dictionary (dict) (See an example below)

Here is an example. From:

    <entity class="foo.Bar" id="panda">
        <param type="bool" name="enabled">false</param>
        <param type="dict" name="data">
            <item type="list" key="collection">
                <item type="str">shiroyuki</item>
                <item type="str">is</item>
                <item type="str">happy</item>
            <item type="str" key="code">1234</item>

The equivalence to the Python code used to instantiate this entity will be:

panda = foo.Bar(enabled = False, data = {
        'collection': ['shiroyuki', 'is', 'happy'],
        'code': 1234,


How to define parameters and items can be used with a factorized entity, which will be mentioned in the next step.


For more information about the DTD of the configuration file, please check out the DTD on GitHub.


[1]Only any variations (letter case) of the word ‘true’ or ‘false’ are considered as a valid boolean value.
[2]An import path of a class, as known as a fully-qualified class name, e.g., argparser.ArgumentParser
[3]Any Imagination entity (see Definitions used in this documentation)

Next step? Dynamically define an entity with a factory entity.