Front Library Reference

The lib.build.front Module

Front build management.

A front is a web site.

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

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.

complete(request, key)[source]

Start a complete action in a thread.

Parameters:
  • request – (object) WebOb request object.
  • key – (string) Authentication key.
Returns:

(boolean) True if succeeds.

progress(request)[source]

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

Start a build in a thread.

Parameters:request – (pyramid.request.Request instance) Current request.
Returns:(boolean)
stop(request=None)[source]

Stop building.

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

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.

class publiforge.lib.build.front.FrontBuildManager(settings)[source]

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

Return a list of URLs of available agents.

build_list(project_id, user_id=None)[source]

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.

call(request, url, method, *args)[source]

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.

complete(request, build_id, key)[source]

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)

find_agent(request, processor_id)[source]

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).

forget_results(project_id, user_id=None, build_ids=None, pack_id=None)[source]

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.
is_owner(request, build_id, user_id=None)[source]

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)

processor(request, processor_id)[source]

Return a processor tree.

Parameters:
Returns:

(lxml.etree.ElementTree or None)

progress(request, build_ids)[source]

Return the progress of builds.

Parameters:
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
refresh_agent_list(request)[source]

Refresh processor list for each agent.

Parameters:request – (pyramid.request.Request instance) Current request.
result(build_id)[source]

Return the result of a build.

Parameters:build_id – (string) Build ID.
Returns:(dictionary)
start_build(request, processing, processor, pack, tasks=None)[source]

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

Start waiting builds.

Parameters:request – (pyramid.request.Request instance) Current request.
stop(request, build_ids, user_id=None)[source]

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.

The lib.opener Module

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

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

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

Return True if it can produce an editor.

Return type:bool
classmethod can_render()[source]

Return True if it can produce a rendering.

Return type:bool
classmethod can_write()[source]

Return True if it can simply modify the file.

Return type:bool
css(mode, request=None)[source]

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)

description(request=None)[source]

Description in local or default language.

Parameters:request (pyramid.request.Request) – (optional) Current request.
classmethod edit(request, action, storage, path, content=None)[source]

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

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.

has_seeds()[source]

Return True if at least one seed exists.

Return type:bool
information(request, name)[source]

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)

install_environment(request=None, opener_id=None, target=None, can_reset=False)[source]

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)

is_valid(request, storage, path, content=None, values=None)[source]

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).

javascript(mode, request=None)[source]

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)

label(request=None)[source]

Label in local or default language.

Parameters:request (pyramid.request.Request) – (optional) Current request.
match(fullname, content=None)[source]

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.

navigate(directory, filename, direction)[source]

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.

overview(request, storage, path, content=None)[source]

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.

position(directory, filename)[source]

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).

read(request, storage, path, content=None)[source]

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.

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

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 resources_dirs(filename, media_type)[source]

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

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)

route()[source]

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).
save(request, storage, path, content, values)[source]

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

seed_list(request)[source]

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
title(request, storage, path, content=None)[source]

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.

write(request, storage, path, content=None)[source]

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.

class publiforge.lib.opener.OpenerManager(settings)[source]

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.

add_static_views(configurator)[source]

Possibly, add static view for openers.

Parameters:configurator (pyramid.config.Configurator) – Object to configure a Pyramid application registry.
descriptions(request, opener_ids=None)[source]

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)

get_opener(filename, storage)[source]

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.

has_seeds(opener_ids)[source]

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

Return a list of IDs of available openers.

Return type:list
seed_fullpath(request, path)[source]

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

Parameters:
Returns:

(string or None)

seed_list(request, opener_ids)[source]

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)

The lib.handler Module

A handler manages access to a storage and its indexing.

class publiforge.lib.handler.Handler(handler_manager, storage)[source]

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).

add(user, path, message)[source]

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.
clone(request=None)[source]

Launch an action to clone a storage.

Parameters:request – (pyramid.request.Request instance, optional) Current request.
create(user, seed, path, name, message)[source]

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.
dir_infos(*args)

Cache function.

duplicate(user, path, original, name, message)[source]

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

Schedule index.

launch(request, action, args=(), kwargs=None)[source]

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.

