Front Library Reference

The lib.build.front Module

Front build management.

A front is a web site.

class publiforge.lib.build.front.FrontBuildManager(settings)

This class manages front builds.

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

self._agents is a dictionary such as {url: (agent_id, password, weight, processor_list, processor_expire_time, concurrent),... } which stores agent features.

self._builds is a dictionary of FrontBuild 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, project_id, user_id. According to build events, it can also contains files, values and error keys.

self._results[build_id]['status'] is one of the following strings: stop, fatal or end.

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

agent_urls()

Return a list of URLs of available agents.

refresh_agent_list(request)

Refresh processor list for each agent.

Parameters:request – (pyramid.request.Request instance) Current request.

find_agent(request, processor_id)

Find an agent which serves processor_id.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• processor_id – (string) ID of the processor agent must serve.

Returns:

(tuple): A tuple such as (url, uid) or (None, None).

processor(request, processor_id)

Return a processor tree.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• processor_id – (string) Processor ID

Returns:

(lxml.etree.ElementTree or None)

start_build(request, processing, processor, pack, tasks=None)

Find an agent, convert processing and pack into dictionaries, create a build, add it in self._builds dictionary and try to start it.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• processing – (Processing instance) Processing object.
• processor – (lxml.etree.ElementTree instance) Processor of current processing.
• pack – (Pack instance) Pack object.
• tasks – (tuple, optional) A tuple such as (task_ko, task_ok). If it is not None, the pack is transfered to the task according to success.

Returns:

(string or None) Build ID.

start_waiting(request)

Start waiting builds.

Parameters:request – (pyramid.request.Request instance) Current request.

progress(request, build_ids)

Return the progress of builds.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• build_ids – (list) Build ID list.

Returns:

(tuple) Return a tuple such as (<working>, <progress_dictionary>).

<working> is a boolean indicating whether one of the processing is in progress.

<progress_dictionary> is a dictionary such as {<build_id>: (<step>, <percent>, <message>, <start_time>, <agent_id)>),...} where <step> is one of the following:

• wait: waiting
• start: starting
• sync: synchronizing storages between front and agent
• a_???: an AgentBuildManager step
• get: getting result
• warn: a warning occurred
• error: an error occurred
• fatal: a fatal error occurred
• stop: stopping
• end: successfully completed
• none: unknown or not in progress build

complete(request, build_id, key)

Get the result and possibly download the output directory in storage.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• build_id – (string) Build ID.
• key – (string) Key to authenticate the request.

Returns:

(boolean)

stop(request, build_ids, user_id=None)

Stop a build.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• build_ids – (list, optional) IDs of build to stop.
• user_id – (integer, optional) Current user ID.

result(build_id)

Return the result of a build.

Parameters:build_id – (string) Build ID. Returns:(dictionary)

forget_results(project_id, user_id=None, build_ids=None, pack_id=None)

Forget results for one pack or several builds.

Parameters:

• project_id – (integer) Project ID.
• user_id – (integer, optional) Current user ID.
• build_ids – (list, optional) IDs of build to forget.
• pack_id – (string, optional) Pack ID.

build_list(project_id, user_id=None)

List all builds of a project.

Parameters:

• project_id – (integer) Project ID.
• user_id – (integer, optional) User ID.

Returns:

(list) A list of dictionaries.

Returned dictionaries are sorted by start time. Each dictionary has following keys: build_id, start, status, processing_id, pack_id, user_id and output.

is_owner(request, build_id, user_id=None)

Check if user user_id has launched the build build_id.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• build_id – (string) Build to check
• user_id – (integer, optional) User ID to check. By default, the current user is checked.

Return type:

(boolean)

call(request, url, method, *args)

Call an agent method directly or via RPC.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• url – (string) The agent URL or localhost to call without RPC.
• method – (string) Method to call
• args – Non-keyworded arguments for method.

Returns:

(tuple) A tuple such as (<error>, <result>) where <error> is a string and <result> depends on method.

In addition to the required arguments, this method sends also a context dictionary with lang (language for error messages), front_id, password (to authenticate front), user_id and local (True if called without XML-RPC). If this method is called for a local agent, it adds a request key in context.

class publiforge.lib.build.front.FrontBuild(build_manager, build_id, user_id, lang, processing, pack)

This class manages a build locally and via an agent.

self.result is a dictionary with following keys: status, log, start, expire, project_id, user_id. At the process end, it can also have files, values, error and end keys.

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

self.result['expire'] is the date beyond which the build is destroyed.

self.key is a key to authenticate transaction between front and agent.

start(request)

Start a build in a thread.

Parameters:request – (pyramid.request.Request instance) Current request. Returns:(boolean)

progress(request)

Return the progress of build.

Parameters:request – (pyramid.request.Request instance) Current request. Returns:(tuple) A tuple such as (<step>, <percent>, <message>, <start_time>, <agent_id)>).

complete(request, key)

Start a complete action in a thread.

Parameters:

• request – (object) WebOb request object.
• key – (string) Authentication key.

Returns:

(boolean) True if succeeds.

stop(request=None)

Stop building.

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

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

Parameters:

• error – (string, optional) Error message.
• level – (string, default=’fatal’) Error level: warn, error or fatal.

Returns:

(boolean) True if it is stopped.

The lib.opener Module

A file opener is a class to display, render and edit some specific kind of file.

class publiforge.lib.opener.OpenerManager(settings)

This class manages file openers.

Parameters:settings (dict) – Setting dictionary.

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

self._openers is a ‘sorted by preference’ list of available file openers.

ids()

Return a list of IDs of available openers.

Return type:list

add_static_views(configurator)

Possibly, add static view for openers.

Parameters:configurator (pyramid.config.Configurator) – Object to configure a Pyramid application registry.

get_opener(filename, storage)

Find the best opener for file filename.

Parameters:

• filename (str) – Full path to file to check.
• storage (dict) – Storage dictionary.

Return type:

tuple

Returns:

A tuple such as (opener, content) where opener is not None if an opener matches.

descriptions(request, opener_ids=None)

Return a dictionary of tuples such as (label, description) for each opener of opener_ids list.

Parameters:

• request (pyramid.request.Request) – (optional) Current request.
• opener_ids – (dicrionary, optional) List of IDs of opener to check. If None, return the descriptions of all openers.

Returns:

(list)

has_seeds(opener_ids)

Return True if at least one opener among openers has a seed.

Parameters:opener_ids – (list) List of IDs of opener to check. Returns:(boolean)

seed_list(request, opener_ids)

Return a list of couples such as (seed_file, seed_label).

Parameters:

• request – (pyramid.request.Request instance) Current request.
• opener_ids – (list) List of IDs of opener to use.

Returns:

(list)

seed_fullpath(request, path)

Install the environment and return the absolute path to the seed file.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• path – (string) Relative path to the seed.

Returns:

(string or None)

class publiforge.lib.opener.Opener(opener_manager, opener_id, opener_xml)

Base class for file opener class.

Parameters:

• opener_manager (OpenerManager) – Application OpenerManager object.
• opener_id (str) – ID of this opener.
• opener_xml (lxml.etree.ElementTree) – ID of this opener.

label(request=None)

Label in local or default language.

Parameters:request (pyramid.request.Request) – (optional) Current request.

description(request=None)

Description in local or default language.

Parameters:request (pyramid.request.Request) – (optional) Current request.

information(request, name)

Return a description of object name in local or default language.

Parameters:

• request (pyramid.request.Request) – Current request.
• name – (string) Name of the variable on which we are looking for information.

Returns:

(string or None)

has_seeds()

Return True if at least one seed exists.

Return type:bool

seed_list(request)

Return a list of couples such as (seed_file, seed_label) where seed_file is a relative path to the seed file and seed_label a localized label.

Parameters:request (pyramid.request.Request) – Current request. Return type:list

match(fullname, content=None)

Check whether this opener matches with the file fullname.

Parameters:

• fullname (str) – Full path to file to check.
• content (str) – (optional) Content of the file to check.

Return type:

tuple

Returns:

A tuple such as (match, content) where match is True if the opener matches.

read(request, storage, path, content=None)

Literal XHTML to display the file content.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the file to read.
• content (str) – (optional) Content of the file to read.

Return type:

str

Returns:

A piece of literal XHTML code.

title(request, storage, path, content=None)

