Skip to content

Deque

Deque deprecated 

Deque(
    values: Iterable[_T] | None = None,
    maxlen: float | None = None,
    *,
    directory: str | PathLike[str] | None = None,
    **kwargs: Unpack[SettingsKwargs]
)

Bases: MutableSequence[_T], Generic[_T]

Deprecated

Deque is deprecated and not maintained.

Persistent sequence with double-ended queue semantics.

Double-ended queue is an ordered collection with optimized access at its endpoints.

Items are serialized to disk. Deque may be initialized from directory path where items are stored.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += range(5)
    print(list(deque))
    # [0, 1, 2, 3, 4]
    for value in range(5):
        deque.appendleft(-value)
    print(len(deque))
    # 10
    print(list(deque))
    # [-4, -3, -2, -1, 0, 0, 1, 2, 3, 4]
    print(deque.pop())
    # 4
    print(deque.popleft())
    # -4
    deque.reverse()
    print(list(deque))
    # [3, 2, 1, 0, 0, -1, -2, -3]

Double-ended queue is an ordered collection with optimized access at its endpoints.

Items are serialized to disk. Deque may be initialized from directory path where items are stored.

Parameters:

Name Type Description Default

values

Iterable[_T] | None

Values to initialize deque. Defaults to None.

 None

maxlen

float | None

Maximum length of deque. Defaults to None (infinite).

 None

directory

str | PathLike[str] | None

Directory path to store items. Defaults to None.

 None

**kwargs

Unpack[SettingsKwargs]

additional keyword arguments for Settings.

 {}
Source code in src/typed_diskcache/utils/deque.py 
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def __init__(
    self,
    values: Iterable[_T] | None = None,
    maxlen: float | None = None,
    *,
    directory: str | PathLike[str] | None = None,
    **kwargs: Unpack[SettingsKwargs],
) -> None:
    """Persistent sequence with double-ended queue semantics.

    Double-ended queue is an ordered collection with optimized access at its
    endpoints.

    Items are serialized to disk. Deque may be initialized from directory path
    where items are stored.

    Args:
        values: Values to initialize deque. Defaults to None.
        maxlen: Maximum length of deque. Defaults to None (infinite).
        directory: Directory path to store items. Defaults to None.
        **kwargs: additional keyword arguments for
            [`Settings`][typed_diskcache.model.Settings].
    """
    eviction_policy = kwargs.pop("eviction_policy", EvictionPolicy.NONE)
    if eviction_policy != EvictionPolicy.NONE:
        warnings.warn(
            "Deque eviction policy must be none",
            te.TypedDiskcacheWarning,
            stacklevel=2,
        )

    kwargs["eviction_policy"] = EvictionPolicy.NONE
    self._cache = Cache(directory=directory, **kwargs)
    self._maxlen = float("inf") if maxlen is None else maxlen
    super().extend(values or [])

cache property 

cache: Cache

Cache object for deque.

maxlen property 

maxlen: float

Maximum length of deque.

append 

append(value: _T) -> None

Add value to back of deque.

Parameters:

Name Type Description Default

value

_T

Value to add to back of deque.

 required

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.append("a")
    deque.append("b")
    deque.append("c")
    print(list(deque))
    # ['a', 'b', 'c']
Source code in src/typed_diskcache/utils/deque.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
@context
@override
def append(self, value: _T) -> None:
    """Add `value` to back of deque.

    Args:
        value: Value to add to back of deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.append("a")
            deque.append("b")
            deque.append("c")
            print(list(deque))
            # ['a', 'b', 'c']
        ```
    """
    with self.cache.conn.session() as session:
        with transact(session):
            with self._cache.conn.enter_session(session) as context:
                context.run(self.cache.push, value, side="back", retry=True)
                if len(self.cache) > self._maxlen:
                    context.run(self.popleft)

appendleft 

appendleft(value: _T) -> None

Add value to front of deque.

Parameters:

Name Type Description Default

value

_T

Value to add to front of deque.

 required

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.appendleft("a")
    deque.appendleft("b")
    deque.appendleft("c")
    list(deque)
    # ['c', 'b', 'a']
Source code in src/typed_diskcache/utils/deque.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
@context
def appendleft(self, value: _T) -> None:
    """Add `value` to front of deque.

    Args:
        value: Value to add to front of deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.appendleft("a")
            deque.appendleft("b")
            deque.appendleft("c")
            list(deque)
            # ['c', 'b', 'a']
        ```
    """
    with self.cache.conn.session() as session:
        with transact(session):
            with self._cache.conn.enter_session(session) as context:
                context.run(self.cache.push, value, side="front", retry=True)
                if len(self.cache) > self._maxlen:
                    context.run(self.pop)

copy 

copy() -> Self

