Library Reference 

chrysalio.lib.attachment.attachment_url(request: Request, category: str, key: str, filename: str) → str | None[source]

Return the URL of an attachement file or None if it does not exist or attachments are not activated.

Parameters:

request (pyramid.request.Request) – Current request.
category (str) – Category of attachement (e.g. Users).
key (str) – Key to access to the attachments.
filename (str) – Name of file to retrieve.

Return type:

chrysalio.lib.attachment.attachment_update(request: Request, category: str, key: str, field: cgi_FieldStorage, replace: str | None = None, prefix: str = '') → tuple[str, str | None][source]

Update the content of the attachment directory.

Parameters:

request (pyramid.request.Request) – Current request.
category (str) – Category of attachement (e.g. Users).
key (str) – Key to access to the attachments.
field (webob.compat.cgi_FieldStorage) – File to retrieve.
replace (str) – (optional) File to delete before adding the new file.
prefix (str) – (optional) Prefix for newly created attachment key.

Return type:

Returns:

A tuple such as (attachments_key, file_path).

The `lib.breadcrumbs` Module

Breadcrumbs utility.

class chrysalio.lib.breadcrumbs.Breadcrumbs(request: Request, sep: str = ' » ')[source]

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

Parameters:

request (pyramid.request.Request) – Current request.
sep (str) – (optional) Separator for brundcrumb trail.

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_params, chunks_to_compare).

is_empty() → bool[source]: Check if it is necessary to display the breadcrumb trial.

pop()[source]: Pop last breadcrumb.

trail(without_last: bool = False) → str[source]

Output XHTML breadcrumb trail.

Parameters:: without_last (bool) – (default = False) If True, remove the last chunk.
Return type:: str

crumb_trail() → list[source]

Return a trail of crumbs to compare with menu entries. Each crumb is tuple of a list of path chunks and a comparison length.

Return type:: list
Returns:: A list of crumbs. Each crumb is a tuple such as ([chunk1, chunk2,...], root_chunks) where root_chunks is a number of route path chunks to compare to highlight a menu entry

current_title() → str[source]

Title of current page.

Return type:: str

current_route_name() → str[source]

Route name of current page.

Return type:: str

current_path() → str[source]

Path of current page.

Return type:: str

back_title() → str[source]

Output title of previous page.

Return type:: str

back_path() → str[source]

Output the path of previous page.

Return type:: str

The `lib.config` Module

Various functions to parse configuration files or settings.

chrysalio.lib.config.update_acl(configurator, principals)[source]

Update root factory Access Control List (ACL) with permissions.

Parameters:

configurator (pyramid.config.Configurator) – Object used to do configuration declaration within the application.
principals (tuple)

principals is a tuple such as:

DOCUMENT_PRINCIPALS = (
    ('document', _('Document management'), (
        ('viewer', _('View all documents'), (
            'document-view',)),
        ('editor', _('Edit any document'), (
            'document-view', 'document-edit'))
    )),
)

chrysalio.lib.config.config_get(config, section, option, default=None)[source]

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.

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

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

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

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:

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

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

chrysalio.lib.config.settings_get_namespace(settings, namespace)[source]

Retrieve all options beginning by a name space.

Parameters:

settings (pyramid.registry.Registry.settings) – Settings object.
namespace (str) – Prefix of options to retrieve.

Return type:

chrysalio.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:

The `lib.filter` Module

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

class chrysalio.lib.filter.Filter(request: Request, filter_id: str, inputs: list, initials: list | None = None, remove: str | None = None, comparisons: OrderedDict | None = None)[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),...).
initials (list) – (optional) Initial conditions.
remove (str) – (optional) Number of the condition to remove from the previous filter.
comparisons (collections.OrderedDict) – (optional) Customize list of comparaisons.

For inputs the available_values field must be:

None for a string value
'' for a string value with auto-completion
True for a boolean value
0 for an integer value
a list of value/label for closed list of values.

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() → bool[source]: Return True if a filter is empty.

clear()[source]: Clear filter.

