idstools.database¶

Module Contents¶

class idstools.database.DBMaster[source]¶

ALL_BACKENDS = "('mdsplus', 'hdf5')"¶

classmethod create_connection(imasargs, target_dd_version=None)[source]¶

classmethod get_connection(imasargs)[source]¶

static get_database_dir(database: str, user: str = None)[source]¶

The function get_database_dir returns the directory path for a given database, and raises an error if the path does not exist.

Parameters:¶

database: str¶

The database parameter is a string that represents the name of the database file or directory.

user: str = None¶

The user parameter is an optional parameter that represents the user for whom the database directory is being retrieved.

Returns:¶

the directory path of the specified database if it exists. If the database does not exist, it raises a FileNotFoundError. If the database parameter is None, it returns None.

static get_database_files(user=None, database=None, version=None, backends=None)[source]¶

The function get_database_files retrieves a list of database files based on the specified user, database, version, and backends.

Parameters:¶

user=None¶

The user parameter is used to specify the user for whom the database files are being retrieved. If no user is specified, it defaults to None.

database=None¶

The database parameter is used to specify the name of the database.

version=None¶

The version parameter is used to specify a specific version of the database.

backends=None¶

The backends parameter is a list of strings that specifies the database backends to retrieve files from. The possible values for backends are hdf5 and mdsplus. If backends is not provided, it defaults to DBMaster.ALL_BACKENDS

Returns:¶

The function get_database_files returns a list of tuples. Each tuple contains the name of a database, followed by a list of tuples. Each inner tuple contains a version number, followed by a list of tuples. Each innermost tuple contains the name of a backend (either hdf5 or mdsplus), followed by a dictionary of database files.

static get_database_files_from_folder(folder=None, backends=None)[source]¶

Retrieve database files from a folder based on specified backends.

Parameters:¶

folder=None¶

The folder path from which to retrieve database files.

backends=None¶

A list of strings specifying the database backends to retrieve files from. The possible values for backends are ‘hdf5’ and ‘mdsplus’. If backends is not provided, it defaults to DBMaster.ALL_BACKENDS

Returns:¶

A list of tuples. Each tuple contains the backend name (either ‘hdf5’ or ‘mdsplus’), followed by a dictionary of database files.

Return type:¶

list

static get_databases(user: str = None) → list[source]¶

The function get_databases returns a sorted list of databases in a user’s directory.

Parameters:¶

user: str = None¶

The user parameter is a string that represents the username of the user for whom the databases are being retrieved.

Returns:¶

a list of databases.

static get_databases_with_versions(user: str = None) → list[source]¶

The function get_databases_with_versions returns a list of tuples, where each tuple contains the name of a database and a list of its versions, for a given user.

Parameters:¶

user: str = None¶

The user parameter is a string that represents the username or identifier of the user for whom the databases and their versions are being retrieved. It is an optional parameter and can be set to None if not applicable.

Returns:¶

a list of tuples. Each tuple contains the name of a database and a list of versions associated with that database. The list is sorted by the database names.

static get_db_Path(user, database, version)[source]¶

Function that returns a pathlib Path to desired database, depending on the user, database and version names.

Parameters:¶

user¶

Status of user: either public or local. A public user should just be left as public, whereas a local user should write their proper identifier

database¶

Name of database where the data is harbored

version¶

String of number of data version

Return type:¶

pathlib.Path

classmethod get_dd_version()[source]¶

static get_hdf5_physical_file(user, database, version, pulse, run)[source]¶

The function get_hdf5_physical_file returns the path to an HDF5 file based on the user, database, version, pulse, and run.

Parameters:¶

user¶

The “user” parameter represents the name of the user who is accessing the HDF5 physical file.

database¶

The “database” parameter refers to the name of the database where the HDF5 files are stored.

version¶

The “version” parameter represents the version of the database.

pulse¶

The “pulse” parameter represents the pulse number. It is a numerical value that identifies a specific pulse in a dataset.

run¶

The “run” parameter represents the run number.

Returns:¶

the path to an HDF5 physical file.

static get_hdf5_pulses(user: str = None, database: str = None, version: str = None, status=None, as_dictionary=False) → list[source]¶

The function get_hdf5_pulses retrieves a list of pulses from HDF5 master files. It needs to specify full path till version.

Parameters:¶

user: str = None¶

The user parameter is a string that represents the user for whom the MDSPlus pulses are being retrieved.

database: str = None¶

The database parameter is a string that represents the name of the database. It is used to specify the directory where the MDSplus pulses are stored.

version: str = None¶

The version parameter is used to specify the version of the MDSplus database. It is a string that represents the version number.

as_dictionary=False¶

The as_dictionary parameter is a boolean flag that determines the format of the returned pulses. If as_dictionary is set to True, the pulses will be returned as a dictionary where the keys are the pulse numbers and the values are lists of runs associated with each pulse.Defaults to False

Returns:¶

a list of tuples. Each tuple contains the following elements, The tuple includes the pulse number, run number, HDF5_BACKEND backend, database, user, version, and data file path.

static get_hdf5_pulses_from_folder(folder: str = None, as_dictionary=False) → list[source]¶

static get_mds_plus_pulses(user: str = None, database: str = None, version: str = None, status: str = None, as_dictionary=False) → list[source]¶

The function get_mds_plus_pulses retrieves a list of MDSPlus pulses based on the provided user, database, version, and status parameters.

Parameters:¶

user: str = None¶

The user parameter is a string that represents the user for whom the MDSPlus pulses are being retrieved.

database: str = None¶

The database parameter is a string that represents the name of the database. It is used to specify the directory where the MDSplus pulses are stored.

version: str = None¶

The version parameter is used to specify the version of the MDSplus database. It is a string that represents the version number.

status: str = None¶

The “status” parameter is used to filter the pulses based on their status. If a status is provided, only pulses with that status will be included in the result. If no status is provided, all pulses will be included.

as_dictionary=False¶

The as_dictionary parameter is a boolean flag that determines the format of the returned pulses. If as_dictionary is set to True, the pulses will be returned as a dictionary where the keys are the pulse numbers and the values are lists of runs associated with each pulse.Defaults to False

Returns:¶

a list of pulses.

static get_mds_plus_pulses_from_folder(folder: str = None, as_dictionary=False) → list[source]¶

static get_mdsplus_physical_files(user, database, version, pulse, run)[source]¶

The function get_mdsplus_physical_files returns the MDS+ database filenames for a given IMAS database.

Parameters:¶

user¶

The “user” parameter is the username of the user accessing the IMAS database.

database¶

The database parameter refers to the name of the IMAS database.

version¶

The “version” parameter represents the version of the IMAS database.

pulse¶

The parameter “pulse” represents the pulse number in the IMAS database.

run¶

The “run” parameter is the run number.

Returns:¶

The function get_mdsplus_physical_files returns a tuple of three strings. The first string is the filename with the extension “.characteristics”, the second string is the filename with the extension “.datafile”, and the third string is the filename with the extension “.tree”.

static get_physical_files(user, database, version, pulse, run, backend)[source]¶

The function get_physical_files returns the physical files storing a database based on the specified backend.

Parameters:¶

user¶

The user parameter represents the user who is requesting the physical files.

database¶

The “database” parameter refers to the name or identifier of the database for which you want to retrieve the physical files.

version¶

The version parameter represents the version of the database. It is used to retrieve the physical files associated with a specific version of the database.

pulse¶

The “pulse” parameter refers to a specific pulse or shot number in a database. It is used to identify a particular data acquisition event or experiment.

run¶

The “run” parameter is used to specify the run number or identifier for the database. It is likely used to retrieve the physical files associated with a specific run of the database.

backend¶

The “backend” parameter refers to the type of database backend being used. It can have two possible values: “mdsplus” or “hdf5”.

Returns:¶

The function get_physical_files returns the physical file path storing the specified database.

static get_pulse_status(yaml_file_path) → str[source]¶

The function get_pulse_status reads a YAML file from a given path and returns the value of the “status” key in the file’s metadata.

Parameters:¶

yaml_file_path¶

The path parameter is a string that represents the file path to a YAML file.

Returns:¶

the value of the “status” key from the metadata dictionary.

static get_user_dir(user: str = None)[source]¶

The function get_user_dir returns the database directory path for a given user or the current user’s directory path if no user is specified.