Copy deque with same directory and max length.

Source code in src/typed_diskcache/utils/deque.py 
174
175
176
177
178
179
def copy(self) -> Self:
    """Copy deque with same directory and max length."""
    new = object.__new__(type(self))
    new._cache = self.cache  # noqa: SLF001
    new._maxlen = self.maxlen  # noqa: SLF001
    return new

count 

count(value: _T) -> int

Return number of occurrences of value in deque.

Parameters:

Name Type Description Default

value

_T

Value to count in deque.

 required

Returns:

Type Description
int

Count of items equal to value in deque.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += [num for num in range(1, 5) for _ in range(num)]
    print(deque.count(0))
    # 0
    print(deque.count(1))
    # 1
    print(deque.count(4))
    # 4
Source code in src/typed_diskcache/utils/deque.py 
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
@override
def count(self, value: _T) -> int:
    """Return number of occurrences of `value` in deque.

    Args:
        value: Value to count in deque.

    Returns:
        Count of items equal to value in deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque += [num for num in range(1, 5) for _ in range(num)]
            print(deque.count(0))
            # 0
            print(deque.count(1))
            # 1
            print(deque.count(4))
            # 4
        ```
    """
    return sum(1 for item in self if item == value)

extend 

extend(values: Iterable[_T]) -> None

Extend back side of deque with values from iterable.

Parameters:

Name Type Description Default

values

Iterable[_T]

Iterable of values to append to deque.

 required

Examples:

1
2
3
4
5
6
7
8
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.extend("abc")
    print(list(deque))
    # ['a', 'b', 'c']
Source code in src/typed_diskcache/utils/deque.py 
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
@context
@override
def extend(self, values: Iterable[_T]) -> None:
    """Extend back side of deque with values from `iterable`.

    Args:
        values: Iterable of values to append to deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.extend("abc")
            print(list(deque))
            # ['a', 'b', 'c']
        ```
    """
    for value in values:
        self.append(value)

extendleft 

extendleft(values: Iterable[_T]) -> None

Extend front side of deque with values from iterable.

Parameters:

Name Type Description Default

values

Iterable[_T]

Iterable of values to append to deque.

 required

Examples:

1
2
3
4
5
6
7
8
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.extendleft("abc")
    print(list(deque))
    # ['c', 'b', 'a']
Source code in src/typed_diskcache/utils/deque.py 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
@context
def extendleft(self, values: Iterable[_T]) -> None:
    """Extend front side of deque with values from `iterable`.

    Args:
        values: Iterable of values to append to deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.extendleft("abc")
            print(list(deque))
            # ['c', 'b', 'a']
        ```
    """
    for value in values:
        self.appendleft(value)

pop 

pop() -> _T

Remove and return value at back of deque.

Returns:

Type Description
_T

Value at back of deque.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += "ab"
    print(deque.pop())
    # 'b'
    print(deque.pop())
    # 'a'
    deque.pop()
    # Traceback (most recent call last):
    #     ...
    # IndexError: pop from an empty deque
Source code in src/typed_diskcache/utils/deque.py 
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
@override
def pop(self) -> _T:  # pyright: ignore[reportIncompatibleMethodOverride]
    """Remove and return value at back of deque.

    Returns:
        Value at back of deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque += "ab"
            print(deque.pop())
            # 'b'
            print(deque.pop())
            # 'a'
            deque.pop()
            # Traceback (most recent call last):
            #     ...
            # IndexError: pop from an empty deque
        ```
    """
    container = self.cache.pull(side="back", retry=True)
    if container.default:
        raise te.TypedDiskcacheIndexError("pop from an empty deque")
    return container.value

popleft 

popleft() -> _T

Remove and return value at front of deque.

Returns:

Type Description
_T

Value at front of deque.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += "ab"
    print(deque.popleft())
    # 'a'
    print(deque.popleft())
    # 'b'
    deque.popleft()
    # Traceback (most recent call last):
    #     ...
    # IndexError: pop from an empty deque
Source code in src/typed_diskcache/utils/deque.py 
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
def popleft(self) -> _T:
    """Remove and return value at front of deque.

    Returns:
        Value at front of deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque += "ab"
            print(deque.popleft())
            # 'a'
            print(deque.popleft())
            # 'b'
            deque.popleft()
            # Traceback (most recent call last):
            #     ...
            # IndexError: pop from an empty deque
        ```
    """
    container = self.cache.pull(side="front", retry=True)
    if container.default:
        raise te.TypedDiskcacheIndexError("pop from an empty deque")
    return container.value

remove 

remove(value: _T) -> None

Remove first occurrence of value in deque.

Parameters:

Name Type Description Default

value

_T

