Files

A File object is rarely used directly by end users, but it is a common base class for input and output data structures that may contain files. The File object enables transparent serialization of binary file data for serialization to .json, .yaml, or .toml which makes saving data structures to disk in a human-readable format or sending them over HTTP seamless even when they contain binary data.

qcio.Files

File model for handling string and binary data.

Binary data is encoded as base64 strings during serialization.

Attributes:

Name	Type	Description
files	Dict[str, Union[str, bytes]]	A dict mapping filename to str or bytes data.

add_file

add_file(
    filepath: Union[Path, str],
    relative_dir: Optional[Path] = None,
) -> None

Add a file to the object. The file will be added at to the files attribute with the filename as the key and the file data as the value.

Parameters:

Name	Type	Description	Default
filepath	Union[Path, str]	The path to the file.	required
relative_dir	Optional[Path]	The directory to make the file relative to. Helpful when adding files from a subdirectory.	None

Example

    my_obj.add_file("path/to/file.txt")
    print(my_obj.files)
    # Output: {"file.txt": "file data"}

Source code in qcio/models/base_models.py

def add_file(
    self, filepath: Union[Path, str], relative_dir: Optional[Path] = None
) -> None:
    """Add a file to the object. The file will be added at to the `files` attribute
        with the filename as the key and the file data as the value.

    Args:
        filepath: The path to the file.
        relative_dir: The directory to make the file relative to. Helpful when
            adding files from a subdirectory.

    Example:
        ```python
            my_obj.add_file("path/to/file.txt")
            print(my_obj.files)
            # Output: {"file.txt": "file data"}
        ```
    """
    filepath = Path(filepath)
    raw_bytes = filepath.read_bytes()
    try:
        data: Union[str, bytes] = raw_bytes.decode("utf-8")  # str
    except UnicodeDecodeError:
        data = raw_bytes  # bytes

    # Set filename relative to relative_dir
    if relative_dir:
        filename = str(filepath.relative_to(relative_dir))
    else:
        filename = filepath.name

    self.files[filename] = data
    # Add files to __pydantic_fields_set__ to ensure they are included in .save()
    self.__pydantic_fields_set__.add("files")

add_files

add_files(
    directory: StrOrPath,
    recursive: bool = False,
    exclude: Optional[List[str]] = None,
) -> None

Add all files in a directory to the object.

Parameters:

Name	Type	Description	Default
directory	StrOrPath	The directory to add files from.	required
recursive	bool	Whether to recursively add files from subdirectories.	False
exclude	Optional[List[str]]	A list of filenames to exclude from the directory.	None

Source code in qcio/models/base_models.py

def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: Optional[List[str]] = None,
) -> None:
    """Add all files in a directory to the object.

    Args:
        directory: The directory to add files from.
        recursive: Whether to recursively add files from subdirectories.
        exclude: A list of filenames to exclude from the directory.
    """
    directory = Path(directory)
    if exclude is None:
        exclude = []
    if recursive:
        files = directory.rglob("*")
    else:
        files = directory.glob("*")
    for filepath in files:
        if filepath.is_file() and filepath.name not in exclude:
            self.add_file(filepath, directory)

save_files

save_files(directory: StrOrPath = Path('.')) -> None

Write all files to the specified directory

Source code in qcio/models/base_models.py

def save_files(self, directory: StrOrPath = Path(".")) -> None:
    """Write all files to the specified directory"""
    directory = Path(directory)
    directory.mkdir(exist_ok=True)
    for filename, data in self.files.items():
        mode = "w" if isinstance(data, str) else "wb"
        filepath = directory / filename
        # In case filename is a relative path, create the parent directories
        filepath.parent.mkdir(exist_ok=True, parents=True)
        filepath.open(mode).write(data)