tlcconfig.options#

Configuration options for 3LC

This module contains the configuration options for 3LC. These options can be set in a config file, as environment variables, or as command line arguments when launching the object service.

Module Contents#

Classes#

Class

Description

OPTION

Base class for all 3LC options

OBJECT_SERVICE_PORT

Port for the server.

OBJECT_SERVICE_DASHBOARD

Whether to serve the Dashboard from Object Service.

OBJECT_SERVICE_HOST

Host for the server.

OBJECT_SERVICE_LICENSE

Specify license or license file

OBJECT_SERVICE_CACHE_IN_MEMORY_SIZE

Specify the amount of memory to use for caching, in bytes.

OBJECT_SERVICE_CACHE_TIME_OUT

Specify the cache item time out, in seconds.

PROJECT_ROOT_URL_OPTION

Location for reading and writing 3LC data.

PROJECT_SCAN_URLS_OPTION

Locations to scan for 3LC objects (runs and tables) following a standard 3LC project layout.

EXTRA_TABLE_SCAN_URLS_OPTION

Extra (non-recursive) locations to scan for 3LC Table objects.

EXTRA_RUN_SCAN_URLS_OPTION

Extra (non-recursive) locations to scan for 3LC Run objects.

LOGFILE

Log file for the 3LC logger.

LOGLEVEL

Log level for the 3LC logger.

DISPLAY_PROGRESS

Whether to display progress bars or not.

TELEMETRY

Whether to send Telemetry or not.

ALIASES

List of aliases.

Functions#

Function

Description

get_default_root_dir

Return the default root directory. This directory has a “projects” subdir that contains 3LC projects.

get_default_log_dir

Return the default log root directory.

get_default_config_dir

Return the default config file directory.

API#

tlcconfig.options.get_default_root_dir() str#

Return the default root directory. This directory has a “projects” subdir that contains 3LC projects.

This function is platform dependent, and the default is platform dependent:

  • Linux: $HOME/.local/share/3LC/ or $XDG_DATA_HOME/3LC/

  • macOS: $HOME/Library/Application Support/3LC/

  • Windows: %LOCALAPPDATA%\3LC\3LC\

Returns:

The default root directory.

tlcconfig.options.get_default_log_dir() str#

Return the default log root directory.

This function is platform dependent, and the default is platform dependent:

  • Linux: $HOME/.local/state/3LC/log or $XDG_STATE_HOME/3LC/log

  • macOS: $HOME/Library/Logs/3LC/Logs

  • Windows: %LOCALAPPDATA%\3LC\3LC\Logs

Returns:

The default log root directory.

tlcconfig.options.get_default_config_dir() str#

Return the default config file directory.

This function is platform dependent, and the default is platform dependent:

  • Linux: $HOME/.config/3LC or $XDG_CONFIG_HOME/3LC

  • macOS: $HOME/Library/Application Support/3LC

  • Windows: %LOCALAPPDATA%\3LC\3LC

Returns:

The default config file directory.

class tlcconfig.options.OPTION#

Base class for all 3LC options

default: Any = None#

The default value for this option if it is not specified anywhere.

envvar: str = <Multiline-String>#

The environment variable to use for this option

key: str = <Multiline-String>#

The key used for this option in the config file.

This is the fully qualified key, e.g. “object-server.port” corresponds to the following yaml:

object-server:
    port: 5015
argument: str = <Multiline-String>#

The command line argument for this option

data_type: Any = None#

The type of the option’s value

required: bool = False#

Whether this option is required or not

validate_func: Callable[[Any], bool] | None = None#

A function to validate the value of this option

transform_func: Callable[[Any], Any] | None = None#

A function to transform the value of this option before reading it.

The use case for this is e.g. to expand environment variables or do shell expansion in the value.

classmethod class_from_key(key: str) type[tlcconfig.options.OPTION]#

Get the option class from a key.

Parameters:

key – The key to look up, which should corresponds to the OPTION.key attribute of an option class.

Returns:

The option class corresponding to the key.

Raises:

RuntimeError – If the key does not corresponds to a valid option class.

classmethod is_hidden() bool#

Whether this option should be hidden or not.

Returns:

True if this option should be hidden, False otherwise.

class tlcconfig.options.OBJECT_SERVICE_PORT#

Bases: tlcconfig.options.OPTION

Port for the server.

default = 5015#
key = service.port#
data_type = None#
transform_func = None#
envvar = TLC_SERVICE_PORT#
argument = --port#
class tlcconfig.options.OBJECT_SERVICE_DASHBOARD#

Bases: tlcconfig.options.OPTION

Whether to serve the Dashboard from Object Service.

default = False#
key = service.dashboard#
data_type = None#
envvar = TLC_SERVICE_DASHBOARD#
argument = --dashboard#
transform_func = None#
required = False#
class tlcconfig.options.OBJECT_SERVICE_HOST#

Bases: tlcconfig.options.OPTION

Host for the server.

key = service.host#
envvar = TLC_SERVICE_HOST#
argument = --host#
default = 127.0.0.1#
data_type = None#
class tlcconfig.options.OBJECT_SERVICE_LICENSE#

Bases: tlcconfig.options.OPTION

Specify license or license file

