DiskProtocol

DiskProtocol

DiskProtocol(directory: str | PathLike[str], **kwargs: Any)

Bases: Protocol

Cache key and value serialization for SQLite database and files.

Parameters:

Name	Type	Description	Default
directory	str | PathLike[str]	directory for cache	required
**kwargs	Any	additional keyword arguments. These arguments may not be used directly in this class, but are added to prevent errors in inherited classes.	{}

Source code in src/typed_diskcache/interface/disk.py

def __init__(self, directory: str | PathLike[str], **kwargs: Any) -> None: ...

directory property writable

directory: Path

Return the directory for the cache.

hash

hash(key: Any) -> int

Return the hash value for key.

Parameters:

Name	Type	Description	Default
key	Any	key to hash	required

Returns:

Type	Description
int	hash value

Source code in src/typed_diskcache/interface/disk.py

def hash(self, key: Any) -> int:
    """Return the hash value for `key`.

    Args:
        key: key to hash

    Returns:
        hash value
    """

put

put(key: Any) -> tuple[Any, bool]

Convert key to a format suitable for storage in the Cache table.

This method takes a key and converts it into a database-compatible key and a boolean indicating whether the key is in its raw form.

Parameters:

Name	Type	Description	Default
key	Any	The key to convert.	required

Returns:

Type	Description
tuple[Any, bool]	(database key, raw boolean) pair

Source code in src/typed_diskcache/interface/disk.py

def put(self, key: Any) -> tuple[Any, bool]:
    """Convert `key` to a format suitable for storage in the Cache table.

    This method takes a key and converts it into a database-compatible key
    and a boolean indicating whether the key is in its raw form.

    Args:
        key: The key to convert.

    Returns:
        (database key, raw boolean) pair
    """

get

get(key: Any, *, raw: bool) -> Any

Convert fields key and raw from Cache table to a Python key.

This method takes a database key and a flag indicating if the key is stored in its raw form, and converts them back to the corresponding Python key.

Parameters:

Name	Type	Description	Default
key	Any	The database key to convert.	required
raw	bool	A flag indicating if the key is stored in its raw form.	required

Returns:

Type	Description
Any	The corresponding Python key.

Source code in src/typed_diskcache/interface/disk.py

def get(self, key: Any, *, raw: bool) -> Any:
    """Convert fields `key` and `raw` from Cache table to a Python key.

    This method takes a database key and a flag indicating if the key is stored
    in its raw form, and converts them back to the corresponding Python key.

    Args:
        key: The database key to convert.
        raw: A flag indicating if the key is stored in its raw form.

    Returns:
        The corresponding Python key.
    """

prepare

prepare(value: Any, *, key: Any = ...) -> Path | None

Prepare filename and full-path tuple for file storage.

This method takes a value and an optional key, and prepares a full path for storing the file.

Parameters:

Name	Type	Description	Default
value	Any	The value to store.	required
key	Any	The key for the item (optional).	...

Returns:

Type	Description
Path | None	A full path, or None if preparation fails.

Source code in src/typed_diskcache/interface/disk.py

def prepare(self, value: Any, *, key: Any = ...) -> Path | None:
    """Prepare filename and full-path tuple for file storage.

    This method takes a value and an optional key, and prepares
    a full path for storing the file.

    Args:
        value: The value to store.
        key: The key for the item (optional).

    Returns:
        A full path, or None if preparation fails.
    """

store

store(
    value: Any,
    *,
    key: Any = ...,
    filepath: Path | None = ...
) -> tuple[int, CacheMode, str | None, bytes | None]

Convert value to fields for Cache table.

This method converts a value into a tuple containing the size, mode, filename, and value suitable for storage in the Cache table.

Parameters:

Name	Type	Description	Default
value	Any	The value to store.	required
key	Any	The key for the item.	...
filepath	Path | None	The full path for the file.	...

Returns:

Type	Description
tuple[int, CacheMode, str | None, bytes | None]	(size, mode, filename, value) tuple for Cache table

Source code in src/typed_diskcache/interface/disk.py

def store(
    self, value: Any, *, key: Any = ..., filepath: Path | None = ...
) -> tuple[int, CacheMode, str | None, bytes | None]:
    """Convert `value` to fields for Cache table.

    This method converts a value into a tuple containing the size, mode,
    filename, and value suitable for storage in the Cache table.

    Args:
        value: The value to store.
        key: The key for the item.
        filepath: The full path for the file.

    Returns:
        (size, mode, filename, value) tuple for Cache table
    """

astore async

astore(
    value: Any,
    *,
    key: Any = ...,
    filepath: Path | None = ...
) -> tuple[int, CacheMode, str | None, bytes | None]

Asynchronously convert value to fields for Cache table.

This method is the asynchronous version of store. It converts a value into a tuple containing the size, mode, filename, and value suitable for storage in the Cache table.

Parameters:

Name	Type	Description	Default
value	Any	The value to store.	required
key	Any	The key for the item.	...
filepath	Path | None	The full path for the file.	...

Returns:

Type	Description
tuple[int, CacheMode, str | None, bytes | None]	(size, mode, filename, value) tuple for Cache table

Source code in src/typed_diskcache/interface/disk.py