mkdir(user, path, name, message)[source]

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

Return the progress of action on the storage.

Returns:(tuple) A tuple such as (status, message). See Handler class.
recover()[source]

Recover from an interrupted commit or pull.

remove(user, path, filenames, message)[source]

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.
rename(user, path, filename, new_name, message)[source]

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.
replace(user, path, content, message)[source]

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.
report(status, message=None)[source]

Save a report.

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

(string or None) Message.

synchronize(request, force=False)[source]

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.

upload(user, path, upload_files, filename, message)[source]

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.
class publiforge.lib.handler.HandlerManager(settings, cache_manager, opener_manager=None)[source]

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.

currently_managed()[source]

Return a list of ID of currently managed storages.

delete_index(update=True)[source]

Delete all indexes.

Parameters:update (bool) – (default=True) If True update indexes after deleting.
get_handler(storage_id, storage=None)[source]

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)

index(storage_id, in_thread=False)[source]

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.
progress(storage_ids, pending=False)[source]

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.

remove_handler(storage_id)[source]

Remove handler from handler list.

Parameters:storage_id – (string) Storage ID.
search(storage_id, fieldnames, query, limit=None)[source]

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.

vcs_list()[source]

Return a list of available Version Control System.

The lib.xml Module

XML manipulation.

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

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.import_configuration(settings, filename, only=None, error_if_exists=True, xml=None, request=None)[source]

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.load(filename, relaxngs=None, data=None, noline=False, parser=None)[source]

Legacy function.

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

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.local_text(root_elt, xpath, request=None, lang=None, default='')[source]

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

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.validate_xml(tree, relaxngs, noline=False)[source]

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.xml_wrap(text, depth)[source]

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

XPath function: camel_case().

publiforge.lib.xml.xpath_make_id(context, name, mode)[source]

XPath function: make_id().

publiforge.lib.xml.xpath_relpath(context, path, start)[source]

XPath function: relpath().

publiforge.lib.xml.xpath_wrap(context, text, depth)[source]

XPath function: xml_wrap().

The lib.i18n Module

Localization management.

publiforge.lib.i18n.add_translation_dirs(configurator, package)[source]

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

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

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.translate_field(request, i18n_fields)[source]

Return the best translation according to user language.

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

Retrieve a value from a configuration object.

Parameters:
Return type:

str Read value or default value.

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

Retrieve a list of values from a configuration object.

Parameters:
Return type:

list

publiforge.lib.config.config_get_namespace(config, section, namespace)[source]

Retrieve all options beginning by a name space.

Parameters:
Return type:

dict

publiforge.lib.config.settings_get_directories(settings, namespace, conf_file)[source]

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

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

Retrieve a list of values from a settings dictionary.

Parameters:
Return type:

list

The lib.utils Module

Some various utilities.

publiforge.lib.utils.age(mtime)[source]

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

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.cache_key(cache, method_name, *args)[source]

Compute a cache key.

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

(string)

publiforge.lib.utils.camel_case(text)[source]

Convert text in Camel Case.

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

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.decrypt(value, key)[source]

Decryption function.

Parameters:
  • value (str) – String to decrypt.
  • key (str) – Encryption key.
Return type:

str

Returns:

Clear value or None.

publiforge.lib.utils.duration(request, seconds)[source]

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

Check the validity of an email address.

Parameters:email (str) – Address to check.
Return type:bool
publiforge.lib.utils.encrypt(value, key)[source]

Encryption function.

Parameters:
  • value (str) – String to encrypt.
  • key (str) – Encryption key.
Return type:

str

Returns:

Encrypted value or None.

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

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.export_file_set(root_elt, record, file_type)[source]

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

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.has_permission(request, *perms)[source]

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.hash_sha(value, key='')[source]

Cryptographic hash function with SHA1 algorithm.

Parameters:
  • value – (string) String to hash.
  • key – (string, optional) Encryption key.
publiforge.lib.utils.image_metadata(img_file)[source]

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).
publiforge.lib.utils.load_regex(filename)[source]

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.make_id(name, mode=None, truncate=None)[source]

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.normalize_filename(filename, mode='simple', is_dir=False)[source]

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