Parameters:¶

user: str = None¶

The user parameter is a string that represents the username of the user for whom the directory path is being retrieved. If the user parameter is not provided or is None, it will default to the current logged-in user obtained using os.getlogin().

Returns:¶

a file path. If the user is not specified or is “public”, it returns the file path to the “public/imasdb/” directory in the user’s home directory. If the user is not “public”, itreturns the file path to the “shared/imasdb/” directory in the IMAS_HOME directory.

static get_version_dir(version: str, database: str, user: str = None)[source]¶

The function get_version_dir returns the directory path for a specific version of a database, given the version, database name, and optional user.

Parameters:¶

version: str¶

The version parameter is a string that represents the version of the database.

database: str¶

The database parameter is a string that represents the name of the database.

user: str = None¶

The user parameter is an optional parameter

Returns:¶

the directory path for the specified version of a database. If the version directory exists, it returns the path. If the version directory does not exist, it raises a FileNotFoundError. If the version parameter is None, it returns None.

static get_versions(database: str, user: str = None) → list[source]¶

The function get_versions returns a sorted list of versions in a given database directory.

Parameters:¶

database: str¶

A string representing the name of the database.

user: str = None¶

The user parameter is an optional parameter

Returns:¶

a sorted list of versions.

static get_versions_with_databases(user: str = None) → list[source]¶

The function get_versions_with_databases returns a list of tuples, where each tuple contains a version number and a list of databases associated with that version.

Parameters:¶

user: str = None¶

The user parameter is an optional string

Returns:¶

a list of tuples. Each tuple contains a version number and a list of databases that have that version.

The list is sorted in ascending order based on the version numbers.

static hdf5_list_pulse_run(locpath)[source]¶

Function that lists Pulse and Run numbers from a given database, in HDF5

Parameter¶

locpath: str or Path

Path in which the database files are stored

rtype:

list of tuple (pulse,run)

static mds_list_pulse_run(locpath, with_status=None, as_dict=False)[source]¶

Function that lists Pulse and Run numbers from a given database, in MDSPLUS

Parameters:¶

locpath¶

Path in which the database files are stored

with_status=None¶

If set, will list only pulses with given status (in associated yaml file, e.g. ‘obsolete’, ‘active’)

Return type:¶

list of tuple (pulse,run)

static pulse_list2_dict(pulselist)[source]¶

Utility function that returns a dict from a list of pairs (pulse,run)

Parameters:¶

pulselist¶

List of tuples (pulse,run)

Returns:¶

dict key=pulse

Return type:¶

value=[runs]

idstools.database.read_scenario(scenario_file_path: str, in_ids_list: list = None, out_ids_list: list = None, test_mode: bool = False, **test_args)[source]¶

This function reads a scenario file and takes in optional input and output IDs lists, as well as a test mode flag and additional test arguments.

Parameters:¶

scenario_file_path: str¶

The file path of the scenario file that contains the test cases.

in_ids_list: list = None¶

A list of input IDS names that should be read from the scenario file.

out_ids_list: list = None¶

A list of output IDS names It is used to specify the list of output IDs that the function should read from the scenario file. If this parameter is not provided, the function will read all output IDs from the scenario file.

test_mode: bool = False¶

A boolean flag indicating whether the function is being called in test mode or not. If test_mode is True, the function will execute in a way that is suitable for testing purposes. Defaults to False

idstools.database.read_scenario_with_args(imasargs, in_ids_list: list = None, out_ids_list: list = None, test_mode: bool = False, **test_args)[source]¶

This function reads a scenario file and takes in optional input and output IDs lists, as well as a test mode flag and additional test arguments.

Parameters:¶

imasargs¶

The file path of the scenario file that contains the test cases.

in_ids_list: list = None¶

A list of input IDS names that should be read from the scenario file.

out_ids_list: list = None¶

A list of output IDS names It is used to specify the list of output IDs that the function should read from the scenario file. If this parameter is not provided, the function will read all output IDs from the scenario file.

test_mode: bool = False¶

A boolean flag indicating whether the function is being called in test mode or not. If test_mode is True, the function will execute in a way that is suitable for testing purposes. Defaults to False

idstools.database.logger¶