Library Reference

The lib.i18n Module

Localization management.

ciowarehouse2.lib.i18n.translate(text, lang=None, request=None)

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:

str

The lib.utils Module

Some various utilities.

ciowarehouse2.lib.utils.files2response(request: Request, abs_paths: list[str], common_path: str | None = None, download_name: str | None = None) → FileResponse | None

Prepare files for download and return a Pyramid response.

Parameters:

• request (pyramid.request.Request) – Current request.

• abs_paths (list) – List of absolute paths to files to download.

• common_path (str) – (optional) Root of all files.

• download_name (str) – (optional) Visible name during download.

Return type:

pyramid.response.FileResponse

Returns:

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

ciowarehouse2.lib.utils.file2response(request: Request, abs_path: str, download_name: str | None = None, content_type: str | None = None) → FileResponse

Return a Pyramid FileResponse containing the given file.

Parameters:

• request (pyramid.request.Request) – Current request.

• abs_path (str) – Absolute path to file to encapsulate.

• download_name (str) – Visible name during download.

Return type:

pyramid.response.FileResponse

ciowarehouse2.lib.utils.file_move_check(warehouse1_root: str, ciopath1: CioPath, warehouse2_root: str, ciopath2: CioPath, overwrite_ok: bool = False, mode: str = 'move') → tuple[CioPath | None, str | None]

Check files for a move or copy and return absolute paths.

Parameters:

• warehouse1_root (str) – Root of warehouse of the source.

• ciopaht1 – CioPath of the first file.

• warehouse2_root (str) – Root of the warehouse of the target.

• ciopath2 (.lib.ciopath.CioPath) – CioPath of the srecond file.

• overwrite_ok (bool) – (default=False) If True, silently overwrite the destination file.

• mode (str) – ('move', 'copy', 'rename') The way the move must operate.

Return type:

tuple

Returns:

A tuple such as (ciopath2, error).

ciowarehouse2.lib.utils.normalize_filename(filename: str, mode: str = 'simple', is_dir: bool = False) → str

Normalize file name.

Parameters:

• filename (str) – File name to normalize.

• mode (str) – (default=’simple’) Strategy to normalize file name ('simple' or 'strict').

• is_dir (bool) – (default=False) True if the file is a directory.

Return type:

str

ciowarehouse2.lib.utils.ciopaths2absolute_paths(request: Request, ciopaths_str: list[str]) → list[str]

Convert a list of CioPath into a list of absolute paths.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciopaths_str (list) – List of strings representing CioPath.

Return type:

list

ciowarehouse2.lib.utils.sort_key(name: str) → str

Key for sorting according to a name.

Parameters:

name (str) – Name to convert.

Return type:

str

ciowarehouse2.lib.utils.build_callback(registry, build_env: dict, result: dict, request: Request | None = None)

Function called after the build is completed.

Parameters:

• registry – Application registry.

• build_env (dict) – Build environment.

• result (dict) – Result of the processing. See: cioservice.lib.build.Build.

• request (pyramid.request.Request) – (optional) Current request.

ciowarehouse2.lib.utils.cache_user_renderings(namespace_prefix: str, region: str | None = None)

A decorator to retrieve in the user cache the dictionary renderings.

Parameters:

• namespace_prefix (str) – Prefix of the cache namespace.

• region (str) – (optional) Name of region.

ciowarehouse2.lib.utils.cache_user_seeds(namespace_prefix: str, region: str | None = None)

A decorator to retrieve in the user cache the dictionary of seeds.

Parameters:

• namespace_prefix (str) – Prefix of the cache namespace.

• region (str) – (optional) Name of region.

ciowarehouse2.lib.utils.isodt2str(isodt: str) → str

Return a string representing the given datetime in local time zone in an ISO format.

Parameters:

isodt (str) – ISO datetime format.

Return type:

str

ciowarehouse2.lib.utils.isodt2age(request: Request, isodt: str) → str

Return a string representing the given datetime as an age.

Parameters:

• request (pyramid.request.Request) – Current request.

• isodt (str) – ISO datetime format.

Return type:

str

ciowarehouse2.lib.utils.wait4thumbnails(request: Request, thumbnails: list[tuple[CioPath, str, str | None]], trials: int = 4)

Wait a while to be sure each thumbnail of the list is created.

Parameters:

• request (pyramid.request.Request) – Current request.

• thumbnails (list) – A list of tuples such as (ciopath, size, thumbnail_ext).