Normalize name.

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

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

Transform a reStructuredText into XHTML.

Parameters:rst (str) – reStructuredText.
Return type:str
Returns:XHTML.
publiforge.lib.utils.shift_files(direction, index, record, files, form)[source]

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.size_label(size, is_dir)[source]

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.token(length=None)[source]

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.unzip(archive, outpath, normalize_mode=None)[source]

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.wrap(text, width=70, indent=0)[source]

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.

The lib.log Module

Various functions to manage logs.

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

Write a message in the activity log.

Parameters:
publiforge.lib.log.log_activity_setup(global_config)[source]

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_error(request, error)[source]

Write an error message in the log.

Parameters:request (pyramid.request.Request) – Current request.
publiforge.lib.log.setup_logging(log_level='INFO', log_file=None, log_format=None)[source]

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

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=OrderedDict([('=', '='), ('!=', u'u2260'), ('>', '>'), ('>=', u'u2265'), ('<', '<'), ('<=', u'u2264')]))[source]

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')]]

append_condition(key, comparison, value, operator='AND')[source]

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

Clear filter.

html_conditions()[source]

An HTML representation of the current conditions.

Return type:webhelpers2.html.literal
html_inputs(form, tag='span')[source]

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

is_empty()[source]

Return True if a filter is empty.

remove_condition(index)[source]

Remove one AND-condition of the filter.

Parameters:index (str) – Index of the AND-condition to remove.
sql(dbquery, table_name)[source]

Complete a SqlAlchemy query with of the current filter.

Parameters:
Return type:

sqlalchemy.orm.query.Query

whoosh()[source]

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

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.current_processing(request, project_id=None, processing_id=None, pack=None)[source]

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

Return the current processing object.

Parameters:
Returns:

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

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

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_storage(request, storage_id=None, only_dict=True)[source]

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

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.file_details(request, record, only_visible=True)[source]

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

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

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

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

Return selected files in the current selection.

Parameters:request – (pyramid.request.Request instance) Current request.
Returns:(tuple)
publiforge.lib.viewutils.paging_groups(request, paging_id='groups')[source]

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.paging_users(request, only_active=True)[source]

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.save_vcs_user(request, storage)[source]

Save user name and password for VCS in database.

Parameters:
publiforge.lib.viewutils.selection2container(request, container_type, container, file_type, paths, processing=None)[source]

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.task_auto_build(request, pack, task=None)[source]

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.

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

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.variable_input(form, name, var_type, var=None, **attrs)[source]

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_schema(processor, values, with_visibility=True)[source]

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

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.vcs_user(request, storage)[source]

Return a VCS user tuple.

Parameters:
Returns:

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

The lib.packutils Module

Some various utilities for packs.

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

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.operator4task(pack, link_type, task_id=None)[source]

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

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

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)

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

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

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_content(request, project_id, message, label=None, handler=None)[source]

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.pack_upload_settings(request, project_id, pack_doc=None, pack_id=None)[source]

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.paging_packs(request, project_id)[source]

Return a Paging object filled with packs of project project_id.

Parameters:
Returns:

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

The lib.form Module

Form validation and rendering library.

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

Form validation class.

begin(url=None, multipart=False, **attrs)[source]

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 button(url, label='', src=None, title=None, class_='button')[source]

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

See button().

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

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

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.

classmethod end()[source]

Ouput the </form> tag.

error(name)[source]

Return error message for field name.

Parameters:name (str) – Input ID.
Return type:str
Returns:Translated error message.
forget(prefix)[source]

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

Parameters:prefix (str) – Prefix to select fields.
grid_checkbox(name, label, required=False, hint=None, class_='', clear=False, **attrs)[source]

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

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.

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

Output an item with label, hint and error message.

See grid_item().

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

Output a password field in a CSS grid layout.

This method takes the same options as grid_text().

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

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_text(name, label, required=False, hint=None, class_='', clear=False, **attrs)[source]

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_textarea(name, label, required=False, hint=None, class_='', clear=False, **attrs)[source]

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.

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

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.

has_error(name=None)[source]

Return True if field name has an error.

