bluemira.base.file ================== .. py:module:: bluemira.base.file .. autoapi-nested-parse:: File I/O functions and some path operations Attributes ---------- .. autoapisummary:: bluemira.base.file.BM_ROOT bluemira.base.file.SUB_DIRS Classes ------- .. autoapisummary:: bluemira.base.file.FileManager Functions --------- .. autoapisummary:: bluemira.base.file._get_relpath bluemira.base.file.get_bluemira_root bluemira.base.file.try_get_bluemira_private_data_root bluemira.base.file.get_bluemira_path bluemira.base.file.try_get_bluemira_path bluemira.base.file.make_bluemira_path bluemira.base.file.force_file_extension bluemira.base.file.get_files_by_ext bluemira.base.file.file_name_maker bluemira.base.file.working_dir Module Contents --------------- .. py:data:: BM_ROOT :value: '!BM_ROOT!' .. py:data:: SUB_DIRS :value: ['equilibria', 'neutronics', 'systems_code', 'CAD', 'plots', 'geometry'] .. py:function:: _get_relpath(folder: str, subfolder: str) -> str .. py:function:: get_bluemira_root() -> str Get the bluemira root install folder. :returns: '/home/user/code/bluemira' :rtype: The full path to the bluemira root folder, e.g. .. py:function:: try_get_bluemira_private_data_root() -> str | None Get the bluemira-private-data root install folder. :returns: '/home/user/code/bluemira-private-data' :rtype: The full path to the bluemira root folder, e.g. .. rubric:: Notes Normal users will not have access to bluemira-private-data; it will be used exclusively for tests which require private data and files. .. py:function:: get_bluemira_path(path: str = '', subfolder: str = 'bluemira') -> str Get a bluemira path of a module subfolder. Defaults to root folder. :param path: The desired path from which to create a full path :param subfolder: The subfolder (from the bluemira root) in which to create a path Defaults to the source code folder, but can be e.g. 'tests', or 'data' :rtype: The full path to the desired `path` in the subfolder specified .. py:function:: try_get_bluemira_path(path: str = '', subfolder: str = 'bluemira', *, allow_missing: bool = True) -> str | None Try to get the bluemira path of a module subfolder. If the path doesn't exist then optionally carry on regardless or raise an error. :param path: The desired path from which to create a full path :param subfolder: The subfolder (from the bluemira root) in which to create a path Defaults to the source code folder, but can be e.g. 'tests', or 'data' :param allow_missing: Whether or not to raise an error if the path does not exist :returns: * The full path to the desired `path` in the subfolder specified, or None if the * *requested path doesn't exist.* :raises ValueError: If the requested path doesn't exist and the `allow_missing` flag is False. .. py:function:: make_bluemira_path(path: str = '', subfolder: str = 'bluemira') -> str Create a new folder in the path, provided one does not already exist. :param path: The desired path from which to create a full path :param subfolder: The subfolder (from the bluemira root) in which to create a path Defaults to the source code folder, but can be e.g. 'tests', or 'data' :returns: The full path to the desired `path` in the subfolder .. py:function:: force_file_extension(file_path: str, valid_extensions: str | list[str]) -> str If the file path does not have one of the valid extensions, append the first valid one :param file_path: path to file :param valid_extensions: collection of valid extensions :rtype: File path .. py:function:: get_files_by_ext(folder: str, extension: str) -> list[pathlib.Path] Get filenames of files in folder with the specified extension. :param folder: The full path directory in which to look for files :param extension: The extension of the desired file-type :returns: The list of full path filenames found in the folder .. py:function:: file_name_maker(filename: str | os.PathLike, *, lowercase: bool = False) -> str Ensure the file name is acceptable. :param filename: Full filename or path :param lowercase: Whether or not to force lowercase filenames :rtype: Full filename or path, corrected .. py:function:: working_dir(directory: str) Change working directory .. py:class:: FileManager(reactor_name: str, reference_data_root: str = 'data/bluemira', generated_data_root: str = 'data/bluemira') A class for managing file operations. .. py:attribute:: _reactor_name :type: str .. py:attribute:: _reference_data_root :type: str .. py:attribute:: _generated_data_root :type: str .. py:attribute:: reference_data_dirs :type: dict[str, str] .. py:attribute:: generated_data_dirs :type: dict[str, str] .. py:property:: reactor_name Gets the reactor name for this instance. .. py:property:: generated_data_root :type: str Gets the generated data root directory for this instance. .. py:property:: reference_data_root :type: str Get the reference data root directory for this instance. .. py:method:: replace_bm_root(keyword: str = BM_ROOT) Replace the keyword in input paths with path to local bluemira installation. .. py:method:: _verify_reference_data_root() Check that the reference data root defined in this instance is a valid directory. :raises ValueError: If the reference data root for this instance is not a valid directory. .. py:method:: make_reactor_folder(subfolder: str) -> dict[str, str] Initialise a data storage folder tree. :param subfolder: The subfolder of the bluemira directory in which to add the data structure :rtype: The dictionary of subfolder names to full paths (useful shorthand) .. py:method:: set_reference_data_paths() Generate the reference data paths for this instance, based on the reactor name. .. py:method:: create_reference_data_paths() Generate the reference data paths for this instance, based on the reactor name. Also builds the relevant directory structure. .. py:method:: create_generated_data_paths() Generate the generated data paths for this instance, based on the reactor name. Also builds the relevant directory structure. .. py:method:: build_dirs(*, create_reference_data_paths: bool = False) Create the directory structures for this instance and sets the path references. .. py:method:: get_path(sub_dir_name: str, path: str | os.PathLike, *, make_dir: bool = False) -> str Get a path within the generated data sub-sdirectories. If the path does not exist then it will optionally be created as a directory. :param sub_dir_name: The name of the sub-directory to create the path under. Must be one of the names in bluemira.base.file.SUB_DIRS. :param path: The path to create under the sub-directory. :param make_dir: Optionally create a directory at the path, by default False. :rtype: The path within the data sub-directories.