Skip to content

CacheProtocol

CacheProtocol 

CacheProtocol(
    directory: str | PathLike[str] | None = ...,
    disk_type: (
        type[DiskProtocol]
        | Callable[..., DiskProtocol]
        | None
    ) = ...,
    disk_args: Mapping[str, Any] | None = ...,
    **kwargs: Unpack[SettingsKwargs]
)

Bases: Protocol

Disk and file backed cache.

Parameters:

Name Type Description Default

directory

str | PathLike[str] | None

directory for cache

 ...

disk_type

type[DiskProtocol] | Callable[..., DiskProtocol] | None

DiskProtocol class or callable

 ...

disk_args

Mapping[str, Any] | None

keyword arguments for disk_type

 ...

**kwargs

Unpack[SettingsKwargs]

additional keyword arguments for Settings.

 {}
Source code in src/typed_diskcache/interface/cache.py 
51
52
53
54
55
56
57
def __init__(
    self,
    directory: str | PathLike[str] | None = ...,
    disk_type: type[DiskProtocol] | Callable[..., DiskProtocol] | None = ...,
    disk_args: Mapping[str, Any] | None = ...,
    **kwargs: Unpack[SettingsKwargs],
) -> None: ...

directory property 

directory: Path

Directory for cache.

timeout property 

timeout: float

Timeout for cache operations.

conn property 

conn: Connection

Database connection.

disk property 

disk: DiskProtocol

Disk object.

settings property 

settings: Settings

Settings for cache.

get 

get(
    key: Any, default: _AnyT, *, retry: bool = ...
) -> Container[Any | _AnyT]

