Library Reference

The lib.i18n Module

Localization management.

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

cioservice.lib.utils.location2abs_base(locations: dict, location_id: str) → str | None

Return the absolute path to the base of location location_id.

Pram dict locations:

Dictionary of locations. It can be updated during the operation.

Parameters:

location_id (str) – ID of the searched location. A named location is like 'private', a workspace is like 'Sandbox'.

Return type:

str or None

cioservice.lib.utils.location_path2abs_path(locations: dict, location_path: str) → str | None

Return an absolute path for a location path using the dictionary of locations. A location path must contain ':' ('private:MyDocument') and can begin with '/' ('/Sandbox:Images/foo.png').

Pram dict locations:

Dictionary of locations. It can be updated during the operation.

Parameters:

path (str) – Location path.

Return type:

class:str or None

cioservice.lib.utils.flag_image(theme: str, flag_id: str, active: bool) → str

Return an URL to an image ON or OFF according to active.

Parameters:

• theme (str) – Current theme.

• flag_id (str) – ID of the flag. For instance, 'favorite'.

• active (bool) – State of the flag.

Return type:

str

The lib.service Module

Base class for services.

class cioservice.lib.service.Service(registry: ScriptRegistry)

Base class to manage a service.

Parameters:

registry (chrysalio.scripts.ScriptRegistry) – Application registry.

classmethod register(environment, service_class)

Method to register the service.

Parameters:

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

• service_class – Service class.

need_dialog(context: str) → bool

Return True if this service needs a dialog box before launching.

Parameters:

context (str) – Context name (processor ID…).

Return type:

bool

classmethod need_files(context: str) → bool

Return True if this service needs input files.

Parameters:

context (str) – Context name (processor ID…).

Return type:

bool

need_write_permission(context: str) → bool

Return True if this service needs permission to write output files.

Parameters:

context (str) – Context name (processor ID…).

Return type:

bool

select_files(params: dict)

Select in the build parameters dictionary files which are candidate for the service.

Parameters:

params (dict) – Dictionary defining the parameters of the build.

select_files_message(params: dict) → str

Return a message specifying files to be selected.

Parameters:

params (dict) – Dictionary defining the parameters of the build.

Return type:

pyramid.i18n.TranslationString

authorized(caller: str, **kwargs) → bool

Check if the service is authorized .

Parameters:

• caller (str) – Name of the caller: ‘cioexecute’, ‘browse_view’…

• kwargs (dict) – Keyworded arguments to decide if the service is authorized. It can contain the following keys: ‘job’, ‘warehouse’, ‘file_writer’, ‘meta_writer’.

Return type:

bool

make_build(build_id: str, params: dict, stopping: Event | None = None) → Build

Create a build object.

Parameters:

• build_id (str) – ID of the build.

• params (dict) – Dictionary defining the parameters of the build. It has the keys 'job_id', 'context', 'lang', 'ttl', settings, 'values', 'files', 'resources' and 'output'. It possibly has the key 'dbsession'.

• stopping (threading.Event) – (optional) Flag to stop the processing.

Return type:

.lib.build

run(build: Build) → dict

Prepare the service for execution and launch it.

Parameters:

build (.lib.build.Build) – Current build object.

Return type:

dict

Returns:

A dictionary of results.

write_traces(build: Build, domain: str | None = None)

Write trace messages into the database and/or a log file.

Parameters:

• build (.lib.build.Build) – Current build object

• domain (str) – (optional) Domain of the log.

write_running(build: Build)

Write a “running” message into the database.

Parameters:

build (.lib.build.Build) – Current build object

erase_running(build: Build)

Erase the “running” message in the database.

Parameters:

build (.lib.build.Build) – Current build object

variables(context: str | None, request: Request | None = None) → dict

Return an ordered dictionary of variables.

Parameters:

• context (str) – Context name (processor ID…).

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

Return type:

dict

Each variable has a name (the key in the ordered dictionary and a describing dictionary with the following keys:

• 'group': home group

• 'type' (required): a type among 'string', 'boolean', 'integer', 'decimal', 'regex' and 'list'

• 'label' (required)

• 'hint': a hint to set the variable

• 'required': a boolean to specify if the variable must have a value

• 'visible': the variable is visible before launching

• 'default': default value

• 'regex': a string required for regex type only

• 'options': a dictionary required for list type only

variables_groups(context: str, request: Request) → dict

Return a dictionary of groups of variables.

Parameters:

• context (str) – Context name (processor ID…).

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

Return type:

dict

values_tabview(request: Request, context: str, form: Form, values: dict) → str

Generate the value tab.

Parameters:

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

• context (str) – Context name (processor ID…).

• form (.lib.form.Form) – Current form object.

• values (dict) – Values of the variables.

Return type:

str

values_schema(schema, defaults: dict, dbjob: DBJob, visible_only: bool = False, relax: bool = False)

Update a Colander schema with default values for form with values.

Parameters:

• schema (colander.SchemaNode) – Colander schema to update.

• defaults (dict) – Dictionary of default values for a form.

• dbjob (.models.dbjob.DBJob) – SQLAlchemy object DBJob.

• visible_only (bool) – (default=False) If True, list only visible variables.

• relax (bool) – (default=False) If True, required is ignored.

values_tabedit(request: Request, context: str, form: Form, visible_only: bool = False) → str

Generate the value tab for edition.

Parameters:

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

• context (str) – Context name (processor ID…).

• form (.lib.form.Form) – Current form object.

Pram bool visible_only:

(default=False) If True, list only visible variables.

Return type:

chrysalio.helpers.literal.Literal

The lib.build Module

Build management.

class cioservice.lib.build.Build(lock_dir, manager, build_id, params, stopping)

This class manages a build.

Parameters:

• lock_dir (str) – Absolute path to a directory which stores the lock files.

• manager (.lib.build_manager) – Manager for this build.

• build_id (str) – Build ID.

• params (dict) – Dictionary defining the parameters of the build.

• stopping (threading.Event) – Flag to stop the processing.

A build has the following keys attributes:

• 'job_id': job ID

• 'uid': build ID

• 'context': Name of the context (processor ID…)

• 'lang': prefered language for messages

• 'ttl': Time To Live for an execution

• 'deadline': deadline for the run

• 'settings': settings for this build

• 'values': values for the variables

• 'files': list of files to process

• 'resources': list of resources

• 'locations': dictionary of locations of templates or warehouses

• 'caller': a dictionary with login, name and email of the caller

• 'callback': ID of the callback function

• 'dbsession': possible current SQLAlchemy session

• 'output': absolute path to the possible output directory

• 'stopping': threading.Event as a Flag to stop the processing

• 'current': a dictionary describing the file under processing

• 'result': dictionary containing the result

The build.current dictionary have the following keys:

• 'input_file': absolute path to the original input file

• 'fup': absolute path to the File Under Processing

The build.result dictionary has, at least, following keys:

• 'no_execution': True if the execution is impossible

• 'infos': information messages

• 'warnings': warning messages

• 'errors': errors messages

• 'traces': log

• 'files': list of absolute paths to successful files

• 'output': if success, an absolute or relative path to the result

  directory

It may have:

• 'output_url': a possibly URL to the result directory

• 'to_refresh': a list of relative path to refresh

lock()

Lock the build.

Return type:

bool

unlock()

Unlock the build.

relock()

Refresh the lock of the build.

aborted()

Check if the process has been aborted.

Return type:

bool

output_info(output=None)

Add ‘output’ key in the build result and add an information with location of the result, possibly as a link.

Parameters:

output (str) – (optional) Forced ouput.

output_unrefreshed()

Try to remove the record of last refresh for the current output.

progress()

Return the progress of the build .

Return type:

tuple

Returns:

A tuple such as (file_percent, file_name, step_percent, step_trace).

progress_file(current=None, total=None, increase=None)

Set the file progress.

progress_step(current=None, total=None, increase=None)

Set the step progress.

progress_save()

Save the current progress in the build environment.

dbsession_factory()

Retrieve a DB session maker function if the current self.dbsession is None.

Return type:

sqlalchemy.orm.session.sessionmaker() or None

attachments_path()

Return a absolute path to the attachments directory or None.

Return type:

class:str or None

aborted_message()

Check if an aborted message is needed.

clear_messages()

Clear information, warning and error messages.

info(text)

Add an information message in the result.

Parameters:

text (str) – Information.

warning(text)

Add a warning message in the result.

Parameters:

text (str) – Warning.

error(text)

Add an error message in the result.

Parameters:

text (str) – Error.

trace(text, status='T')

Add a trace message in the result.

Parameters:

• text (str) – Trace.

• status (str) – (default=’T’) Type of trace: ‘T’=normal, ‘E’=error, ‘W’=warning, ‘I’=info.

Each trace is a tuple such as (status, text).

clear_traces()

Clear traces.

The lib.build_manager Module

Management of parallelized builds.

class cioservice.lib.build_manager.BuildManager(concurrency: int = 3, registry: Registry | None = None)

This class manages the launch of parallelized builds.

Parameters:

• concurrency (int) – (default=DEFAULT_CONCURRENCY) Maximum number of builds running at the same time.

• registry – Application registry or registry like.

The build environment is a dictionary with the following keys:

• 'job': job dictionary

• 'params': dictionary of parameters for the build

• 'status': current status ('pending', 'in_spool', 'running', 'stopping' or 'completed')

• 'launch': launch time

• 'duration': duration of the processing

• 'result': (optional) result of the processing

set_registry(registry: Registry)

Set the internal registry.

Parameters:

registry – Application registry or registry like.

add_callback(callback_id: str, callback_function)

Add a callback function.

Parameters:

• callback_id (str) – Callback ID.

• callback_function (str) – Callback fucntion.

remove_callback(callback_id: str)

Remove a callback function.

Parameters:

• callback_id (str) – Callback ID.

• callback_function (str) – Callback fucntion.

build_env(build_id: str, check_stopping: bool = False) → dict | None

Return the build environment for build build_id.

Parameters:

• build_id (str) – Build ID.

• check_stopping (bool) – (default=False) if True, check if the build is stopping correctly.

Return type:

dict or None

register(build_id: str, job: dict, params: dict) → str | None

Register a new build.

Parameters:

• build_id (str) – Build ID.

• job (dict) – Job to launch.

• params (dict) – Parameters of the build.

Returns:

Error message or None.

run(build_id: str, build_env: dict | None = None) → str | None

Add a build to the spool and try to launch it.

Parameters:

• build_id (str) – Build ID.

• build_env (dict) – (optional) The environment of the current build.

Returns:

Error message or None.

set_progress(build_id: str, progress: list)

Save the current progress value in the build environment.

Parameters:

• build_id (str) – Build ID.

• progress (list) – A tuple such as [file_percent, file_name, step_percent, step_trace].

stop(build_id: str, build_env: dict | None = None) → dict | None

Stop a build and return its environment.

Parameters:

• build_id (str) – ID of the build to stop.

• build_env (dict) – (optional) The environment of the current build.

Return type:

dict or None

completed(build_id: str, callback_id: str, result: dict)

Call back for a completed build.

Parameters:

• build_id (str) – ID of the completed build.

• callback_id (str) – ID of the callback function.

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

classmethod clean_logs(dbsession)

Clean up old logs.

Parameters:

dbsession (sqlalchemy.orm.session.Session) – SQLAlchemy session.

set_launch_time(build_id: str, build_env: dict)

Set the launch time and reset the duration.

Parameters:

• build_id (str) – Build ID.

• build_env (dict) – ID of the completed build.

attachments_path() → str | None

Return a absolute path to the attachments directory or None.

Return type:

class:str or None

dbsession_factory()

Retrieve a DB session maker function.

Return type:

sqlalchemy.orm.session.sessionmaker() or None

class cioservice.lib.build_manager.ServiceThread(service, build_id, params, callback)

A thread to execute a service.

Parameters:

• service (.lib.service.Service) – Service to execute.

• build_id (str) – ID of the build.

• params (dict) – Dictionary defining the parameters of the build.

• callback – Call back function to call at the end of the processing.

See lib.service.Service.run() for details on params.

The attribute result contains the result of the processing.

run()

Prepare the service for execution and launch it.

stop()

Stop the execution.

join(timeout: float | None = None)

Wait until the thread terminates.

Parameters:

timeout (float) – (optional) A timeout for stopping in seconds.