Globals - accessing doit internals

During the life-cycle of a command invocation, some properties of doit are stored in global singletons, provided by the doit.Globals class.

class doit.globals.Globals

Accessors to doit singletons.

Variables

dep_manager – (doit.dependency.Dependency) The doit dependency manager, holding all persistent task data.

dep_manager

The doit dependency manager holds the persistent state of doit. This includes relations of tasks among each other or results, returned from their latest runs. It basically consists of all the information stored in doit’s database file.

The dep_manager attribute is initialized right before tasks are loaded, which means it allows to be accessed during all task evaluation phases, in particular during:

• Task creation, i.e. from the body of any task_* function.

• Task execution, i.e. from the code executed by one of the task’s actions.

• Task cleanup, i.e. from the the code executed by one of the tasks’s clean activities.

The Dependency class has members to access persistent doit data via its API:

class doit.dependency.Dependency(db_class, backend_name, checker_cls=<class 'doit.dependency.MD5Checker'>, codec_cls=<class 'doit.dependency.JSONCodec'>, module_name=None)

Manage tasks dependencies.

Each dependency is saved in “db”. There are several “db” backends. It uses a Key-Value format where the key is task-name and value is a dictionary. Each task has a dictionary where keys are dependency’s (absolute file path), and the value is the dependency signature. Apart from dependencies other values are also saved on the task dictionary:

• _values_: task’s values

• result: task result

And also some internal doit attributes:

• ignore:

• deps:

• checker:

Those can be accessed with generic DB get(), see below…

Variables

• name (string) – filepath of the DB file

• _closed (bool) – DB was flushed to file

get_result(task_name)

get the result saved from a task

Return (dict or md5sum)

get_value(task_id, key_name)

get saved value from task

Parameters

• task_id (str) –

• key_name (str) – key result dict of the value

get_values(task_name)

get all saved values from a task

Return dict

The class internally interacts with a data base backend which may be accessed via the backend attribute. An experienced user may also modify persistently stored doit data through that attribute. As an example of a backend API, look at the common methods exposed by the default DbmDB backend implementation:

class doit.dependency.DbmDB

A simple Key-Value database interface

DbmDB.get(task_id, dependency)

Get value stored in the DB.

Returns

string or None if entry not found

DbmDB.set(task_id, dependency, value)

Store value in the DB.

DbmDB.remove(task_id)

remove saved dependencies from DB for taskId

There are other backends available in doit, see the documentation on DB backend on how to select between them.

dep_manager example

An example of using the exposed dependency manager is a task, where at creation time the target of the task action is not yet known, because it is determined during execution. Then it would be possible to store that target in the dependency manager by returning it from the action. A clean action is subsequently able to query dep_manager for that result and perform the cleanup action:

import doit

DOIT_CONFIG = dict(
    verbosity=2,
)


def task_create():
    # dependency manager is defined for all code inside the generator:
    dep_manager = doit.Globals.dep_manager

    def action():
        # assume some involved logic to define ident:
        ident = 42
        print('Created', ident)

        # store for clean:
        return dict(created=ident)

    def clean(task):
        result = dep_manager.get_result(task.name)
        if result:
            ident = result['created']
            print('Deleted', ident)

            # possibly forget the task, after it was cleaned:
            dep_manager.remove(task.name)

    return dict(
        actions=[action],
        clean=[clean],
    )