• trails (int) – (default=``THUMBNAIL_TRIALS``) Number of trials for each thumbnail.

ciowarehouse2.lib.utils.ciotype_thumbnails(request: Request, ciopaths: tuple[CioPath]) → dict[CioPath, tuple[CioType, str, str | None]]

Retrieve CioType`s and extensions of a given list of `CioPath.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciopaths (tuple) – A tuple of CioPath.

Return type:

dict

ciowarehouse2.lib.utils.thumbnail_absolute_path(request: Request, ciotype: CioType, ciopath: CioPath, icon: str, thumbnail_ext: str | None) → str

Return the absolute path to the thumbnail or to the icon.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciotype (.lib.ciotype.CioType) – CioType of the file.

• ciopath – CioPath of the file.

• icon (str) – File name of the icon.

• thumbnail_ext (str) – Extension of the thumbnail.

Path ciopath:

.lib.ciopath.CioPath

Return type:

str

ciowarehouse2.lib.utils.query_in(field: str, values: tuple | list) → str

Create an optimized query for a multivalued field.

Parameters:

• field (str) – Field name.

• values (tuple) – Possible values.

Return type:

str

ciowarehouse2.lib.utils.query_in_quoted(field: str, values: tuple | list) → str

Create an optimized query for a multivalued field with quoted values.

Parameters:

• field (str) – Field name.

• values (tuple) – Possible values.

Return type:

str

ciowarehouse2.lib.utils.scope_query(request: Request, scope: str, directory_ciopath: CioPath, flat: bool = False) → str | None

Create a query to restrick the search in the current and authorized scope.

Parameters:

• request (pyramid.request.Request) – Current request.

• scope (str) – Scope of the search: 'all', 'favorite', 'warehouse' or 'directory'.

• directory_ciopath – CioPath of the current directory, possibly an empty one.

• flat (bool) – if True use facet field instead of directory field.

Return type:

str

ciowarehouse2.lib.utils.warehouses_in_scope(request: Request, scope: str, warehouse_id: str | None) → tuple[str, ...]

Find ID of warehouses in the scope.

Parameters:

• request (pyramid.request.Request) – Current request.

• scope (str) – Scope of the search: 'all', 'favorite', 'warehouse' or 'directory'.

• warehouse_id (str) – Warehouse ID if exists.

Return type:

list

ciowarehouse2.lib.utils.warehouses_favorite(request: Request) → tuple[str, ...]

Return a dictionary of favorite warehouses.

Parameters:

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

Return type:

tuple

ciowarehouse2.lib.utils.warehouses_in_menu(request: Request) → dict

Return a dictionary of warehouses in the menu.

Parameters:

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

Return type:

dict

ciowarehouse2.lib.utils.apply_regex(request: Request, regex_file: str, content: str) → str

Apply a list of regular expressions from a file.

Parameters:

• request (pyramid.request.Request) – Current request.

• regex_file (str) – Absolute path to the file containing regular expressions.

• content (str) – Content to process.

Return type:

str

The lib.backend Module

Backend management.

class ciowarehouse2.lib.backend.CioBackend(settings: dict, uid: str)

Class to manage backend calls.

Parameters:

• settings (pyramid.registry.Registry.settings) – Settings object.

• uid (str) – UID of the current site (ex. ciodemosite).

ping(pending: bool = False, running: bool = False) → str | None

Ping the backend server.

Parameters:

• pending (bool) – (optional) Return pending state.

• running (bool) – (optional) Return running state sorted by warehouse.

Return type:

pyramid.i18n.TranslationString

inspect(segments: bool = False) → tuple[InspectReply | None, str | None]

Inspect the index.

Return type:

tuple

Returns:

A tuple such as (reply, error).

reset(not_thumbs: bool = False) → str | None

Reset the index and remove thumbnails.

Parameters:

not_thumbs (bool) – (optional) Do not remove thumbnails.

Return type:

pyramid.i18n.TranslationString

index(warehouse: Warehouse, paths: list | tuple | None = None, force: bool = False, skip_thumbs: bool = False, no_thumbs: bool = False) → str | None

Index paths inside a given warehouse.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse.

• paths (list) – (optional) Relative paths inside the warehouse to index.

• force (bool) – (optional) Force indexing.

• no_thumbs (bool) – (optional) Skip thumbnails creation.

Return type:

pyramid.i18n.TranslationString

delete(warehouse: Warehouse, paths: list | tuple | None = None, not_thumbs: bool = False) → str | None