get(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

get(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

Retrieve value from cache.

If key is missing, return container with default.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

default

Any

Value to return if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def get(self, key: Any, default: Any = ..., *, retry: bool = ...) -> Container[Any]:
    """Retrieve value from cache.

    If `key` is missing, return container with `default`.

    Args:
        key: Key for item.
        default: Value to return if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if key not found.
    """

aget async 

aget(
    key: Any, default: _AnyT, *, retry: bool = ...
) -> Container[Any | _AnyT]

aget(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

aget(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

Asynchronously retrieve value from cache.

If key is missing, return container with default.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

default

Any

Value to return if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
async def aget(
    self, key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]:
    """Asynchronously retrieve value from cache.

    If `key` is missing, return container with `default`.

    Args:
        key: Key for item.
        default: Value to return if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if key not found.
    """

set 

set(
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...
) -> bool

Set key and value in cache.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

value

Any

Value for item.

 required

expire

float | None

Seconds until item expires.

 ...

tags

str | Iterable[str] | None

Tags to associate with key.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if item was set.
Source code in src/typed_diskcache/interface/cache.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def set(
    self,
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...,
) -> bool:
    """Set `key` and `value` in cache.

    Args:
        key: Key for item.
        value: Value for item.
        expire: Seconds until item expires.
        tags: Tags to associate with key.
        retry: Retry if database timeout occurs.

    Returns:
        True if item was set.
    """

aset async 

aset(
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...
) -> bool

Asynchronously set key and value in cache.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

value

Any

Value for item.

 required

expire

float | None

Seconds until item expires.

 ...

tags

str | Iterable[str] | None

Tags to associate with key.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if item was set.
Source code in src/typed_diskcache/interface/cache.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
async def aset(
    self,
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...,
) -> bool:
    """Asynchronously set `key` and `value` in cache.

    Args:
        key: Key for item.
        value: Value for item.
        expire: Seconds until item expires.
        tags: Tags to associate with key.
        retry: Retry if database timeout occurs.

    Returns:
        True if item was set.
    """

delete 

delete(key: Any, *, retry: bool = ...) -> bool

Delete corresponding item for key from cache.

Missing keys are ignored.

Parameters:

Name Type Description Default

key

Any

Key matching item.

 required

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if item was deleted.
Source code in src/typed_diskcache/interface/cache.py 
179
180
181
182
183
184
185
186
187
188
189
190
def delete(self, key: Any, *, retry: bool = ...) -> bool:
    """Delete corresponding item for `key` from cache.

    Missing keys are ignored.

    Args:
        key: Key matching item.
        retry: Retry if database timeout occurs.

    Returns:
        True if item was deleted.
    """

adelete async 

adelete(key: Any, *, retry: bool = ...) -> bool

Asynchronously delete corresponding item for key from cache.

Missing keys are ignored.

Parameters:

Name Type Description Default

key

Any

Key matching item.

 required

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if item was deleted.
Source code in src/typed_diskcache/interface/cache.py 
192
193
194
195
196
197
198
199
200
201
202
203
async def adelete(self, key: Any, *, retry: bool = ...) -> bool:
    """Asynchronously delete corresponding item for `key` from cache.

    Missing keys are ignored.

    Args:
        key: Key matching item.
        retry: Retry if database timeout occurs.

    Returns:
        True if item was deleted.
    """

clear 

clear(*, retry: bool = ...) -> int

Remove all items from cache.

Removing items is iterative. Each iteration removes a subset of items. Concurrent writes may occur.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception.

Parameters:

Name Type Description Default

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Count of rows removed.
Source code in src/typed_diskcache/interface/cache.py 
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
def clear(self, *, retry: bool = ...) -> int:
    """Remove all items from cache.

    Removing items is iterative. Each iteration removes a subset of items.
    Concurrent writes may occur.

    If a [`TimeoutError`][] occurs, the first element of the exception's `args`
    attribute will be the number of items removed before the exception.

    Args:
        retry: Retry if database timeout occurs.

    Returns:
        Count of rows removed.
    """

aclear async 

aclear(*, retry: bool = ...) -> int

Asynchronously remove all items from cache.

Removing items is iterative. Each iteration removes a subset of items. Concurrent writes may occur.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception.

Parameters:

Name Type Description Default

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Count of rows removed.
Source code in src/typed_diskcache/interface/cache.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
async def aclear(self, *, retry: bool = ...) -> int:
    """Asynchronously remove all items from cache.

    Removing items is iterative. Each iteration removes a subset of items.
    Concurrent writes may occur.

    If a [`TimeoutError`][] occurs, the first element of the exception's `args`
    attribute will be the number of items removed before the exception.

    Args:
        retry: Retry if database timeout occurs.

    Returns:
        Count of rows removed.
    """

stats 

stats(*, enable: bool = ..., reset: bool = ...) -> Stats

Return cache statistics hits and misses.

Parameters:

Name Type Description Default

enable

bool

Enable collecting statistics.

 ...

reset

bool

Reset hits and misses to 0.

 ...

Returns:

Type Description
Stats

(hits, misses)
Source code in src/typed_diskcache/interface/cache.py 
237
238
239
240
241
242
243
244
245
246
def stats(self, *, enable: bool = ..., reset: bool = ...) -> Stats:
    """Return cache statistics hits and misses.

    Args:
        enable: Enable collecting statistics.
        reset: Reset hits and misses to 0.

    Returns:
        (hits, misses)
    """

astats async 

astats(*, enable: bool = ..., reset: bool = ...) -> Stats

Asynchronously return cache statistics hits and misses.

Parameters:

Name Type Description Default

enable

bool

Enable collecting statistics.

 ...

reset

bool

Reset hits and misses to 0.

 ...

Returns:

Type Description
Stats

(hits, misses)
Source code in src/typed_diskcache/interface/cache.py 
248
249
250
251
252
253
254
255
256
257
async def astats(self, *, enable: bool = ..., reset: bool = ...) -> Stats:
    """Asynchronously return cache statistics hits and misses.

    Args:
        enable: Enable collecting statistics.
        reset: Reset hits and misses to 0.

    Returns:
        (hits, misses)
    """

volume 

volume() -> int

Return estimated total size of cache on disk.

Returns:

Type Description
int

Size in bytes.
Source code in src/typed_diskcache/interface/cache.py 
259
260
261
262
263
264
def volume(self) -> int:
    """Return estimated total size of cache on disk.

    Returns:
        Size in bytes.
    """

avolume async 

avolume() -> int

Asynchronously return estimated total size of cache on disk.

Returns:

Type Description
int

Size in bytes.
Source code in src/typed_diskcache/interface/cache.py 
266
267
268
269
270
271
async def avolume(self) -> int:
    """Asynchronously return estimated total size of cache on disk.

    Returns:
        Size in bytes.
    """

close 

close() -> None

Close database connection.

Source code in src/typed_diskcache/interface/cache.py 
273
274
def close(self) -> None:
    """Close database connection."""

aclose async 

aclose() -> None

Asynchronously close database connection.

Source code in src/typed_diskcache/interface/cache.py 
276
277
async def aclose(self) -> None:
    """Asynchronously close database connection."""

touch 

touch(
    key: Any,
    *,
    expire: float | None = ...,
    retry: bool = ...
) -> bool

Touch key in cache and update expire time.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

expire

float | None

Seconds until item expires. If None, no expiry.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if key was touched.
Source code in src/typed_diskcache/interface/cache.py 
279
280
281
282
283
284
285
286
287
288
289
def touch(self, key: Any, *, expire: float | None = ..., retry: bool = ...) -> bool:
    """Touch `key` in cache and update `expire` time.

    Args:
        key: Key for item.
        expire: Seconds until item expires. If None, no expiry.
        retry: Retry if database timeout occurs.

    Returns:
        True if key was touched.
    """

atouch async 

atouch(
    key: Any,
    *,
    expire: float | None = ...,
    retry: bool = ...
) -> bool

Asynchronously touch key in cache and update expire time.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

expire

float | None

Seconds until item expires. If None, no expiry.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if key was touched.
Source code in src/typed_diskcache/interface/cache.py 
291
292
293
294
295
296
297
298
299
300
301
302
303
async def atouch(
    self, key: Any, *, expire: float | None = ..., retry: bool = ...
) -> bool:
    """Asynchronously touch `key` in cache and update `expire` time.

    Args:
        key: Key for item.
        expire: Seconds until item expires. If None, no expiry.
        retry: Retry if database timeout occurs.

    Returns:
        True if key was touched.
    """

add 

add(
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...
) -> bool

Add key and value item to cache.

Similar to set, but only add to cache if key not present.

Operation is atomic. Only one concurrent add operation for a given key will succeed.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

value

Any

Value for item.

 required

expire

float | None

Seconds until the key expires. If None, no expiry.

 ...

tags

str | Iterable[str] | None

Tags to associate with key.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if item was added.
Source code in src/typed_diskcache/interface/cache.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
def add(
    self,
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...,
) -> bool:
    """Add `key` and `value` item to cache.

    Similar to `set`, but only add to cache if key not present.

    Operation is atomic. Only one concurrent add operation for a given key
    will succeed.

    Args:
        key: Key for item.
        value: Value for item.
        expire: Seconds until the key expires. If None, no expiry.
        tags: Tags to associate with key.
        retry: Retry if database timeout occurs.

    Returns:
        True if item was added.
    """

aadd async 

aadd(
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...
) -> bool

Asynchronously add key and value item to cache.

Similar to set, but only add to cache if key not present.

Operation is atomic. Only one concurrent add operation for a given key will succeed.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

value

Any

Value for item.

 required

expire

float | None

Seconds until the key expires. If None, no expiry.

 ...

tags

str | Iterable[str] | None

Tags to associate with key.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
bool

True if item was added.
Source code in src/typed_diskcache/interface/cache.py 
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
async def aadd(
    self,
    key: Any,
    value: Any,
    *,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...,
) -> bool:
    """Asynchronously add `key` and `value` item to cache.

    Similar to `set`, but only add to cache if key not present.

    Operation is atomic. Only one concurrent add operation for a given key
    will succeed.

    Args:
        key: Key for item.
        value: Value for item.
        expire: Seconds until the key expires. If None, no expiry.
        tags: Tags to associate with key.
        retry: Retry if database timeout occurs.

    Returns:
        True if item was added.
    """

pop 

pop(
    key: Any, default: _AnyT, *, retry: bool = ...
) -> Container[Any | _AnyT]

pop(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

pop(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

Remove corresponding item for key from cache and return value.

If key is missing, return default.

Operation is atomic. Concurrent operations will be serialized.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

default

Any

Value to return if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
def pop(self, key: Any, default: Any = ..., *, retry: bool = ...) -> Container[Any]:
    """Remove corresponding item for `key` from cache and return value.

    If `key` is missing, return `default`.

    Operation is atomic. Concurrent operations will be serialized.

    Args:
        key: Key for item.
        default: Value to return if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if key not found.
    """

apop async 

apop(
    key: Any, default: _AnyT, *, retry: bool = ...
) -> Container[Any | _AnyT]

apop(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

apop(
    key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]

Asynchronously remove corresponding item for key from cache and return value.

If key is missing, return default.

Operation is atomic. Concurrent operations will be serialized.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

default

Any

Value to return if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
async def apop(
    self, key: Any, default: Any = ..., *, retry: bool = ...
) -> Container[Any]:
    """
    Asynchronously remove corresponding item for `key` from cache and return value.

    If `key` is missing, return `default`.

    Operation is atomic. Concurrent operations will be serialized.

    Args:
        key: Key for item.
        default: Value to return if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if key not found.
    """

filter 

filter(
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...
) -> Generator[Any, None, None]

Filter by tags.

Parameters:

Name Type Description Default

tags

str | Iterable[str]

Tags to filter by.

 required

method

FilterMethodLiteral | FilterMethod

'and' or 'or' filter method.

 ...

Yields:

Type Description
Any

Key of item matching tags.
Warning

This method is unstable and will be improved in the future.

Source code in src/typed_diskcache/interface/cache.py 
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
def filter(
    self,
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...,
) -> Generator[Any, None, None]:
    """Filter by tags.

    Args:
        tags: Tags to filter by.
        method: 'and' or 'or' filter method.

    Yields:
        Key of item matching tags.

    Warning:
        This method is unstable and will be improved in the future.
    """

afilter 

afilter(
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...
) -> AsyncGenerator[Any, None]

Asynchronously filter by tags.

Parameters:

Name Type Description Default

tags

str | Iterable[str]

Tags to filter by.

 required

method

FilterMethodLiteral | FilterMethod

'and' or 'or' filter method.

 ...

Yields:

Type Description
AsyncGenerator[Any, None]

Key of item matching tags.
Warning

This method is unstable and will be improved in the future.

Source code in src/typed_diskcache/interface/cache.py 
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
def afilter(
    self,
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...,
) -> AsyncGenerator[Any, None]:
    """Asynchronously filter by tags.

    Args:
        tags: Tags to filter by.
        method: 'and' or 'or' filter method.

    Yields:
        Key of item matching tags.

    Warning:
        This method is unstable and will be improved in the future.
    """
    ...  # pragma: no cover

incr 

incr(
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...
) -> int

Increment value by delta for item with key.

If key is missing and default is None then raise KeyError. Else if key is missing and default is not None then use default for value.

Operation is atomic. All concurrent increment operations will be counted individually.

Assumes value may be stored in a SQLite column. Most builds that target machines with 64-bit pointer widths will support 64-bit signed integers.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

delta

int

Amount to increment.

 ...

default

int | None

Value if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Incremented value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
def incr(
    self,
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...,
) -> int:
    """Increment value by delta for item with key.

    If key is missing and default is None then raise [`KeyError`][]. Else if key
    is missing and default is not None then use default for value.

    Operation is atomic. All concurrent increment operations will be
    counted individually.

    Assumes value may be stored in a SQLite column. Most builds that target
    machines with 64-bit pointer widths will support 64-bit signed integers.

    Args:
        key: Key for item.
        delta: Amount to increment.
        default: Value if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Incremented value or default if key not found.
    """

aincr async 

aincr(
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...
) -> int

Async increment value by delta for item with key.

If key is missing and default is None then raise [KeyError]. Else if key is missing and default is not None then use default for value.

Operation is atomic. All concurrent increment operations will be counted individually.

Assumes value may be stored in a SQLite column. Most builds that target machines with 64-bit pointer widths will support 64-bit signed integers.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

delta

int

Amount to increment.

 ...

default

int | None

Value if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Incremented value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
async def aincr(
    self,
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...,
) -> int:
    """Async increment value by delta for item with key.

    If key is missing and default is None then raise [`KeyError`]. Else if key
    is missing and default is not None then use default for value.

    Operation is atomic. All concurrent increment operations will be
    counted individually.

    Assumes value may be stored in a SQLite column. Most builds that target
    machines with 64-bit pointer widths will support 64-bit signed integers.

    Args:
        key: Key for item.
        delta: Amount to increment.
        default: Value if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Incremented value or default if key not found.
    """

decr 

decr(
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...
) -> int

Decrement value by delta for item with key.

If key is missing and default is None then raise KeyError. Else if key is missing and default is not None then use default for value.

Operation is atomic. All concurrent decrement operations will be counted individually.

Unlike Memcached, negative values are supported. Value may be decremented below zero.

Assumes value may be stored in a SQLite column. Most builds that target machines with 64-bit pointer widths will support 64-bit signed integers.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

delta

int

Amount to decrement.

 ...

default

int | None

Value if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Decremented value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
def decr(
    self,
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...,
) -> int:
    """Decrement value by delta for item with key.

    If key is missing and default is None then raise [`KeyError`][]. Else if key
    is missing and default is not None then use default for value.

    Operation is atomic. All concurrent decrement operations will be
    counted individually.

    Unlike Memcached, negative values are supported. Value may be
    decremented below zero.

    Assumes value may be stored in a SQLite column. Most builds that target
    machines with 64-bit pointer widths will support 64-bit signed integers.

    Args:
        key: Key for item.
        delta: Amount to decrement.
        default: Value if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Decremented value or default if key not found.
    """

adecr async 

adecr(
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...
) -> int

Async decrement value by delta for item with key.

If key is missing and default is None then raise KeyError. Else if key is missing and default is not None then use default for value.

Operation is atomic. All concurrent decrement operations will be counted individually.

Unlike Memcached, negative values are supported. Value may be decremented below zero.

Assumes value may be stored in a SQLite column. Most builds that target machines with 64-bit pointer widths will support 64-bit signed integers.

Parameters:

Name Type Description Default

key

Any

Key for item.

 required

delta

int

Amount to decrement.

 ...

default

int | None

Value if key is missing.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Decremented value or default if key not found.
Source code in src/typed_diskcache/interface/cache.py 
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
async def adecr(
    self,
    key: Any,
    delta: int = ...,
    default: int | None = ...,
    *,
    retry: bool = ...,
) -> int:
    """Async decrement value by delta for item with key.

    If key is missing and default is None then raise [`KeyError`][]. Else if key
    is missing and default is not None then use default for value.

    Operation is atomic. All concurrent decrement operations will be
    counted individually.

    Unlike Memcached, negative values are supported. Value may be
    decremented below zero.

    Assumes value may be stored in a SQLite column. Most builds that target
    machines with 64-bit pointer widths will support 64-bit signed integers.

    Args:
        key: Key for item.
        delta: Amount to decrement.
        default: Value if key is missing.
        retry: Retry if database timeout occurs.

    Returns:
        Decremented value or default if key not found.
    """

evict 

evict(
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...,
    retry: bool = False
) -> int

Remove items with matching tag from cache.

Removing items is an iterative process. In each iteration, a subset of items is removed. Concurrent writes may occur between iterations.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception occurred.

Parameters:

Name Type Description Default

tags

str | Iterable[str]

Tags identifying items.

 required

method

FilterMethodLiteral | FilterMethod

'and' or 'or' filter method.

 ...

retry

bool

Retry if database timeout occurs.

 False

Returns:

Type Description
int

Count of rows removed.
Source code in src/typed_diskcache/interface/cache.py 
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
def evict(
    self,
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...,
    retry: bool = False,
) -> int:
    """Remove items with matching `tag` from cache.

    Removing items is an iterative process. In each iteration, a subset of
    items is removed. Concurrent writes may occur between iterations.

    If a [`TimeoutError`][] occurs, the first element of the exception's
    `args` attribute will be the number of items removed before the
    exception occurred.

    Args:
        tags: Tags identifying items.
        method: 'and' or 'or' filter method.
        retry: Retry if database timeout occurs.

    Returns:
        Count of rows removed.
    """

aevict async 

aevict(
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...,
    retry: bool = False
) -> int

Async remove items with matching tag from cache.

Removing items is an iterative process. In each iteration, a subset of items is removed. Concurrent writes may occur between iterations.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception occurred.

Parameters:

Name Type Description Default

tags

str | Iterable[str]

Tags identifying items.

 required

method

FilterMethodLiteral | FilterMethod

'and' or 'or' filter method.

 ...

retry

bool

Retry if database timeout occurs.

 False

Returns:

Type Description
int

Count of rows removed.
Source code in src/typed_diskcache/interface/cache.py 
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
async def aevict(
    self,
    tags: str | Iterable[str],
    *,
    method: FilterMethodLiteral | FilterMethod = ...,
    retry: bool = False,
) -> int:
    """Async remove items with matching `tag` from cache.

    Removing items is an iterative process. In each iteration, a subset of
    items is removed. Concurrent writes may occur between iterations.

    If a [`TimeoutError`][] occurs, the first element of the exception's
    `args` attribute will be the number of items removed before the
    exception occurred.

    Args:
        tags: Tags identifying items.
        method: 'and' or 'or' filter method.
        retry: Retry if database timeout occurs.

    Returns:
        Count of rows removed.
    """

expire 

expire(
    now: float | None = ..., *, retry: bool = ...
) -> int

Remove expired items from cache.

Removing items is an iterative process. In each iteration, a subset of items is removed. Concurrent writes may occur between iterations.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception occurred.

Parameters:

Name Type Description Default

now

float | None

Current time. If None, use time.time().

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Count of items removed.
Source code in src/typed_diskcache/interface/cache.py 
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
def expire(self, now: float | None = ..., *, retry: bool = ...) -> int:
    """Remove expired items from cache.

    Removing items is an iterative process. In each iteration, a subset of
    items is removed. Concurrent writes may occur between iterations.

    If a [`TimeoutError`][] occurs, the first element of the exception's
    `args` attribute will be the number of items removed before the
    exception occurred.

    Args:
        now: Current time. If None, use [`time.time()`][time.time].
        retry: Retry if database timeout occurs.

    Returns:
        Count of items removed.
    """

aexpire async 

aexpire(
    now: float | None = ..., *, retry: bool = ...
) -> int

Async remove expired items from cache.

Removing items is an iterative process. In each iteration, a subset of items is removed. Concurrent writes may occur between iterations.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception occurred.

Parameters:

Name Type Description Default

now

float | None

Current time. If None, use time.time().

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Count of items removed.
Source code in src/typed_diskcache/interface/cache.py 
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
async def aexpire(self, now: float | None = ..., *, retry: bool = ...) -> int:
    """Async remove expired items from cache.

    Removing items is an iterative process. In each iteration, a subset of
    items is removed. Concurrent writes may occur between iterations.

    If a [`TimeoutError`][] occurs, the first element of the exception's
    `args` attribute will be the number of items removed before the
    exception occurred.

    Args:
        now: Current time. If None, use [`time.time()`][time.time].
        retry: Retry if database timeout occurs.

    Returns:
        Count of items removed.
    """

cull 

cull(*, retry: bool = ...) -> int

Cull items from cache until volume is less than size limit.

Removing items is an iterative process. In each iteration, a subset of items is removed. Concurrent writes may occur between iterations.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception occurred.

Parameters:

Name Type Description Default

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Count of items removed.
Source code in src/typed_diskcache/interface/cache.py 
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
def cull(self, *, retry: bool = ...) -> int:
    """Cull items from cache until volume is less than size limit.

    Removing items is an iterative process. In each iteration, a subset of
    items is removed. Concurrent writes may occur between iterations.

    If a [`TimeoutError`][] occurs, the first element of the exception's
    `args` attribute will be the number of items removed before the
    exception occurred.

    Args:
        retry: Retry if database timeout occurs.

    Returns:
        Count of items removed.
    """

acull async 

acull(*, retry: bool = ...) -> int

Async cull items from cache until volume is less than size limit.

Removing items is an iterative process. In each iteration, a subset of items is removed. Concurrent writes may occur between iterations.

If a TimeoutError occurs, the first element of the exception's args attribute will be the number of items removed before the exception occurred.

Parameters:

Name Type Description Default

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
int

Count of items removed.
Source code in src/typed_diskcache/interface/cache.py 
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
async def acull(self, *, retry: bool = ...) -> int:
    """Async cull items from cache until volume is less than size limit.

    Removing items is an iterative process. In each iteration, a subset of
    items is removed. Concurrent writes may occur between iterations.

    If a [`TimeoutError`][] occurs, the first element of the exception's
    `args` attribute will be the number of items removed before the
    exception occurred.

    Args:
        retry: Retry if database timeout occurs.

    Returns:
        Count of items removed.
    """

push 

push(
    value: Any,
    *,
    prefix: str | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...
) -> Any

Push value onto side of queue identified by prefix in cache.

When prefix is None, integer keys are used. Otherwise, string keys are used.

Operation is atomic. Concurrent operations will be serialized.

See also pull.

Parameters:

Name Type Description Default

value

Any

Value for item.

 required

prefix

str | None

Key prefix. If None, key is integer.

 ...

side

QueueSideLiteral | QueueSide

Either 'back' or 'front'.

 ...

expire

float | None

Seconds until the key expires. If None, no expiry.

 ...

tags

str | Iterable[str] | None

Tags to associate with key.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Any

Key of the pushed item.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import typed_diskcache


def main() -> None:
    cache = typed_diskcache.Cache()
    print(cache.push("first value"))
    # 500000000000000
    print(cache.get(500000000000000))
    # first value
    print(cache.push("second value"))
    # 500000000000001
    print(cache.push("third value", side="front"))
    # 499999999999999
    print(cache.push(1234, prefix="userids"))
    # userids-500000000000000
Source code in src/typed_diskcache/interface/cache.py 
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
def push(  # noqa: PLR0913
    self,
    value: Any,
    *,
    prefix: str | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...,
) -> Any:
    """Push `value` onto `side` of queue identified by `prefix` in cache.

    When prefix is None, integer keys are used. Otherwise, string keys are used.

    Operation is atomic. Concurrent operations will be serialized.

    See also [`pull`][typed_diskcache.interface.CacheProtocol.pull].

    Args:
        value: Value for item.
        prefix: Key prefix. If None, key is integer.
        side: Either 'back' or 'front'.
        expire: Seconds until the key expires. If None, no expiry.
        tags: Tags to associate with key.
        retry: Retry if database timeout occurs.

    Returns:
        Key of the pushed item.

    Examples:
        ```python
        import typed_diskcache


        def main() -> None:
            cache = typed_diskcache.Cache()
            print(cache.push("first value"))
            # 500000000000000
            print(cache.get(500000000000000))
            # first value
            print(cache.push("second value"))
            # 500000000000001
            print(cache.push("third value", side="front"))
            # 499999999999999
            print(cache.push(1234, prefix="userids"))
            # userids-500000000000000
        ```
    """

apush async 

apush(
    value: Any,
    *,
    prefix: str | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...
) -> Any

Async push value onto side of queue identified by prefix in cache.

When prefix is None, integer keys are used. Otherwise, string keys are used.

Operation is atomic. Concurrent operations will be serialized.

See also apull.

Parameters:

Name Type Description Default

value

Any

Value for item.

 required

prefix

str | None

Key prefix. If None, key is integer.

 ...

side

QueueSideLiteral | QueueSide

Either 'back' or 'front'.

 ...

expire

float | None

Seconds until the key expires. If None, no expiry.

 ...

tags

str | Iterable[str] | None

Tags to associate with key.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Any

Key of the pushed item.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import typed_diskcache


async def main() -> None:
    cache = typed_diskcache.Cache()
    print(await cache.apush("first value"))
    # 500000000000000
    print(await cache.aget(500000000000000))
    # first value
    print(await cache.apush("second value"))
    # 500000000000001
    print(await cache.apush("third value", side="front"))
    # 499999999999999
    print(await cache.apush(1234, prefix="userids"))
    # userids-500000000000000
Source code in src/typed_diskcache/interface/cache.py 
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
async def apush(  # noqa: PLR0913
    self,
    value: Any,
    *,
    prefix: str | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    expire: float | None = ...,
    tags: str | Iterable[str] | None = ...,
    retry: bool = ...,
) -> Any:
    """Async push `value` onto `side` of queue identified by `prefix` in cache.

    When prefix is None, integer keys are used. Otherwise, string keys are used.

    Operation is atomic. Concurrent operations will be serialized.

    See also [`apull`][typed_diskcache.interface.CacheProtocol.apull].

    Args:
        value: Value for item.
        prefix: Key prefix. If None, key is integer.
        side: Either 'back' or 'front'.
        expire: Seconds until the key expires. If None, no expiry.
        tags: Tags to associate with key.
        retry: Retry if database timeout occurs.

    Returns:
        Key of the pushed item.

    Examples:
        ```python
        import typed_diskcache


        async def main() -> None:
            cache = typed_diskcache.Cache()
            print(await cache.apush("first value"))
            # 500000000000000
            print(await cache.aget(500000000000000))
            # first value
            print(await cache.apush("second value"))
            # 500000000000001
            print(await cache.apush("third value", side="front"))
            # 499999999999999
            print(await cache.apush(1234, prefix="userids"))
            # userids-500000000000000
        ```
    """

pull 

pull(
    *,
    prefix: str | None = ...,
    default: None,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | None]

pull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, _AnyT],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | _AnyT]

pull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

pull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

pull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

Pull key and value item pair from side of queue in cache.

When prefix is None, integer keys are used. Otherwise, string keys are used.

If queue is empty, return default.

Operation is atomic. Concurrent operations will be serialized.

See also push and get.

Parameters:

Name Type Description Default

prefix

str | None

Key prefix. If None, key is integer.

 ...

default

tuple[Any, Any] | None

Value to return if key is missing.

 ...

side

QueueSideLiteral | QueueSide

Either 'back' or 'front'.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if queue is empty.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import typed_diskcache


def main() -> None:
    cache = typed_diskcache.Cache()
    print(cache.pull())
    # Container(default=True, expire_time=None, tags=None)
    for letter in "abc":
        print(cache.push(letter))
    # 500000000000000
    # 500000000000001
    # 500000000000002
    container = cache.pull()
    print(container.key)
    # 500000000000000
    print(container.value)
    # a
    container = cache.pull(side="back")
    print(container.value)
    # c
    print(cache.push(1234, prefix="userids"))
    # userids-500000000000000
    container = cache.pull(prefix="userids")
    print(container.value)
    # 1234
Source code in src/typed_diskcache/interface/cache.py 
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
def pull(
    self,
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...,
) -> Container[Any]:
    """Pull key and value item pair from `side` of queue in cache.

    When prefix is None, integer keys are used. Otherwise, string keys are used.

    If queue is empty, return default.

    Operation is atomic. Concurrent operations will be serialized.

    See also [`push`][typed_diskcache.interface.CacheProtocol.push]
    and [`get`][typed_diskcache.interface.CacheProtocol.get].

    Args:
        prefix: Key prefix. If None, key is integer.
        default: Value to return if key is missing.
        side: Either 'back' or 'front'.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if queue is empty.

    Examples:
        ```python
        import typed_diskcache


        def main() -> None:
            cache = typed_diskcache.Cache()
            print(cache.pull())
            # Container(default=True, expire_time=None, tags=None)
            for letter in "abc":
                print(cache.push(letter))
            # 500000000000000
            # 500000000000001
            # 500000000000002
            container = cache.pull()
            print(container.key)
            # 500000000000000
            print(container.value)
            # a
            container = cache.pull(side="back")
            print(container.value)
            # c
            print(cache.push(1234, prefix="userids"))
            # userids-500000000000000
            container = cache.pull(prefix="userids")
            print(container.value)
            # 1234
        ```
    """

apull async 

apull(
    *,
    prefix: str | None = ...,
    default: None,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | None]

apull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, _AnyT],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | _AnyT]

apull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

apull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

apull(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

Async pull key and value item pair from side of queue in cache.

When prefix is None, integer keys are used. Otherwise, string keys are used.

If queue is empty, return default.

Operation is atomic. Concurrent operations will be serialized.

See also apush and aget.

Parameters:

Name Type Description Default

prefix

str | None

Key prefix. If None, key is integer.

 ...

default

tuple[Any, Any] | None

Value to return if key is missing.

 ...

side

QueueSideLiteral | QueueSide

Either 'back' or 'front'.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if queue is empty.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import typed_diskcache


async def main() -> None:
    cache = typed_diskcache.Cache()
    print(await cache.apull())
    # Container(default=True, expire_time=None, tags=None)
    for letter in "abc":
        print(await cache.apush(letter))
    # 500000000000000
    # 500000000000001
    # 500000000000002
    container = await cache.apull()
    print(container.key)
    # 500000000000000
    print(container.value)
    # a
    container = await cache.apull(side="back")
    print(container.value)
    # c
    print(await cache.apush(1234, prefix="userids"))
    # userids-500000000000000
    container = await cache.apull(prefix="userids")
    print(container.value)
    # 1234
Source code in src/typed_diskcache/interface/cache.py 
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
async def apull(
    self,
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...,
) -> Container[Any]:
    """Async pull key and value item pair from `side` of queue in cache.

    When prefix is None, integer keys are used. Otherwise, string keys are used.

    If queue is empty, return default.

    Operation is atomic. Concurrent operations will be serialized.

    See also [`apush`][typed_diskcache.interface.CacheProtocol.apush]
    and [`aget`][typed_diskcache.interface.CacheProtocol.aget].

    Args:
        prefix: Key prefix. If None, key is integer.
        default: Value to return if key is missing.
        side: Either 'back' or 'front'.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if queue is empty.

    Examples:
        ```python
        import typed_diskcache


        async def main() -> None:
            cache = typed_diskcache.Cache()
            print(await cache.apull())
            # Container(default=True, expire_time=None, tags=None)
            for letter in "abc":
                print(await cache.apush(letter))
            # 500000000000000
            # 500000000000001
            # 500000000000002
            container = await cache.apull()
            print(container.key)
            # 500000000000000
            print(container.value)
            # a
            container = await cache.apull(side="back")
            print(container.value)
            # c
            print(await cache.apush(1234, prefix="userids"))
            # userids-500000000000000
            container = await cache.apull(prefix="userids")
            print(container.value)
            # 1234
        ```
    """

peek 

peek(
    *,
    prefix: str | None = ...,
    default: None,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | None]

peek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, _AnyT],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | _AnyT]

peek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

peek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

peek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

Peek at key and value item pair from side of queue in cache.

When prefix is None, integer keys are used. Otherwise, string keys are used.

If queue is empty, return default.

Expired items are deleted from cache. Operation is atomic. Concurrent operations will be serialized.

See also pull and push.

Parameters:

Name Type Description Default

prefix

str | None

Key prefix. If None, key is integer.

 ...

default

tuple[Any, Any] | None

Value to return if key is missing.

 ...

side

QueueSideLiteral | QueueSide

Either 'back' or 'front'.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if queue is empty.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import typed_diskcache


def main() -> None:
    cache = typed_diskcache.Cache()
    for letter in "abc":
        print(cache.push(letter))
    # 500000000000000
    # 500000000000001
    # 500000000000002
    container = cache.peek()
    print(container.key)
    # 500000000000002
    print(container.value)
    # c
    container = cache.peek(side="front")
    print(container.key)
    # 500000000000000
    print(container.value)
    # a
Source code in src/typed_diskcache/interface/cache.py 
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
def peek(
    self,
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...,
) -> Container[Any]:
    """Peek at key and value item pair from `side` of queue in cache.

    When prefix is None, integer keys are used. Otherwise, string keys are used.

    If queue is empty, return default.

    Expired items are deleted from cache. Operation is atomic. Concurrent
    operations will be serialized.

    See also [`pull`][typed_diskcache.interface.CacheProtocol.pull]
    and [`push`][typed_diskcache.interface.CacheProtocol.push].

    Args:
        prefix: Key prefix. If None, key is integer.
        default: Value to return if key is missing.
        side: Either 'back' or 'front'.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if queue is empty.

    Examples:
        ```python
        import typed_diskcache


        def main() -> None:
            cache = typed_diskcache.Cache()
            for letter in "abc":
                print(cache.push(letter))
            # 500000000000000
            # 500000000000001
            # 500000000000002
            container = cache.peek()
            print(container.key)
            # 500000000000002
            print(container.value)
            # c
            container = cache.peek(side="front")
            print(container.key)
            # 500000000000000
            print(container.value)
            # a
        ```
    """

apeek async 

apeek(
    *,
    prefix: str | None = ...,
    default: None,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | None]

apeek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, _AnyT],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any | _AnyT]

apeek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any],
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

apeek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

apeek(
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...
) -> Container[Any]

Async peek at key and value item pair from side of queue in cache.

When prefix is None, integer keys are used. Otherwise, string keys are used.

If queue is empty, return default.

Expired items are deleted from cache. Operation is atomic. Concurrent operations will be serialized.

See also apull and apush.

Parameters:

Name Type Description Default

prefix

str | None

Key prefix. If None, key is integer.

 ...

default

tuple[Any, Any] | None

Value to return if key is missing.

 ...

side

QueueSideLiteral | QueueSide

Either 'back' or 'front'.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value or default if queue is empty.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import typed_diskcache


async def main() -> None:
    cache = typed_diskcache.Cache()
    for letter in "abc":
        print(await cache.apush(letter))
    # 500000000000000
    # 500000000000001
    # 500000000000002
    container = await cache.apeek()
    print(container.key)
    # 500000000000002
    print(container.value)
    # c
    container = await cache.apeek(side="front")
    print(container.key)
    # 500000000000000
    print(container.value)
    # a
Source code in src/typed_diskcache/interface/cache.py 
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
async def apeek(
    self,
    *,
    prefix: str | None = ...,
    default: tuple[Any, Any] | None = ...,
    side: QueueSideLiteral | QueueSide = ...,
    retry: bool = ...,
) -> Container[Any]:
    """Async peek at key and value item pair from `side` of queue in cache.

    When prefix is None, integer keys are used. Otherwise, string keys are used.

    If queue is empty, return default.

    Expired items are deleted from cache. Operation is atomic. Concurrent
    operations will be serialized.

    See also [`apull`][typed_diskcache.interface.CacheProtocol.apull]
    and [`apush`][typed_diskcache.interface.CacheProtocol.apush].

    Args:
        prefix: Key prefix. If None, key is integer.
        default: Value to return if key is missing.
        side: Either 'back' or 'front'.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value or default if queue is empty.

    Examples:
        ```python
        import typed_diskcache


        async def main() -> None:
            cache = typed_diskcache.Cache()
            for letter in "abc":
                print(await cache.apush(letter))
            # 500000000000000
            # 500000000000001
            # 500000000000002
            container = await cache.apeek()
            print(container.key)
            # 500000000000002
            print(container.value)
            # c
            container = await cache.apeek(side="front")
            print(container.key)
            # 500000000000000
            print(container.value)
            # a
        ```
    """

peekitem 

peekitem(
    *, last: bool = ..., retry: bool = ...
) -> Container[Any]

Peek at key and value item pair in cache based on iteration order.

Expired items are deleted from cache. Operation is atomic. Concurrent operations will be serialized.

Parameters:

Name Type Description Default

last

bool

Last item in iteration order.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import typed_diskcache


def main() -> None:
    cache = typed_diskcache.Cache()
    for num, letter in enumerate("abc"):
        cache[letter] = num
    container = cache.peekitem()
    print(container.key, container.value)
    # ('c', 2)
    container = cache.peekitem(last=False)
    print(container.key, container.value)
    # ('a', 0)
Source code in src/typed_diskcache/interface/cache.py 
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
def peekitem(self, *, last: bool = ..., retry: bool = ...) -> Container[Any]:
    """Peek at key and value item pair in cache based on iteration order.

    Expired items are deleted from cache. Operation is atomic. Concurrent
    operations will be serialized.

    Args:
        last: Last item in iteration order.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value.

    Examples:
        ```python
        import typed_diskcache


        def main() -> None:
            cache = typed_diskcache.Cache()
            for num, letter in enumerate("abc"):
                cache[letter] = num
            container = cache.peekitem()
            print(container.key, container.value)
            # ('c', 2)
            container = cache.peekitem(last=False)
            print(container.key, container.value)
            # ('a', 0)
        ```
    """

