sda.misc.config =============== .. py:module:: sda.misc.config .. autoapi-nested-parse:: Functions to parse the ``~/sda.json`` :ref:`Configuration file . Create a ~/sda.json file in your HOME that contains all machine-specific information (e.g: path to data folders). See :data:`~sda.misc.config.DBFORMAT` for expected format. Attributes ---------- .. autoapisummary:: sda.misc.config.CONFIG_PATH_DEFAULT sda.misc.config.CONFIG_PATH_JSON sda.misc.config.CONFIG_DATA_SHAREPOINTS_KEY sda.misc.config.configuration_dict Functions --------- .. autoapisummary:: sda.misc.config.validate_and_normalize_path sda.misc.config.deep_update sda.misc.config.get_config sda.misc.config.get_test_data_only_config sda.misc.config.append_test_data_to_config sda.misc.config.get_config_with_test_data sda.misc.config.init_config_json sda.misc.config.get_user_config Module Contents --------------- .. py:data:: CONFIG_PATH_DEFAULT .. py:data:: CONFIG_PATH_JSON .. py:data:: CONFIG_DATA_SHAREPOINTS_KEY :value: 'DATA_SHAREPOINTS' .. py:function:: validate_and_normalize_path(path_str, context = '') Validate and normalize a path string using pathlib, preserving literal backslashes. :param path_str: Path string to validate and normalize :type path_str: :py:class:`str` :param context: Context information for error messages :type context: :py:class:`str`, *optional* :returns: (path_object, error_message). If valid, error_message is empty. If invalid, path_object is None. :rtype: :py:class:`tuple[Path | None`, :py:class:`str]` .. py:function:: deep_update(dict1, dict2) Recursively update dict1 with dict2. This function merges two dictionaries, where dict2 overrides dict1. If both dictionaries have a key with a dictionary value, it merges them recursively. If the value in dict2 is not a dictionary, it simply replaces the value in dict1. :param dict1: The original dictionary to be updated. :type dict1: :py:class:`dict` :param dict2: The dictionary with values to update dict1. :type dict2: :py:class:`dict` :returns: dict1 is updated in place. :rtype: :py:obj:`None` .. py:function:: get_config(config_path = CONFIG_PATH_JSON) Read the default SDA config.json file `config_path`. Original code taken from RADIS (https://github.com/radis/radis/issues/328) When SDA_USE_TEST_DATA environment variable is set to "true", automatically appends test data paths to the configuration for CI/testing environments. :param config_path: Path to configuration file. Override default file with the entries of the user config filen in CONFIG_PATH_DEFAULT. By default CONFIG_PATH_JSON. :type config_path: :py:class:`Path`, *optional* :returns: Configuration, with test data paths automatically included if SDA_USE_TEST_DATA=true :rtype: :py:class:`dict` :raises JSONDecodeError: If there is an error reading the JSON file (e.g. syntax error). :raises .. minigallery:`: :py:class:`sda.misc.config.get_config: .. py:function:: get_test_data_only_config(config, test_data_root = None) Create configuration with only test data paths to avoid SharePoint validation errors. This function replaces all SharePoint paths with only test data paths, preventing validation errors when SharePoint paths don't exist in CI environments. :param config: Configuration dictionary to modify :type config: :py:class:`dict` :param test_data_root: Root path for test data. If None, uses tests/data relative to project root. :type test_data_root: :py:class:`Path`, *optional* :returns: Modified configuration with only test data paths :rtype: :py:class:`dict` .. rubric:: Examples >>> config = get_config() # Contains SharePoint paths >>> ci_config = get_ci_only_config(config) # Only test data paths .. py:function:: append_test_data_to_config(config, test_data_root = None) Append test data paths to config for CI testing. This function adds test data sharepoints to the configuration dictionary to allow tests to run with local test fixtures instead of requiring real SharePoint data. :param config: Configuration dictionary to modify :type config: :py:class:`dict` :param test_data_root: Root path for test data. If None, uses tests/data relative to project root. :type test_data_root: :py:class:`Path`, *optional* :returns: Modified configuration with test data paths added :rtype: :py:class:`dict` .. rubric:: Examples >>> config = get_config() >>> config = append_test_data_to_config(config) >>> # Now config contains test data paths for T097, T083, etc. .. py:function:: get_config_with_test_data(config_path = CONFIG_PATH_JSON, test_data_root = None) Get configuration with test data paths appended. This is a convenience function that combines get_config() and append_test_data_to_config() for easy use in tests. :param config_path: Path to configuration file, by default CONFIG_PATH_JSON :type config_path: :py:class:`Path`, *optional* :param test_data_root: Root path for test data. If None, uses tests/data relative to project root. :type test_data_root: :py:class:`Path`, *optional* :returns: Configuration with test data paths included :rtype: :py:class:`dict` .. rubric:: Examples >>> config = get_config_with_test_data() >>> # Use in tests or CI environments .. py:function:: init_config_json(config_path_json, verbose=1) Create a `sda.json` file in the user's home directory if it does not exist. :param config_path_json: Path to the configuration file. :type config_path_json: :py:class:`Path` :param verbose: Verbosity level. If `verbose` is greater than 1, print the path of the configuration file. By default, it is set to False (no output). :type verbose: :py:class:`int`, *optional* :raises JSONDecodeError: If there is an error reading the JSON file (e.g. syntax error). :raises FileNotFoundError: If the file does not exist. .. py:function:: get_user_config(config_path = CONFIG_PATH_JSON) Read configuration file and returns it. :param config_path: Configuration file, by default CONFIG_PATH_JSON :type config_path: :py:class:`Path`, *optional* :returns: Configuration :rtype: :py:class:`dict` :raises JSONDecodeError: If there is an error reading the JSON file (e.g. syntax error). .. py:data:: configuration_dict