Delete index entries of a given warehouse.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse.

• paths (list) – (optional) Relative paths inside the warehouse.

• not_thumbs (bool) – (optional) Do not remove thumbnails.

Return type:

pyramid.i18n.TranslationString

search(query: str, limit: int = 10, offset: int = 0, sort_by: str | None = None, reverse: bool = False, snippets: int = 0) → tuple[SearchReply | None, str | None]

Search files.

Parameters:

• query (str) – Query.

• limit (int) – (default = 10) Maximum of returned hits.

• offset (int) – (default = 0) Offset of the range of returned hits.

• sort_by (str) – (default = None) Name of the field for sorting the result.

• reverse (bool) – (default = False) Reverse the sort.

• snippets (int) – (default = 0) Length of the context to show.

Return type:

tuple

Returns:

A tuple such as (reply, error)

suggest(bootstrap: str, scope_query: str | None = None, no_file_names: bool = False, limit: int = 12) → tuple[list | None, str | None]

Suggest queries.

Parameters:

• bootstrap (str) – Terms to initiate the suggestion.

• scope_query (str) – Query to limit the scope of suggestions.

• no_file_names (bool) – (default = False) Exclude file names from suggestions.

• limit (int) – (default = 10) Maximum of returned suggestions.

Return type:

tuple

Returns:

A tuple such as (suggestions, error)

The lib.ciotype Module

CioType is similar to a MIME type: type/subtype+suffix?parameter=value.

class ciowarehouse2.lib.ciotype.CioType(type_: str | None, subtype: str | None = None)

A class to manage CioType.

Parameters:

string (str) – String representation of a CioType.

classmethod from_str(string: str | None) → CioType

Return a new CioType created from a string.

classmethod from_request(request: Request) → CioType

Look for a CioType in a request.

Parameters:

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

Return type:

.lib.ciotype.CioType

uid() → str

Return a Unique ID for this CioType.

Return type:

str

match(other) → bool

Return true if the given CioType matches with this one.

Return type:

bool

is_directory()

Return true if CioType represents a directory.

Return type:

bool

route() → str

Return a safe string representing the CioType in a route.

The lib.ciopath Module

A class that uniquely represents a file.

class ciowarehouse2.lib.ciopath.CioPath(wid: str | None, path: str | None = None, is_dir: bool = False)

A class to manage CioPath.

Parameters:

• wid (str) – Warehouse ID.

• path (str) – (optional) Relative path inside the warehouse.

• is_dir (bool) – (default=False) True if the given CioPath is a directory.

classmethod from_str(string: str | None, is_dir: bool = False) → CioPath

Return a new CioPath created from a string.

Parameters:

string (str) – String representing a CioPath

classmethod from_paths(wid: str, root: str, paths: list[str] | set[str]) → list[CioPath]

Return a list or CioPath from a list of relative paths.

Parameters:

• wid (str) – Warehouse ID.

• root (str) – Absolute path to the root of the warehouse.

• paths (list) – List of relative paths inside the given warehouse.

classmethod from_request(request: Request, is_dir: bool = False) → CioPath

Look for a CioPath in a request.

Parameters:

• request (pyramid.request.Request) – Current request.

• is_dir (bool) – (default=False) True if the given CioPath is a directory.

uid() → str

Return a Unique ID for this CioPath.

Return type:

str

is_root() → bool

True if it is the root of the warehouse.

is_directory() → bool

True if the path points to a directory.

directory() → str | None

Return the path of the directory containing the file.

facet(of_file: bool = False) → str | None

Return the facet repesentation of the directory containing the file or of the file itself.

file_name() → str | None

Return the file name.

absolute_path(root: str | None) → str | None

Return the absolute path to the file.

absolute_info(root: str | None) → str | None

Return the absolute path to the information file linked to the given CioPath.

absolute_lock(root: str | None) → str | None

Return the absolute path to the lock file linked to the given CioPath.

route() → str

Return a piece of route representing the CioPath.

mimetype() → str | None

Return the MIME type of the CioPath.

contains(other: CioPath) → bool

True if the given CioPath is strictly contained in current one.

join(path: str, is_dir: bool = False) → CioPath

Creates a {CioPath} with path adjoined to self.

parent() → CioPath

