Agent Library Reference

The lib.build.agent Module

Agent build management.

An agent is a Web service.

class publiforge.lib.build.agent.AgentBuildManager(settings)

This class manages agent builds.

One instance of AgentBuildManager is created during application initialization. It is only used in agent mode. It is stored in application registry.

self._processors is a tuple such as (processor_dictionary, root_list, available_list). processor_dictionary is a dictionary such as {processor_id: processor_path,...}.

self._fronts is a dictionary such as {front_id: password,...}.

self._builds is a dictionary of AgentBuild objects.

self._results is a dictionary of dictionaries such as {build_id: result_dict}. result_dict is a dictionary with following keys: status, log, expire. According to build events, it can also contains files, values and error keys.

self._results[build_id]['status'] is one of the following strings: a_stop, a_fatal or a_end.

self._results[build_id]['log'] is a list of tuples such as (timestamp, step, percent, message).

agent_id()

Get agent unique ID.

processor_list()

Refresh information and return a list of available processors and the number of possible concurrent builds.

Returns:(tuple) A tuple such as (processor_list, concurrent).

add_processors(path)

Add all processors in path path.

Parameters:path – (string) Where to look for processors.

processor_path(processor_id)

Return processor path if exists.

Parameters:processor_id – (string) Processor ID. Returns:(string)

processor_xml(processor_id)

Return processor XML if exists.

Parameters:processor_id – (string) Processor ID. Returns:(string)

front_list()

Return a list of authorized fronts.

authorized_front(front_id, password)

True if front_id is authorized to use agent services.

activity()

Return the global activity i.e. the number of active or pending builds.

Returns:(integer) Number of builds or -1 if the maximum number is reached.

synchronizing(build_id, lock=True)

Data synchronization for the build build_id.

Parameters:

• build_id – (string) Build ID.
• lock – (boolean, default=True) If True try to add build build_id in the list of synchronizations.

Returns:

(boolean)

start_build(build_id, context, processing, pack, end_url=None)

Create a build, add it in self._builds dictionary and try to start it.

Parameters:

• build_id – (string) Build ID.
• context – (dictionary) See FrontBuildManager call() method.
• processing – (dictionary) A processing dictionary.
• pack – (dictionary) A pack dictionary.
• end_url – (string, optional) URL to call to complete the build.

Returns:

(AgentBuild or None)

progress(build_id)

Return the progress of build.

Parameters:build_id – (string) Build ID. Returns:(tuple) A tuple such as (<step>, <percent>, <message>).

The step <step> is one of the following:

• a_start: starting
• a_env: importing processor environment
• a_build: building
• a_warn: a warning occurred
• a_error: an error occurred
• a_fatal: a fatal error occurred
• a_stop: stopping
• a_end: successfully completed
• none: unknown or not in progress build

stop(build_id)

Stop a build.

Parameters:build_id – (string) Build ID.

result(build_id)

Return the result of build.

Parameters:build_id – (string) Build ID. Returns:(dictionary) self._result or {'status': 'none'}.

The status <status> is one of the following:

• a_stop: stopped
• a_fatal: a fatal error occurred
• a_end: successfuly completed
• none: unknown build

class publiforge.lib.build.agent.AgentBuild(build_manager, build_id, context, processing, pack, end_url)

This class manages one local build.

self.result is a dictionary with the following keys: status, message, log. Log entry is a list of tuples such as (<timestamp>, <step>, <percent>, <message>). Processor can add keys like: files, values.

start()

Start the processing.

stop()

Stop building.

stopped(error=None, level='a_fatal')

Check if there is a fatal error and if the build is stopped.

Parameters:

• error (str) – (optional) Error message.
• level (str) – (default=’a_fatal’) Error level: a_warn, a_error or a_fatal.

Return type:

bool

Returns:

True if it is stopped.

output2attic()

Copy the content of Output directory to Attic directory.

get_in_attic(target, dependencies=None, relations=None)

Try to retrieve the last version of a file in the attic and copy it in the Output directory.

Parameters:

• target – (string) Path to target file.
• dependencies – (list, optional) List of files to compare with to known if it is necessary to process.
• relations – (list, optional) List of closely related files to retrieve with the target file.

Returns:

(boolean) True if the operation succeeded.

message(text)

Add a message in result['values'].

Parameters:text – (string or pyramid.i18n.TranslationString) Message text.

log(message, step=None, percent=None)

Append an entry to result['log'].

Parameters:

• message – (string) Message to write in log.
• step – (string, optional) If not None, progress is updated.
• percent – (int, optional) Percent of progress for step <step>.

translate(text)

Return text translated.

Parameters:text – (string) Text to translate.

Modules

A processor use a module to realize its processing.

publiforge.lib.processor.load_relaxngs(build, config)

Load Relax NG files defined in configuration.

Parameters:

• build – (AgentBuild) Main Build object.
• config – (ConfigParser.ConfigParser instance) Configuration with a [RelaxNG] section.

Returns:

(dictionary) A dictionary of lxml.etree.RelaxNG objets.

publiforge.lib.processor.bin_directory()