apeekitem async 

apeekitem(
    *, last: bool = ..., retry: bool = ...
) -> Container[Any]

Async peek at key and value item pair in cache based on iteration order.

Expired items are deleted from cache. Operation is atomic. Concurrent operations will be serialized.

Parameters:

Name Type Description Default

last

bool

Last item in iteration order.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
Container[Any]

Container with cached value.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
import typed_diskcache


async def main() -> None:
    cache = typed_diskcache.Cache()
    for num, letter in enumerate("abc"):
        cache[letter] = num
    container = await cache.apeekitem()
    print(container.key, container.value)
    # ('c', 2)
    container = await cache.apeekitem(last=False)
    print(container.key, container.value)
    # ('a', 0)
Source code in src/typed_diskcache/interface/cache.py 
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
async def apeekitem(self, *, last: bool = ..., retry: bool = ...) -> Container[Any]:
    """Async peek at key and value item pair in cache based on iteration order.

    Expired items are deleted from cache. Operation is atomic. Concurrent
    operations will be serialized.

    Args:
        last: Last item in iteration order.
        retry: Retry if database timeout occurs.

    Returns:
        Container with cached value.

    Examples:
        ```python
        import typed_diskcache


        async def main() -> None:
            cache = typed_diskcache.Cache()
            for num, letter in enumerate("abc"):
                cache[letter] = num
            container = await cache.apeekitem()
            print(container.key, container.value)
            # ('c', 2)
            container = await cache.apeekitem(last=False)
            print(container.key, container.value)
            # ('a', 0)
        ```
    """

check 

check(
    *, fix: bool = ..., retry: bool = ...
) -> list[WarningMessage]

Check database and file system consistency.

Intended for use in testing and post-mortem error analysis.

While checking the Cache table for consistency, a writer lock is held on the database. The lock blocks other cache clients from writing to the database. For caches with many file references, the lock may be held for a long time. For example, local benchmarking shows that a cache with 1,000 file references takes ~60ms to check.

Parameters:

Name Type Description Default

fix

bool

Correct inconsistencies.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
list[WarningMessage]

List of warnings.
Source code in src/typed_diskcache/interface/cache.py 
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
def check(
    self, *, fix: bool = ..., retry: bool = ...
) -> list[warnings.WarningMessage]:
    """Check database and file system consistency.

    Intended for use in testing and post-mortem error analysis.

    While checking the Cache table for consistency, a writer lock is held
    on the database. The lock blocks other cache clients from writing to
    the database. For caches with many file references, the lock may be
    held for a long time. For example, local benchmarking shows that a
    cache with 1,000 file references takes ~60ms to check.

    Args:
        fix: Correct inconsistencies.
        retry: Retry if database timeout occurs.

    Returns:
        List of warnings.
    """

acheck async 

acheck(
    *, fix: bool = ..., retry: bool = ...
) -> list[WarningMessage]

Async check database and file system consistency.

Intended for use in testing and post-mortem error analysis.

While checking the Cache table for consistency, a writer lock is held on the database. The lock blocks other cache clients from writing to the database. For caches with many file references, the lock may be held for a long time. For example, local benchmarking shows that a cache with 1,000 file references takes ~60ms to check.

Parameters:

Name Type Description Default

fix

bool

Correct inconsistencies.

 ...

retry

bool

Retry if database timeout occurs.

 ...

Returns:

Type Description
list[WarningMessage]

List of warnings.
Source code in src/typed_diskcache/interface/cache.py 
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
async def acheck(
    self, *, fix: bool = ..., retry: bool = ...
) -> list[warnings.WarningMessage]:
    """Async check database and file system consistency.

    Intended for use in testing and post-mortem error analysis.

    While checking the Cache table for consistency, a writer lock is held
    on the database. The lock blocks other cache clients from writing to
    the database. For caches with many file references, the lock may be
    held for a long time. For example, local benchmarking shows that a
    cache with 1,000 file references takes ~60ms to check.

    Args:
        fix: Correct inconsistencies.
        retry: Retry if database timeout occurs.

    Returns:
        List of warnings.
    """

iterkeys 

iterkeys(
    *, reverse: bool = ...
) -> Generator[Any, None, None]

