Metadata-Version: 2.4
Name: foyer-py
Version: 0.0.6
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries
License-File: LICENSE
Summary: Python bindings for the foyer Rust hybrid cache library.
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/icestreamlabs/foyer-py
Project-URL: Issues, https://github.com/icestreamlabs/foyer-py/issues
Project-URL: Repository, https://github.com/icestreamlabs/foyer-py

# foyer-py

Python bindings for the Rust [`foyer`](https://github.com/foyer-rs/foyer) hybrid cache library.

`foyer-py` is published on PyPI and imported as `foyer`.

## Current status

- Sync in-memory cache bindings are available.
- Sync hybrid cache bindings are available (internally uses Tokio).
- Native async APIs are available for both cache types.
- Keys: `bytes`, `str`, `int`.
- Values: `bytes`.

## Quick start

```python
import foyer

cache = foyer.Cache(16)
cache.insert("hello", b"world")

assert cache.get("hello") == b"world"
assert cache.contains("hello")
assert cache.entries == 1
```

### Hybrid cache (sync API)

```python
import tempfile
import foyer

with tempfile.TemporaryDirectory() as path:
    cache = foyer.HybridCache(path, memory_capacity=64 * 1024 * 1024, storage_capacity=256 * 1024 * 1024)
    cache.insert(42, b"The answer")
    assert cache.get(42) == b"The answer"
    cache.close()
```

### Async APIs

```python
import asyncio
import tempfile
import foyer


async def main() -> None:
    cache = foyer.AsyncCache(16)
    await cache.insert("hello", b"world")
    assert await cache.get("hello") == b"world"

    with tempfile.TemporaryDirectory() as path:
        hybrid = await foyer.AsyncHybridCache.create(path)
        await hybrid.insert(42, b"The answer")
        assert await hybrid.get(42) == b"The answer"
        await hybrid.close()


asyncio.run(main())
```

## Wheel coverage

GitHub Actions builds wheels for:

- Linux: `x86_64`, `aarch64` (manylinux)
- macOS: `universal2` (Intel + Apple Silicon)
- Windows: `x86_64`

Releases are published from tags matching `v*` (for example `v0.0.3`).

