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
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.
storage.put(("users", "alice", "name"), "Alice")
value = storage.get(("users", "alice", "name"))
Layer 2: Container
Hierarchy and parent-child relationships over flat keys.
container = Container(storage, ("users", "alice"))
container.create()
children = container.children() # ["name", "age"]
Layer 3: View
Data structure abstractions (dict, list, set) over containers.
users = DictView.open_root(tx)
users["alice"] = "data"
Installation
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
Documentation
See docs/ for detailed documentation:
docs/layers/layer1_storage.md— Storage layerdocs/layers/layer2_container.md— Container layerdocs/layers/layer3_view.md— View layerdocs/general/architecture.md— Architecture overviewdocs/general/philosophy.md— Design philosophy
License
Apache-2.0
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file virtuals_py-0.1.2.tar.gz.
File metadata
- Download URL: virtuals_py-0.1.2.tar.gz
- Upload date:
- Size: 167.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
293db7f87273acc1c976f0ccef04775524dc01b55576e2333974274a5c4cebe4
|
|
| MD5 |
a9e1025456d2036792fcbc013fb8083a
|
|
| BLAKE2b-256 |
dabf4e246803b9bd8838a1f87006cd81d9dc3318248bdff55d4886c6b4b9769b
|
Provenance
The following attestation bundles were made for virtuals_py-0.1.2.tar.gz:
Publisher:
publish-py.yml on nustackdev/virtuals
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
virtuals_py-0.1.2.tar.gz -
Subject digest:
293db7f87273acc1c976f0ccef04775524dc01b55576e2333974274a5c4cebe4 - Sigstore transparency entry: 2349318484
- Sigstore integration time:
-
Permalink:
nustackdev/virtuals@36029118a75ca3acda7ea57bac1dc2a713b13d0e -
Branch / Tag:
refs/tags/py-v0.1.2 - Owner: https://github.com/nustackdev
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-py.yml@36029118a75ca3acda7ea57bac1dc2a713b13d0e -
Trigger Event:
push
-
Statement type:
File details
Details for the file virtuals_py-0.1.2-py3-none-any.whl.
File metadata
- Download URL: virtuals_py-0.1.2-py3-none-any.whl
- Upload date:
- Size: 239.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
86f2e748c97a38ff36953a023d16a852fb6bc6f81dd5007369d80be470668fc3
|
|
| MD5 |
b1e5e1eff496e4f622fb2ac076ef04c2
|
|
| BLAKE2b-256 |
3f812e9d181865292900fba5fb39e11d7df9ffdbf3faf95f580d80ddf347c736
|
Provenance
The following attestation bundles were made for virtuals_py-0.1.2-py3-none-any.whl:
Publisher:
publish-py.yml on nustackdev/virtuals
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
virtuals_py-0.1.2-py3-none-any.whl -
Subject digest:
86f2e748c97a38ff36953a023d16a852fb6bc6f81dd5007369d80be470668fc3 - Sigstore transparency entry: 2349318919
- Sigstore integration time:
-
Permalink:
nustackdev/virtuals@36029118a75ca3acda7ea57bac1dc2a713b13d0e -
Branch / Tag:
refs/tags/py-v0.1.2 - Owner: https://github.com/nustackdev
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-py.yml@36029118a75ca3acda7ea57bac1dc2a713b13d0e -
Trigger Event:
push
-
Statement type:
