Agent Library Reference

The lib.build.agent Module

Agent build management.

An agent is a Web service.

class publiforge.lib.build.agent.AgentBuildManager(settings)[source]

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()[source]

Get agent unique ID.

processor_list()[source]

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)[source]

Add all processors in path path.

Parameters:path – (string) Where to look for processors.
processor_path(processor_id)[source]

Return processor path if exists.

Parameters:processor_id – (string) Processor ID.
Returns:(string)
processor_xml(processor_id)[source]

Return processor XML if exists.

Parameters:processor_id – (string) Processor ID.
Returns:(string)
front_list()[source]

Return a list of authorized fronts.

authorized_front(front_id, password)[source]

True if front_id is authorized to use agent services.

activity()[source]

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)[source]

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)[source]

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)[source]

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)[source]

Stop a build.

Parameters:build_id – (string) Build ID.
result(build_id)[source]

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)[source]

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()[source]

Start the processing.

stop()[source]

Stop building.

stopped(error=None, level='a_fatal')[source]

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()[source]

Copy the content of Output directory to Attic directory.

get_in_attic(target, dependencies=None, relations=None)[source]

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)[source]

Add a message in result['values'].

Parameters:text – (string or pyramid.i18n.TranslationString) Message text.
log(message, step=None, percent=None)[source]

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)[source]

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)[source]

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()[source]

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)[source]

Main class for Validator processor.

start()[source]

Start the processor.

The lib.processor.leprisme Module

LePrisme module transforms files into another files or values.

class publiforge.lib.processor.leprisme.Processor(build)[source]

Main class for LePrisme processor.

start()[source]

Start the processor.

config(section, option, default=None)[source]

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)[source]

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)[source]

Compute a file ID according to processor configuration.

Parameters:fullname – (string) Absolute path to file to process.
finalize()[source]

Finalization.

XML Transformation via XSL stylesheet.

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

Class for XML transformation.

start(filename, fid, data)[source]

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)[source]

Class for Publiset management.

fullname(file_elt)[source]

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)[source]

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)[source]

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)[source]

Class for INI script managment.

convert_media(filename, ini_file, done_tag, percent)[source]

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)[source]

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)[source]

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)[source]

Class for Zip container.

make(fid, output)[source]

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)[source]

Class for Open Container Format (OCF) file.

make(fid, output)[source]

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)[source]

Main class for Publiseter processor.

start()[source]

Start the processor.

config(section, option, default=None)[source]

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)[source]

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)[source]

Finalization.

The lib.processor.generator Module

This module generate something from nothing.

class publiforge.lib.processor.generator.Processor(build)[source]

Main class for generator processor.

start()[source]

Start the processor.

message(text)[source]

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

Parameters:text – (string or pyramid.i18n.TranslationString) Message text.
storage_handler(storage_id, storage=None)[source]

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)[source]

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.