File

File is a special DataModel, which is automatically generated when a DataChain is created from files, such as in dc.read_storage:

import datachain as dc

chain = dc.read_storage("gs://datachain-demo/dogs-and-cats")
chain.print_schema()

Output:

file: File@v1
    source: str
    path: str
    size: int
    version: str
    etag: str
    is_latest: bool
    last_modified: datetime
    location: Union[dict, list[dict], NoneType]

File classes include various metadata fields describing the underlying file, along with methods to read and manipulate file contents.

File

File(**kwargs)

Bases: DataModel

DataModel for reading binary files.

Attributes:

• source (str) –

  The source of the file (e.g., 's3://bucket-name/').

• path (str) –

  The path to the file (e.g., 'path/to/file.txt').

• size (int) –

  The size of the file in bytes. Defaults to 0.

• version (str) –

  The version of the file. Defaults to an empty string.

• etag (str) –

  The ETag of the file. Defaults to an empty string.

• is_latest (bool) –

  Whether the file is the latest version. Defaults to True.

• last_modified (datetime) –

  The last modified timestamp of the file. Defaults to Unix epoch (1970-01-01T00:00:00).

• location (dict | list[dict]) –

  The location of the file. Defaults to None.

Source code in datachain/lib/file.py

def __init__(self, **kwargs):
    super().__init__(**kwargs)
    self._catalog = None
    self._caching_enabled: bool = False

as_image_file

as_image_file() -> ImageFile

Convert the file to a ImageFile object.

Source code in datachain/lib/file.py

def as_image_file(self) -> "ImageFile":
    """Convert the file to a `ImageFile` object."""
    if isinstance(self, ImageFile):
        return self
    file = ImageFile(**self.model_dump())
    file._set_stream(self._catalog, caching_enabled=self._caching_enabled)
    return file

as_text_file

as_text_file() -> TextFile

Convert the file to a TextFile object.

Source code in datachain/lib/file.py

def as_text_file(self) -> "TextFile":
    """Convert the file to a `TextFile` object."""
    if isinstance(self, TextFile):
        return self
    file = TextFile(**self.model_dump())
    file._set_stream(self._catalog, caching_enabled=self._caching_enabled)
    return file

as_video_file

as_video_file() -> VideoFile

Convert the file to a VideoFile object.

Source code in datachain/lib/file.py

def as_video_file(self) -> "VideoFile":
    """Convert the file to a `VideoFile` object."""
    if isinstance(self, VideoFile):
        return self
    file = VideoFile(**self.model_dump())
    file._set_stream(self._catalog, caching_enabled=self._caching_enabled)
    return file

export

export(
    output: Union[str, PathLike[str]],
    placement: ExportPlacement = "fullpath",
    use_cache: bool = True,
    link_type: Literal["copy", "symlink"] = "copy",
    client_config: Optional[dict] = None,
) -> None

Export file to new location.

Source code in datachain/lib/file.py

def export(
    self,
    output: Union[str, os.PathLike[str]],
    placement: ExportPlacement = "fullpath",
    use_cache: bool = True,
    link_type: Literal["copy", "symlink"] = "copy",
    client_config: Optional[dict] = None,
) -> None:
    """Export file to new location."""
    self._caching_enabled = use_cache
    dst = self.get_destination_path(output, placement)
    dst_dir = os.path.dirname(dst)
    client: Client = self._catalog.get_client(dst_dir, **(client_config or {}))
    client.fs.makedirs(dst_dir, exist_ok=True)

    if link_type == "symlink":
        try:
            return self._symlink_to(dst)
        except OSError as exc:
            if exc.errno not in (errno.ENOTSUP, errno.EXDEV, errno.ENOSYS):
                raise

    self.save(dst, client_config=client_config)

get_destination_path

get_destination_path(
    output: Union[str, PathLike[str]],
    placement: ExportPlacement,
) -> str

Returns full destination path of a file for exporting to some output based on export placement

Source code in datachain/lib/file.py

def get_destination_path(
    self, output: Union[str, os.PathLike[str]], placement: ExportPlacement
) -> str:
    """
    Returns full destination path of a file for exporting to some output
    based on export placement
    """
    if placement == "filename":
        path = unquote(self.name)
    elif placement == "etag":
        path = f"{self.etag}{self.get_file_suffix()}"
    elif placement == "fullpath":
        path = unquote(self.get_full_name())
        source = urlparse(self.source)
        if source.scheme and source.scheme != "file":
            path = posixpath.join(source.netloc, path)
    elif placement == "checksum":
        raise NotImplementedError("Checksum placement not implemented yet")
    else:
        raise ValueError(f"Unsupported file export placement: {placement}")
    return posixpath.join(output, path)  # type: ignore[union-attr]

get_file_ext

get_file_ext()

Returns last part of file name without ..

Source code in datachain/lib/file.py

def get_file_ext(self):
    """Returns last part of file name without `.`."""
    return PurePosixPath(self.path).suffix.strip(".")

get_file_stem

get_file_stem()

Returns file name without extension.

Source code in datachain/lib/file.py

def get_file_stem(self):
    """Returns file name without extension."""
    return PurePosixPath(self.path).stem

get_file_suffix

get_file_suffix()

Returns last part of file name with ..

Source code in datachain/lib/file.py

def get_file_suffix(self):
    """Returns last part of file name with `.`."""
    return PurePosixPath(self.path).suffix

get_fs

get_fs()

Returns fsspec filesystem for the file.

Source code in datachain/lib/file.py

def get_fs(self):
    """Returns `fsspec` filesystem for the file."""
    return self._catalog.get_client(self.source).fs

get_full_name

get_full_name()

Returns name with parent directories.

Source code in datachain/lib/file.py

def get_full_name(self):
    """Returns name with parent directories."""
    return self.path

get_local_path

get_local_path() -> Optional[str]

Return path to a file in a local cache.

Returns None if file is not cached. Raises an exception if cache is not setup.

Source code in datachain/lib/file.py

def get_local_path(self) -> Optional[str]:
    """Return path to a file in a local cache.

    Returns None if file is not cached.
    Raises an exception if cache is not setup.
    """
    if self._catalog is None:
        raise RuntimeError(
            "cannot resolve local file path because catalog is not setup"
        )
    return self._catalog.cache.get_path(self)

get_path

get_path() -> str

Returns file path.

Source code in datachain/lib/file.py

def get_path(self) -> str:
    """Returns file path."""
    path = unquote(self.get_uri())
    source = urlparse(self.source)
    if source.scheme == "file":
        path = urlparse(path).path
        path = url2pathname(path)
    return path

get_uri

get_uri()

Returns file URI.

Source code in datachain/lib/file.py

def get_uri(self):
    """Returns file URI."""
    return f"{self.source}/{self.get_full_name()}"

open

open(mode: Literal['rb', 'r'] = 'rb') -> Iterator[Any]

Open the file and return a file object.

Source code in datachain/lib/file.py

@contextmanager
def open(self, mode: Literal["rb", "r"] = "rb") -> Iterator[Any]:
    """Open the file and return a file object."""
    if self.location:
        with VFileRegistry.open(self, self.location) as f:  # type: ignore[arg-type]
            yield f

    else:
        if self._caching_enabled:
            self.ensure_cached()
        client: Client = self._catalog.get_client(self.source)
        with client.open_object(
            self, use_cache=self._caching_enabled, cb=self._download_cb
        ) as f:
            yield io.TextIOWrapper(f) if mode == "r" else f

read

read(length: int = -1)

Returns file contents.

Source code in datachain/lib/file.py

def read(self, length: int = -1):
    """Returns file contents."""
    return self.read_bytes(length)

read_bytes

read_bytes(length: int = -1)

Returns file contents as bytes.

Source code in datachain/lib/file.py

def read_bytes(self, length: int = -1):
    """Returns file contents as bytes."""
    with self.open() as stream:
        return stream.read(length)

read_text

read_text()

Returns file contents as text.

Source code in datachain/lib/file.py

def read_text(self):
    """Returns file contents as text."""
    if self.location:
        raise VFileError(
            "Reading text from virtual file is not supported",
            self.source,
            self.path,
        )

    with self.open(mode="r") as stream:
        return stream.read()

resolve

resolve() -> Self

Resolve a File object by checking its existence and updating its metadata.

Returns:

• File ( Self ) –

  The resolved File object with updated metadata.

Source code in datachain/lib/file.py

def resolve(self) -> "Self":
    """
    Resolve a File object by checking its existence and updating its metadata.

    Returns:
        File: The resolved File object with updated metadata.
    """
    if self._catalog is None:
        raise RuntimeError("Cannot resolve file: catalog is not set")

    try:
        client = self._catalog.get_client(self.source)
    except NotImplementedError as e:
        raise RuntimeError(
            f"Unsupported protocol for file source: {self.source}"
        ) from e

    try:
        info = client.fs.info(client.get_full_path(self.path))
        converted_info = client.info_to_file(info, self.path)
        return type(self)(
            path=self.path,
            source=self.source,
            size=converted_info.size,
            etag=converted_info.etag,
            version=converted_info.version,
            is_latest=converted_info.is_latest,
            last_modified=converted_info.last_modified,
            location=self.location,
        )
    except (FileNotFoundError, PermissionError, OSError) as e:
        logger.warning("File system error when resolving %s: %s", self.path, str(e))

    return type(self)(
        path=self.path,
        source=self.source,
        size=0,
        etag="",
        version="",
        is_latest=True,
        last_modified=TIME_ZERO,
        location=self.location,
    )

save

save(
    destination: str, client_config: Optional[dict] = None
)

Writes it's content to destination

Source code in datachain/lib/file.py

def save(self, destination: str, client_config: Optional[dict] = None):
    """Writes it's content to destination"""
    destination = stringify_path(destination)
    client: Client = self._catalog.get_client(destination, **(client_config or {}))

    if client.PREFIX == "file://" and not destination.startswith(client.PREFIX):
        destination = Path(destination).absolute().as_uri()

    client.upload(self.read(), destination)

FileError

FileError(message: str, source: str, path: str)

Bases: DataChainError

Source code in datachain/lib/file.py

def __init__(self, message: str, source: str, path: str):
    self.message = message
    self.source = source
    self.path = path
    super().__init__(f"Error in file '{source}/{path}': {message}")

TarVFile

Bases: VFile

Virtual file model for files extracted from tar archives.

open classmethod

open(file: File, location: list[dict])

Stream file from tar archive based on location in archive.

Source code in datachain/lib/file.py

@classmethod
def open(cls, file: "File", location: list[dict]):
    """Stream file from tar archive based on location in archive."""
    tar_file = cls.parent(file, location)

    loc = location[0]

    if (offset := loc.get("offset", None)) is None:
        raise VFileError("'offset' is not specified", file.source, file.path)

    if (size := loc.get("size", None)) is None:
        raise VFileError("'size' is not specified", file.source, file.path)

    client = file._catalog.get_client(tar_file.source)
    fd = client.open_object(tar_file, use_cache=file._caching_enabled)
    return FileSlice(fd, offset, size, file.name)