Return a title for the current file.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the native file.
• content (str) – (optional) Initial content of the file to edit.

Return type:

str or None

Returns:

A piece of XHTML representing the title of the file.

overview(request, storage, path, content=None)

Return an overview for the current file.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the native file.
• content (str) – (optional) Initial content of the file to edit.

Return type:

str or None

Returns:

A piece of XHTML representing the file.

classmethod can_render()

Return True if it can produce a rendering.

Return type:bool

classmethod render(request, storage, path, content=None, native=None)

Literal XHTML to display file rendering.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the file to render.
• content (str) – (optional) Content of the file to render.
• native – (optional) Object to convert.

Return type:

native object

Return type:

str

Returns:

A piece of literal XHTML code.

classmethod can_write()

Return True if it can simply modify the file.

Return type:bool

write(request, storage, path, content=None)

XHTML form and content for the file to write.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the file to write.
• content (str) – (optional) Content of the file to write.

Return type:

tuple

Returns:

A tuple such as (form, literal_html, content) where content is the current state of the content.

classmethod can_edit()

Return True if it can produce an editor.

Return type:bool

classmethod edit(request, action, storage, path, content=None)

XHTML form and content for the file to edit.

Parameters:

• request (pyramid.request.Request) – Current request.
• action (str) – (‘sav!’, ‘wrt!’ or ‘edt!’) Current action
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the file to edit.
• content (str) – (optional) Content of the file to edit.

Return type:

Form or str

Returns:

A tuple such as (form, literal_html, native) where native is the current state of the file.

classmethod find_media(filename, media_type, media_id, patterns=None, extensions=None)

Return the absolute path to the media media_id.

Parameters:

• filename – (string) Full path to file being processed.
• media_type – (‘image’, ‘audio’ or ‘video’) Media type.
• media_id – (string) Media ID.
• patterns – (list, optional) List of patterns to check.
• extensions – (list, optional) List of extensions to check.

Returns:

(string) URL media file or None.

classmethod resources_dirs(filename, media_type)

Return the list of resource directories.

Parameters:

• filename – (string) Full path to file being processed.
• media_type – (‘image’, ‘audio’ or ‘video’) Media type.

Returns:

(list)

classmethod resources_files(path, media_type, media_only)

Return the list of media files of path directory.

Parameters:

• path – (string) Full path to the directory to browse.
• media_type – (‘image’, ‘audio’ or ‘video’) Media type.
• media_only – (boolean) If True, return files following the media extension only.

Returns:

(list)

save(request, storage, path, content, values)

Reconstitute and save the current file.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the file to save.
• content (str) – Initial value of content.
• values (dict) – Form values.

Return type:

bool

is_valid(request, storage, path, content=None, values=None)

Check whether the content is valid.

Parameters:

• request (pyramid.request.Request) – Current request.
• storage (dict) – Storage dictionary.
• path (str) – Relative path to the native file.
• content (str) – (optional) Content of the file.
• values (dict) – (optional) Form values or request POST parameters.

Return type:

tuple

Returns:

A tuple such as (is_valid, content).

css(mode, request=None)

Return a list of CSS files for the mode mode.

Parameters:

• mode – ('read', 'render', 'write' or 'edit') Current mode for CSS.
• request – (pyramid.request.Request instance, optional) Current request.

Returns:

(tuple)

javascript(mode, request=None)

Return list of JavaScript files for the mode mode.

Parameters:

• mode – ('read', 'render', 'write' or 'edit') Current mode for CSS.
• request – (pyramid.request.Request instance, optional) Current request.

Returns:

(tuple)

position(directory, filename)

Return the number of files of the same type and the position of the current file.

Parameters:

• directory – (string) Full path to the directory containing the current file.
• filename – (string) Name of the current file.

Returns:

(tuple) A tuple such as (position, count).

navigate(directory, filename, direction)

Return the next or previous file of the same type.

Parameters:

• directory – (string) Full path to the directory containing the current file.
• filename – (string) Name of the current file.
• direction – ('previous' or 'next') Direction of the navigation.

Returns:

(string) Full path to next (or previous) file or None.

route()

Return a route path and a full path to a directory for static data.

Returns:(tuple) A tuple such as (route_path, directory_path) or (None, None).

install_environment(request=None, opener_id=None, target=None, can_reset=False)

Install the opener directory, possibly with inheritance, in the opener cache directory.

Parameters:

• request – (pyramid.request.Request instance, optional) Current request.
• opener_id – (string, optional) ID of the opener to install, by default the object itself.
• target – (string, optional) Full path to the target directory.
• can_reset – (boolean, default=False) If can_reset is True and opener.develop is 'true' in settings, the opener is destroyed and created again.

Returns:

(boolean)

The lib.handler Module

A handler manages access to a storage and its indexing.

class publiforge.lib.handler.HandlerManager(settings, cache_manager, opener_manager=None)

This class manages all handlers.

Parameters:

• settings – (dictionary) Setting dictionary.
• cache_manager – (beaker.cache.CacheManager instance) Global Beaker cache manager.
• opener_manager – (OpenerManager, optional) Global opener manager.

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

self.cache_manager is a beaker.cache.CacheManager instance.

self._indexers is a dictionary such as {indexer_id: (value_type, extrators),...} where extractors is a list of tuples like (indexed_files_regex, type, parameter, max_length).

self._handlers is a dictionary of Handler objects.

vcs_list()

Return a list of available Version Control System.

currently_managed()

Return a list of ID of currently managed storages.

get_handler(storage_id, storage=None)

Create or retrieve a Storage Control System for storage storage_id.

Parameters:

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

Returns:

(Handler instance or None)

remove_handler(storage_id)

Remove handler from handler list.

Parameters:storage_id – (string) Storage ID.

progress(storage_ids, pending=False)

Return the progress of actions on storages.

Parameters:

• storage_ids – (list) Storage ID list.
• pending – (boolean, default=False) True if there is a pending work.

Returns:

(tuple) Return a tuple such as (working, progress_list).

working is a boolean indicating whether one of the storage is in progress. progress_list is a list of items like (status, message). See Handler class.

index(storage_id, in_thread=False)

Index storage storage_id directly or in a thread.

Parameters:

• storage_id – (string) ID of storage to index.
• in_thread – (boolean, default=False) Launch indexing in a thread or not.

delete_index(update=True)

Delete all indexes.

Parameters:update (bool) – (default=True) If True update indexes after deleting.

search(storage_id, fieldnames, query, limit=None)

Search in storage storage_id.

Parameters:

• storage_id (str) – ID of storage to search.
• fieldnames (list) – List of fields to search.
• query (str) – A query in the Whoosh default query language.
• limit (int) – (optional) Maximum number of results.

Return type:

list

Returns:

A list of dictionaries. Each dictionary has the keys score, storage_id and path plus the keys reprensenting the stored fields.

class publiforge.lib.handler.Handler(handler_manager, storage)

This class manages access to one storage.

self.uid is the ID of the associated storage.

self.expire is the deadline for this object.

self.cache is a beaker.cache.Cache instance.

self.vcs is a Vcs instance.

self.indexing is the indexing status of the storage in a tuple such as (status, start_time, delay_to_start, indexed_file_regex):

• '': no index
• 'ok': no pending indexing operation
• 'update': waiting for indexing
• 'delete': waiting for deleting index
• 'run': in progress

run status can be completed by next step: run>delete>index.

self._report is a tuple such as (status, message, expire, ttl) where expire is the report validity date and status is one of the following strings:

• 'wait': waiting for VCS operation
• 'run': VCS operation in progress
• 'error': VCS operation ended with error
• 'end': VCS operation ended with success

self._refresh is a tuple such as (time_to_refresh, refresh_period).

clone(request=None)

Launch an action to clone a storage.

Parameters:request – (pyramid.request.Request instance, optional) Current request.

synchronize(request, force=False)

Launch an action to synchronize storage with its source.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• force – (boolean, default=False) Force synchronization even if period is not over.

Returns:

(boolean) True if it really launch a synchronization.

If force is False, the synchronizaton is only done if the delay of synchro_period seconds has expired.

report(status, message=None)

Save a report.

Parameters:

• status – (string) Current status. See Handler class.
• message – (string, optional) Message to write in report.

Returns:

(string or None) Message.

progress()

Return the progress of action on the storage.

Returns:(tuple) A tuple such as (status, message). See Handler class.

