Contents

• Basic usage
  • Bloks
  • Bloks registration
  • Models
  • Overriding Models
  • Standalone executables
    • Add entries in the argparse configuration
    • Create the executable
    • Builtin generic scripts
  • Writing and launching tests
    • Writing tests
    • Launching tests with the nose plugin
    • Launching tests with anyblok_nose
  • Configuration files
    • Syntax
    • Default configuration files

Basic usage

To demonstrate, we will write a simple application; let’s call it WorkApp.

Here are the Models we’ll create, with their fields. Anyblok being an ORM framework, these will be Python classes, backed by database tables.

• Employee

  • name: employee’s name
  • office (Room): the room where the employee works
  • position: employee position (manager, developer…)

• Room

  • number: describe the room in the building
  • address: postal address
  • employees: men and women working in that room

• Address

  • street
  • zipcode
  • city
  • rooms: room list

• Position

  • name: position name

Bloks

Within AnyBlok, all business logic objects, among them in the first place Models must be declared as part of some Blok.

Bloks themselves are subclasses of the Blok base class. They have basic metadata attributes (author, version, dependencies…) and methods to import the business logic objects declarations.

Bloks also bear the methods for installation, update and removal.

Here’s a very minimal (and pretty much useless) valid Blok:

from anyblok.blok import Blok

class MyFirstBlok(Blok):
    """ This is valid blok """

To demonstrate the extreme modularity that can be achieved with Anyblok, we’ll organize the application in four different bloks:

Office blok

File tree:

workapp
├── (...)
└── office_blok
  ├── __init__.py
  └── office.py

__init__.py file:

from anyblok.blok import Blok


class OfficeBlok(Blok):

    version = '1.0.0'
    author = 'Suzanne Jean-Sébastien'
    logo = 'relative/path'

    def install(self):
        """ method called at blok installation time """
        address = self.registry.Address.insert(street='14-16 rue Soleillet',
                                               zip='75020', city='Paris')
        self.registry.Room.insert(number=308, address=address)

    def update(self, latest_version):
        if latest_version is None:
            self.install()

    @classmethod
    def import_declaration_module(cls):
        from . import office

So for instance, in this example, we’ll import the office module (which defines Address and Room Models, see below) and at the time of first installation (detected by latest_version being None), we’ll create an Address and a Room instance right away, as base data.

Note

this anticipates a bit on the Model base usage.

Position blok

File tree:

workapp
├── (...)
└── position_blok
    ├── __init__.py
    └── position.py

__init__.py file:

from anyblok.blok import Blok


class PositionBlok(Blok):

    version = '1.0.0'

    def install(self):
        self.registry.Position.multi_insert({'name': 'CTO'},
                                            {'name': 'CEO'},
                                            {'name': 'Administrative Manager'},
                                            {'name': 'Project Manager'},
                                            {'name': 'Developer'})

    def update(self, latest_version):
        if latest_version is None:
            self.install()

    @classmethod
    def import_declaration_module(cls):
        from . import position  # noqa

Same here, the installation automatically creates some data, in this case Position instances.

Employee blok

Bloks can have requirements. Each blok define its dependencies:

• required:

  list of the bloks that must be installed (and loaded at startup) before

• optional:

  list of bloks that will be installed before the present one, if they are available in the application.

File tree:

employee_blok
├── __init__.py
├── config.py
└── employee.py

__init__.py file:

from anyblok.blok import Blok


class EmployeeBlok(Blok):

    version = '1.0.0'

    required = ['office']

    optional = ['position']

    def install(self):
        room = self.registry.Room.query().filter(
            self.registry.Room.number == 308).first()
        employees = [dict(name=employee, room=room)
                     for employee in ('Georges Racinet',
                                      'Christophe Combelles',
                                      'Sandrine Chaufournais',
                                      'Pierre Verkest',
                                      'Franck Bret',
                                      "Simon André",
                                      'Florent Jouatte',
                                      'Clovis Nzouendjou',
                                      "Jean-Sébastien Suzanne")]
        self.registry.Employee.multi_insert(*employees)

    def update(self, latest_version):
        if latest_version is None:
            self.install()

    @classmethod
    def import_declaration_module(cls):
        from . import config
        from . import employee

EmployeePosition blok:

Some bloks can be installed automatically if some specific other bloks are installed. They are called conditional bloks.

File tree:

employee_position_blok
├── __init__.py
└── employee.py

__init__.py file:

from anyblok.blok import Blok

class EmployeePositionBlok(Blok):

    version = '1.0.0'
    priority = 200

    conditional = [
        'employee',
        'position',
    ]

    def install(self):
        Employee = self.registry.Employee

        position_by_employee = {
            'Georges Racinet': 'CTO',
            'Christophe Combelles': 'CEO',
            'Sandrine Chaufournais': u"Administrative Manager",
            'Pierre Verkest': 'Project Manager',
            'Franck Bret': 'Project Manager',
            u"Simon André": 'Developer',
            'Florent Jouatte': 'Developer',
            'Clovis Nzouendjou': 'Developer',
            u"Jean-Sébastien Suzanne": 'Developer',
        }

        for employee, position in position_by_employee.items():
            Employee.query().filter(Employee.name == employee).update({
                'position_name': position})

    def update(self, latest_version):
        if latest_version is None:
            self.install()

    @classmethod
    def import_declaration_module(cls):
        from . import employee  # noqa

Warning

There are no strong dependencies between conditional blok and bloks, so the priority number of the conditional blok must be bigger than bloks defined in the conditional list. Bloks are loaded by dependencies and priorities so a blok with small dependency/priority will be loaded before a blok with an higher dependency/priority.

Bloks registration

Now that we have our Bloks, they must be registered through the bloks setuptools entry point:

setup(
    # (...)
    entry_points={
        'bloks': [
            'office=workapp.office_blok:OfficeBlok',
            'employee=workapp.employee_blok:EmployeeBlok',
            'position=workapp.position_blok:PositionBlok',
            'employee-position=workapp.employee_position_blok:EmployeePositionBlok',
        ],
    },
)

Models

With AnyBlok, most of the business logic is organized as Models. There are two types of Model:

• SQL: They bear Fields, and correspond to a table in the database, that’s automatically created and updated if needed.
• Non SQL: No persistent data, but still useful to attach methods onto them, which then could be overridden by downstream Bloks.

To declare a Model, use the Declarations.register decorator:

from anyblok import Declarations

@Declarations.register(Declarations.Model)
class AAnyBlokModel:
    """ The first Model of our application """

Note

At this point, it is important to realize that this Model class won’t be used directly in this form, which is but a Declaration. It will actually be just one element of a whole inheritance hierarchy, which AnyBlok constructs for each database, according to its installed Bloks. This is the fundamental way AnyBlok’s flexibility works (see Overriding Models).

Here’s an example SQL model, with just one Column:

from anyblok import Declarations
from anyblok.column import String

register = Declarations.register
Model = Declarations.Model


@register(Model)
class ASQLModel:

    acolumn = String(label="The first column", primary_key=True)

This Model will be backed by the asqlmodel table, whose rows will correspond to Model instances.

Once the application has started, the fully assembled Model class is available within the Registry, which itself can be accessed in various ways, depending on the context.

In particular, the Registry is available on any Model instance as the registry attribute. So, from instance, from a method of another Model, we could create an instance of ASQLModel in this way:

def mymethod(self):
    self.registry.ASQLModel.insert(acolumn="Foo")

Another example would be the install() methods of our Bloks above.

Note

There is a Registry instance for each database, and it holds for each Model the resulting concrete class after all overrides have been applied.

Warning

SQL Models must have a primary key made of one or more columns (those flagged with primary_key=True)

Note

The table name depends on the registry tree. Here the table is asqlmodel. If a new model is defined under ASQLModel (example UnderModel: asqlcolumn_undermodel), the registry model will be stored as Model.ASQLModel.UnderModel

Let’s then proceed with our more concrete example:

office_blok.office:

from anyblok import Declarations
from anyblok.column import Integer, String
from anyblok.relationship import Many2One

register = Declarations.register
Model = Declarations.Model


@register(Model)
class Address:

    id = Integer(label="Identifier", primary_key=True)
    street = String(label="Street", nullable=False)
    zip = String(label="Zip", nullable=False)
    city = String(label="City", nullable=False)

    def __str__(self):
        return "%s %s %s" % (self.street, self.zip, self.city)


@register(Model)
class Room:

    id = Integer(label="Identifier", primary_key=True)
    number = Integer(label="Number of the room", nullable=False)
    address = Many2One(label="Address", model=Model.Address, nullable=False,
                       one2many="rooms")

    def __str__(self):
        return "Room %d at %s" % (self.number, self.address)

The relationships can also define the opposite relation. Here the address Many2One relation also declares the room One2Many relation on the Address Model.

A Many2One or One2One relationship must have an existing column. The column_name attribute allows to choose the linked column, if this attribute is missing then the value is “‘model.table’.’remote_column’” If the linked column does not exist, the relationship creates the column with the same type as the remote_column.

position_blok.position:

from anyblok import Declarations
from anyblok.column import String

register = Declarations.register
Model = Declarations.Model


@register(Model)
class Position:

    name = String(label="Position", primary_key=True)

    def __str__(self):
        return self.name

employee_blok.employee:

from anyblok import Declarations
from anyblok.column import String
from anyblok.relationship import Many2One

register = Declarations.register
Model = Declarations.Model


@register(Model)
class Employee:

    name = String(label="Number of the room", primary_key=True)
    room = Many2One(label="Office", model=Model.Room, one2many="employees")

    def __str__(self):
        return "%s in %s" % (self.name, self.room)

Overriding Models

If one declares two Models with the same name, the second Model will subclass the first one in the final assembled Model class. This is mostly interesting when the two declarations belong to different bloks.

employee_position_blok.employee:

from anyblok import Declarations
from anyblok.relationship import Many2One

register = Declarations.register
Model = Declarations.Model


@register(Model)
class Employee:

    position = Many2One(label="Position", model=Model.Position, nullable=False)

    def __str__(self):
        res = super(Employee, self).__str__()
        return "%s (%s)" % (res, self.position)

Standalone executables

If the AnyBlok application is an HTTP server running through some WSGI compatibility layer, such as AnyBlok / Pyramid, one does not need to care about running processes: the WSGI server provides them already.

But in other cases, including background processing alongside HTTP workers, we need to setup executables.

Add entries in the argparse configuration

Some applications may require options. Options are grouped by category. And the application chooses the option category to display.

employee_blok.config:

from anyblok.config import Configuration


@Configuration.add('message', label="This is the group message")
def add_interpreter(parser, configuration):
    parser.add_argument('--message-before', dest='message_before')
    parser.add_argument('--message-after', dest='message_after')

Create the executable

The application can be a simple script or a setuptools script. For a setuptools script, add this in the setup.py:

setup(
    ...
    entry_points={
        'console_scripts': ['exampleblok=exampleblok.scripts:exampleblok'],
        'bloks': bloks,
    },
)

The script must display:

• the provided message_before
• the lists of the employee by address and by room
• the provided message_after

scripts.py:

import anyblok
from logging import getLogger
from anyblok.config import Configuration

logger = getLogger()


def exampleblok():
    # Initialise the application, with a name and a version number
    # select the groupe of options to display
    # return a registry if the database are selected
    registry = anyblok.start(
        'Example Blok', argparse_groups=['message', 'logging'])

    if not registry:
        return

    message_before = Configuration.get('message_before')
    message_after = Configuration.get('message_after')

    if message_before:
        logger.info(message_before)

    for address in registry.Address.query().all():
        for room in address.rooms:
            for employee in room.employees:
                logger.info(employee)

    if message_after:
        logger.info(message_after)

Display the help of your application:

jssuzanne:anyblok jssuzanne$ ./bin/exampleblok -h
usage: exampleblok [-h]
                   [--logging-level {NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL}]
                   [--logging-level-qualnames LOGGING_LEVEL_QUALNAMES [LOGGING_LEVEL_QUALNAMES ...]]
                   [--logging-config-file LOGGING_CONFIGFILE]
                   [--logging-json-config-file JSON_LOGGING_CONFIGFILE]
                   [--logging-yaml-config-file YAML_LOGGING_CONFIGFILE]
                   [-c CONFIGFILE] [--without-auto-migration]
                   [--db-name DB_NAME] [--db-driver-name DB_DRIVER_NAME]
                   [--db-user-name DB_USER_NAME] [--db-password DB_PASSWORD]
                   [--db-host DB_HOST] [--db-port DB_PORT] [--db-echo]

[options] -- other arguments

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIGFILE         Relative path of the config file
  --without-auto-migration

Logging:
  --logging-level {NOTSET,DEBUG,INFO,WARNING,ERROR,CRITICAL}
  --logging-level-qualnames LOGGING_LEVEL_QUALNAMES [LOGGING_LEVEL_QUALNAMES ...]
                        Limit the log level on a qualnames list
  --logging-config-file LOGGING_CONFIGFILE
                        Relative path of the logging config file
  --logging-json-config-file JSON_LOGGING_CONFIGFILE
                        Relative path of the logging config file (json). Only
                        if the logging config file doesn't filled
  --logging-yaml-config-file YAML_LOGGING_CONFIGFILE
                        Relative path of the logging config file (yaml). Only
                        if the logging and json config file doesn't filled

Database:
  --db-name DB_NAME     Name of the database
  --db-driver-name DB_DRIVER_NAME
                        the name of the database backend. This name will
                        correspond to a module in sqlalchemy/databases or a
                        third party plug-in
  --db-user-name DB_USER_NAME
                        The user name
  --db-password DB_PASSWORD
                        database password
  --db-host DB_HOST     The name of the host
  --db-port DB_PORT     The port number
  --db-echo

Create an empty database and call the script:

jssuzanne:anyblok jssuzanne$ createdb anyblok
jssuzanne:anyblok jssuzanne$ ./bin/exampleblok -c anyblok.cfg --message-before "Get the employee ..." --message-after "End ..."
2014-1129 10:54:27 INFO - anyblok:root - Registry.load
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Blok 'anyblok-core' loaded
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Assemble 'Model' entry
2014-1129 10:54:27 INFO - anyblok:alembic.migration - Context impl PostgresqlImpl.
2014-1129 10:54:27 INFO - anyblok:alembic.migration - Will assume transactional DDL.
2014-1129 10:54:27 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'system_cache_id_seq' as owned by integer column 'system_cache(id)', assuming SERIAL and omitting
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Initialize 'Model' entry
2014-1129 10:54:27 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Install the blok 'anyblok-core'
2014-1129 10:54:27 INFO - anyblok:root - Registry.reload
2014-1129 10:54:27 INFO - anyblok:root - Registry.load
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Blok 'anyblok-core' loaded
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Blok 'office' loaded
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Assemble 'Model' entry
2014-1129 10:54:27 INFO - anyblok:alembic.migration - Context impl PostgresqlImpl.
2014-1129 10:54:27 INFO - anyblok:alembic.migration - Will assume transactional DDL.
2014-1129 10:54:27 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'address_id_seq' as owned by integer column 'address(id)', assuming SERIAL and omitting
2014-1129 10:54:27 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'system_cache_id_seq' as owned by integer column 'system_cache(id)', assuming SERIAL and omitting
2014-1129 10:54:27 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'room_id_seq' as owned by integer column 'room(id)', assuming SERIAL and omitting
2014-1129 10:54:27 INFO - anyblok:anyblok.registry - Initialize 'Model' entry
2014-1129 10:54:28 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Install the blok 'office'
2014-1129 10:54:28 INFO - anyblok:root - Registry.reload
2014-1129 10:54:28 INFO - anyblok:root - Registry.load
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'anyblok-core' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'office' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'position' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Assemble 'Model' entry
2014-1129 10:54:28 INFO - anyblok:alembic.migration - Context impl PostgresqlImpl.
2014-1129 10:54:28 INFO - anyblok:alembic.migration - Will assume transactional DDL.
2014-1129 10:54:28 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'address_id_seq' as owned by integer column 'address(id)', assuming SERIAL and omitting
2014-1129 10:54:28 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'system_cache_id_seq' as owned by integer column 'system_cache(id)', assuming SERIAL and omitting
2014-1129 10:54:28 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'room_id_seq' as owned by integer column 'room(id)', assuming SERIAL and omitting
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Initialize 'Model' entry
2014-1129 10:54:28 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Install the blok 'position'
2014-1129 10:54:28 INFO - anyblok:root - Registry.reload
2014-1129 10:54:28 INFO - anyblok:root - Registry.load
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'anyblok-core' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'office' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'position' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Blok 'employee' loaded
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Assemble 'Model' entry
2014-1129 10:54:28 INFO - anyblok:alembic.migration - Context impl PostgresqlImpl.
2014-1129 10:54:28 INFO - anyblok:alembic.migration - Will assume transactional DDL.
2014-1129 10:54:28 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'system_cache_id_seq' as owned by integer column 'system_cache(id)', assuming SERIAL and omitting
2014-1129 10:54:28 INFO - anyblok:anyblok.registry - Initialize 'Model' entry
2014-1129 10:54:29 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Install the blok 'employee'
2014-1129 10:54:29 INFO - anyblok:root - Registry.reload
2014-1129 10:54:29 INFO - anyblok:root - Registry.load
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Blok 'anyblok-core' loaded
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Blok 'office' loaded
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Blok 'position' loaded
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Blok 'employee' loaded
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Blok 'employee-position' loaded
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Assemble 'Model' entry
2014-1129 10:54:29 INFO - anyblok:alembic.migration - Context impl PostgresqlImpl.
2014-1129 10:54:29 INFO - anyblok:alembic.migration - Will assume transactional DDL.
2014-1129 10:54:29 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'system_cache_id_seq' as owned by integer column 'system_cache(id)', assuming SERIAL and omitting
2014-1129 10:54:29 INFO - anyblok:alembic.autogenerate.compare - Detected added column 'employee.position_name'
2014-1129 10:54:29 WARNING - anyblok:anyblok.migration - (IntegrityError) column "position_name" contains null values
'ALTER TABLE employee ALTER COLUMN position_name SET NOT NULL' {}
2014-1129 10:54:29 INFO - anyblok:anyblok.registry - Initialize 'Model' entry
2014-1129 10:54:29 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Install the blok 'employee-position'
2014-1129 10:54:30 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'anyblok-core'
2014-1129 10:54:30 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'office'
2014-1129 10:54:30 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'position'
2014-1129 10:54:30 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'employee'
2014-1129 10:54:30 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'employee-position'
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Get the employee ...
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Sandrine Chaufournais in Room 308 at 14-16 rue Soleillet 75020 Paris (Administrative Manager)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Christophe Combelles in Room 308 at 14-16 rue Soleillet 75020 Paris (CEO)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Clovis Nzouendjou in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Florent Jouatte in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Simon André in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Jean-Sébastien Suzanne in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Georges Racinet in Room 308 at 14-16 rue Soleillet 75020 Paris (CTO)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Pierre Verkest in Room 308 at 14-16 rue Soleillet 75020 Paris (Project Manager)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - Franck Bret in Room 308 at 14-16 rue Soleillet 75020 Paris (Project Manager)
2014-1129 10:54:30 INFO - anyblok:exampleblok.scripts - End ...

The registry is loaded twice:

• The first load installs the bloks anyblok-core, office, position and employee
• The second load installs the conditional blok employee-position and runs a migration to add the field employee_name

Call the script again:

jssuzanne:anyblok jssuzanne$ ./bin/exampleblok -c anyblok.cfg --message-before "Get the employee ..." --message-after "End ..."
2014-1129 10:57:52 INFO - anyblok:root - Registry.load
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Blok 'anyblok-core' loaded
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Blok 'office' loaded
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Blok 'position' loaded
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Blok 'employee' loaded
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Blok 'employee-position' loaded
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Assemble 'Model' entry
2014-1129 10:57:52 INFO - anyblok:alembic.migration - Context impl PostgresqlImpl.
2014-1129 10:57:52 INFO - anyblok:alembic.migration - Will assume transactional DDL.
2014-1129 10:57:52 INFO - anyblok:alembic.ddl.postgresql - Detected sequence named 'system_cache_id_seq' as owned by integer column 'system_cache(id)', assuming SERIAL and omitting
2014-1129 10:57:52 INFO - anyblok:alembic.autogenerate.compare - Detected NOT NULL on column 'employee.position_name'
2014-1129 10:57:52 INFO - anyblok:anyblok.registry - Initialize 'Model' entry
2014-1129 10:57:52 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'anyblok-core'
2014-1129 10:57:52 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'office'
2014-1129 10:57:52 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'position'
2014-1129 10:57:52 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'employee'
2014-1129 10:57:52 INFO - anyblok:anyblok.bloks.anyblok_core.declarations.system.blok - Load the blok 'employee-position'
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Get the employee ...
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Sandrine Chaufournais in Room 308 at 14-16 rue Soleillet 75020 Paris (Administrative Manager)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Christophe Combelles in Room 308 at 14-16 rue Soleillet 75020 Paris (CEO)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Clovis Nzouendjou in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Florent Jouatte in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Simon André in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Jean-Sébastien Suzanne in Room 308 at 14-16 rue Soleillet 75020 Paris (Developer)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Georges Racinet in Room 308 at 14-16 rue Soleillet 75020 Paris (CTO)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Pierre Verkest in Room 308 at 14-16 rue Soleillet 75020 Paris (Project Manager)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - Franck Bret in Room 308 at 14-16 rue Soleillet 75020 Paris (Project Manager)
2014-1129 10:57:52 INFO - anyblok:exampleblok.scripts - End ...

The registry is loaded only once, because the bloks are already installed

Builtin generic scripts

Anyblok provides some helper generic console scripts out of the box:

• anyblok_createdb

• anyblok_updatedb

• anyblok_interpreter .. note:

  if IPython is in the sys.modules then the interpreter is an IPython interpreter
  

• anyblok_nose (nose test)

TODO: I know it’s not a setuptools documentation but it could be kind to show a complete minimalist exampe of setup.py with requires (to anyblok). We could also display the full tree from root

A direct link to download the full working example.

Writing and launching tests

We want to foster a very test friendly culture in the AnyBlok community, that’s why we cover tests writing and launching in this “Basic usage” page.

That being said, such a dynamic framework represent a challenge for tests, because the application constructs, e.g., application Models, must not be imported directly. Instead, a proper Registry must be set up one way or another before the test launcher kicks in, and that interferes wildly with coverage reports.

Also, the Anyblok Registry being tightly tied to a database, we need to set it up before hand (most common in application tests) or manage it from the tests (mostly meant for the framework tests, but could find its use for some applications or middleware).

Note

all of this means that the tests we’re discussing aren’t stricto sensu unit tests, but rather integration tests. Nevertheless, we casually speak of them as unit tests if they stay lightweight and are about testing individual AnyBlok components.

Nothing prevents application developers to also write true unit tests, perhaps for subroutines that don’t interact with the database at all.

To address these challenges, AnyBlok ships with helper base classes (see below), and provides two different ways to lauch the tests, both based on nose.

Writing tests

The most commonly used helper base class is BlokTestCase. It provides everything Blok developers need for their daily workflow: a working registry is setup once for the whole test run, is exposed as a class attribute, and the tests are insulated by rollbacking the database transaction.

Another interesting base class is SharedDataTestCase. It uses database savepoints to share a common fixture among tests of the same class. In concrete test subclasses, any data created by the setUpSharedData classmethod will be available to all tests, and will be rollbacked once all of them have run. This can save a lot of time in the test runs.

Note

it is advisable to delete the imported base class from the test module, like so:

from anyblok.tests.testcase import SharedDataTestCase

class MyTest(SharedDataTestCase):

   (...)

del SharedDataTestCase

in some cases, test launchers can be confused by the presence of the base class in the module namespace, resulting in some double launchings.

We should also mention DBTestCase, which is more suited for code that interacts at a deeper level with the framework (including the framework itself). It creates and drops the database for each test case, and therefore makes the whole run terribly slow, but that’s sometimes a price worth paying.

Warning

One must separate the launches of BlokTestCases and of DBTestCases in different runs.

Launching tests with the nose plugin

Summary: use this if you need accurate coverage results. This is a good fit for Continuous Integration (CI).

AnyBlok comes with a nose plugin right away. Once the testing database is set up, and described by proper environment variables or default configuration files, you can test your bloks with the --with-anyblok-bloks option.

Warning

don’t use this if you need advanced tests selection such as replaying failed tests, or cherry picking one specific test which triggers imports that are unwanted before the registry is set up.

Prefer anyblok_nose in that case.

Here’s an example, adapted from AnyBlok’s .travis.yml:

export ANYBLOK_DATABASE_URL=postgresql:///travis_ci_test
anyblok_createdb --install-all-bloks
nosetests anyblok/bloks --with-anyblok-bloks -v -s --with-coverage --cover-package=anyblok

In case the coverage plugin is also in use, as in the example above, Anyblok’s nose plugin will perform all Blok loadings and Model final classes assemblies (i.e., loads of BlokManager and RegistryManager) after the coverage startup, thus giving you correct coverage results)

Note

If you want to test several Bloks depending on each other, while making sure the tests of the lower ones don’t need the upper ones being installed, and still maintain proper coverage results, you can do it with several runs.

For an example of this, see anyblok_wms_base/.travis.yml

Launching tests with anyblok_nose

Summary: use this if you want the full tests selection capabilities of nosetests, and don’t care about coverage. This is a good fit for development and debug workflows.

AnyBlok provides the anyblok_nose script right out of the box. It takes care of all needed AnyBlok initialization, and only then invokes the nose launcher.

This is the most respectful way of nose internals, but coverage is blind with respect to any code imported or run during the Registry setup. You can use it with --failed, cherry pick any specific test without worrying whether that’ll trigger nose importing a declaration class before the Registry, etc.

Synopsis:

anyblok_nose [ANYBLOK OPTIONS...] -- [NOSE ARGUMENTS...]

Typical usage is with a configuration file <basedoc_conf_files> (this example also demonstrate the usage of more nose options):

anyblok_nose -c mytest.cfg -- workapp/employee_blok --with-doctest --failed --pdb

Configuration files

Custom or builtin AnyBlok console scripts accept the -c parameter, to specify a configuration file instead of passing all the options in the command line. Example:

anyblok_createdb -c myapp.cfg

Syntax

The configuration file allow to load all the initialisation variable:

[AnyBlok]
key = value

You can extend an existing config file:

[AnyBlok]
extend = ``path of the configfile``

The logging configuration are also loaded, see logging configuration file format:

[AnyBlok]
logging_configfile = ``name of the config file``
# json_logging_configfile = logging config file write with json
# yaml_logging_configfile = logging config file write with yaml

loggers]
keys=root,anyblok

[handlers]
keys=consoleHandler

[formatters]
keys=consoleFormatter

[logger_root]
level=INFO
handlers=consoleHandler

[logger_anyblok]
level=INFO
handlers=consoleHandler
qualname=anyblok
propagate=1

[handler_consoleHandler]
class=StreamHandler
level=INFO
formatter=consoleFormatter
args=(sys.stdout,)

[formatter_consoleFormatter]
class=anyblok.logging.consoleFormatter
format=%(database)s:%(levelname)s - %(message)s
datefmt=

Default configuration files

You can define default system or user configuration file in fonction of your OS:

• linux

  • system: /etc/xdg/AnyBlok/conf.cfg
  • user: /home/user name/.config/AnyBlok/conf.cfg

• mac os x

  • system: /Library/Application Support/AnyBlok/conf.cfg
  • user: /Users/user name/Library/Application Support/AnyBlok/conf.cfg

Note

Works also for windows, See https://pypi.python.org/pypi/appdirs. The entry used are:

• system: site_config_dir
• user: user_config_dir

Theses configuration files are loaded before the specific configuration file. If the configuration file does not exist then it will not raise error