Return absolute path to PubliForge binary directory.

The lib.processor.validator Module

This module validates XML files against their Relax NG.

class publiforge.lib.processor.validator.Processor(build)

Main class for Validator processor.

start()

Start the processor.

The lib.processor.leprisme Module

LePrisme module transforms files into another files or values.

class publiforge.lib.processor.leprisme.Processor(build)

Main class for LePrisme processor.

start()

Start the processor.

config(section, option, default=None)

Retrieve a value from a configuration object.

Parameters:

• section – (string) Section name.
• option – (string) Option name.
• default – (string, optional) Default value

Returns:

(string) Read value or default value.

config_list(section, option, default=None)

Retrieve a list of values from a configuration object.

Parameters:

• section – (string) Section name.
• option – (string) Option name.
• default – (list, optional) Default values.

Returns:

(list)

make_id(fullname)

Compute a file ID according to processor configuration.

Parameters:fullname – (string) Absolute path to file to process.

finalize()

Finalization.

XML Transformation via XSL stylesheet.

class publiforge.lib.processor.leprisme.transform.Transform(processor, steps)

Class for XML transformation.

start(filename, fid, data)

Start the transformation.

Parameters:

• filename (str) – Relative path to the original file to transform.
• fid (str) – File ID.
• data (class:str or lxml.etree.ElementTree) – Name of file to transform or its content as a string or a tree.

Publiset management.

class publiforge.lib.processor.leprisme.publiset.Publiset(processor, base_path)

Class for Publiset management.

fullname(file_elt)

Find the full path of a file from a file tag.

Parameters:file_elt – (etree.Element object) File element. Returns:(string) Full path name.

compose(filename, set_root)

Compose an XML document from a publiset XML composition.

Parameters:

• filename – (string) Name of the composition file.
• set_root – (lxml.etree.Element instance) composition element.

Returns:

(etree.ElementTree object) Document tree or None.

classmethod create(element)

Create an empty publiset document and fill it with element.

Parameters:element – (lxml.etree.Element instance) Main element. Returns:(etree.ElementTree)

INI scripts management.

class publiforge.lib.processor.leprisme.iniscript.IniScript(processor)

Class for INI script managment.

convert_media(filename, ini_file, done_tag, percent)

Convert a media (image, audio or video).

Parameters:

• filename – (string) Relative path to the original file to transform.
• ini_file – (string) Path to INI file.
• done_tag – (string) Tag to mark the once the conversion is done.
• percent – (integer) Percentage of progress.

Returns:

(boolean)

post_execution(ini_file, target_file, done_tag)

Process post INI script.

Parameters:

• ini_file – (string) Path to INI file.
• target_file – (string) Path to target file.
• done_tag – (string) Tag to mark the once the conversion is done.

find_media(media_type, media_id, patterns, target=None)

Look for a media.

Parameters:

• media_type – (string) Type of media (image, audio or video).
• media_id – (string) Media ID.
• patterns – (list) List of patterns to check.
• target – (string, optional) Full path to target file.

Returns:

(string) Full path to source file or None.

Container factory management.

class publiforge.lib.processor.leprisme.containers.ZipFactory(processor)

Class for Zip container.

make(fid, output)

Make an ePub file.

Parameters:

• fid – (string) File identifier.
• output – (string) Full path to output directory.

Returns:

(string) Full path to zip file.

class publiforge.lib.processor.leprisme.containers.OcfFactory(processor)

Class for Open Container Format (OCF) file.

make(fid, output)

Make an Open Container Format file and check its validity.

Parameters:

• fid – (string) File identifier.
• output – (string) Full path to output directory.

Returns:

(string) Full path to ePub file.

The lib.processor.publiseter Module

This module makes Publiset XML file from a pack structure.

class publiforge.lib.processor.publiseter.Processor(build)

Main class for Publiseter processor.

start()

Start the processor.

config(section, option, default=None)

Retrieve a value from a configuration object.

Parameters:

• section – (string) Section name.
• option – (string) Option name.
• default – (string, optional) Default value

Returns:

(string) Read value or default value.

config_list(section, option, default=None)

Retrieve a list of values from a configuration object.

Parameters:

• section – (string) Section name.
• option – (string) Option name.
• default – (list, optional) Default values.

Returns:

(list)

finalize(force=False)

Finalization.

The lib.processor.generator Module

This module generate something from nothing.

class publiforge.lib.processor.generator.Processor(build)

Main class for generator processor.

start()

Start the processor.

message(text)

Add a message in build.result['values'].

Parameters:text – (string or pyramid.i18n.TranslationString) Message text.

storage_handler(storage_id, storage=None)

Update environment for storage storage_id with handler and user information and return the current storage handler.

Parameters:

• storage_id – (string) Storage ID.
• storage – (Storage instance, optional).

Returns:

(tuple or None) A tuple such as (storage_handler, (vcs_user_id, vcs_password, user_name)).

config(section, option, default=None)

Retrieve a value from a configuration object.

Parameters:

• section – (string) Section name.
• option – (string) Option name.
• default – (string, optional) Default value

Returns:

(string) Read value or default value.