dir_infos(*args)

Cache function.

upload(user, path, upload_files, filename, message)

Synchronize, upload files and propagate.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• path – (string) Relative path to files.
• upload_files – (list) List fo cgi.FieldStorage of the file to upload.
• filename – (string or None`) Name of file to upload or None.
• message – (string) Commit message.

create(user, seed, path, name, message)

Create a new file according to the seed file.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• seed – (string) Full path to the seed file.
• path – (string) Relative path to file to create.
• name – (string) Name of the file to create.
• message – (string) Commit message.

duplicate(user, path, original, name, message)

Duplicate the original file.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• path – (string) Relative path to file to create.
• original – (string) Name of the original file.
• name – (string) Name of the file to create.
• message – (string) Commit message.

mkdir(user, path, name, message)

Make a directory.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• path – (string) Relative path to directory to create.
• name – (string) Name of directory to create.
• message – (string) Commit message.

add(user, path, message)

Synchronize, add files and propagate.

Parameters:

• user (list) – VCS user like (vcs_user_id, vcs_password, user_name).
• path (str) – Relative path to files.
• message (str) – Commit message.

rename(user, path, filename, new_name, message)

Synchronize, rename a file and propagate.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• path – (string) Relative path to files.
• filename – (string) Name of file to move.
• new_name – (string) New name.
• message – (string) Commit message.

remove(user, path, filenames, message)

Synchronize, remove files and propagate.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• path – (string) Relative path to files.
• filenames – (list) Names of files to remove.
• message – (string) Commit message.

replace(user, path, content, message)

Synchronize, replace one file and propagate.

Parameters:

• user – (list) VCS user like (vcs_user_id, vcs_password, user_name).
• path – (string) Relative path to files.
• content – (string) New content of the file to replace.

recover()

Recover from an interrupted commit or pull.

index()

Schedule index.

launch(request, action, args=(), kwargs=None)

Launch a new action in a thread.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• action – (function) Action to launch.
• args – (tuple, optional) Arguments for the action.
• kwargs – (dictionary, optional) Keyword arguments for the action.

Returns:

(boolean) True if action has been launched.

Only one action per storage at a time is possible.

The lib.xml Module

XML manipulation.

publiforge.lib.xml.load_xml(filename, relaxngs=None, data=None, noline=False, parser=None)

Load an XML document and validate it against a Relax NG file.

Parameters:

• filename (str) – Path to XML file.
• relaxngs (dict) – (optional) Relax NG dictionary such as {<pattern>: <relax_ng_file>,...}. If it is None, no validation is performed.
• data (str, bytes or lxml.etree.ElementTree) – (optional) Content of the XML document. If it is not None, it is used in place of the content of the file filename.
• noline (bool) – (default=False) If True, the error message does not contain line numbers.
• parser (class:etree.XMLParser) – (optional) Specific parser for etree.parse function.

Return type:

str, TranslationString or ElementTree

Returns:

An error message or an instance of lxml.etree.ElementTree class.

publiforge.lib.xml.load(filename, relaxngs=None, data=None, noline=False, parser=None)

Legacy function.

publiforge.lib.xml.validate_xml(tree, relaxngs, noline=False)

Load an XML document and validate it against a Relax NG file.

Parameters:

• tree (lxml.etree.ElementTree) – XML document.
• relaxngs (dict) – Relax NG dictionary such as {<pattern>: <relax_ng_file>,...}.
• noline (bool) – (default=False) If True, the error message does not contain line numbers.

Return type:

str, TranslationString or None

Returns:

An error message or None.

publiforge.lib.xml.local_text(root_elt, xpath, request=None, lang=None, default='')

Return the text in local language of the root_elt element child selected by xpath.

Parameters:

• root_elt – (lxml.etree.Element instance) Root element.
• xpath – (string) XPath expression.
• request – (pyramid.request.Request instance, optional) Current request.
• lang – (string, optional) Preferred language.
• default – (string, optional) Default label.

Returns:

(string)

If label does not exist in the asked language, this method returns the label in default language or in english or the first label or ‘’.

publiforge.lib.xml.upload_configuration(request, perm, only=None)

Upload a XML configuration file.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• perm – (string) Level of permission needed.
• only – (string, optional) user, group, storage or project.

publiforge.lib.xml.import_configuration(settings, filename, only=None, error_if_exists=True, xml=None, request=None)

Import a XML configuration file.

Parameters:

• settings – (dictionary) Application settings
• filename – (string) Full path to file to import.
• only – (string, optional) user, group, storage, indexer or project.
• error_if_exists – (boolean, default=True) It returns an error if an item already exists.
• xml – (string, optional) Content of the XML document.
• request – (pyramid.request.Request instance, optional) Current request.

Returns:

(list) A list of error messages.

publiforge.lib.xml.export_configuration(elements, filename=None, command=False)

Export an XML configuration and return it as a pyramid.response.Response object.

Parameters:

• elements – (list) List of lxml.etree.Element objects.
• filename – (string, optional) Name of file to export. Default to 'publiforge'.
• command – (boolean, default=False) True if called by command line.

Returns:

(pyramid.response.Response instance)

publiforge.lib.xml.xml_wrap(text, depth)

Return a dictionary with the localized texts contained in an XML element.

Parameters:

• text (str) – Text to wrap and indent.
• depth (int) – Depth of the parent element in the entire XML structure.

Return type:

str

publiforge.lib.xml.xpath_camel_case(context, text)

XPath function: camel_case().

publiforge.lib.xml.xpath_make_id(context, name, mode)

XPath function: make_id().

publiforge.lib.xml.xpath_relpath(context, path, start)

XPath function: relpath().

publiforge.lib.xml.xpath_wrap(context, text, depth)

XPath function: xml_wrap().

The lib.i18n Module

Localization management.

publiforge.lib.i18n.locale_negotiator(request)

Locale negotiator to figure out the language to use.

Parameters:request (pyramid.request.Request) – Current request. Return type:str

publiforge.lib.i18n.localizer(locale_name, directories=None)

Create a pyramid.i18n.Localizer object corresponding to the provided locale name from the translations found in the list of translation directories.

Parameters:

• locale_name (str) – Current language.
• directories (list) – (optional) Translation directories.

Return type:

pyramid.i18n.Localizer

publiforge.lib.i18n.add_translation_dirs(configurator, package)

Add one or more translation directory paths to the current configuration state according to settings and package name.

Parameters:

• configurator (pyramid.config.Configurator) – Object used to do configuration declaration within the application.
• package (str) – Name of the calling package.

publiforge.lib.i18n.translate_field(request, i18n_fields)

Return the best translation according to user language.

Parameters:

• request (pyramid.request.Request) – Current request.
• i18n_fields (dict) – Dictionary of avalaible translations.

Return type:

str

The lib.config Module

Various functions to parse configuration files or settings.

publiforge.lib.config.config_get(config, section, option, default=None)

Retrieve a value from a configuration object.

Parameters:

• config (configparser.ConfigParser) – Configuration object.
• section (str) – Section name.
• option (str) – Option name.
• default (str) – (optional) Default value

Return type:

str Read value or default value.

publiforge.lib.config.config_get_list(config, section, option, default=None)

Retrieve a list of values from a configuration object.

Parameters:

• config (configparser.ConfigParser) – Configuration object.
• section (str) – Section name.
• option (str) – Option name.
• default (list) – (optional) Default values.

Return type:

list

publiforge.lib.config.config_get_namespace(config, section, namespace)

Retrieve all options beginning by a name space.

Parameters:

• config (configparser.ConfigParser) – Configuration object.
• section (str) – Section name.
• namespace (str) – Prefix of options to retrieve.

Return type:

dict

publiforge.lib.config.settings_get_list(settings, option, default=None)

Retrieve a list of values from a settings dictionary.

Parameters:

• settings (pyramid.registry.Registry.settings) – Settings object.
• option (str) – Option name.
• default (list) – (optional) Default values.

Return type:

list

publiforge.lib.config.settings_get_directories(settings, namespace, conf_file)

Retrieve all directories whose root is contained in one of the directories listed in namespace.roots, name matches one of the patterns listed in namespace.patterns and containing the file filename.

Parameters:

• settings (pyramid.registry.Registry.settings) – Settings object.
• namespace (str) – Prefix of options to retrieve.
• namespace – Prefix of options to retrieve.
• conf_file (str) – Name of configuration file to search in each directory.

Return type:

dict

The lib.utils Module

Some various utilities.

publiforge.lib.utils.has_permission(request, *perms)

Check if the user has at least one of the specified permissions.

Parameters:

• request ((class:pyramid.request.Request) – Current request.
• perms (list) – List of permission groups.

Return type:

bool

See Permissions.

publiforge.lib.utils.copy_content(src_dir, dst_dir, exclude=(), force=False)

Copy the content of a src_dir directory into a dst_dir directory.

Parameters:

• src_dir – (string) Source directory path.
• dst_dir – (string) Destination directory path.
• exclude – (list, optional) List of files to exclude.
• force – (booelan, optional) Force copy even if the target file has the same date.

publiforge.lib.utils.camel_case(text)

Convert text in Camel Case.

publiforge.lib.utils.normalize_name(name)

Normalize name.

publiforge.lib.utils.normalize_filename(filename, mode='simple', is_dir=False)

Normalize file name.

Parameters:

• filename – (string) File name to normalize.
• mode – (NORMALIZE_FILE_MODE, default=’simple’) Strategy to normalize file name.
• is_dir – (boolean, default=False) The .

publiforge.lib.utils.normalize_spaces(text, truncate=None)

Normalize spaces and, possibly, truncate result.

Parameters:

• text (str) – Text to normalize.
• truncate (int) – (optional) If not None, maximum lenght of the returned string.

Return type:

str or None

publiforge.lib.utils.make_id(name, mode=None, truncate=None)

Make an ID with name.

Parameters:

• name (str) – Name to use.
• truncate (int) – (optional) If not None, maximum length of the returned string.
• mode (str) – (‘standard’, ‘token’, ‘xmlid’ or ‘class’, optional) Strategy to make ID.

Return type:

str

Examples of transformation of 12Test___Té*t;?!:

• mode = None: 12test___té*t;?!
• mode = ‘standard’: 12Test_Té_t_
• mode = ‘token’: 12test_te_t_
• mode = ‘xmlid’: _12test_te_t_
• mode = ‘class’: 12Test_Te_t_

publiforge.lib.utils.wrap(text, width=70, indent=0)

Transform a reStructuredText into XHTML.

Parameters:

• text – (string) Text to wrap.
• width – (integer, default 70) The maximum length of wrapped lines.
• indent – (integer, default 0) Initial and subsequent indentation.

Returns:

(string) Wrapped text.

publiforge.lib.utils.hash_sha(value, key='')

Cryptographic hash function with SHA1 algorithm.

Parameters:

• value – (string) String to hash.
• key – (string, optional) Encryption key.

publiforge.lib.utils.encrypt(value, key)

Encryption function.

Parameters:

• value (str) – String to encrypt.
• key (str) – Encryption key.

Return type:

str

Returns:

Encrypted value or None.

publiforge.lib.utils.decrypt(value, key)

Decryption function.

Parameters:

• value (str) – String to decrypt.
• key (str) – Encryption key.

Return type:

str

Returns:

Clear value or None.

publiforge.lib.utils.token(length=None)

Generate a token of length length or with a length between 8 an 16 characters.

Parameters:length (int) – (optional) Length of the token. Return type:str Returns:Token.

publiforge.lib.utils.email_is_valid(email)

Check the validity of an email address.

Parameters:email (str) – Address to check. Return type:bool

publiforge.lib.utils.unzip(archive, outpath, normalize_mode=None)

Extract an archive ignoring forbidden files.

Parameters:

• archive – (string or file) Name of the ZIP file.
• outpath – (string) Full path where extract the archive.
• outpath – (NORMALIZE_MODE, optional) Full path where extract the archive.

publiforge.lib.utils.get_mime_type(filename)

Return the mime type of filename.

Parameters:filename – (string) File name. Returns:(tuple) A tuple such as (mime_type, subtype). For instance: ('text/plain', 'plain').

publiforge.lib.utils.size_label(size, is_dir)

Return a size in o, Kio, Mio or Gio.

Parameters:

• size – (integer) Size in figures.
• is_dir – (boolean) True if it is about a directory.

Returns:

(string or pyramid.i18n.TranslationString)

publiforge.lib.utils.age(mtime)

Return an age in minutes, hours, days or date.

Parameters:mtime – (datetime) Modification time. Returns:(pyramid.i18n.TranslationString or string) Return an age or a date if mtime is older than a year.

publiforge.lib.utils.duration(request, seconds)

Return a duration in seconds, minutes, hours and days.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• seconds – (integer) Number of seconds to convert.

Returns:

(string)

publiforge.lib.utils.cache_key(cache, method_name, *args)

Compute a cache key.

Parameters:

• cache – (beaker.cache.Cache instance)
• method_name – (string)
• args – (positional arguments)

Returns:

(string)

publiforge.lib.utils.cache_decorator()

Decorator to cache a method of a class with self.cache attribute.

self.cache is a beaker.cache.Cache instance.

The method being decorated must only be called with positional arguments, and the arguments must support being stringified with str().

publiforge.lib.utils.export_file_set(root_elt, record, file_type)

Save set of files in a XML object.

Parameters:

• root_elt – (lxml.etree.Element instance) Element that linked the result.
• record – (Processing or Pack instance).
• file_type – (‘file’, ‘resource’ or ‘template’) File type.

publiforge.lib.utils.shift_files(direction, index, record, files, form)

Shift a file in the list of files of a record (pack or processing).

Parameters:

• direction – (‘mup’ or ‘dwn’) Direction of the move.
• index – (string) Item to move in files.
• record – (Processing or Pack instance) Current pack object.
• files – (dictionary) See file_details() function.
• form – (Form instance) Current form

publiforge.lib.utils.execute(command, cwd=None, no_exit_code=False)

Run the command described by command. Wait for command to complete. If the return code is not zero, return output and an error message.

Parameters:

• command – (list) Splitted command to execute.
• cwd – (string, optional) If it is not None, the current directory will be changed to cwd before it is executed.
• no_exit_code – (boolean, default=False) If the command is known to exit with code 0 even if there is an error, assign this argument to True.

Returns:

(tuple) An error message such as (output, error) where output is a string and error a pyramid.i18n.TranslationString.

publiforge.lib.utils.rst2xhtml(rst)

Transform a reStructuredText into XHTML.

Parameters:rst (str) – reStructuredText. Return type:str Returns:XHTML.

publiforge.lib.utils.load_regex(filename)

Load a list of regular expressions.

Parameters:filename – (string) Name of file to load. Returns:(list) A list of re.pattern objects.

publiforge.lib.utils.image_metadata(img_file)

Retrieve metadata (exif or XMP) of the image.

Parameters:img_file (str) – Absolute path to the image file. Return type:tuple Returns:A tuple such as (title, description, size).

The lib.log Module

Various functions to manage logs.

publiforge.lib.log.setup_logging(log_level='INFO', log_file=None, log_format=None)

Initialize logging system.

Parameters:

• log_level (str) – (‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’) Log level. By default INFO.
• log_file (str) – (optional) Path to log file.
• log_format (str) – (optional) Format for log entry. By default, %(asctime)s %(levelname)-8s %(message)s

publiforge.lib.log.log_activity_setup(global_config)

Create log directory.

Parameters:global_config (dict) – Dictionary describing the INI file with keys __file__ and here. Return type:bool Returns:Return True if activity log is activated.

publiforge.lib.log.log_activity(request, action, *args)

Write a message in the activity log.

Parameters:

• request (pyramid.request.Request) – Current request.
• action (str) – Action in action.
• args (list) – Non-keyworded arguments.

publiforge.lib.log.log_error(request, error)

Write an error message in the log.

Parameters:request (pyramid.request.Request) – Current request.

The lib.filter Module

Class to manage a filter to select items among a collection.

class publiforge.lib.filter.Filter(request, filter_id, inputs, initials=None, remove=None, comparisons={'!=': u'u2260', '<': '<', '<=': u'u2264', '=': '=', '>': '>', '>=': u'u2265'})

A class to manage filters.

Parameters:

• request (pyramid.request.Request) – Current request.
• filter_id (str) – Filter ID.
• inputs (list) – A list of inputs like ((key, label, is_static, available_values),...). available_values is None for an input with text values, True for those with boolean values and a list of value/label for closed list of values.
• initials (list) – (optional) Initial conditions.
• remove (str) – (optional) Number of the condition to remove from the previous filter.
• comparisons (OrderedDict) – (optional) Customize list of comparaisons.

A filter is a list of AND-conditions. Each AND-condition is a list of OR-conditions. An OR-condition is a tuple such as (key, comparison, value).

The comparison is one of the items of comparisons and can be '=', '!=', '>', '>=', '<' or '<='. The value can be a boolean, a string or a TranslationString instance.

For instance, the filter:

(id=2 OR id>5) AND active AND group!='Foo' is stored as:

[[('id', '=', 2), ('id', '>', 5)], [('active', '=', True)], [('group', '!=', 'Foo')]]

is_empty()

Return True if a filter is empty.

clear()

Clear filter.

append_condition(key, comparison, value, operator='AND')

Append an AND-condition to the filter.

Parameters:

• key (str) – The key to use.
• comparison (str) – ('=', '!=', '>', '<',…) How to compare.
• value (str, bool or TranslationString) – The value of the filter. It is optional for boolean filter and its default value is True.
• operator (str) – (‘AND’ or ‘OR’, default=’AND’) The operator to use to complete the filter.

remove_condition(index)

Remove one AND-condition of the filter.

Parameters:index (str) – Index of the AND-condition to remove.

html_conditions()

An HTML representation of the current conditions.

Return type:webhelpers2.html.literal

html_inputs(form, tag='span')

An HTML representation of the current inputs.

Parameters:

• form (lib.form.Form) – Current form.
• tag (str) – (Default=’div’) Tag which wraps each input line.

Return type:

webhelpers2.html.literal

sql(dbquery, table_name)

Complete a SqlAlchemy query with of the current filter.

Parameters:

• dbquery (sqlalchemy.orm.query.Query) – SqlAlchemy query to complete.
• table_name (str) – Name of the default SQL table.

Return type:

sqlalchemy.orm.query.Query

whoosh()

Return the current filter in Whoosh query language.

Return type:tuple Returns:a tuble search as (fieldnames, query).

The lib.viewutils Module

Some various utilities for views.

publiforge.lib.viewutils.connect_user(request, code, password=None)

If the user with code and password is authorized, it updates last_login field in database and returns an User object.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• code – (string) Login of the user to connect.
• password – (string, optional) Clear password.

Returns:

(User instance or integer) The connected user or an error code.

If password is None, password checking is not performed.

Values of the error code are:

• 1: incorrect user code or password
• 2: inactive account
• 3: expired account
• 4: forbidden IP

publiforge.lib.viewutils.get_action(request)

Return a tuple such as (action, items) where action is a string such as <act><?|!><item_id> and items is a list of selected items in a list form.

Parameters:request – (pyramid.request.Request instance) Current request. Returns:(tuple) A tuple such as (action, items).

Each submit button returns a string such as <act><?|!><item_id>.x where <item_id> is the item identifier or # for all selected items, <?|!> means respectively confirm or proceed and <act> is one of the following action:

• act: activate
• agp: add groups
• aur: add users
• bld: build
• ccl: cancel
• cls: close
• del: delete
• drl: delete role
• dtk: delete task
• dvl: delete value
• des: description
• dif: get diff
• dir: make directory
• dnl: download
• dwn: move down
• dup: duplicate
• exp: export
• get: get from selection
• imp: import
• not: modify a note
• npk: create a new pack with selection
• ipk: import pack with configuration and content
• mup: move up
• new: create a new object
• nxt: transition to next task
• ovw: toggle overview
• ren: rename
• rgp: remove groups
• rur: remove users
• rmv: remove
• sch: search
• shw: show
• sel: put in selection
• stp: stop
• syn: synchronize
• tak: take
• upl: upload

Checkbox inputs return string such as #<item_id>.

For instance, del!# and ['#user1', '#user2'] means “delete user1 and user2”. syn!DataHg means “synchronize DataHg and only this one”.

publiforge.lib.viewutils.get_selection(request)

Return selected files in the current selection.

Parameters:request – (pyramid.request.Request instance) Current request. Returns:(tuple)

publiforge.lib.viewutils.paging_users(request, only_active=True)

Return a Paging object filled with users.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• only_active – (boolean, default=True) if True, only active users are included.

Returns:

(tuple) A tuple such as (paging, filters) where paging is a Paging object and filters a dictionary of filters.

publiforge.lib.viewutils.paging_groups(request, paging_id='groups')

Return a Paging object filled with groups.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• paging_id – (string, default=’groups’) Paging ID: 'groups' for adding purpose and groups! for administration purpose.

Returns:

(tuple) A tuple such as (paging, filters) where paging is a Paging object and filters a dictionary of filters.

publiforge.lib.viewutils.current_storage(request, storage_id=None, only_dict=True)

Initialize, if necessary, request.session['storage'] and return it as current storage dictionary.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• storage_id – (integer, optional) ID of storage to get context.
• only_dict – (boolean, default=True) If False, it returns the entire Storage object.

Returns:

(tuple) A tuple such as (storage_dictionary, handler) or (storage_object, handler) or a pyramid.httpexceptions.`HTTPNotFound exception.

storage_dictionary has the following keys: storage_id, label, description, perm, vcs_engine, vcs_url, public_url, indexed.

publiforge.lib.viewutils.dbquery_storages(dbquery, user_id, with_index=False)

Return the query to find storages of a user.

Parameters:

• dbquery (sqlalchemy.orm.query.Query) – Current SqlAlchemy query to update.
• user_id (int) – Current user_id
• with_index (bool) – (default=False) If True select only storages with indexed files.

Return type:

sqlalchemy.orm.query.Query

publiforge.lib.viewutils.vcs_user(request, storage)

Return a VCS user tuple.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• storage – (dictionary) Storage dictionary.

Returns:

(tuple) A VCS user tuple (user_id, password, name).

publiforge.lib.viewutils.save_vcs_user(request, storage)

Save user name and password for VCS in database.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• storage – (dictionary) Storage dictionary.

publiforge.lib.viewutils.file_details(request, record, only_visible=True)

Return a dictionary of details on file contained in record.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• record – (Processing or Pack instance).
• only_visible – (boolean, default=True) If True, it returns a list of only visible files otherwise it returns a dictionary.

Returns:

(dictionary) A dictionary with keys file, resource and template. Each value of this dictionary is a tuple of tuples such as (file_type, storage_id, path, target, visible).

publiforge.lib.viewutils.file_download(request, path, filenames, download_name=None)

Prepare file for download and return a Pyramid response.

Parameters:

• request (pyramid.request.Request) – Current request.
• path (str) – Absolute path to files.
• filenames (list) – List of files to download.
• download_name (str) – (optional) Visible name during download.

Return type:

pyramid.response.FileResponse

Returns:

Return a FileResponse or raise a pyramid.httpexceptions.HTTPNotFound exception.

publiforge.lib.viewutils.file_upload(request, path, message)

Update a file in a storage.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• path – (string) Path of the file to update starting with storage ID.
• message – (string) Message for commit.

Returns:

(boolean) True if operation still in progress.

publiforge.lib.viewutils.selection2container(request, container_type, container, file_type, paths, processing=None)

Update the list of files of type file_type for the container container_type.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• container_type – (‘prc’ or ‘pck’) 'prc' for processing and 'pck' for pack.
• container – (Pack or Processing) Current pack object or processing object according to container_type.
• file_type – (‘file’, ‘resource’, ‘template’ or ‘output’) File type.
• paths – (list) List of files to add.
• processing – (Processing instance, optional) Reference processing object.

publiforge.lib.viewutils.current_project(request, project_id=None, only_dict=True)

Update request.session['project'] and return it as current project dictionary or return a SqlAlchemy object.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project_id – (integer, optional) ID of project to get context.
• only_dict – (boolean, default=True) If False, it returns the entire Project object.

Returns:

(dictionary, Project or None) None if error. Dictionary has the following keys: project_id, label, description, deadline, entries, perm, role_labels, my_roles, processing_labels, task_labels, processing_id (default processing) and pack_id (current pack).

publiforge.lib.viewutils.current_processing(request, project_id=None, processing_id=None, pack=None)

Return the current processing object.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project_id – (integer, optional) ID of project to retrieve processing.
• processing_id – (integer, optional) ID of processing to retrieve.
• pack – (Pack instance, optional) Current pack.

Returns:

(tuple) A tuple such as (processing, processor, output).

processing is a Processing object. processor is a lxml.etree.ElementTree object representing the used processor. output is a dictionary with keys storage_id, storage_label and path.

If this function fails, it raises a pyramid.httpexceptions.`HTTPNotFound exception.

publiforge.lib.viewutils.current_processing_output(request, processing, pack=None)

Return the current processing object.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• processing – (Processing instance) Current processing.
• pack – (Pack instance, optional) Current pack.

Returns:

(dictionary) A dictionary with following keys: storage_id , storage_label’, path.

publiforge.lib.viewutils.variable_schema(processor, values, with_visibility=True)

Return a schema to validate variable form.

Parameters:

• processor – (lxml.etree.ElementTree instance) Processor of current processing.
• values – (dictionary) Values affected to variables.
• with_visibility – (boolean, default=True) If True, create schema for visibility.

Returns:

(tuple) A tuple such as (schema, defaults) where schema is a colander.SchemaNode instance and defaults a dictionary.

publiforge.lib.viewutils.variable_schema_node(name, var_type, var=None)

Return a SchemaNode according to var_type.

Parameters:

• name – (string) Name of the variable.
• var_type – (string) Type of the variable.
• var – (lxml.etree.Element instance, optional) Variable node.

Returns:

(colander.SchemaNode instance)

publiforge.lib.viewutils.variable_input(form, name, var_type, var=None, **attrs)

Return an input tag for the variable name.

Parameters:

• form – (Form instance) Current form.
• name – (string) Name of the variable.
• var_type – (string) Type of the variable.
• var – (lxml.etree.Element instance, optional) Variable node.
• attrs – (dictionary) Keyworded arguments for webhelpers2.html.tags object.

Returns:

(one of Form tag instance)

publiforge.lib.viewutils.variable_description(request, variables, name, values=None, processor_default=False, default=False)

Return a description of variable name.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• variables – (lxml.etree.Element instance) <variables> DOM object.
• name – (string) Name of the variable.
• values – (dictionary, optional) Values affected to the variables.
• processor_default – (boolean, default=False) Show the processor default value if any.
• default – (boolean, default=False) Show the processing default value.

Returns:

(string)

publiforge.lib.viewutils.task_auto_build(request, pack, task=None)

Launch build for a task of type auto.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• pack – (Pack instance) Current pack object.
• task – (Task instance, optional) Current task for pack.

Returns:

(boolean) True if build is successfully launched.

The lib.packutils Module

Some various utilities for packs.

publiforge.lib.packutils.create_pack(request, filenames, path='.')

Create a new pack with selected files.

Parameters:

• request (pyramid.request.Request) – Current request.
• filenames (list) – Names of files to add to a new pack.
• path – (string, optional) Common path.

Return type:

tuple A tuple such as (project_id, pack_id) or (None, None) if failed.

publiforge.lib.packutils.pack2task(request, pack, link_type, target_task_id)

Move pack pack to task with ID target_task_id.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• pack – (Pack instance) Pack object.
• link_type – (string) Type of link: normal, back, redo or kept.
• target_task_id – (integer) Task ID. If None, the first non auto task is used.

publiforge.lib.packutils.pack_download(request, project_id, pack_id)

Download files of a pack in a ZIP file.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project_id – (string) ID of pack to download.
• pack_id – (string) ID of pack to download.

Returns:

(pyramid.response.FileResponse instance or raise a pyramid.httpexceptions.HTTPNotFound exception.)

publiforge.lib.packutils.pack_upload_settings(request, project_id, pack_doc=None, pack_id=None)

Import pack settings.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project_id – (string) Current project ID.
• pack_doc – (lxml.etree.ElementTree instance, optional) Pack XML DOM.
• pack_id – (integer, optional) Forced pack ID.

publiforge.lib.packutils.pack_upload_content(request, project_id, message, label=None, handler=None)

Import pack content.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project_id – (string) Current project ID.
• message – (string) Message for version control system.
• label – (string, optional) Label of pack to replace. If None, the pack must be a new one.
• handler – (file handler, optional) File handler.

Returns:

(None or pyramid.i18n.TranslationString)

publiforge.lib.packutils.paging_packs(request, project_id)

Return a Paging object filled with packs of project project_id.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project_id – (integer) Project ID.

Returns:

(tuple) A tuple such as (paging, filters) where paging is a Paging object and filters a dictionary of filters.

publiforge.lib.packutils.operator4task(pack, link_type, task_id=None)

Find the operator for task task_id according mode link_type.

Parameters:

• pack – (Pack instance) Pack object.
• link_type – (string) Type of link: normal, back, redo or kept.
• task_id – (integer, optional) Task ID. If None, the first non auto task is used.

Returns:

(tuple) A tuple such as (task_id, operator_type, operator_id).

publiforge.lib.packutils.operator_label(request, project, operator_type, operator_id)

Return localized operator label.

Parameters:

• request – (pyramid.request.Request instance) Current request.
• project – (dictionary) Current project dictionary.
• operator_type – (string) Operator type.
• operator_id – (integer) Operator ID.

Returns:

(string)

publiforge.lib.packutils.operator_labels(project, with_auto=False)

Return a list of all operators of the project project.

Parameters:

• project – (dictionary) Current project dictionary.
• with_auto – (boolean) If True add automatic operator in the list.

Returns:

(list)

The lib.form Module

Form validation and rendering library.

class publiforge.lib.form.SameAs(request, reference)

This class implements a colander validator to check if to fields are identical.

publiforge.lib.form.button(url, label='', src=None, title=None, class_='button')

Output a link on a label and an image with a button aspect.

Parameters:

• url (str) – Target URL.
• label (str) – (optional) Label for roll over and alt.
• src (str) – (optional) Image path.
• title (str) – (optional) Label for roll over.
• class (str) – (default=’button’) The class attribute.

Return type:

str HTML tag.

publiforge.lib.form.grid_item(name, label, content, required=False, hint=None, error=None, class_=None, tag='div', clear=False)

Display an item with label, hint and error message.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• content (str) – HTML content.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• error (str) – (optional) Error message.
• class (str) – (optional) The class attribute.
• tag (str) – (default=’div’) Tag which contains content, hint and error message.
• clear (bool) – (default=False) If True, add a <div class="clear"/> at the end.

Return type:

str

This ouputs a structure such as:

<div class="[class_]">
  <label for="[name]"><em>[label]<strong>*</strong></em></label>
  <tag>
    [content]
    <em>[hint]</em>
    <strong class="error">[form.error(name)]</strong>
  </tag>
  <div class="clear"></div>
</div>

If class_ is an empty string, 'formItem' is used.

class publiforge.lib.form.Form(request, schema=None, defaults=None, secure=True, obj=None, force_defaults=False)

Form validation class.

validate(obj=None)

Check if the form is validated.

Parameters:obj (object) – (optional) Object to fill. Return type:bool Returns:True if validated.

has_error(name=None)

Return True if field name has an error.

Parameters:name (str) – (optional) Input ID. Return type:bool

set_error(name, message)

Set an error message for field name.

Parameters:

• name (str) – Input ID.
• message (str) – Error message.

error(name)

Return error message for field name.

Parameters:name (str) – Input ID. Return type:str Returns:Translated error message.

static(name)

The field name will not be updated by the form.

Parameters:name (str) – Name of field to set static.

forget(prefix)

Fields beginning by prefix are forgotten when the page is refreshed.

Parameters:prefix (str) – Prefix to select fields.

classmethod make_safe_id(name)

Make a string safe for including in an id attribute

Parameters:name (str) – String to transform. Return type:str

begin(url=None, multipart=False, **attrs)

Ouput the <form> tag.

Parameters:

• url (str) – (optional) URL to submit form, by default, the current URL.
• multipart (bool) – (default=False) If set to True, the enctype is set to multipart/form-data.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

classmethod end()

Ouput the </form> tag.

classmethod submit(name, label=None, class_='button', **attrs)

Output a submit button with the label as the caption.

Parameters:

• name (str) – Input ID.
• label (str) – (optional) Button caption.
• class (str) – (default=’button’) The class attribute.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

classmethod submit_image(name, label, src, class_=None)

Output an image submit button.

Parameters:

• name (str) – Input ID.
• label (str) – Label for roll over and alt.
• src (str) – Image path.
• class (str) – The class attribute.

Return type:

str

Returns:

HTML tag.

classmethod submit_cancel(label)

Output a cancel submit button.

Parameters:label (str) – Label for roll over and alt. Return type:str Returns:HTML tag.

classmethod button(url, label='', src=None, title=None, class_='button')

Output a link on a label and an image with a button aspect.

See button().

classmethod grid_item(label, content, required=False, hint=None, error=None, class_=None, tag='div', clear=False)

Output an item with label, hint and error message.

See grid_item().

hidden(name, value=None, **attrs)

Output a hidden field.

Parameters:

• name (str) – Input ID.
• value (str) – (optional) Hidden value.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

text(name, value=None, **attrs)

Output a standard text field.

Parameters:

• name (str) – Input ID.
• value (str) – (optional) Default value.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.
• attrs – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

password(name, value=None, **attrs)

Output a password field.

This method takes the same options as text().

checkbox(name, value=u'1', checked=False, **attrs)

Output a check box.

Parameters:

• name (str) – Input ID.
• value (str) – (default=u‘1’) The value to return to the application if the box is checked.
• checked (bool) – (default=False) True if the box should be initially checked.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

custom_checkbox(name, value=u'1', checked=False, class_=None, **attrs)

Output a check box followed by an empty label to customize the aspect of the box.

Parameters:

• name (str) – Input ID.
• value (str) – (default=u‘1’) The value to return to the application if the box is checked.
• checked (bool) – (default=False) True if the box should be initially checked.
• class (str) – (default=’wbCustomCheckbox’) The class attribute.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

radio(name, value, checked=False, **attrs)

Output a radio button.

Parameters:

• name (str) – Input ID.
• value (str) – (default=‘1’) The value to return to the application if the radio is checked.
• checked (bool) – (default=False) True if the radio should be initially checked.
• label (str) – (optional) A text label to display to the right of the radio.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

select(name, selected_values, options, autosubmit=False, **attrs)

Output a dropdown selection box.

Parameters:

• name (str) – Input ID.
• selected_value (str or list) – A string or list of strings or integers giving the value(s) that should be preselected.
• options ((list of str, int or (value, label) pairs)) – The label will be shown on the form; the option will be returned to the application if that option is chosen. If you pass a string or int instead of a 2-tuple, it will be used for both the value and the label.
• autosubmit (bool) – (default=False) If True, it adds onchange="submit()" attribute.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

upload(name, value=None, **attrs)

Output a file upload field.

Parameters:

• name (str) – Input ID.
• value (str) – (optional) Default value.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

textarea(name, content='', **attrs)

Output a text input area.

Parameters:

• name (str) – Input ID.
• content (str) – (optional) Default value.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

HTML tag.

grid_text(name, label, required=False, hint=None, class_='', clear=False, **attrs)

Output a standard text field in a CSS grid layout.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• class (str) – (optional) The class attribute.
• clear (bool) – (default=False) If True, add a <div class="clear"/> at the end.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

Output a grid layout.

grid_password(name, label, required=False, hint=None, class_='', clear=False, **attrs)

Output a password field in a CSS grid layout.

This method takes the same options as grid_text().

grid_checkbox(name, label, required=False, hint=None, class_='', clear=False, **attrs)

Output a check box in a CSS grid layout.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• class (str) – (optional) The class attribute.
• clear (bool) – (default=False) If True, add a <div class="clear"/> at the end.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

Output a grid layout.

grid_custom_checkbox(name, label, required=False, hint=None, clear=False, class_='formItem', **attrs)

Output a custom check box in a CSS grid layout.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• clear (bool) – (default=False) If True, add a <div class="wbClear"/> at the end.
• class (str) – (optional) The class attribute.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

Output a grid layout.

grid_select(name, label, options, autosubmit=False, required=False, hint=None, class_='', clear=False, **attrs)

Output a dropdown selection box in a CSS grid layout.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• options ((list of str, int or (value, label) pairs)) – Values in the dropdown list.
• autosubmit (bool) – (default=False) If True, it adds onchange="submit()" attribute.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• class (str) – (optional) The class attribute.
• clear (bool) – (default=False) If True, add a <div class="clear"/> at the end.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

Output a grid layout.

grid_upload(name, label, required=False, hint=None, class_='', clear=False, **attrs)

Output a file upload field in a CSS grid layout.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• class (str) – (optional) The class attribute.
• clear (bool) – (default=False) If True, add a <div class="clear"/> at the end.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

Output a grid layout.

grid_textarea(name, label, required=False, hint=None, class_='', clear=False, **attrs)

Output a text input area in a CSS grid layout.

Parameters:

• name (str) – Input ID.
• label (str) – Label.
• required (bool) – (default=False) Indicate if this field is required.
• hint (str) – (optional) Help message.
• class (str) – (optional) The class attribute.
• clear (bool) – (default=False) If True, add a <div class="clear"/> at the end.
• attrs (dict) – Keyworded arguments for webhelpers2.html.tags object.

Return type:

str

Returns:

Output a grid layout.

The lib.breadcrumbs Module

Breadcrumbs utility.

class publiforge.lib.breadcrumbs.Breadcrumbs(request)

User breadcrumb trail, current title page and back URL management.

This class uses session and stores its history in session['breadcrumbs']. It is a list of crumbs. Each crumb is a tuple such as (<title>, <route_name>, <route_parts>, <chunks_to_compare>).

trail()

Output XHTML breadcrumb trail.

current_title()

Title of current page.

current_path()

Path of current page.

back_title()

Output title of previous page.

back_path()

Output the path of previous page.

back_button()

A button to return to the previous page.

add(title, length=10, root_chunks=10, replace=None, anchor=None, keep=False)

Add a crumb in breadcrumb trail.

Parameters:

• title – (string) Page title in breadcrumb trail.
• length – (int, default=10) Maximum crumb number. If 0, it keeps the current length.
• root_chunks – (int, default=10) Number of path chunks to compare to highlight menu item.
• replace – (string, optional): If current path is replace, this method call pop() before any action.
• anchor – (string, optional) Anchor to add.
• keep – (boolean, optional) If True, keep the last crumb even if it is the same as the current.

pop()

Pop last breadcrumb.

The lib.menu Module

Class to manage user menus.

class publiforge.lib.menu.Menu(request)

User menu management.

update()

Update the session with menu content.

xhtml()

Return an <ul> structure with current entry highlighted.

The lib.tabset Module

Widget to create tabs.

class publiforge.lib.tabset.TabSet(request, labels)

A class to manages tabs.

toc(tab_id)

Output a table of content of the TabSet in an <ul> structure.

Parameters:tab_id – (string) Tab set ID. Returns:(string) <ul> structure.

tab_begin(index, access_key=None)

Open a tab zone.

Parameters:

• index – (integer) Tab index.
• access_key – (string, optional) Access key for tab.

Returns:

(string) Opening fieldset structure with legend.

classmethod tab_end()

Close a tab zone.

The lib.rsync Module

Provides a high-level interface to some librsync functions.

This is a python wrapper around the lower-level _librsync module, which is written in C.

class publiforge.lib.rsync.LikeFile(infile, need_seek=None)

File-like object used by SigFile, DeltaFile, and PatchFile.

classmethod check_file(likefile, need_seek=None)

Raise type error if likefile doesn’t have necessary attributes.

read(length=-1)

Build up self.outbuf, return first length bytes.

close()

Close infile.

class publiforge.lib.rsync.SigFile(infile, blocksize=65536)

File-like object which incrementally generates a librsync signature

class publiforge.lib.rsync.DeltaFile(signature, new_file)

File-like object which incrementally generates a librsync delta.

class publiforge.lib.rsync.PatchedFile(basis_file, delta_file)

File-like object which applies a librsync delta incrementally.

exception publiforge.lib.rsync.LibRSyncError

Signifies error in internal librsync processing (bad signature, etc.)

underlying _librsync.librsyncError’s are regenerated using this class because the C-created exceptions are by default unPickleable. There is probably a way to fix this in _librsync, but this scheme was easier.

publiforge.lib.rsync.get_block_size(filename)

Return a reasonable block size to use on files of length file_len

If the block size is too big, deltas will be bigger than is necessary. If the block size is too small, making deltas and patching can take a really long time.

The lib.vcs Module

Version Control System library.

class publiforge.lib.vcs.Vcs(path, url, user_id=None, password=None)

Abstract base class for version control class.

clone(handler=None)

Create a copy of an existing repository in a directory. (abstract)

Parameters:handler – (Handler instance, optional) Owner of this action. Returns:(string) Error message or None if it succeeds.

pull_update(handler=None)

Pull changes and update. (abstract)

Parameters:handler – (Handler instance, optional) Owner of this action. Returns:(string) Error message or None if it succeeds.

commit_push(message, user_id, password, name, handler=None)

Commit and push changes. (abstract)

Parameters:

• message – (string) Commit message.
• user_id – (string) User ID for VCS access.
• password – (string) Cleared password for VCS access.
• name – (string) Name for VCS access.
• handler – (Handler instance, optional) Owner of this action.

Returns:

(string) Error message or None if it succeeds.

remove_untracked(path, handler)

Remove untracked files. (abstract)

Parameters:

• path – (string) Relative path to browse.
• handler – (Handler instance) Owner of this action.

revert_all(handler)

Revert all files of the repository. (abstract)

Parameters:handler – (Handler instance) Owner of this action.

backout(name, handler)

Reverse effect of earlier changeset. (abstract)

Parameters:

• name – (string) Name for VCS access.
• handler – (Handler instance) Owner of this action.

recover(handler)

Recover from an interrupted commit or pull. (abstract)

Parameters:handler – (Handler instance) Owner of this action.

last_change()

Return the last change on the repository. (abstract)

Returns:(tuple) A tuple such as (date, changeset, user).

log(path, filename, limit=1)

Show revision history of file filename.

Parameters:

• path – (string) Relative path to file.
• filename – (string) Name of the file.
• limit – (integer, default=1) Maximum number of entries in log.

Returns:

(list of tuples or string) Log or error message.

Each tuple or entry is like (date, changeset, user, message).

directory_log(path, quick=False)

List all files of a directory with VCS informations.

Parameters:

• path – (string) Relative path of the directory.
• quick – (boolean) True to have a quick information.

Returns:

(tuple) A tuple such as (dirs, files) where dirs and files are lists such as [name, type, size, date, revision, user, message].

add(path, handler=None)

Add all new files in path. (abstract)

Parameters:

• path – (string) Relative path to browse.
• handler – (Handler instance, optional) Owner of this action.

Returns:

(string) Error message or None if it succeeds.

create(seed, path, name, handler)

Create a new file according to the seed file.

Parameters:

• seed – (string) Full path to the seed file.
• path – (string) Relative path to directory to create.
• name – (string) Name of directory to create.
• handler – (Handler instance) Owner of this action.

duplicate(path, original, name, handler)

Duplicate the original file.

Parameters:

• path – (string) Relative path to directory to create.
• original – (string) Name of the original file.
• name – (string) Name of directory to create.
• handler – (Handler instance) Owner of this action.

mkdir(path, name, handler=None)

Make the directroy name.

Parameters:

• path – (string) Relative path to directory to create.
• name – (string) Name of directory to create.
• handler – (Handler instance, optional) Owner of this action.

rename(path, filename, new_name, handler)

Rename a file. (abstract)

Parameters:

• path – (string) Relative path to file to rename.
• filename – (string) Name of the file to remove.
• new_new – (string) New name.
• handler – (Handler instance) Owner of this action.

Returns:

(string) Error message or None if it succeeds.

remove(path, filename, handler)

Remove a file. (abstract)

Parameters:

• path – (string) Relative path to file to remove.
• filename – (string) Name of the file to remove.
• handler – (Handler instance) Owner of this action.

Returns:

(string) Error message or None if it succeeds.

revision(fullname, revision)

Retrieve a revision. (abstract)

Parameters:

• fullname – (string) Full name of the file.
• revision – (string) Revision number to retrieve.

Returns:

(string) Content of the file.

diff(fullname, revision)

Return differences between revision revision and current revision. (abstract)

Parameters:

• fullname – (string) Full name of the file.
• revision – (string) Revision number to compare.

Returns:

(string) Differences.

full_path(*path)

Return normalized full path of path file or an error message if it is outside the storage.

Parameters:path – (strings) Path chunks. Returns:(string or pyramid.i18n.TranslationString instance) Full path or error message.

class publiforge.lib.vcs.VcsNone(path, url, user_id=None, password=None)

No Version Control System.

clone(handler=None)

Create a directory.

See abstract function clone().

pull_update(handler=None)

Do nothing.

See abstract function pull_update().

commit_push(message, user_id, password, name, handler=None)

Do nothing.

See abstract function commit_push().

remove_untracked(path, handler)

Do nothing.

See remove_untracked().

revert_all(handler)

Do nothing.

See abstract function revert_all().

backout(name, handler)

Do nothing.

See backout().

recover(handler)

Do nothing.

See recover().

last_change()

Return the last change on the repository.

See last_change().

log(path, filename, limit=1)

show revision history of file filename.

See log().

add(path, handler=None)

Do nothing.

See abstract function add().

rename(path, filename, new_name, handler)

Rename a file.

See rename().

remove(path, filename, handler)

Remove a file.

See remove().

revision(fullname, revision)

Retrieve a revision.

See revision().

diff(fullname, revision)

Return differences between revision revision and current revision.

See diff().

Storage with Mercurial Version Control management.

class publiforge.lib.vcs.hg.VcsMercurialUi(src=None)

Override Mercurial ui class for PubliForge use.

write(*args, **opts)

Write args in log as informations.

write_err(*args, **opts)

Write args in log as errors.

class publiforge.lib.vcs.hg.VcsMercurialUiLog(src=None)

Ui class to retrieve file information.

write(*args, **opts)

This method collects log information.

class publiforge.lib.vcs.hg.VcsMercurial(path, url, user_id=None, password=None)

Version control system with Mercurial.

clone(handler=None)

Create a copy of an existing repository in a directory.

See abstract function clone().

pull_update(handler=None)

Pull changes and update.

See abstract function pull_update().

commit_push(message, user_id, password, name, handler=None)

Commit and push changes.

See abstract method commit_push().

remove_untracked(path, handler)

Remove untracked files.

See remove_unrtacked().

revert_all(handler)

Revert all files of the repository.

backout(name, handler)

Reverse effect of earlier changeset.

See backout().

recover(handler)

Recover from an interrupted commit or pull.

last_change()

Return the last change on the repository.

See last_change().

log(path, filename, limit=1)

Show revision history of file filename.

See log().

directory_log(path, quick=False)

List all files of a directory with VCS informations.

See directory_log().

add(path, handler=None)

Add all new files in path.

See abstract function add().

rename(path, filename, new_name, handler)

Rename a file.

remove(path, filename, handler)

Remove a file.

See abstract function remove().

revision(fullname, revision)

Retrieve a revision.

See revision().

diff(fullname, revision)

Return differences between revision revision and current revision.

See diff().

class publiforge.lib.vcs.hg.VcsLocal(path, url, user_id=None, password=None)

Version control system for local files.

clone(handler=None)

Initialize a Mercurial repository and copy source.

See abstract function clone().

Storage with Subversion Version Control System management.

class publiforge.lib.vcs.svn.VcsSubversion(path, url, user_id=None, password=None)

Version control system with Subversion.

clone(handler=None)

Create a copy of an existing repository in a directory.

See abstract function clone().

pull_update(handler=None)

Pull changes and update.

See abstract function pull_update().

commit_push(message, user_id, password, name, handler=None)

Commit and push changes.

See abstract method commit_push().

remove_untracked(path, handler)

Remove untracked files.

See remove_unrtacked().

revert_all(handler)

Revert all files of the repository.

backout(name, handler)

Reverse effect of earlier changeset.

See backout().

recover(handler)

Recover from an interrupted commit or pull.

last_change()

Return the last change on the repository.

See last_change().

log(path, filename, limit=1)

show revision history of file filename.

See log().

add(path, handler=None)

Add all new files in path.

See abstract function add().

mkdir(path, name, handler=None)

Make the directroy name.

See abstract function mkdir().

rename(path, filename, new_name, handler)

Rename a file.

remove(path, filename, handler)

Remove a file.

See abstract function remove().

revision(fullname, revision)

Retrieve a revision.

See revision().

diff(fullname, revision)

Return differences between revision revision and current revision.

See diff().