# ttlcollections - Pure python collections with Time-to-live
`ttlcollections` is a pure Python implementation of a various data structures with built-in TTL (time to live) functionality, using nothing but the standard library.
As of now `ttlcollections` implements 2 data structures: a queue and a stack.
The difference between a stack and a queue is that the former follows the LIFO (Last-in First-out) scheme, while the latter follows the FIFO (First-in First out) scheme.
These 2 collections are implemented using `collections.deque` for fast `O(1)` complexity when accessing elements trough `pop`/`get` and `push`/`put`
### Example - TTLQueue
```python
from ttlcollections import TTLQueue
import time
q = TTLQueue(ttl=60) # Elements that are older than 60 seconds will be deleted
q.put(1)
time.sleep(60)
q.get() # Will raise ttlcollections.errors.QueueEmpty because the TTL for 1 has expired
:param ttl: If you want to override the default ttl
of the class for a specific element, you can specify
that, defaults to 0 (use the default TTL)
:param ttl: int, optional
:raises StackFull: If the stack is full
```
##### `TTLStack` - `pop()`
Pops an item from the stack, raising StackEmpty if the stack is empty
```
:raises StackEmpty: If the stack is empty
```
##### `TTLStack` - `expire()`
Pops expired element out of the stack if their TTL has expired by `when` units of time (usually seconds)
```
:param when: The expiry date to check items against.
Items' whose insertion date, according to self.timer, is less or equal than this number
will be automatically deleted
:type when: int
```
#### Notes
Please consider that the TTL expiration check is done at every mutating operation (e.g. `put` or `pop`) and that already expired elements may take space in memory until one of these methods is called.
You can force the TTL expiration check by calling the `expire` method. This method takes a single parameter and will delete all items in the collection that have expired the by the current time (according to the timer function) plus the specified amount of time units (usually seconds). For the current time you can use the collection's internal timer function (e.g. `TTLQueue.timer()`)