Value to remove.

 required

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += "aab"
    deque.remove("a")
    print(list(deque))
    # ['a', 'b']
    deque.remove("b")
    print(list(deque))
    # ['a']
    deque.remove("c")
    # Traceback (most recent call last):
    #     ...
    # ValueError: deque.remove(value): value not in deque
Source code in src/typed_diskcache/utils/deque.py 
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
@override
def remove(self, value: _T) -> None:
    """Remove first occurrence of `value` in deque.

    Args:
        value: Value to remove.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque += "aab"
            deque.remove("a")
            print(list(deque))
            # ['a', 'b']
            deque.remove("b")
            print(list(deque))
            # ['a']
            deque.remove("c")
            # Traceback (most recent call last):
            #     ...
            # ValueError: deque.remove(value): value not in deque
        ```
    """
    for key in self.cache.iterkeys():
        with suppress(KeyError):
            item = self.cache[key]
            if not item.default and value == item.value:
                del self.cache[key]
                return

    raise te.TypedDiskcacheValueError("deque.remove(value): value not in deque")

rotate 

rotate(steps: int = 1) -> None

Rotate deque right by steps.

If steps is negative then rotate left.

Parameters:

Name Type Description Default

steps

int

Number of steps to rotate. Defaults to 1.

 1

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += range(5)
    deque.rotate(2)
    print(list(deque))
    # [3, 4, 0, 1, 2]
    deque.rotate(-1)
    print(list(deque))
    # [4, 0, 1, 2, 3]
Source code in src/typed_diskcache/utils/deque.py 
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
def rotate(self, steps: int = 1) -> None:
    """Rotate deque right by `steps`.

    If steps is negative then rotate left.

    Args:
        steps: Number of steps to rotate. Defaults to 1.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque += range(5)
            deque.rotate(2)
            print(list(deque))
            # [3, 4, 0, 1, 2]
            deque.rotate(-1)
            print(list(deque))
            # [4, 0, 1, 2, 3]
        ```
    """
    size = len(self)
    if not size:
        return

    if steps >= 0:
        steps %= size
        for _ in range(steps):
            try:
                value = self.pop()
            except IndexError:
                return
            self.appendleft(value)

        return

    steps *= -1
    steps %= size
    for _ in range(steps):
        try:
            value = self.popleft()
        except IndexError:
            return
        self.append(value)

reverse 

reverse() -> None

Reverse deque in place.

Examples:

1
2
3
4
5
6
7
8
9
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque += "abc"
    deque.reverse()
    list(deque)
    # ['c', 'b', 'a']
Source code in src/typed_diskcache/utils/deque.py 
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
@override
def reverse(self) -> None:
    """Reverse deque in place.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque += "abc"
            deque.reverse()
            list(deque)
            # ['c', 'b', 'a']
        ```
    """
    temp = Deque(reversed(self), maxlen=self.maxlen)
    self.clear()
    self.extend(temp)
    temp._cache.close()
    temp_directory = temp._cache.directory
    del temp
    shutil.rmtree(temp_directory)

clear 

clear() -> None

Remove all elements from deque.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque("abc")
    print(len(deque))
    # 3
    deque.clear()
    print(list(deque))
    # []
Source code in src/typed_diskcache/utils/deque.py 
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
@override
def clear(self) -> None:
    """Remove all elements from deque.

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque("abc")
            print(len(deque))
            # 3
            deque.clear()
            print(list(deque))
            # []
        ```
    """
    self.cache.clear(retry=True)

__len__ 

__len__() -> int

deque.len() <==> len(deque)

Returns:

Type Description
int

length of deque
Source code in src/typed_diskcache/utils/deque.py 
482
483
484
485
486
487
488
489
@override
def __len__(self) -> int:
    """deque.__len__() <==> len(deque)

    Returns:
        length of deque
    """
    return len(self.cache)

__getitem__ 

__getitem__(key: SupportsIndex) -> _T

deque.getitem(index) <==> deque[index]

Return corresponding item for index in deque.

Parameters:

Name Type Description Default

key

SupportsIndex

index of item

 required

Returns:

Type Description
_T

corresponding item

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.extend("abcde")
    deque[1]
    # 'b'
    deque[-2]
    # 'd'
Source code in src/typed_diskcache/utils/deque.py 
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
@override
def __getitem__(self, key: SupportsIndex) -> _T:  # pyright: ignore[reportIncompatibleMethodOverride]
    """deque.__getitem__(index) <==> deque[index]

    Return corresponding item for `index` in deque.

    Args:
        key: index of item

    Returns:
        corresponding item

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.extend("abcde")
            deque[1]
            # 'b'
            deque[-2]
            # 'd'
        ```
    """
    return _index_deque(self, self.cache, key, partial(_get_item, self.cache))

__setitem__ 