The option can be either be the license key or point to a local file containing the license key.

default = <Multiline-String>#
key = service.license#
envvar = TLC_LICENSE#
argument = --license#
data_type = None#
transform_func = None#
class tlcconfig.options.OBJECT_SERVICE_CACHE_IN_MEMORY_SIZE#

Bases: tlcconfig.options.OPTION

Specify the amount of memory to use for caching, in bytes.

Setting the value to 0 will disable in-memory caching.

Default: 1073741824 (1 GB)

default = 1073741824#
key = service.cache_in_memory_size#
argument = --cache-size#
data_type = None#
class tlcconfig.options.OBJECT_SERVICE_CACHE_TIME_OUT#

Bases: tlcconfig.options.OPTION

Specify the cache item time out, in seconds.

Setting the value to 0 will disable cache eviction based on time.

Default: 3600 (1 hour)

default = 3600#
key = service.cache_time_out#
argument = --cache-time-out#
data_type = None#
class tlcconfig.options.PROJECT_ROOT_URL_OPTION#

Bases: tlcconfig.options.OPTION

Location for reading and writing 3LC data.

This option is mandatory and must point to a location (e.g. directory on disk or object store bucket) with write access. The location will be created if it does not exist.

If the option value contains an environment variable, it will be expanded.

default = None#

As returned by get_default_root_dir

key = indexing.project-root-url#
envvar = TLC_CONFIG_PROJECT_ROOT_URL#
argument = --project-root-url#
required = True#
data_type = None#
transform_func = None#
validate_func = None#
class tlcconfig.options.PROJECT_SCAN_URLS_OPTION#

Bases: tlcconfig.options.OPTION

Locations to scan for 3LC objects (runs and tables) following a standard 3LC project layout.

Usually a ‘projects’ directory containing multiple projects. Default directories will be created if they do not exist.

default = []#
key = indexing.project-scan-urls#
data_type = None#
transform_func = None#
class tlcconfig.options.EXTRA_TABLE_SCAN_URLS_OPTION#

Bases: tlcconfig.options.OPTION

Extra (non-recursive) locations to scan for 3LC Table objects.

This option allows searching individual folders/locations for 3LC Table objects outside the standard hierarchy of a 3LC project structure. For example:

  • “C:\Users\user\Documents\3LC\tables”

  • “s3://my-bucket/3LC/tables”.

Note: these locations will not be scanned recursively.

Indexed Tables from these extra locations can be used interchangeably with other Tables discovered by the system.

default = []#
key = indexing.extra-table-scan-urls#
data_type = None#
transform_func = None#
class tlcconfig.options.EXTRA_RUN_SCAN_URLS_OPTION#

Bases: tlcconfig.options.OPTION

Extra (non-recursive) locations to scan for 3LC Run objects.

This option allows searching individual folders/locations for 3LC Run objects outside the standard hierarchy of a 3LC project structure. For example:

  • “C:\Users\user\Documents\3LC\runs”

  • “s3://my-bucket/3LC/runs”.

Note: these locations will not be scanned recursively.

Indexed Runs from these extra locations can be used interchangeably with other Runs discovered by the system.

default = []#
key = indexing.extra-run-scan-urls#
data_type = None#
transform_func = None#
class tlcconfig.options.LOGFILE#

Bases: tlcconfig.options.OPTION

Log file for the 3LC logger.

The directory will be created if it does not exist.

If the option value contains an environment variable, it will be expanded.

default = None#

As returned by get_default_log_dir / 3LC.log

key = logging.logfile#
envvar = TLC_LOGFILE#
argument = --logfile#
data_type = None#
transform_func = None#
validate_func = None#
class tlcconfig.options.LOGLEVEL#

Bases: tlcconfig.options.OPTION

Log level for the 3LC logger.

The tlc Python package adheres to the standard Python logging levels:

  • DEBUG: Detailed information, typically of interest only when diagnosing problems.

  • INFO: Confirmation that things are working as expected.

  • WARNING: An indication that something unexpected happened, or indicative of some problem in the near future (e.g. “disk space low”). The software is still working as expected.

  • ERROR: Due to a more serious problem, the software has not been able to perform some function.

  • CRITICAL: A serious error, indicating that the program itself may be unable to continue running.

default = WARNING#
key = logging.loglevel#
envvar = TLC_LOGLEVEL#
argument = --loglevel#
transform_func = None#
validate_func = None#
class tlcconfig.options.DISPLAY_PROGRESS#

Bases: tlcconfig.options.OPTION

Whether to display progress bars or not.

The option can be either 0 or 1, where 0 means no progress bars and 1 means progress bars.

default = 1#
data_type = None#
transform_func = None#
key = tlc.display-progress#
envvar = TLC_DISPLAY_PROGRESS#
argument = --display-progress#
validate_func = None#
class tlcconfig.options.TELEMETRY#

Bases: tlcconfig.options.OPTION

Whether to send Telemetry or not.

default = 0#
data_type = None#
key = tlc.telemetry#
envvar = TLC_TELEMETRY#
argument = --telemetry#
transform_func = None#
class tlcconfig.options.ALIASES#

Bases: tlcconfig.options.OPTION

List of aliases.

default = None#
data_type = None#
key = aliases#
transform_func = None#