async def astore(
    self, value: Any, *, key: Any = ..., filepath: Path | None = ...
) -> tuple[int, CacheMode, str | None, bytes | None]:
    """Asynchronously convert `value` to fields for Cache table.

    This method is the asynchronous version of
    [`store`][typed_diskcache.interface.disk.DiskProtocol.store].
    It converts a value into a tuple containing the size, mode, filename, and value
    suitable for storage in the Cache table.

    Args:
        value: The value to store.
        key: The key for the item.
        filepath: The full path for the file.

    Returns:
        (size, mode, filename, value) tuple for Cache table
    """

fetch

fetch(
    *,
    mode: CacheMode,
    filename: str | PathLike[str] | None,
    value: Any
) -> Any

Convert fields from Cache table to a Python value.

This method converts the fields mode, filename, and value from the Cache table back to the corresponding Python value.

Parameters:

Name	Type	Description	Default
mode	CacheMode	The mode of the value (none, binary, text, or pickle).	required
filename	str | PathLike[str] | None	The filename of the corresponding value.	required
value	Any	The database value.	required

Returns:

Type	Description
Any	The corresponding Python value.

Source code in src/typed_diskcache/interface/disk.py

def fetch(
    self, *, mode: CacheMode, filename: str | PathLike[str] | None, value: Any
) -> Any:
    """Convert fields from Cache table to a Python value.

    This method converts the fields `mode`, `filename`, and `value` from the Cache
    table back to the corresponding Python value.

    Args:
        mode: The mode of the value (none, binary, text, or pickle).
        filename: The filename of the corresponding value.
        value: The database value.

    Returns:
        The corresponding Python value.
    """

afetch async

afetch(
    *,
    mode: CacheMode,
    filename: str | PathLike[str] | None,
    value: Any
) -> Any

Asynchronously convert fields from Cache table to a Python value.

This method is the asynchronous version of fetch. It converts the fields mode, filename, and value from the Cache table back to the corresponding Python value.

Parameters:

Name	Type	Description	Default
mode	CacheMode	The mode of the value (none, binary, text, or pickle).	required
filename	str | PathLike[str] | None	The filename of the corresponding value.	required
value	Any	The database value.	required

Returns:

Type	Description
Any	The corresponding Python value.

Source code in src/typed_diskcache/interface/disk.py

async def afetch(
    self, *, mode: CacheMode, filename: str | PathLike[str] | None, value: Any
) -> Any:
    """Asynchronously convert fields from Cache table to a Python value.

    This method is the asynchronous version of
    [`fetch`][typed_diskcache.interface.disk.DiskProtocol.fetch].
    It converts the fields `mode`, `filename`, and `value`
    from the Cache table back to the corresponding Python value.

    Args:
        mode: The mode of the value (none, binary, text, or pickle).
        filename: The filename of the corresponding value.
        value: The database value.

    Returns:
        The corresponding Python value.
    """

remove

remove(file_path: str | PathLike[str]) -> None

Remove a file given by file_path.

This method is cross-thread and cross-process safe. If an OSError occurs, it is suppressed.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike[str]	The relative path to the file.	required

Source code in src/typed_diskcache/interface/disk.py

def remove(self, file_path: str | PathLike[str]) -> None:
    """Remove a file given by `file_path`.

    This method is cross-thread and cross-process safe. If an OSError occurs,
    it is suppressed.

    Args:
        file_path: The relative path to the file.
    """

aremove async

aremove(file_path: str | PathLike[str]) -> None

Asynchronously remove a file given by file_path.

This method is the asynchronous version of remove. It is cross-thread and cross-process safe. If an OSError occurs, it is suppressed.

Parameters:

Name	Type	Description	Default
file_path	str | PathLike[str]	The relative path to the file.	required

Source code in src/typed_diskcache/interface/disk.py

async def aremove(self, file_path: str | PathLike[str]) -> None:
    """Asynchronously remove a file given by `file_path`.

    This method is the asynchronous version of
    [`remove`][typed_diskcache.interface.disk.DiskProtocol.remove].
    It is cross-thread and cross-process safe.
    If an OSError occurs, it is suppressed.

    Args:
        file_path: The relative path to the file.
    """

filename

filename(key: Any = ..., value: Any = ...) -> Path

Return full-path for file storage.

Filename will be a randomly generated 28 character hexadecimal string with ".val" suffixed. Two levels of sub-directories will be used to reduce the size of directories. On older filesystems, lookups in directories with many files may be slow.

The default implementation ignores the key and value parameters.

Parameters:

Name	Type	Description	Default
key	Any	key for item.	...
value	Any	value for item.	...

Returns:

Type	Description
Path	full-path

Source code in src/typed_diskcache/interface/disk.py

def filename(self, key: Any = ..., value: Any = ...) -> Path:
    """Return full-path for file storage.

    Filename will be a randomly generated 28 character hexadecimal string
    with ".val" suffixed. Two levels of sub-directories will be used to
    reduce the size of directories. On older filesystems, lookups in
    directories with many files may be slow.

    The default implementation ignores the `key` and `value` parameters.

    Args:
        key: key for item.
        value: value for item.

    Returns:
        full-path
    """

model_dump

model_dump() -> tuple[str, dict[str, Any]]

Return the model name and model state.

This method returns a tuple containing the model name and a dictionary representing the model state.

Returns:

Type	Description
tuple[str, dict[str, Any]]	(model name, model state) tuple

Source code in src/typed_diskcache/interface/disk.py

def model_dump(self) -> tuple[str, dict[str, Any]]:
    """Return the model name and model state.

    This method returns a tuple containing the model name and a dictionary
    representing the model state.

    Returns:
        (model name, model state) tuple
    """