Parameters:name (str) – (optional) Input ID.
Return type:bool
hidden(name, value=None, **attrs)[source]

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.

classmethod make_safe_id(name)[source]

Make a string safe for including in an id attribute

Parameters:name (str) – String to transform.
Return type:str
password(name, value=None, **attrs)[source]

Output a password field.

This method takes the same options as text().

radio(name, value, checked=False, **attrs)[source]

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

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.

set_error(name, message)[source]

Set an error message for field name.

Parameters:
  • name (str) – Input ID.
  • message (str) – Error message.
static(name)[source]

The field name will not be updated by the form.

Parameters:name (str) – Name of field to set static.
classmethod submit(name, label=None, class_='button', **attrs)[source]

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

Output a cancel submit button.

Parameters:label (str) – Label for roll over and alt.
Return type:str
Returns:HTML tag.
classmethod submit_image(name, label, src, class_=None)[source]

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.

text(name, value=None, **attrs)[source]

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.

textarea(name, content='', **attrs)[source]

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.

upload(name, value=None, **attrs)[source]

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.

validate(obj=None)[source]

Check if the form is validated.

Parameters:obj (object) – (optional) Object to fill.
Return type:bool
Returns:True if validated.
class publiforge.lib.form.SameAs(request, reference)[source]

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

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

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.

The lib.breadcrumbs Module

Breadcrumbs utility.

class publiforge.lib.breadcrumbs.Breadcrumbs(request)[source]

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>).

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

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

A button to return to the previous page.

back_path()[source]

Output the path of previous page.

back_title()[source]

Output title of previous page.

current_path()[source]

Path of current page.

current_title()[source]

Title of current page.

pop()[source]

Pop last breadcrumb.

trail()[source]

Output XHTML breadcrumb trail.

The lib.menu Module

Class to manage user menus.

class publiforge.lib.menu.Menu(request)[source]

User menu management.

update()[source]

Update the session with menu content.

xhtml()[source]

Return an <ul> structure with current entry highlighted.

The lib.tabset Module

Widget to create tabs.

class publiforge.lib.tabset.TabSet(request, labels)[source]

A class to manages tabs.

tab_begin(index, access_key=None)[source]

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

Close a tab zone.

toc(tab_id)[source]

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

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

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.DeltaFile(signature, new_file)[source]

File-like object which incrementally generates a librsync delta.

exception publiforge.lib.rsync.LibRSyncError[source]

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.

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

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

classmethod check_file(likefile, need_seek=None)[source]

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

close()[source]

Close infile.

read(length=-1)[source]

Build up self.outbuf, return first length bytes.

class publiforge.lib.rsync.PatchedFile(basis_file, delta_file)[source]

File-like object which applies a librsync delta incrementally.

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

File-like object which incrementally generates a librsync signature

publiforge.lib.rsync.get_block_size(filename)[source]

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

Abstract base class for version control class.

add(path, handler=None)[source]

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.

backout(name, handler)[source]

Reverse effect of earlier changeset. (abstract)

Parameters:
  • name – (string) Name for VCS access.
  • handler – (Handler instance) Owner of this action.
clone(handler=None)[source]

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.
commit_push(message, user_id, password, name, handler=None)[source]

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.

create(seed, path, name, handler)[source]

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.
diff(fullname, revision)[source]

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.

directory_log(path, quick=False)[source]

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].

duplicate(path, original, name, handler)[source]

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.
full_path(*path)[source]

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

Return the last change on the repository. (abstract)

Returns:(tuple) A tuple such as (date, changeset, user).
log(path, filename, limit=1)[source]

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).

mkdir(path, name, handler=None)[source]

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.
pull_update(handler=None)[source]

Pull changes and update. (abstract)

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

Recover from an interrupted commit or pull. (abstract)

Parameters:handler – (Handler instance) Owner of this action.
remove(path, filename, handler)[source]

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.

remove_untracked(path, handler)[source]

Remove untracked files. (abstract)

Parameters:
  • path – (string) Relative path to browse.
  • handler – (Handler instance) Owner of this action.
rename(path, filename, new_name, handler)[source]

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.

revert_all(handler)[source]

Revert all files of the repository. (abstract)

