Metadata-Version: 2.4
Name: dequedict
Version: 0.1.2
Summary: Fast ordered dict with deque-like operations at both ends
Author: sebastian
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typing_extensions>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"

# DequeDict

Ordered dictionary with O(1) deque operations at both ends.

## Features

- **O(1) key lookup** — like `dict`
- **O(1) pop/peek from both ends** — like `deque`
- **O(1) appendleft, move_to_end, delete by key**
- **Full typing support** with `.pyi` stubs

## Installation

```bash
pip install dequedict
```

## Usage

```python
from dequedict import DequeDict, DefaultDequeDict

dd = DequeDict([("a", 1), ("b", 2), ("c", 3)])

dd["d"] = 4              # Set
value = dd["a"]          # Get
del dd["b"]              # Delete

dd.peekleft()            # First value
dd.popleft()             # Remove first
dd.appendleft("z", 0)    # Insert at front
dd.move_to_end("a")      # Move to back

# DefaultDequeDict: auto-create values like defaultdict
groups = DefaultDequeDict(list)
groups["a"].append(1)
groups["a"].append(2)
```

## API

| Method | Description |
|--------|-------------|
| `peekleft()` / `peek()` | First/last value |
| `peekleftitem()` / `peekitem()` | First/last (key, value) |
| `popleft()` / `pop()` | Remove and return first/last |
| `popleftitem()` / `popitem()` | Remove and return first/last pair |
| `appendleft(key, value)` | Insert at front |
| `move_to_end(key, last=True)` | Move to front or back |
| `get`, `keys`, `values`, `items`, `clear`, `copy`, `update`, `setdefault` | Standard dict ops |

## Performance

Mac M1, Python 3.11, C extension:

| Operation | DequeDict | dict | deque | OrderedDict |
|-----------|-----------|------|-------|-------------|
| Key lookup | 32 ns | **23 ns** | O(n) | 24 ns |
| Peek left | **22 ns** | N/A | 23 ns | 59 ns |
| Peek right | **22 ns** | N/A | 23 ns | 70 ns |
| Pop left ×100 | 3.7 µs | N/A | **2.1 µs** | 7.7 µs |
| Delete by key ×100 | 4.3 µs | **2.8 µs** | O(n) | 6.0 µs |
| Insert ×100 | **6.6 µs** | 9.5 µs | N/A | 6.8 µs |

Pop is ~1.8x slower than deque due to dict maintenance, but provides O(1) key lookup.

## Benchmarks

```bash
python benchmarks/benchmark.py
```

## Tests

```bash
pip install pytest
python -m pytest tests/ -v
```

## License

MIT