Return the CioPath` without its final component, if there is one.

touch(root: str | None) → CioPath

Update the date of modification of the file.

The lib.vcs Module

Class for warehouses with Git as VCS.

class ciowarehouse2.lib.vcs_git.VcsGit(uid: str, root: str, dbwarehouse: DBWarehouse, password: str | None = None)

Class to manage warehouses with Git as VCS.

Parameters:

• uid (str) – ID of this VCS i.e. ID of the corresponding warehouse.

• root (str) – Absolute path to the warehouse directory.

• dbwarehouse (.models.dbwarehouse.DBWarehouse) – (optional) DBWarehouse defining the warehouse managed by this VCS.

• password (str) – (optional) Clear password for clone/pull access.

init()

Initialize a local Git repository.

Return type:

pyramid.i18n.TranslationString or None

Returns:

Error message or None if it succeeds.

is_dirty() → bool

Return True if the repository data has been modified.

Return type:

bool

clone() → str | None

Create a copy of an existing repository.

Return type:

pyramid.i18n.TranslationString or None

pull() → str | None

Pull from a remote repository or do nothing.

Return type:

pyramid.i18n.TranslationString or None

add(ciopath: CioPath | None = None) → str | None

Add new files in path path.

Parameters:

ciopath (.lib.ciopath.CioPath) – (optional) CioPath of the file to add.

Return type:

pyramid.i18n.TranslationString or None

remove(ciopath: CioPath) → str | None

Remove a file or a directory.

Parameters:

ciopath (.lib.ciopath.CioPath) – CioPath of the file to remove.

Return type:

pyramid.i18n.TranslationString or None

move(ciopath1: CioPath, ciopath2: CioPath, overwrite_ok: bool = False, mode: str = 'move') → tuple[CioPath | None, str | None]

Move or copy a file inside the warehouse.

Parameters:

• ciopaht1 – CioPath of the first file.

• ciopath2 (.lib.ciopath.CioPath) – CioPath of the srecond file.

• overwrite_ok (bool) – (default=False) If True, do nothing if files are the same.

• mode (str) – ('move', 'copy', 'rename') The way the move must operate.

Return type:

tuple

Returns:

A tuple such as (final_ciopath2, error).

copy(ciopath1: CioPath, ciopath2: CioPath, overwrite_ok: bool = False) → tuple[CioPath | None, str | None]

Copy a file.

Parameters:

• ciopaht1 – CioPath of the first file.

• ciopath2 (.lib.ciopath.CioPath) – CioPath of the srecond file.

• overwrite_ok (bool) – (default=False) If True, do nothing if files are the same.

Return type:

pyramid.i18n.TranslationString or None

commit(message: str, name: str, email: str = '') → str | None

Commit changes.

Parameters:

• message (str) – Message for mommit.

• name (str) – Name of the author.

• email (str) – (optional) Emial of the author.

Return type:

pyramid.i18n.TranslationString or None

Returns:

Error message or None if it succeeds.

log(ciopath: CioPath, limit: int = 20) → tuple

Show revision history.

Parameters:

• ciopaht – CioPath of the file.

• limit (init) – (default=20) Maximum number of commits.

Return type:

list

Returns:

A list of tuples such as (commit_id, datetime, commiter_name, message).

Class for warehouses without Version Control System.

class ciowarehouse2.lib.vcs_none.VcsNone(uid: str, root: str, dbwarehouse: DBWarehouse | None = None)

Class to manage warehouses without VCS.

Parameters:

• uid (str) – ID of this VCS i.e. ID of the corresponding warehouse.

• root (str) – Absolute path to the warehouse directory.

• dbwarehouse (.models.dbwarehouse.DBWarehouse) – (optional) DBWarehouse defining the warehouse managed by this VCS.

init()

Possibly create the root directory.

Return type:

None

classmethod is_dirty() → bool

Return False.

Return type:

bool

clone()

Call meth:init and possibly fill the warehouse.

Return type:

None

pull()

Do a clone if source exists and root directory is empty.

Return type:

None

add(ciopath: CioPath | None = None)

Do nothing.

Return type:

None

remove(ciopath: CioPath) → str | None

Remove a file or a directory.

Parameters:

ciopath (.lib.ciopath.CioPath) – CioPath of the file to remove.

Return type:

pyramid.i18n.TranslationString or None

move(ciopath1: CioPath, ciopath2: CioPath, overwrite_ok: bool = False, mode: str = 'move') → tuple[CioPath | None, str | None]

Move or copy a file inside the warehouse.

Parameters:

• ciopaht1 – CioPath of the first file.

• ciopath2 (.lib.ciopath.CioPath) – CioPath of the srecond file.

• overwrite_ok (bool) – (default=False) If True, do nothing if files are the same.

• mode (str) – ('move', 'copy', 'rename') The way the move must operate.

Return type:

tuple

Returns:

A tuple such as (final_ciopath2, error).

move_(ciopath1: CioPath, ciopath2: CioPath, overwrite_ok: bool, mode: str) → tuple[CioPath | None, str | None]

Method used by VcsNone and VcsGit to move files.

copy(ciopath1: CioPath, ciopath2: CioPath, overwrite_ok: bool = False) → tuple[CioPath | None, str | None]

Copy a file.

Parameters:

• ciopaht1 – CioPath of the first file.

• ciopath2 (.lib.ciopath.CioPath) – CioPath of the second file.

• overwrite_ok (bool) – (default=False) If True, do nothing if files are the same.

Return type:

pyramid.i18n.TranslationString or None

commit(message: str, name: str, email: str = '')

Do nothing.

Return type:

None

log(ciopath: CioPath, limit: int = 20)

Do nothing.

Return type:

None

The lib.warehouse Module

Warehouse class.

class ciowarehouse2.lib.warehouse.Warehouse(registry, dbwarehouse: DBWarehouse, locations: dict)

Class to manage a warehouse.

Parameters:

• registry (dict) – Application registry.

• dbwarehouse (.models.dbwarehouse.DBWarehouse) – SQLAlchemy object representing the warehouse

• locations (dict) – Dictionary of locations.

label(request: Request) → str

Return a translated label.

Parameters:

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

Return type:

str

description(request: Request) → str

Return a translated description.

Parameters:

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

Return type:

str

must_refresh(now: bool = False, force: bool = False) → bool

Check if the warehouse must be refreshed.

refresh(request: Request, ciopaths: list[CioPath] | set[CioPath] | None = None, now: bool = False, force: bool = False, in_thread: bool = False) → str | None

Call the backend for refreshing the index. If paths is None, do a full refresh.

Parameters:

• request (pyramid.request.Request) – Current request.

• paths (list) – (optional) List of CioPath to refresh.

• now (bool) – (default=False) If True, force refreshing even if the deadline is not reached.

• force (bool) – (default=False) If True, force refreshing even if the source is older than the index.

• in_thread (bool) – (default=False) Launch the refresh in a thread.

Return type:

str

refreshed()

Set the refreshed flag.

to_refresh(inputs: list[str], paths: list[str]) → list[CioPath]

Compute an optimized list of CioPath to refresh.

Parameters:

• inputs (list) – List of absolute paths to the input files.

• paths (str) – List of relative paths to the output files.

Return type:

list

commit_and_refresh(request: Request, ciopaths: list[CioPath] | set[CioPath], message: str, force: bool = False, in_thread: bool = False)

Commit new files and refresh the warehouse.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciopaths (list) – List of CioPath.

• message (pyramid.i18n.TranslationString) – Commit message.

• force (bool) – (default=False) If True, force refreshing even if the source is older than the index.

• in_thread (bool) – (default=False) Launch the refresh in a thread.

file_trail(request: Request, ciopath: CioPath) → str

Return a HTML trail of the given CioPath.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current directory.

Return type:

str

file_normalize(file_name: str, is_dir: bool = False) → str | None

Return a normalized file name or None if the file is in the excluded file list.

Parameters:

• fielname (str) – Name to normalize.

• is_dir (bool) – (default=False) True if the file is a directory.

Return type:

str

move_from(from_warehouse: Warehouse, from_ciopath: CioPath, to_ciopath: CioPath, overwrite_ok: bool = False, mode: str = 'move') → tuple[CioPath | None, str | None]

Move or copy a file from an another warehouse.

Parameters:

• from_warehouse (.lib.warehouse.Warehouse) – Source warehouse object.

• from_ciopath (.lib.ciopath.CioPath) – CioPath of the source file.

• to_ciopath (.lib.ciopath.CioPath) – CioPath of the destination file.

• overwrite_ok (bool) – (default=False) If True, silently overwrite the destination file.

• mode (str) – ('move', 'copy', 'rename') The way the move must operate.

Return type:

tuple

Returns:

A tuple such as (final_to_ciopath, error).

lock(name: str, ciopath: CioPath | None = None, relock: bool = False) → tuple[bool, str]

Lock a file, a directory or the whole warehouse with a name.

Parameters:

• name (str) – Name of the responsible of the lock.

• ciopath (.lib.ciopath.CioPath) – (optional) CioPath of the file to lock.

• relock (bool) – If True update the date/time of the lock.

Return type:

str

unlock(ciopath: CioPath | None = None)

Unlock a file, a directory or the whole warehouse.

Parameters:

ciopath (.lib.ciopath.CioPath) – (optional) CioPath of the file to unlock.

unlock_all()

Remove lock directory.

seeds(request, *args, **kwargs)

Use of user cache.

jobs(request: Request) → dict

Return a dictionary of available jobs for this warehouse.

Parameters:

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

Return type:

dict

job(request: Request, job_id: str, config: ConfigParser | None = None) → dict | None

Return a dictionary representing the job.

Parameters:

• request (pyramid.request.Request) – Current request.

• job_id (str) – Job ID.

• config (configparser.ConfigParser) – (optional) Configuration parser based on application configuration file.

Return type:

dict

Returns:

A dictionary with keys 'job_id', 'i18n_label', 'i18n_description', 'icon', 'threaded', 'ttl', 'priority', 'settings', 'service_id'. If a problem succeeds, it returns None.

classmethod error(message: str, request: Request | None = None)

Log an error message.

Parameters:

• message (str) – Error message.

• request (pyramid.request.Request) – (optional) Current request or None if called by populate script.

classmethod warning(message: str, request: Request | None = None)

Log an warning message.

Parameters:

• message (str) – Warning message.

• request (pyramid.request.Request) – (optional) Current request or None if called by populate script.

The lib.manager Module

A file manager is responsible for displaying and, possibly, editing a file.

class ciowarehouse2.lib.manager.Manager

Base class for file managers.

This object provides rendering for a particular type of file.

viewings and editings attributes are lists of dictionaries with the following keys:

• 'label': (required) label of the rendering

• 'template': (required) Chameleon template to use

• 'css': list of paths to CSS file

• 'js': list of path to Javascript file

• 'only4groups': set of groups of authorized users for editing

classmethod register(environment: Configurator | dict, manager_class) → Manager

Method to register the manager.

Parameters:

• environment (pyramid.config.Configurator or dict) – Object used to do configuration declaration within the application or a ScriptRegistry to simulate the application registry.

• manager_class – Manager class.

• kwargs (dict) – Keyworded arguments

Return type:

.lib.manager.Manager

initialize(config: dict)

Initialize the manager.

Parameters:

config (dict) – Dictionary with keys 'root' and 'develop' where 'root' is the absolute path to the root directory for manager with imports.

install(force: bool = False)

Install a manager in an alternative home directory with its imports.

Parameters:

force (bool) – If True, force installation.

match(ciotype: CioType) → bool

Check whether this file manager matches with the CioType.

Parameters:

ciotype (.lib.ciotype.CioType) – The CioType to compare with mine.

Return type:

bool

current_rendering(request: Request, warehouse: Warehouse, rendering_type: str) → dict | None

Find the current rendering.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• rendering_type (str) – (‘viewing’ or ‘editing’) Type of rendering.

Return type:

dict

view(request: Request, warehouse: Warehouse, ciopath: CioPath, ts_factory=None) → str | None

Return a string containing HTML to display the file.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current file.

• ts_factory – (optional) Translation String Factory fucntion.

Return type:

str or None

can_edit() → bool

Return True if it can produce an editor.

Return type:

bool

edit(request: Request, warehouse: Warehouse, ciopath: CioPath, ts_factory=None) → str | None

Return a string containing HTML to edit the file.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current file.

• ts_factory – (optional) Translation String Factory fucntion.

Return type:

str or None

save(request: Request, warehouse: Warehouse, ciopath: CioPath, editing: dict, values: dict, go_on: bool, original: ElementTree | None = None) → str | None

Save the file.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current file.

• editing (dict) – Dictionary representing the editing.

• values (dict) – Modified values.

• go_on (bool) – True if the modification continues after saving.

• original (lxml.etree._ElementTree) – (optional) Initial content of the file.

Return type:

str or None

Returns:

An error message or None.

edit_finalization(request: Request, warehouse: Warehouse, ciopath: CioPath, message: str | None = None)

Commit changes, unlock files and refresh warehouse.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current file.

• message (str) – (optional) Commit meesage.

Return type:

bool

classmethod file_lock(request: Request, warehouse: Warehouse, ciopath: CioPath) → tuple[bool, str]

Lock a file for myself for the purpose of editing it.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• ciopath (.lib.ciopath.CioPath) – CioPath of the file to lock.

Return type:

bool

classmethod file_unlock(request: Request, warehouse: Warehouse, ciopath: CioPath)

Unlock a file.

Parameters:

• request (pyramid.request.Request) – Current request.

• warehouse (.lib.warehouse.Warehouse) – Object describing the warehouse containing the file.

• ciopath (.lib.ciopath.CioPath) – CioPath of the file to unlock.

abspath_from_home(path: str) → str

Return an absolute path.

Parameters:

path (str) – Absolute path or relative path to the home directory of the manager.

Return type:

str

classmethod themed_urls(request, rendering, name)

Return a list of URLs possibly completed with theme prefix.

Parameters:

• request (pyramid.request.Request) – Current request.

• rendering (dict) – Dictionary defining the rendering.

• name (str) – Name of the bunch of URLs (‘css’, ‘js’)

Return type:

list

The lib.file_info Module

File information class.

ciowarehouse2.lib.file_info.info_read(request: Request, warehouse: Warehouse, ciopath: CioPath, metafields: list | tuple | None = None) → tuple[dict, set[str], set[str] | None]

Return fields, sharings and only4groups for the given path.

Parameters:

• request (pyramid.request.Request) – Current request or None if called by a script.

• warehouse (.lib.warehouse.Warehouse) – Current warehouse object.

• CioPath (.lib.ciopath.CioPath) – CioPath of the file.

• metafields (list) – (optional) List of metadata field IDS to retrieve. If not defined, return all metadata fields of the warehouse.

Return type:

tuple

Returns:

A tuple such as (metadata, sharings, only4groups).

ciowarehouse2.lib.file_info.info_get_root(warehouse_root: str, ciopath: CioPath, remove_fields: bool = False, remove_only4groups: bool = False) → etree.Element | None

Load or create the information XML structure of a given CioPath.

Parameters:

• warehouse_root – Absolute path to the warehouse root.

• ciopath (.lib.ciopaht.CioPath) – The current CioPath.

• remove_fields (bool) – if True metadata fields are removed.

• remove_only4groups (bool) – if True authorized groups are removed.

Return type:

lxml.etree._Element

Returns:

Root element of the information XML file.

ciowarehouse2.lib.file_info.info_save(root_elt: Element, warehouse_root: str, ciopath: CioPath, request: Request | None = None) → bool

Save an information XML file of a given CioPath.

Parameters:

• root_elt (lxml.etree.Element) – Root of the XML document.

• warehouse_root – Absolute path to the warehouse root.

• ciopath (.lib.ciopaht.CioPath) – The current CioPath.

• request (pyramid.request.Request) – (optional) Current request.

Return type:

bool

ciowarehouse2.lib.file_info.info_get_field(request: Request, root_elt: Element, field_id: str)

Return the value of a field in its correct type or None.

Parameters:

• request (pyramid.request.Request) – Current request.

• root_elt (lxml.etree.Element) – Root of the XML document.

• meta_id (str) – ID of the metadata to retrieve.

Returns:

Value of field or None.

ciowarehouse2.lib.file_info.info_set_fields(root_elt: Element, fields: list)

Update metadata fields.

Parameters:

• root_elt (lxml.etree.Element) – Root of the XML document.

• fields (list) – List of metadata fields. Each item is a tuple such as (field_id, value, display).

ciowarehouse2.lib.file_info.info_get_sharings(root_elt: etree.Element | None) → set[str]

Return a list of sharing IDs.

Parameters:

root_elt (lxml.etree.Element) – Root of the XML document.

Return type:

set

ciowarehouse2.lib.file_info.info_add_sharing(root_elt: Element, sharing_id: str) → bool

Add a sharing ID.

Parameters:

• root_elt (lxml.etree.Element) – Root of the XML document.

• sharing_id (str) – Sharing ID.

Return type:

bool

ciowarehouse2.lib.file_info.info_remove_sharing(root_elt: Element, sharing_id: str)

Remove a sharing ID.

Parameters:

• root_elt (lxml.etree.Element) – Root of the XML document.

• sharing_id (str) – Sharing ID.

ciowarehouse2.lib.file_info.info_get_only4groups(root_elt: etree.Element | None) → set[str] | None

Return a list of authorized groups or None if there is no restriction.

Parameters:

root_elt (lxml.etree.Element) – Root of the XML document.

Return type:

set

ciowarehouse2.lib.file_info.value2str(value) → str

Convert a value to a string for XML.

Parameters:

value – Value to convert.

Return type:

str

The lib.file_paging Module

Class to divide large lists of direcrories and files into pages.

ciowarehouse2.lib.file_paging.sortable_column(request: Request, label: str, sort: str, current_sorting: str | None = None, sortable: bool = True) → str

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.

• sortable (bool) – (default=True) Non sortable field management.

Return type:

helpers.literal.Literal

class ciowarehouse2.lib.file_paging.FilePaging(request: Request, ciopath: CioPath, query: str, params: dict | None = None, keep_list: bool = False, snippets: int = 0)

Divide large lists of direcrories and files into pages using a backend.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current directory, possibly an empty one.

• query (str) – Tantivy query.

• params (dict) – (optional) Paging parameters: page number, page size, display mode and sort.

• keep_list (bool) – if True, save a list of (ciopath, cioptype) in the user session.

• snippets (int) – (default = 0) Length of the context to show.

classmethod params(request: Request, ciopath: CioPath, default_sort: str | None = None, default_display: str = 'cards') → dict

Set paging parameters into the paging session return it.

Parameters:

• request (pyramid.request.Request) – Current request.

• ciopath (.lib.ciopath.CioPath) – CioPath of the current directory, possibly an empty one.

• default_sort (str) – (optional) Default sorting (ex. ‘+file_name’).

• default_display (str) – (optional) Default display (ex. ‘cards’).

Return type:

dict

get_pfile(ciopath: CioPath) → dict | None

Retrieve the first item whose CioPath matches.

Parameters:

ciopath (.lib.ciopath.CioPath) – CioPath to search.

Return type:

dict

pager_top() → str

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

Rtye:

str

pager_bottom(pager_format: str = '~4~') → str

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(modes: tuple = ('cards', 'list')) → str

Output buttons to switch between snippets, cards and list mode.

Parameters:

modes (tuple) – Modes to display.

Return type:

str

sortable_column(label: str, sort: str, sortable: bool = True) → str

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.

• sortable (bool) – (default=True) Non sortable field management.

Return type:

helpers.literal.Literal

The lib.wfile Module

Warehouse file class.

class ciowarehouse2.lib.wfile.WFile(request: Request)

Class to operate on files in a warehouse or in a result of search.

Parameters:

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

upload(warehouse: Warehouse, directory_ciopath: CioPath)

Import several files in the current directory.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse object if exists.

• directory_ciopath (.lib.ciopath.CioPath) – CioPath of the current directory .

remove(targets: tuple[str])

Remove files.

Parameters:

targets (tuple) – List of CioType`ǁ`CioPath.

new_file(warehouse: Warehouse | None, directory_ciopath: CioPath, action: str, values: dict) → CioPath | None

Create a new file or a new directory.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse object.

• form – Current form.

• directory_ciopath (.lib.ciopath.CioPath) – CioPath of the current directory, possibly an empty one.

• values (dict) – Values needed by the seeder.

Return type:

.lib.ciopath.CioPath

sharing_create(targets: tuple[str], values: dict, paging: FilePaging)

Save a sharing.

Parameters:

• targets (tuple) – Tuple of CioType`ǁ`CioPath.

• values (dict) – Values such as message, password1 and expiration.

• paging (.lib.file_paging.FilePaging) – Current FilePaging.

The lib.wjob Module

Warehouse job class.

class ciowarehouse2.lib.wjob.WJob(request)

Class to manage jobs manually called in a warehouse.

Parameters:

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

available(warehouse: Warehouse, caller: str = 'browse_view') → OrderedDict | None

Return a list of available jobs for the current warehouse.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse object.

• caller (str) – (default=’browse_view’) Name of the entity which calls the warehouse.

Return type:

dict

Returns:

A dictionary of tuples such as (icon, translated_label, service, context).

prepare(warehouse: Warehouse | None, form: Form, action: str) → tuple[str, str | None]

Prepare a job and a build.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse object.

• form – Current form.

• action (str) – Current action.

Return type:

tuple

Returns:

A tuple such as (action, build_id).

run(build_id: str)

Execute a job on a build.

Parameters:

build_id (str) – ID of a registered build.

get(warehouse: Warehouse | None, job_id: str, caller: str = 'browse_view') → dict | None

Retrieve a warehouse job checking if it is authorized in this context.

Parameters:

• warehouse (.lib.warehouse.Warehouse) – Current warehouse object if exists.

• job_id (str) – Job ID.

• caller (str) – (default=’browse_view’) Name of the entity which calls the warehouse.

Return type:

dict

See: lib.warehouse.Warehouse.job()