Parameters:handler – (Handler instance) Owner of this action.
revision(fullname, revision)[source]

Retrieve a revision. (abstract)

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

(string) Content of the file.

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

No Version Control System.

add(path, handler=None)[source]

Do nothing.

See abstract function add().

backout(name, handler)[source]

Do nothing.

See backout().

clone(handler=None)[source]

Create a directory.

See abstract function clone().

commit_push(message, user_id, password, name, handler=None)[source]

Do nothing.

See abstract function commit_push().

diff(fullname, revision)[source]

Return differences between revision revision and current revision.

See diff().

last_change()[source]

Return the last change on the repository.

See last_change().

log(path, filename, limit=1)[source]

show revision history of file filename.

See log().

pull_update(handler=None)[source]

Do nothing.

See abstract function pull_update().

recover(handler)[source]

Do nothing.

See recover().

remove(path, filename, handler)[source]

Remove a file.

See remove().

remove_untracked(path, handler)[source]

Do nothing.

See remove_untracked().

rename(path, filename, new_name, handler)[source]

Rename a file.

See rename().

revert_all(handler)[source]

Do nothing.

See abstract function revert_all().

revision(fullname, revision)[source]

Retrieve a revision.

See revision().

Storage with Mercurial Version Control management.

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

Version control system for local files.

clone(handler=None)[source]

Initialize a Mercurial repository and copy source.

See abstract function clone().

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

Version control system with Mercurial.

add(path, handler=None)[source]

Add all new files in path.

See abstract function add().

backout(name, handler)[source]

Reverse effect of earlier changeset.

See backout().

clone(handler=None)[source]

Create a copy of an existing repository in a directory.

See abstract function clone().

commit_push(message, user_id, password, name, handler=None)[source]

Commit and push changes.

See abstract method commit_push().

diff(fullname, revision)[source]

Return differences between revision revision and current revision.

See diff().

directory_log(path, quick=False)[source]

List all files of a directory with VCS informations.

See directory_log().

last_change()[source]

Return the last change on the repository.

See last_change().

log(path, filename, limit=1)[source]

Show revision history of file filename.

See log().

pull_update(handler=None)[source]

Pull changes and update.

See abstract function pull_update().

recover(handler)[source]

Recover from an interrupted commit or pull.

remove(path, filename, handler)[source]

Remove a file.

See abstract function remove().

remove_untracked(path, handler)[source]

Remove untracked files.

See remove_unrtacked().

rename(path, filename, new_name, handler)[source]

Rename a file.

revert_all(handler)[source]

Revert all files of the repository.

revision(fullname, revision)[source]

Retrieve a revision.

See revision().

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

Override Mercurial ui class for PubliForge use.

write(*args, **opts)[source]

Write args in log as informations.

write_err(*args, **opts)[source]

Write args in log as errors.

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

Ui class to retrieve file information.

write(*args, **opts)[source]

This method collects log information.

Storage with Subversion Version Control System management.

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

Version control system with Subversion.

add(path, handler=None)[source]

Add all new files in path.

See abstract function add().

backout(name, handler)[source]

Reverse effect of earlier changeset.

See backout().

clone(handler=None)[source]

Create a copy of an existing repository in a directory.

See abstract function clone().

commit_push(message, user_id, password, name, handler=None)[source]

Commit and push changes.

See abstract method commit_push().

diff(fullname, revision)[source]

Return differences between revision revision and current revision.

See diff().

last_change()[source]

Return the last change on the repository.

See last_change().

log(path, filename, limit=1)[source]

show revision history of file filename.

See log().

mkdir(path, name, handler=None)[source]

Make the directroy name.

See abstract function mkdir().

pull_update(handler=None)[source]

Pull changes and update.

See abstract function pull_update().

recover(handler)[source]

Recover from an interrupted commit or pull.

remove(path, filename, handler)[source]

Remove a file.

See abstract function remove().

remove_untracked(path, handler)[source]

Remove untracked files.

See remove_unrtacked().

rename(path, filename, new_name, handler)[source]

Rename a file.

revert_all(handler)[source]

Revert all files of the repository.

revision(fullname, revision)[source]

Retrieve a revision.

See revision().