append_condition(key: str, comparison: str, value: str | bool | int | float, operator: str = '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.

remove_condition(index: str)[source]

Remove one AND-condition of the filter.

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

html_inputs(form: Form, tag: str = 'span') → str[source]

An HTML representation of the current inputs.

Parameters:

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

Return type:

sqlalchemy.orm.query.Query

html_filter() → str[source]

An HTML representation of the current filter.

Return type:: helpers.literal.Literal

sql(dbquery: Query, table_name: str, ignored: list | None = None) → Query[source]

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.
ignored (list) – (optional) List of and-conditions that must be ignored. They should be processed by the caller, probably because of joins.

Return type:

classmethod sql_autocomplete(request: Request, table_class, where: dict | None = None, limit: int = 10, width: int = 0) → list[source]

Suggest terms for auto-completion in SQL.

Parameters:

request (pyramid.request.Request) – Current request.
table_class – SQLAlchemy table class to query.
where (dict) – (optional) WHERE clause for the query.
limit (int) – (default=10) Limit for the search.
width (int) – (default=25) Shorten the length of each suggestion.

Return type:

list

tantivy() → str[source]

Return the current filter in Tantivy query language.

Return type:: str

whoosh() → tuple[tuple, str][source]

Return the current filter in Whoosh query language.

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

The `lib.i18n` Module

Localization management.

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

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

chrysalio.lib.i18n.translate(text, lang=None, request=None)[source]

Return text translated.

Parameters:

text (str) – Text to translate.
lang (str) – (optional) Language to use.
request (pyramid.request.Request) – (optional) Current request to find the current language.

Return type:

chrysalio.lib.i18n.translate_field(request, i18n_fields, default='')[source]

Return the best translation according to user language.

Parameters:

request (pyramid.request.Request) – Current request.
i18n_fields (dict) – Dictionary of avalaible translations.
default (str) – Default label.

Return type:

chrysalio.lib.i18n.record_format_i18n(record)[source]

Update record by converting label and description entries into a dictionary with languages as key.

Parameters:: record (dict) – Dictionary to process.
Return type:: bool
Returns:: True if a label has been found.

chrysalio.lib.i18n.view_i18n_labels(request, form, dbitem, with_label=True, with_description=True)[source]

Return HTML input to edit i18n labels.

Parameters:

request (pyramid.request.Request) – Current request.
dbitem – Current SqlAlchemy object.
with_label (bool) – (default=True) If True, produce input fields for labels.
with_description (bool) – (default=True) If True, produce input fields for descriptions.

Return type:

helpers.literal.Literal

chrysalio.lib.i18n.schema_i18n_labels(request, schema, label_len=0, description_len=0, prefix='', required=True)[source]

Update the Colander schema with fields for label ans, possibly, for descriptions of each available language.

Parameters:

request (pyramid.request.Request) – Current request.
schema (colander.SchemaNode) – Current Colander schema.
label_len (int) – (optional) Maximum length of label. If 0, no field is produced.
description_len (int) – (optional) Maximum length of description. If 0, no field is produced.
prefix (str) – (optional) A prefix for the name of field.
required (bool) – (default=True) True if the label in default language is required.

chrysalio.lib.i18n.defaults_i18n_labels(dbitem, with_label=True, with_description=True, prefix='')[source]

Return a dictionary of default values for labels.

Parameters:

dbitem – Current SqlAlchemy object.
with_label (bool) – (default=True) If True, produce input fields for labels.
with_description (bool) – (default=True) If True, produce input fields for descriptions.
prefix (str) – (optional) A prefix for the name of field.

chrysalio.lib.i18n.edit_i18n_labels(request, form, label_len=0, description_len=0, prefix='')[source]

Return HTML input to edit i18n labels.

Parameters:

request (pyramid.request.Request) – Current request.
label_len (int) – (optional) Maximum length of label. If 0, no field is produced.
description_len (int) – (optional) Maximum length of description. If 0, no field is produced.
prefix (str) – (optional) A prefix for the name of field.

Return type:

helpers.literal.Literal

The `lib.log` Module

Various functions to manage logs.

chrysalio.lib.log.setup_logging(log_level='INFO', log_file=None, log_format=None, filemode='w')[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
filemode (str) – (default=’w’) File mode: 'w' or 'a'.

chrysalio.lib.log.log_activity_setup(config, config_file=None)[source]

Create log directory.

Parameters:

config (configparser.ConfigParser) – Configuration of the site.
config_file (str) – Absolute path to the configuration file.

Return type:

logging.Logger

Returns:

Return LOG_ACTIVITY if activity log is activated.

chrysalio.lib.log.log_info(request, action, *args)[source]

Write an information message in the log.

Parameters:

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

chrysalio.lib.log.log_error(request, error)[source]

Write an error message in the log.

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

chrysalio.lib.log.log_warning(request, warning)[source]

Write a warning message in the log.

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

chrysalio.lib.log.log_debug(request, debug)[source]

Write a debug message in the log.

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

The `lib.mailing` Module

Function to manage e-mails.

class chrysalio.lib.mailing.Mailing(request)[source]

Class to send one or several mails.

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

classmethod is_valid(email)[source]

Check the validity of an email address.

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

send(email)[source]

Send an email.

Parameters:: email (email.message.Message) – MIME type object to send.
Return type:: str or None

mailing(email_template, recipients)[source]

Send an e-mail to several users according to a HTML and a text template.

Parameters:

email_template (dict) – A dictionary containing the e-mail parameters. The keys of this dictionary are: subject, from, text_template, html_tempalte, attachments. subject can be overridden by the user dictionary.
recipients (list) – A list of recipients to whom to send the e-mail. Each recipient is a dictionary containing at least the to key. It is passed to the Chameleon html and text templates.

Return type:

Returns:

List of errors.

The `lib.menu` Module

Class to manage user menus.

class chrysalio.lib.menu.Menu(request: Request, uid: str, framework: list)[source]

User menu base class.

Parameters:

request (pyramid.request.Request) – Current request.
uid (str) – Unique ID used to store the menu in the session.
framework (list) – Full version of the menu.

The framework of the menu is a list of pieces. Each piece has the following structure:

piece = (icon, label, permission, route, (subentry, …))

route can be a name of route or a tuple such as (route_name, params_dict).

In the user session, under uid key, pieces are filtered according to user permissions and converted into menu entries. In an entry:

label is translated
permission is replaced by the final route.

is_empty() → bool[source]

Return True if current menu is empty.

Return type:: bool

xhtml(**kwargs) → str[source]

Return an <ul> structure with current entry highlighted.

Return type:: .helpers.literal.Literal

Options are:

no_icon=True: suppress icons in entries
tooltip=True: add attribute ‘title’ on entries span

classmethod invalidate(request: Request, uid: str)[source]

Invalidate the menu uid if exists.

Parameters:

request (pyramid.request.Request) – Current request.
uid (str) – Unique ID of the menu to invalidate.

The `lib.paging` Module

Class to divide large lists of items into pages.

chrysalio.lib.paging.sortable_column(request: Request, label: str, sort: str, current_sorting: str | None = None) → str[source]

Output a header of column with sort up and sort down buttons.

Parameters:

request (pyramid.request.Request) – Current request.
label (str) – Label of column.
sort (str) – Sort criteria.
current_sorting (str) – (optional) Default current sorting.

Return type:

helpers.literal.Literal

class chrysalio.lib.paging.Paging(request: Request, paging_id: str, collection, params: dict | None = None, item_count: int | None = None)[source]

Divide large lists of items into pages.

Parameters:

request (pyramid.request.Request) – Current request.
paging_id (str) – Paging ID.
collection (list-like object) – Collection object being paged through.
params (dict) – (optional) A dictionary with the following keys: page_size, page, sort and display.
item_count (int) – (optional) Number of items in the collection.
page_sizes (tuple) – (optional) List of suggested page sizes.

This class uses the following parameters in request: page_size, page, sort and display.

It stores its information and filters definitions in session['paging']. This structure looks like: session['paging'] = (page_default_size, {'paging_id1': {'page_size': 80, 'page': 3, 'sort': 'name', 'display': 'cards'}, 'paging_id2': {...}, ...})

classmethod params(request: Request | None, paging_id: str, default_sorting: str | None = None, default_display: str = 'cards') → dict[source]

Return current paging parameters: page number, page size, sorting and display mode.

Parameters:

request (pyramid.request.Request) – Current request.
paging_id (str) – Paging ID.
default_sorting (str) – (optional) Default sorting.
default_display (str) – (‘cards’ or ‘list’, default=’cards’) Default display.

Return type:

Returns:

The paging dictionary. See Paging class.

classmethod get_sort(request: Request, paging_id: str) → str | None[source]

Retrieve the sort criteria from the session.

Parameters:

request (pyramid.request.Request) – Current request.
paging_id (str) – ID of the paging.

Return type:

str or None

classmethod get_page(request: Request, paging_id: str) → int[source]

Retrieve the current page number from the session.

Parameters:

request (pyramid.request.Request) – Current request.
paging_id (str) – ID of the paging.

Return type:

int

get_item(field_id: str, value)[source]

Retrieve the first item whose field field_id has the value value.

Parameters:

field_id (str) – Name of the item field to search.
value – Value to use to find the item.

Return type:

dict or None

set_current_ids(field_id: str)[source]

Save in session['paging'][1][self.paging_id]['current_ids'] the IDs of the items of the page.

Parameters:: field_id (str) – Name of the item field used to store the IDs.

pager_top() → str[source]

Output a string with links to first, previous, next and last pages.

Rtye:: str

pager_bottom(pager_format: str = '~4~') → str[source]

Output a string with links to some previous and next pages.

Parameters:: pager_format (str) – (default=’~4~’) Format string that defines how the pager is rendered.
Return type:: str

display_modes() → str[source]

Output buttons to switch between cards and list mode.

Return type:: str

classmethod navigator(request: Request, paging_id: str, item_id: str, url: str) → str[source]

Return a piece of HTML to go to the previous and the next item.

Parameters:

request (pyramid.request.Request) – Current request.
paging_id (str) – Paging ID.
item_id (str) – ID of the current item.
url (str) – Pattern for the URL of previous and next button.

Return type:

sortable_column(label: str, sort: str) → str[source]

Output a header of column with sort up and sort down buttons.

See sortable_column().

Parameters:

label (str) – Label of column.
sort (str) – Sort criteria.

Return type:

helpers.literal.Literal

The `lib.tabset` Module

Widget to create tabs.

class chrysalio.lib.tabset.Tabset(request, tabset_id, labels)[source]

A class to manage tabs.

Parameters:

request (pyramid.request.Request) – Current request.
tabset_id (str) – ID of the tab set.
labels (list) – A list of translation strings.

begin()[source]

Output the opening tag of the TabSet and its table of content as an <ul> structure.

Return type:: helpers.literal.Literal

classmethod end()[source]

End a tab set.

Return type:: helpers.literal.Literal

class chrysalio.lib.tabset.Tab(tabset, index, label)[source]

A class to manage one tab.

Parameters:

tabset (Tabset) – Parent tab set.
index (int) – Index of the tab.
label (str) – Label of the tab.

begin()[source]

Open a tab zone.

Return type:: helpers.literal.Literal
Returns:: Opening fieldset structure with legend.

classmethod end()[source]

Close a tab zone.

Return type:: helpers.literal.Literal
Returns:: Closing fieldset structure.

The `lib.form` Module

Form validation and rendering library.

chrysalio.lib.form.get_action(request: Request, silent: bool = False) → tuple[str, tuple][source]

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

Parameters:

request (pyramid.request.Request) – Current request.
silent (bool) – (default=False) If True, no alert emitted.

Return type:

Returns:

(tuple) A tuple such as (action, targets).

Each submit button returns a string such as <act><?|!><target_id>.x where <target_id> is the target identifier or # for all selected targets, <?|!> means respectively confirm or proceed and <act> is the action to do.

Checkbox inputs return string such as #<target_id>.

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

class chrysalio.lib.form.SameAs(request: Request, reference: str, message: str | None = None)[source]

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

Parameters:

request (pyramid.request.Request) – Current request.
reference (str) – Name of the field to compare with.
message (str or TranslationString) – (optional) Error message.

chrysalio.lib.form.button(url: str, label: str = '', src: str | None = None, title: str | None = None, class_: str | None = 'cioButton') → str[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=’cioButton’) The class attribute.

Return type:

chrysalio.lib.form.button_icon(url: str, title: str, class_: str = 'cioIconButton') → str[source]

Output a link which looks like an icon.

Parameters:

url (str) – Target URL.
title (str) – Label for roll over.
class (str) – CSS class to give the aspect.

Return type:

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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (optional) The class attribute.

Return type:

This ouputs a structure such as:

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

class chrysalio.lib.form.Form(request: Request, schema: SchemaNode | None = None, defaults: dict | None = None, obj=None, force_defaults: bool = False)[source]

Form validation class.

validate(obj=None) → bool[source]

Check if the form is validated.

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

has_error(name: str | None = None) → bool[source]

Return True if field name has an error.

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

set_error(name: str, message: str)[source]

Set an error message for field name.

Parameters:

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

error(name: str) → str[source]

Return error message for field name.

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

static(name: str)[source]

The field name will not be updated by the form.

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

forget(prefix: str)[source]

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

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

classmethod make_safe_id(name: str) → str[source]

Make a string safe for including in an id attribute

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

begin(url: str | None = None, multipart: bool = False, class_: str | None = 'cioForm', **attrs) → str[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 helpers.tags object.

Return type:

classmethod end() → str[source]: Ouput the </form> tag.

classmethod submit(name: str, label: str | None = None, class_: str = 'cioButton', **attrs) → str[source]

Output a submit button with the label as the caption.

Parameters:

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

Return type:

classmethod submit_image(name: str, label: str, src: str, **attrs) → str[source]

Output an image submit button.

Parameters:

name (str) – Input ID.
label (str) – Label for roll over and alt.
src (str) – Image path.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

classmethod submit_icon(name: str, title: str, class_: str = 'cioIconButton', **attrs) → str[source]

Output a submit button which looks like an icon.

Parameters:

name (str) – Input ID.
title (str) – Label for roll over.
class (str) – CSS class to give the aspect.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

classmethod submit_cancel_icon(title: str, **attrs) → str[source]

Output a cancel submit button which looks like an icon.

Parameters:

title (str) – Label for roll over and alt.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

classmethod submit_cancel(label: str, src: str, **attrs) → str[source]

Output a cancel submit button.

Parameters:

label (str) – Label for roll over and alt.
src (str) – Image path.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

Returns:

HTML tag.

toggle_flag(name: str, title: str, active: bool, class_: str = 'cioFlag', **attrs) → str[source]

Output a submit button simulating a toggle flag.

Parameters:

name (str) – Input ID.
title (str) – Flag title.
active (bool) – State of the flag._
class (str) – (default=’cioFlag’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

classmethod status(label: str, status: str) → str[source]

Output a span showing a status.

Parameters:

label (str) – Status label.
status (str) – ID of the current status.

Return type:

classmethod button(url: str, label: str = '', src: str | None = None, title: str | None = None, class_: str = 'cioButton') → str[source]

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

See button().

classmethod button_icon(url: str, title: str, class_: str = 'cioButton') → str[source]

Output a link which looks like an icon.

See button_icon().

classmethod default_button(name: str)[source]

Create an invisible button to catch the Enter signal for the input submit we want to be the default one.

Parameters:: name (str) – ID of the input submit to activate.

classmethod grid_item(label: str, content: str, required: bool = False, hint: str | None = None, error: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem') → str[source]

Output an item with label, hint and error message.

See grid_item().

hidden(name: str, value: str | None = None, **attrs) → str[source]

Output a hidden field.

Parameters:

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

Return type:

text(name: str, value: str | None = None, **attrs) → str[source]

Output a standard text field.

Parameters:

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

Return type:

password(name: str, value: str | None = None, **attrs) → str[source]

Output a password field.

This method takes the same options as text().

checkbox(name: str, value: str = '1', checked: bool = False, autosubmit: bool = False, **attrs) → str[source]

Output a check box.

Parameters:

name (str) – Input ID.
value (str) – (default=’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.
autosubmit (bool) – (default=False) If True, it adds class="cioAutoSubmit" attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

custom_checkbox(name: str, value: str = '1', checked: bool = False, autosubmit: bool = False, class_: str | None = None, **attrs) → str[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=’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.
autosubmit (bool) – (default=False) If True, it adds class="cioAutoSubmit" attribute.
class (str) – (default=’cioCustomCheckbox’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

radio(name: str, value: str, checked: bool = False, autosubmit: bool = False, **attrs) → str[source]

Output a radio button.

Parameters:

name (str) – Input ID.
value (str) – The value to return to the application if the radio is checked.
checked (bool) – (default=False) True if the box should be initially checked.
autosubmit (bool) – (default=False) If True, it adds class="cioAutoSubmit" attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

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 class="cioAutoSubmit" attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

upload(name: str, value=None, **attrs) → str[source]

Output a file upload field.

Parameters:

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

Return type:

textarea(name: str, content: str = '', **attrs) → str[source]

Output a text input area.

Parameters:

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

Return type:

grid_text(name: str, label: str, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem', **attrs) → str[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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (default=’cioFormItem’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

grid_password(name: str, label: str, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem', **attrs) → str[source]

Output a password field in a CSS grid layout.

This method takes the same options as grid_text().

grid_checkbox(name: str, label: str, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem', **attrs) → str[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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (default=’cioFormItem’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

grid_custom_checkbox(name: str, label: str, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem', **attrs) → str[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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (default=’cioFormItem’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

grid_select(name: str, label: str, options: list[str | int | tuple], autosubmit: bool = False, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_='cioFormItem', **attrs) → str[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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (default=’cioFormItem’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

grid_upload(name: str, label: str, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem', **attrs) → str[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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (default=’cioFormItem’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

grid_textarea(name: str, label: str, required: bool = False, hint: str | None = None, title: str | None = None, clear: bool = False, class_: str = 'cioFormItem', **attrs) → str[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.
title (str) – (optional) Title for the hover effect.
clear (bool) – (default=False) If True, add a <div class="cioClear"/> at the end.
class (str) – (default=’cioFormItem’) The class attribute.
attrs (dict) – Keyworded arguments for helpers.tags object.

Return type:

The `lib.utils` Module

Some various utilities.

chrysalio.lib.utils.tostr(text: str | bytes) → str[source]

Make a conversion according to Python version. (deprecated)

Parameters:: text (str or bytes) – Text to convert.
Return type:: str

chrysalio.lib.utils.tounicode(text: str | bytes) → str[source]

Make a conversion according to Python version. (deprecated)

Parameters:: text (str or bytes) – Text to convert.
Return type:: str

chrysalio.lib.utils.load_guessing_encoding(filename: str) → str | None[source]

Tries to open a file by guessing its encoding.

Parameters:: filename (str) – Absolute path to the file.
Return type:: str or None

chrysalio.lib.utils.copy_content(src_dir: str, dst_dir: str, exclude: list | tuple | None = None, force: bool = False)[source]

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

Parameters:

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

chrysalio.lib.utils.copy_content_re(src_dir: str, dst_dir: str, exclude: Pattern | None = None)[source]

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

Parameters:

src_dir (str) – Source directory path.
dst_dir (str) – Destination directory path.
exclude – (optional) Regular expression to exclude files during the copy.

chrysalio.lib.utils.make_id(name: str, mode: str | None = None, truncate: int | None = None) → str[source]

Make an ID with name.

Parameters:

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

Return type:

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_
mode = ‘no_accent’: 12Test___Te*t.;?!

chrysalio.lib.utils.make_digest(name: str) → str[source]

Create a digest key with name.

Parameters:: name (str) – Name to use.

chrysalio.lib.utils.normalize_spaces(text: str | None, truncate: int | None = None) → str | 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

chrysalio.lib.utils.camel_case(text: str) → str[source]

Convert text in Camel Case.

Parameters:: text (str) – Text to transform.

Examples of transformation:

xml2html -> Xml2Html laTeX -> LaTeX my_way -> MyWay my way -> MyWay my-way -> MyWay

chrysalio.lib.utils.shorten(text: str | None, width: int, placeholder: str = '…') → str[source]

Collapse and truncate the given text to fit in the given width.

Parameters:

text (str) – Text to shorten.
with (int) – The result fits in the width.
placeholder (str) – (default=…) Place holder to use if the size is too big.

Return type:

chrysalio.lib.utils.encrypt(value: bytes, key: str | bytes, init_vector: bytes | None = None) → str | None[source]

Encryption function.

Parameters:

value (bytes) – Value to encrypt.
key (str) – Encryption key.
init_vector (bytes) – (optional) Initialization vector for AES algorithm.

Return type:

bytes

Retrun:

Encrypted value or None.

chrysalio.lib.utils.decrypt(value: bytes, key: str | bytes) → str | None[source]

Encryption function with padding.

Parameters:

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

Return type:

Returns:

Encrypted value or None.

chrysalio.lib.utils.token(length: int | None = None) → str[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.

chrysalio.lib.utils.execute(command: list, cwd: str | None = None, no_exit_code: bool = False, timeout: float | None = None, lang: str | None = None, **kwargs) → tuple[str, str][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 (str) – (optional) If it is not None, the current directory will be changed to cwd before it is executed.
no_exit_code (bool) – (default=False) If the command is known to exit with code 0 even if there is an error, assign this argument to True.
timeout (float) – (default=None) If set and the process hasn’t finished in that time (in seconds), exits with error. The process is not killed.
kwargs (dict) – (optional) Dictionary of keyword arguments.
lang (str) – (optional) User language.

Return type:

Returns:

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

chrysalio.lib.utils.full_url(url: str, user: str | None = None, password: str | None = None) → str[source]

Return an URL with user and possibly password.

Parameters:

url (str) – URL to update.
user (str) – User for VCS access.
password (str) – Password for VCS access.

Return type:

Returns:

Full URL.

chrysalio.lib.utils.mimetype_get(full_path: str) → tuple[str, str][source]

Return the mime type of full_path.

Parameters:: full_path (str) – Absolute path to the file.
Return type:: tuple
Returns:: A tuple such as (mimetype, subtype). For instance: ('text/plain', 'plain').

chrysalio.lib.utils.deltatime_label(seconds: int = 0, minutes: int = 0, hours: int = 0, days: int = 0, lang: str | None = None) → str[source]

Return a translated label for a delta time.

Parameters:

seconds (int) – Number of seconds.
minutes (int) – Number of minutes.
hours (int) – Number of hours.
days (int) – Number of days.
lang (str) – (optional) Language to use.

Return type:

pyramid.i18n.TranslationString

Returns:

Return a human reading translation string.

chrysalio.lib.utils.age(mtime: datetime) → str[source]

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

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

chrysalio.lib.utils.size_label(size: int, is_dir: bool = False) → str[source]

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

Parameters:

size (int) – Size in figures.
is_dir (bool) – (optional) True if it is about a directory.

Return type:

str or pyramid.i18n.TranslationString

chrysalio.lib.utils.convert_value(type_, value)[source]

Convert a string value according to type type_.

Parameters:: type (str) – Type of the value.
Return type:: str, bool, int, float or datetime.date

chrysalio.lib.utils.check_chrysalio_js(js_dir: str)[source]

Check if the chrysalio.js file exists in js_dir directory and if it is the last version and possibly update them.

Parameters:: js_dir (str) – Directory for Javascript files.

chrysalio.lib.utils.check_chrysalio_css(css_dir: str)[source]

Check if the Chrysalio CSS file exists in css_dir directory and if it is the last version and possibly update them.

Parameters:: css_dir (str) – Directory for CSS files.

chrysalio.lib.utils.common_directory(files: list) → str | None[source]

Return the common directory of the list of files.

Parameters:: files (list) – List of files to analyse.
Return type:: str

chrysalio.lib.utils.hash_admin_password(project_dir: str, files: list, password: str)[source]

Add hashed password for administrator in each file of the files list contained in project_dir directory.

Parameters:

project_dir (str) – Project directory containing INI files.
files (tuple) – List of files to process.
password (str) – Clear password.

chrysalio.lib.utils.rst2html(rst: str) → str[source]

Transform a reStructuredText into HTML.

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

The `lib.xml` Module

XML manipulation.

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

This function is similar to load_xml() but returns its result in a Rust way.

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 (etree.XMLParser) – (optional) Specific parser for etree.parse function.
xinclude (bool) – (default=False) If True, activate XInclude.

Return type:

Returns:

A tuple such as (element, error).

chrysalio.lib.xml.load_xml(filename, relaxngs=None, data=None, noline=False, parser=None, xinclude=False)[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 (etree.XMLParser) – (optional) Specific parser for etree.parse function.
xinclude (bool) – (default=False) If True, activate XInclude.

Return type:

str, TranslationString or ElementTree

Returns:

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

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

chrysalio.lib.xml.relaxng4validation(relaxng, attributes=('version',))[source]

Transform a Relax NG dictionary with keys 'root', 'file' and possibly 'namespace' and 'version' into a dictionary compatible with validate_xml().

Parameters:

relaxng (dict) – A Chrysalio Relax NG dictionary.
attributes (tuple) – (default=(‘version’,)) Attributes to take into account in the pattern.

Return type:

dict or None

chrysalio.lib.xml.load_xslt2(filename: str) → tuple[etree.ElementTree | None, str | None][source]

Load a XSL file and create a etree.XSLT object.

This function is similar to load_xslt() but returns its result in a Rust way.

:param str :rtype: lxml.etree.XSLT or str

chrysalio.lib.xml.load_xslt(filename: str)[source]

Load a XSL file and create a etree.XSLT object.

Return type:: lxml.etree.XSLT or str

chrysalio.lib.xml.create_entire_xml(relaxng, elements, validation=True)[source]

Create an entire XML document composed of all elements.

Parameters:

relaxng (dict) – A dictionary with the name of the root element, the value of attribute version and path to the Relax NG file to validate the result.
elements (list) – A list of lxml.etree._Element objects.
validation (bool) – (default=True) Validate the result.

Return type:

TranslationString or lxml.etree._Element

Returns:

An error message or an object lxml.etree._Element.

chrysalio.lib.xml.i18n_xml_text(root_elt, xpath, namespaces=None)[source]

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

Parameters:

root_elt (lxml.etree.Element) – XML root element of the localized text.
xpath (str) – XPath expression to select localized texts.
namespaces (dict) – (optional) Dictionary of possible name spaces.

Return type:

Returns:

A dictionary such {lang1: text_in_lang1,...}

chrysalio.lib.xml.db2xml_i18n_labels(dbitem, root_elt, depth)[source]

Serialize i18n label and descriptio.

Parameters:

dbitem – SQLAlchemy item.
root_elt (lxml.etree.Element) – Root XML element.
depth (int) – Depth of the parent element in the entire XML structure.

chrysalio.lib.xml.xml_wrap(text, depth)[source]

Wrap a text according to the depth of the parent element.

Parameters:

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

Return type:

chrysalio.lib.xml.check_chrysalio_rng(relaxng_dir)[source]

Check if the Relax NG files in relaxng_dir directory is the last version and possibly update them.

Parameters:: relaxng_dir (str) – Directory for Relax NG files.

The `lib.restful` Module

Functions to manage RESTful API.

chrysalio.lib.restful.restful_call(url, login, key, data=None)[source]

RESTful call.

Parameters:

url (str) – RESTful URL to call.
login (str) – Login of an authorized user.
key (str) – Key to decrypt the token.
data (dict) – (optional) Data to transfer.

Return type:

Returns:

A tuple such as (response, error).

chrysalio.lib.restful.restful_login(request, key, token_ttl=None)[source]

Login during a RESTful call.

Parameters:

request (pyramid.request.Request) – Current request.
key (str) – Key to decrypt the token.
token_ttl (float) – (optional) Validity period in seconds for the token.

Return type:

Returns:

Translated error message or None.

The `lib.panel` Module

Panel class.

class chrysalio.lib.panel.Panel(area: tuple[str, ...] | None = None)[source]

Class to manage side panel.

Parameters:: area (list) – (optional) List of route names which determine the area where the panel is visible.

nav_entry: alias of NavPanel

classmethod register(registry: Registry, panel_class, area: tuple[str, ...] | None = None) → Panel | None[source]

Method to register the panel and possibly add it to a navigation menu.

Parameters:

registry (pyramid.registry.Registry) – Application registry.
panel_class – Panel class.
area (list) – (optional) List of route names which determine the area where the panel is visible.
add2systray (bool) – (default=True) If True add the panel to systray.

Return type:

lib.panel.Panel or None

classmethod has_open_panel(request: Request) → str | None[source]

Return 'cioHasOpenPanel' if almost one panel is open.

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

is_open(request: Request) → bool[source]

True if the panel is open.

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

was_open(request: Request) → bool[source]

True if the panel was previously open.

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

open(request: Request)[source]

Open the panel and memorize the state.

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

classmethod reopen_panel(request: Request) → Panel | None[source]

Return a possible panel which can be reopened.

Parameters:: request (pyramid.request.Request) – Current request.
Return type:: .lib.panel.Panel

classmethod reopen(request: Request)[source]

Reopen a panel.

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

refresh(request: Request) → bool[source]

Try to refresh the content of the panel.

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

close(request: Request, prevent_reopen: bool = False)[source]

Close the panel and memorize the state.

Parameters:

request (pyramid.request.Request) – Current request.
prevent_reopen (bool) – If True, prevent the panel to be reopened.

clear_values(request: Request)[source]

Clear all values of this panel.

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

set_values(request: Request, values: dict)[source]

Set values of this panel.

Parameters:

request (pyramid.request.Request) – Current request.
values (dict) – Values to set.

values(request: Request) → dict[source]

Return values of this panel.

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

set_value(request: Request, value_id: str, value)[source]

Set a value of this panel.

Parameters:

request (pyramid.request.Request) – Current request.
value_id (str) – Value ID.
value – Value to set.

value(request: Request, value_id: str) → str | None[source]

Return the value value_id of this panel.

Parameters:

request (pyramid.request.Request) – Current request.
value_id (str) – ID of the requested value.

Return type: