Class Files

mkdocs/structure/files.py:62–178

A collection of [File][mkdocs.structure.files.File] objects.

class Files:
    """A collection of [File][mkdocs.structure.files.File] objects."""

    def __init__(self, files: Iterable[File]) -> None:
        self._src_uris = {f.src_uri: f for f in files}

    def __iter__(self) -> Iterator[File]:
        """Iterate over the files within."""
        return iter(self._src_uris.values())

    def __len__(self) -> int:
        """The number of files within."""
        return len(self._src_uris)

    def __contains__(self, path: str) -> bool:
        """Soft-deprecated, prefer `get_file_from_path(path) is not None`."""
        return PurePath(path).as_posix() in self._src_uris

    @property
    def src_paths(self) -> dict[str, File]:
        """Soft-deprecated, prefer `src_uris`."""
        return {file.src_path: file for file in self}

    @property
    def src_uris(self) -> Mapping[str, File]:
        """
        A mapping containing every file, with the keys being their
        [`src_uri`][mkdocs.structure.files.File.src_uri].
        """
        return self._src_uris

    def get_file_from_path(self, path: str) -> File | None:
        """Return a File instance with File.src_uri equal to path."""
        return self._src_uris.get(PurePath(path).as_posix())

    def append(self, file: File) -> None:
        """Add file to the Files collection."""
        if file.src_uri in self._src_uris:
            warnings.warn(
                "To replace an existing file, call `remove` before `append`.", DeprecationWarning
            )
            del self._src_uris[file.src_uri]
        self._src_uris[file.src_uri] = file

    def remove(self, file: File) -> None:
        """Remove file from Files collection."""
        try:
            del self._src_uris[file.src_uri]
        except KeyError:
            raise ValueError(f'{file.src_uri!r} not in collection')

    def copy_static_files(
        self,
        dirty: bool = False,
        *,
        inclusion: Callable[[InclusionLevel], bool] = InclusionLevel.is_included,
    ) -> None:
        """Copy static files from source to destination."""