Skip to content

Files

A File object is rarely used directly by end users, but it is a common base class for Input and 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.

qcdata.Files

File model for handling string and binary data.

Binary data is encoded as base64 strings during serialization. save writes a text over 1 MiB (UTF-8) to its own file beside the saved file, as it does large arrays.

Attributes:

Name Type Description
files dict[str, str | bytes]

A dict mapping filename to str or bytes data.

add_file

add_file(
    filepath: Path | str, relative_dir: Path | None = None
) -> None

Add a file to the object.

The file is added to the files attribute with the filename as the key and the file data as the value. UTF-8 decodable files are stored as str; all other files are stored as bytes.

Parameters:

Name Type Description Default
filepath Path | str

The path to the file.

required
relative_dir Path | None

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 src/qcdata/models/base_models.py
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
def add_file(self, filepath: Path | str, relative_dir: Path | None = None) -> None:
    """Add a file to the object.

    The file is added to the `files` attribute with the filename as the key and
    the file data as the value. UTF-8 decodable files are stored as `str`; all
    other files are stored as `bytes`.

    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: 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: list[str] | None = 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 list[str] | None

A list of filenames to exclude from the directory.

None
Source code in src/qcdata/models/base_models.py
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
def add_files(
    self,
    directory: StrOrPath,
    recursive: bool = False,
    exclude: list[str] | None = 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.

Text data is written in text mode and binary data in binary mode. Parent directories are created for filenames that contain relative paths.

Parameters:

Name Type Description Default
directory StrOrPath

The directory to write the files to. Created if it does not exist (its parent must already exist). Defaults to the current working directory.

Path('.')
Source code in src/qcdata/models/base_models.py
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
def save_files(self, directory: StrOrPath = Path(".")) -> None:
    """Write all files to the specified directory.

    Text data is written in text mode and binary data in binary mode. Parent
    directories are created for filenames that contain relative paths.

    Args:
        directory: The directory to write the files to. Created if it does not
            exist (its parent must already exist). Defaults to the current
            working 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)