Metadata-Version: 2.4
Name: virtuals-py
Version: 0.1.4
Summary: Virtual Python collections over any storage.
Author-email: Gor Arakelyan <gorarkln@gmail.com>
Maintainer-email: Gor Arakelyan <gorarkln@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/nustackdev/virtuals
Project-URL: Documentation, https://github.com/nustackdev/virtuals#readme
Project-URL: Repository, https://github.com/nustackdev/virtuals
Project-URL: Issues, https://github.com/nustackdev/virtuals/issues
Project-URL: Changelog, https://github.com/nustackdev/virtuals/releases
Keywords: key-value,kv,storage,views,polymorphic,data-structures,dict,list,set,database,persistence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: attrs
Requires-Dist: virtuals-binary-codec
Requires-Dist: kh57
Requires-Dist: typing-extensions>=4.7.0
Provides-Extra: rocksdb
Requires-Dist: rdbpython; extra == "rocksdb"
Provides-Extra: lmdb
Requires-Dist: lmdb; extra == "lmdb"
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Requires-Dist: msgpack>=1.0; extra == "redis"
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "test"
Requires-Dist: hypothesis>=6.0.0; extra == "test"
Provides-Extra: all
Requires-Dist: virtuals-py[dev,test]; extra == "all"
Dynamic: license-file

# Virtuals

Virtual Python collections over any storage.

Dict, list, set, indexed dict, tree — they look and feel like native Python, but they don't physically exist as in-memory collections. They're virtual: lazy views that compose data structure logic over flat tuple-key storage. Any backend that implements the storage protocol gets every data structure for free.

Like SQLAlchemy for Python collections. No SQL, no specific backend. Define your structure, plug in a store.

PyPI: `virtuals-py` | Import: `virtuals`

## What It Does

```python
from virtuals import View, Container
from virtuals.storages.mem import InMemoryStorage
from virtuals.codecs import NoOpCodec

storage = InMemoryStorage(codec=NoOpCodec())
storage.open()

with storage.transaction() as tx:
    users = DictView.open_root(tx)
    users["alice"] = {"name": "Alice", "age": 30}
    users["bob"] = {"name": "Bob", "age": 25}

    # Navigate naturally
    for user_id, profile in users.items():
        print(f"{user_id}: {profile['name']}")

# Under the hood: flat KV pairs with tuple keys
# ("users", "alice", "name") -> "Alice"
# ("users", "alice", "age")  -> 30
```

## Three Layers

### Layer 1: Storage
Generic tuple-key KV store with lexicographic ordering.

```python
storage.put(("users", "alice", "name"), "Alice")
value = storage.get(("users", "alice", "name"))
```

### Layer 2: Container
Hierarchy and parent-child relationships over flat keys.

```python
container = Container(storage, ("users", "alice"))
container.create()
children = container.children()  # ["name", "age"]
```

### Layer 3: View
Data structure abstractions (dict, list, set) over containers.

```python
users = DictView.open_root(tx)
users["alice"] = "data"
```

## Installation

```bash
pip install virtuals-py
pip install virtuals-py[rocksdb]  # with RocksDB backend
```

## Features

- **Virtual collections**: Work with dicts, lists, sets over any KV backend
- **Tuple keys**: Natural hierarchical addressing with lexicographic ordering
- **Backend agnostic**: Works with any ordered KV store (RocksDB, LMDB, in-memory)
- **Observable**: Watch for changes at any level of the hierarchy
- **Transactional**: Full ACID support when the backend provides it
- **Lazy**: Nothing materializes until accessed

## License

Apache-2.0