Iterate Cache keys in database sort order.

Parameters:

Name Type Description Default

reverse

bool

Reverse sort order.

 ...

Yields:

Type Description
Any

Key of item.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import typed_diskcache


def main() -> None:
    cache = typed_diskcache.Cache()
    for key in [4, 1, 3, 0, 2]:
        cache[key] = key
    print(list(cache.iterkeys()))
    # [0, 1, 2, 3, 4]
    print(list(cache.iterkeys(reverse=True)))
    # [4, 3, 2, 1, 0]
Source code in src/typed_diskcache/interface/cache.py 
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
def iterkeys(self, *, reverse: bool = ...) -> Generator[Any, None, None]:
    """Iterate Cache keys in database sort order.

    Args:
        reverse: Reverse sort order.

    Yields:
        Key of item.

    Examples:
        ```python
        import typed_diskcache


        def main() -> None:
            cache = typed_diskcache.Cache()
            for key in [4, 1, 3, 0, 2]:
                cache[key] = key
            print(list(cache.iterkeys()))
            # [0, 1, 2, 3, 4]
            print(list(cache.iterkeys(reverse=True)))
            # [4, 3, 2, 1, 0]
        ```
    """

aiterkeys 

aiterkeys(
    *, reverse: bool = ...
) -> AsyncGenerator[Any, None]

Async iterate Cache keys in database sort order.

Parameters:

Name Type Description Default

reverse

bool

Reverse sort order.

 ...

Yields:

Type Description
AsyncGenerator[Any, None]

Key of item.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import typed_diskcache


async def main() -> None:
    cache = typed_diskcache.Cache()
    for key in [4, 1, 3, 0, 2]:
        cache[key] = key
    print([x async for x in cache.aiterkeys()])
    # [0, 1, 2, 3, 4]
    print([x async for x in cache.aiterkeys(reverse=True)])
    # [4, 3, 2, 1, 0]
Source code in src/typed_diskcache/interface/cache.py 
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
def aiterkeys(self, *, reverse: bool = ...) -> AsyncGenerator[Any, None]:
    """Async iterate Cache keys in database sort order.

    Args:
        reverse: Reverse sort order.

    Yields:
        Key of item.

    Examples:
        ```python
        import typed_diskcache


        async def main() -> None:
            cache = typed_diskcache.Cache()
            for key in [4, 1, 3, 0, 2]:
                cache[key] = key
            print([x async for x in cache.aiterkeys()])
            # [0, 1, 2, 3, 4]
            print([x async for x in cache.aiterkeys(reverse=True)])
            # [4, 3, 2, 1, 0]
        ```
    """
    ...  # pragma: no cover

update_settings 

update_settings(
    settings: Settings | SettingsKwargs | None = ...,
    **kwargs: Unpack[SettingsKwargs]
) -> None

Update cache settings.

Parameters:

Name Type Description Default

settings

Settings | SettingsKwargs | None

New settings.

 ...

**kwargs

Unpack[SettingsKwargs]

Additional settings.

 {}
Source code in src/typed_diskcache/interface/cache.py 
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
def update_settings(
    self,
    settings: Settings | SettingsKwargs | None = ...,
    **kwargs: Unpack[SettingsKwargs],
) -> None:
    """Update cache settings.

    Args:
        settings: New settings.
        **kwargs: Additional settings.
    """

aupdate_settings async 

aupdate_settings(
    settings: Settings | SettingsKwargs | None = ...,
    **kwargs: Unpack[SettingsKwargs]
) -> None

Async update cache settings.

Asynchronous version of update_settings.

Parameters:

Name Type Description Default

settings

Settings | SettingsKwargs | None

New settings.

 ...

**kwargs

Unpack[SettingsKwargs]

Additional settings.

 {}
Source code in src/typed_diskcache/interface/cache.py 
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
async def aupdate_settings(
    self,
    settings: Settings | SettingsKwargs | None = ...,
    **kwargs: Unpack[SettingsKwargs],
) -> None:
    """Async update cache settings.

    Asynchronous version of
    [`update_settings`][typed_diskcache.interface.CacheProtocol.update_settings].

    Args:
        settings: New settings.
        **kwargs: Additional settings.
    """