__setitem__(key: SupportsIndex, value: _T) -> None

deque.setitem(index, value) <==> deque[index] = value

Store value in deque at index.

Parameters:

Name Type Description Default

key

SupportsIndex

index of item

 required

value

_T

value to store

 required

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.extend([None] * 3)
    deque[0] = "a"
    deque[1] = "b"
    deque[-1] = "c"
    print("".join(deque))
    # 'abc'
Source code in src/typed_diskcache/utils/deque.py 
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
@override
def __setitem__(self, key: SupportsIndex, value: _T) -> None:  # pyright: ignore[reportIncompatibleMethodOverride]
    """deque.__setitem__(index, value) <==> deque[index] = value

    Store `value` in deque at `index`.

    Args:
        key: index of item
        value: value to store

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.extend([None] * 3)
            deque[0] = "a"
            deque[1] = "b"
            deque[-1] = "c"
            print("".join(deque))
            # 'abc'
        ```
    """
    set_value = partial(self.cache.__setitem__, value=value)
    _index_deque(self, self.cache, key, set_value)

__delitem__ 

__delitem__(key: SupportsIndex) -> None

deque.delitem(index) <==> del deque[index]

Delete item in deque at index.

Parameters:

Name Type Description Default

key

SupportsIndex

index of item

 required

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.extend([None] * 3)
    del deque[0]
    del deque[1]
    del deque[-1]
    print(len(deque))
    # 0
Source code in src/typed_diskcache/utils/deque.py 
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
@override
def __delitem__(self, key: SupportsIndex) -> None:  # pyright: ignore[reportIncompatibleMethodOverride]
    """deque.__delitem__(index) <==> del deque[index]

    Delete item in deque at `index`.

    Args:
        key: index of item

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.extend([None] * 3)
            del deque[0]
            del deque[1]
            del deque[-1]
            print(len(deque))
            # 0
        ```
    """
    _index_deque(self, self.cache, key, self.cache.__delitem__)

__iadd__ 

__iadd__(values: Iterable[_T]) -> Self

deque.iadd(iterable) <==> deque += iterable

Extend back side of deque with items from iterable.

Parameters:

Name Type Description Default

values

Iterable[_T]

iterable of items to append to deque

 required

Returns:

Type Description
Self

deque with added items
Source code in src/typed_diskcache/utils/deque.py 
583
584
585
586
587
588
589
590
591
592
593
594
595
596
@override
def __iadd__(self, values: Iterable[_T]) -> Self:
    """deque.__iadd__(iterable) <==> deque += iterable

    Extend back side of deque with items from iterable.

    Args:
        values: iterable of items to append to deque

    Returns:
        deque with added items
    """
    self.extend(values)
    return self

__iter__ 

__iter__() -> Iterator[_T]

deque.iter() <==> iter(deque)

Yields:

Type Description
_T

item in deque from front to back
Source code in src/typed_diskcache/utils/deque.py 
598
599
600
601
602
603
604
605
606
607
608
@override
def __iter__(self) -> Iterator[_T]:
    """deque.__iter__() <==> iter(deque)

    Yields:
        item in deque from front to back
    """
    for key in self.cache.iterkeys():
        with suppress(KeyError):
            container = self.cache[key]
            yield container.value

__reversed__ 

__reversed__() -> Iterator[_T]

deque.reversed() <==> reversed(deque)

Yields:

Type Description
_T

item in deque from back to front

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from typed_diskcache.utils.deque import Deque


def main() -> None:
    deque = Deque()
    deque.extend("abcd")
    iterator = reversed(deque)
    print(next(iterator))
    # 'd'
    print(list(iterator))
    # ['c', 'b', 'a']
Source code in src/typed_diskcache/utils/deque.py 
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
@override
def __reversed__(self) -> Iterator[_T]:
    """deque.__reversed__() <==> reversed(deque)

    Yields:
        item in deque from back to front

    Examples:
        ```python
        from typed_diskcache.utils.deque import Deque


        def main() -> None:
            deque = Deque()
            deque.extend("abcd")
            iterator = reversed(deque)
            print(next(iterator))
            # 'd'
            print(list(iterator))
            # ['c', 'b', 'a']
        ```
    """
    for key in self.cache.iterkeys(reverse=True):
        with suppress(KeyError):
            container = self.cache[key]
            yield container.value

__repr__ 

__repr__() -> str

deque.repr() <==> repr(deque)

Returns:

Type Description
str

string representation of deque
Source code in src/typed_diskcache/utils/deque.py 
687
688
689
690
691
692
693
694
@override
def __repr__(self) -> str:
    """deque.__repr__() <==> repr(deque)

    Returns:
        string representation of deque
    """
    return f"{type(self).__name__}(maxlen={self.maxlen})"