| Name | yellowdb JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | A high-performance LSM-tree based key-value database written in Python |
| upload_time | 2025-10-24 21:07:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2025 Arshia Ahmadzadeh
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
database
key-value
lsm-tree
storage
in-memory
performance
embedded
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# YellowDB
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/astral-sh/ruff)
A high-performance **Log-Structured Merge-tree (LSM-tree) based key-value database** written in Python. YellowDB is designed for write-heavy workloads with excellent read performance, combining the benefits of in-memory speed with persistent on-disk storage.
```python
from yellowdb import YellowDB
# Create a database
db = YellowDB(data_directory="./my_database")
# Store data
db.set("user:1", b"Alice")
value = db.get("user:1") # Returns: b"Alice"
# Clean up
db.close()
```
## ✨ Key Features
- **LSM-tree Architecture**: Optimized for write-heavy workloads with fast sequential writes
- **Write-Ahead Logging (WAL)**: ACID-like durability guarantees with crash recovery
- **Concurrent Operations**: Thread-safe operations with support for concurrent reads and writes
- **Automatic Compaction**: Background compaction optimizes storage and read performance
- **Caching Layer**: Built-in write-through cache for frequently accessed data
- **Bloom Filters**: Efficient key lookups without unnecessary disk I/O
- **Batch Operations**: Atomic multi-key operations for consistency
- **Range Queries**: Efficient range scans and iterators over sorted keys
- **Configuration**: Flexible configuration for tuning memory, cache, and compaction behavior
## 🚀 Quick Start
### Installation
```bash
pip install yellowdb
```
### Basic Usage
```python
from yellowdb import YellowDB
# Create and use a database
with YellowDB(data_directory="./my_database") as db:
# Write operations
db.set("key", b"value")
# Read operations
value = db.get("key")
print(value) # b"value"
# Delete operations
db.delete("key")
# Range queries
for key, value in db.range("start_key", "end_key"):
print(f"{key}: {value}")
# Full database scan
for key, value in db.scan():
print(f"{key}: {value}")
```
## 📚 Core Concepts
### LSM-Tree Architecture
YellowDB implements the Log-Structured Merge-tree (LSM-tree) data structure, which:
1. **Writes** are initially buffered in an in-memory structure (memtable)
2. **Write-Ahead Log (WAL)** ensures durability before acknowledgment
3. When memtables reach capacity, they're **flushed to disk as SSTables** (Sorted String Tables)
4. **Compaction** periodically merges SSTables, removing deleted entries and optimizing the tree structure
This design provides:
- Fast writes (appending to log)
- Efficient reads (cached data + tree structure)
- Automatic storage optimization (compaction)
### Components
| Component | Purpose |
|-----------|---------|
| **Memtable** | In-memory sorted buffer for pending writes |
| **SSTable** | Immutable on-disk sorted file containing key-value pairs |
| **WAL** | Write-Ahead Log for crash recovery and durability |
| **Compactor** | Background process managing SSTable merging |
| **Bloom Filter** | Probabilistic data structure for fast key lookups |
| **Cache** | Write-through cache for frequently accessed entries |
## 💻 Usage Examples
### Basic CRUD Operations
```python
from yellowdb import YellowDB
db = YellowDB(data_directory="./my_db")
# Create/Update
db.set("user:100", b'{"name": "Alice", "age": 30}')
# Read
user_data = db.get("user:100")
if user_data:
print(user_data.decode())
# Delete
db.delete("user:100")
db.close()
```
### Batch Operations
Perform multiple operations atomically:
```python
from yellowdb import YellowDB, Batch
db = YellowDB()
# Execute multiple operations in a single batch
with Batch(db) as batch:
batch.put("user:1", b"Alice")
batch.put("user:2", b"Bob")
batch.put("user:3", b"Charlie")
batch.delete("user:4")
db.close()
```
### Range Queries
Query all entries within a key range:
```python
# Get all users between user:100 and user:200
for key, value in db.range("user:100", "user:200"):
print(f"Key: {key}, Value: {value}")
```
### Database Iteration
Scan all entries in sorted order:
```python
# Iterate from the beginning
for key, value in db.scan():
print(f"{key}: {value}")
# Iterate from a specific key
for key, value in db.scan(start_key="user:50"):
print(f"{key}: {value}")
```
### Statistics and Monitoring
```python
stats = db.stats()
print(f"Get operations: {stats['stats']['get_count']}")
print(f"Set operations: {stats['stats']['set_count']}")
print(f"Cache hits: {stats['stats']['cache_hits']}")
print(f"Memtable size: {stats['memtable']['size']} bytes")
print(f"Cache entries: {stats['cache']['entries']}")
```
### Flushing and Compaction
```python
# Manually flush memtable to disk
db.flush()
# Manually trigger compaction
db.compact()
# Check if database is closed
if not db.is_closed():
print("Database is still open")
```
## ⚙️ Configuration
The `Config` class provides singleton configuration for the database:
```python
from yellowdb import YellowDB, Config
# Get the configuration instance
config = Config()
# Set data directory
config.set_data_directory("./my_database")
# Configure memtable size (default: 64 MB)
config.memtable_size = 128 * 1024 * 1024
# Enable/disable caching (default: True)
config.enable_cache = True
# Configure cache size (default: 256 MB)
config.set_cache_size(512 * 1024 * 1024)
# Create database with custom configuration
db = YellowDB()
```
**Key Configuration Options:**
- `data_directory`: Path to store database files (default: `./yellowdb_data`)
- `memtable_size`: Maximum size of memtable before flushing (default: 64 MB)
- `enable_cache`: Enable write-through caching (default: True)
- `cache_size`: Size of the cache layer (default: 256 MB)
- `enable_concurrent_memtables`: Use multiple memtables for higher write throughput (default: False)
- `compression_level`: Compression level for SSTables (default: 6)
- `enable_compression`: Enable data compression (default: True)
## 🌍 Real-World Examples
YellowDB includes production-ready examples for common use cases:
### Session Storage
Replace Redis/Memcached for web session storage:
```python
from examples.session_store import SessionStore
store = SessionStore(ttl_seconds=3600)
session_id = store.create_session("user:100", {"ip": "192.168.1.1"})
session_data = store.get_session(session_id)
```
See [examples/session_store.py](examples/session_store.py) for Flask/FastAPI integration patterns.
### Application Caching
Cache API responses, database queries, and expensive computations:
```python
from examples.cache_layer import CacheLayer
cache = CacheLayer(default_ttl=3600)
# Cache-aside pattern
user = cache.get(
"user:100",
loader_fn=lambda: expensive_db_query(),
ttl=3600
)
# Get cache statistics
stats = cache.get_stats()
print(f"Hit rate: {stats['hit_rate_percent']:.1f}%")
```
See [examples/cache_layer.py](examples/cache_layer.py) for more details.
For comprehensive examples and integration guides, see [examples/README.md](examples/README.md).
## 📖 API Reference
### YellowDB Class
```python
class YellowDB:
"""Main database class for key-value operations."""
def __init__(self, data_directory: Optional[str] = None)
def set(self, key: str, value: bytes) -> None
def get(self, key: str) -> Optional[bytes]
def delete(self, key: str) -> None
def flush(self) -> None
def compact(self) -> None
def scan(self, start_key: Optional[str] = None) -> DatabaseIterator
def range(self, start_key: str, end_key: str) -> RangeIterator
def stats(self) -> Dict[str, Any]
def is_closed(self) -> bool
def close(self) -> None
def destroy(self) -> None
def __enter__(self) -> YellowDB
def __exit__(self, *args) -> None
```
### Batch Class
```python
class Batch:
"""Atomic batch of database operations."""
def __init__(self, database: YellowDB)
def put(self, key: str, value: bytes) -> None
def delete(self, key: str) -> None
def commit(self) -> None
def __enter__(self) -> Batch
def __exit__(self, *args) -> None
```
### Iterators
```python
class DatabaseIterator:
"""Iterator for scanning all entries in sorted order."""
def __iter__(self)
def __next__(self) -> Tuple[str, bytes]
class RangeIterator:
"""Iterator for range queries."""
def __iter__(self)
def __next__(self) -> Tuple[str, bytes]
```
### Configuration
```python
class Config:
"""Singleton configuration class."""
@classmethod
def reset(cls) -> None
def set_data_directory(self, path: str) -> None
def set_cache_size(self, size: int) -> None
def set_memtable_size(self, size: int) -> None
def set_compression_level(self, level: int) -> None
```
### Exceptions
All database errors inherit from `YellowDBError`:
```python
from yellowdb import (
YellowDBError, # Base exception
DatabaseClosedError, # Accessing closed database
DatabaseCorruptedError, # Corruption detected
InvalidKeyError, # Invalid key
InvalidValueError, # Invalid value
KeyNotFoundError, # Key not found
CompactionError, # Compaction failed
WALError, # Write-ahead log error
SerializationError, # Serialization failed
ConfigurationError, # Configuration error
)
```
## 📊 Performance Characteristics
**Write Throughput**: ~50,000-100,000 operations/sec (depending on value size and configuration)
**Read Throughput**: ~100,000+ operations/sec (with caching enabled)
**Key-Value Size Limits**:
- Keys: Maximum 1024 bytes
- Values: Maximum 512 MB
**Typical Memory Usage**:
- Memtable: Configurable (default 64 MB)
- Cache: Configurable (default 256 MB)
- Per-entry overhead: ~50-100 bytes
**Performance Tips**:
- Enable caching for read-heavy workloads
- Use batch operations for bulk writes
- Tune memtable size based on available memory
- Configure compression for I/O-bound workloads
- Use concurrent memtables for very high write throughput
## 🛠️ Development
### Prerequisites
- Python 3.11+
- `pip` package manager
### Install Development Dependencies
```bash
pip install -e ".[dev]"
```
### Linting and Formatting
The project uses `ruff` for code quality:
```bash
# Check code style
ruff check .
# Format code
ruff format .
```
### Running Examples
```bash
# Session storage example
python examples/session_store.py
# Caching layer example
python examples/cache_layer.py
```
### Cleanup
```bash
# Remove test databases created by examples
rm -rf session_db cache_db yellowdb_data
```
## 🤝 Contributing
Contributions are welcome! To contribute:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run linting (`ruff check . && ruff format .`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Copyright (c) 2025 Arshia Ahmadzadeh
## 📖 Documentation & Resources
- **Repository**: [github.com/arshia-ahmadzadeh/yellowdb](https://github.com/arshia-ahmadzadeh/yellowdb)
- **Bug Tracker**: [GitHub Issues](https://github.com/arshia-ahmadzadeh/yellowdb/issues)
- **Examples**: [examples/README.md](examples/README.md)
- **PyPI**: [pypi.org/project/yellowdb](https://pypi.org/project/yellowdb/)
## 🎓 Learning Resources
- **LSM-Trees**: [Original LSM-Tree Paper](https://citeseer.ist.psu.edu/viewdoc/download?doi=10.1.1.44.2782&rep=rep1&type=pdf)
- **Log-Structured Storage**: [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki)
- **Python Best Practices**: [PEP 8](https://www.python.org/dev/peps/pep-0008/)
---
**Built with ❤️ in Python** | MIT Licensed | v1.0.0
Raw data
{
"_id": null,
"home_page": null,
"name": "yellowdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "database, key-value, lsm-tree, storage, in-memory, performance, embedded",
"author": null,
"author_email": "Arshia Ahmadzadeh <squirrelspirits@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c7/d1/9e92411676e0d16c5180a1497b63da4ae9058cb4402fcf20ba9b16f75406/yellowdb-1.0.0.tar.gz",
"platform": null,
"description": "# YellowDB\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/astral-sh/ruff)\n\nA high-performance **Log-Structured Merge-tree (LSM-tree) based key-value database** written in Python. YellowDB is designed for write-heavy workloads with excellent read performance, combining the benefits of in-memory speed with persistent on-disk storage.\n\n```python\nfrom yellowdb import YellowDB\n\n# Create a database\ndb = YellowDB(data_directory=\"./my_database\")\n\n# Store data\ndb.set(\"user:1\", b\"Alice\")\nvalue = db.get(\"user:1\") # Returns: b\"Alice\"\n\n# Clean up\ndb.close()\n```\n\n## \u2728 Key Features\n\n- **LSM-tree Architecture**: Optimized for write-heavy workloads with fast sequential writes\n- **Write-Ahead Logging (WAL)**: ACID-like durability guarantees with crash recovery\n- **Concurrent Operations**: Thread-safe operations with support for concurrent reads and writes\n- **Automatic Compaction**: Background compaction optimizes storage and read performance\n- **Caching Layer**: Built-in write-through cache for frequently accessed data\n- **Bloom Filters**: Efficient key lookups without unnecessary disk I/O\n- **Batch Operations**: Atomic multi-key operations for consistency\n- **Range Queries**: Efficient range scans and iterators over sorted keys\n- **Configuration**: Flexible configuration for tuning memory, cache, and compaction behavior\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install yellowdb\n```\n\n### Basic Usage\n\n```python\nfrom yellowdb import YellowDB\n\n# Create and use a database\nwith YellowDB(data_directory=\"./my_database\") as db:\n # Write operations\n db.set(\"key\", b\"value\")\n\n # Read operations\n value = db.get(\"key\")\n print(value) # b\"value\"\n\n # Delete operations\n db.delete(\"key\")\n\n # Range queries\n for key, value in db.range(\"start_key\", \"end_key\"):\n print(f\"{key}: {value}\")\n\n # Full database scan\n for key, value in db.scan():\n print(f\"{key}: {value}\")\n```\n\n## \ud83d\udcda Core Concepts\n\n### LSM-Tree Architecture\n\nYellowDB implements the Log-Structured Merge-tree (LSM-tree) data structure, which:\n\n1. **Writes** are initially buffered in an in-memory structure (memtable)\n2. **Write-Ahead Log (WAL)** ensures durability before acknowledgment\n3. When memtables reach capacity, they're **flushed to disk as SSTables** (Sorted String Tables)\n4. **Compaction** periodically merges SSTables, removing deleted entries and optimizing the tree structure\n\nThis design provides:\n- Fast writes (appending to log)\n- Efficient reads (cached data + tree structure)\n- Automatic storage optimization (compaction)\n\n### Components\n\n| Component | Purpose |\n|-----------|---------|\n| **Memtable** | In-memory sorted buffer for pending writes |\n| **SSTable** | Immutable on-disk sorted file containing key-value pairs |\n| **WAL** | Write-Ahead Log for crash recovery and durability |\n| **Compactor** | Background process managing SSTable merging |\n| **Bloom Filter** | Probabilistic data structure for fast key lookups |\n| **Cache** | Write-through cache for frequently accessed entries |\n\n## \ud83d\udcbb Usage Examples\n\n### Basic CRUD Operations\n\n```python\nfrom yellowdb import YellowDB\n\ndb = YellowDB(data_directory=\"./my_db\")\n\n# Create/Update\ndb.set(\"user:100\", b'{\"name\": \"Alice\", \"age\": 30}')\n\n# Read\nuser_data = db.get(\"user:100\")\nif user_data:\n print(user_data.decode())\n\n# Delete\ndb.delete(\"user:100\")\n\ndb.close()\n```\n\n### Batch Operations\n\nPerform multiple operations atomically:\n\n```python\nfrom yellowdb import YellowDB, Batch\n\ndb = YellowDB()\n\n# Execute multiple operations in a single batch\nwith Batch(db) as batch:\n batch.put(\"user:1\", b\"Alice\")\n batch.put(\"user:2\", b\"Bob\")\n batch.put(\"user:3\", b\"Charlie\")\n batch.delete(\"user:4\")\n\ndb.close()\n```\n\n### Range Queries\n\nQuery all entries within a key range:\n\n```python\n# Get all users between user:100 and user:200\nfor key, value in db.range(\"user:100\", \"user:200\"):\n print(f\"Key: {key}, Value: {value}\")\n```\n\n### Database Iteration\n\nScan all entries in sorted order:\n\n```python\n# Iterate from the beginning\nfor key, value in db.scan():\n print(f\"{key}: {value}\")\n\n# Iterate from a specific key\nfor key, value in db.scan(start_key=\"user:50\"):\n print(f\"{key}: {value}\")\n```\n\n### Statistics and Monitoring\n\n```python\nstats = db.stats()\nprint(f\"Get operations: {stats['stats']['get_count']}\")\nprint(f\"Set operations: {stats['stats']['set_count']}\")\nprint(f\"Cache hits: {stats['stats']['cache_hits']}\")\nprint(f\"Memtable size: {stats['memtable']['size']} bytes\")\nprint(f\"Cache entries: {stats['cache']['entries']}\")\n```\n\n### Flushing and Compaction\n\n```python\n# Manually flush memtable to disk\ndb.flush()\n\n# Manually trigger compaction\ndb.compact()\n\n# Check if database is closed\nif not db.is_closed():\n print(\"Database is still open\")\n```\n\n## \u2699\ufe0f Configuration\n\nThe `Config` class provides singleton configuration for the database:\n\n```python\nfrom yellowdb import YellowDB, Config\n\n# Get the configuration instance\nconfig = Config()\n\n# Set data directory\nconfig.set_data_directory(\"./my_database\")\n\n# Configure memtable size (default: 64 MB)\nconfig.memtable_size = 128 * 1024 * 1024\n\n# Enable/disable caching (default: True)\nconfig.enable_cache = True\n\n# Configure cache size (default: 256 MB)\nconfig.set_cache_size(512 * 1024 * 1024)\n\n# Create database with custom configuration\ndb = YellowDB()\n```\n\n**Key Configuration Options:**\n\n- `data_directory`: Path to store database files (default: `./yellowdb_data`)\n- `memtable_size`: Maximum size of memtable before flushing (default: 64 MB)\n- `enable_cache`: Enable write-through caching (default: True)\n- `cache_size`: Size of the cache layer (default: 256 MB)\n- `enable_concurrent_memtables`: Use multiple memtables for higher write throughput (default: False)\n- `compression_level`: Compression level for SSTables (default: 6)\n- `enable_compression`: Enable data compression (default: True)\n\n## \ud83c\udf0d Real-World Examples\n\nYellowDB includes production-ready examples for common use cases:\n\n### Session Storage\n\nReplace Redis/Memcached for web session storage:\n\n```python\nfrom examples.session_store import SessionStore\n\nstore = SessionStore(ttl_seconds=3600)\nsession_id = store.create_session(\"user:100\", {\"ip\": \"192.168.1.1\"})\nsession_data = store.get_session(session_id)\n```\n\nSee [examples/session_store.py](examples/session_store.py) for Flask/FastAPI integration patterns.\n\n### Application Caching\n\nCache API responses, database queries, and expensive computations:\n\n```python\nfrom examples.cache_layer import CacheLayer\n\ncache = CacheLayer(default_ttl=3600)\n\n# Cache-aside pattern\nuser = cache.get(\n \"user:100\",\n loader_fn=lambda: expensive_db_query(),\n ttl=3600\n)\n\n# Get cache statistics\nstats = cache.get_stats()\nprint(f\"Hit rate: {stats['hit_rate_percent']:.1f}%\")\n```\n\nSee [examples/cache_layer.py](examples/cache_layer.py) for more details.\n\nFor comprehensive examples and integration guides, see [examples/README.md](examples/README.md).\n\n## \ud83d\udcd6 API Reference\n\n### YellowDB Class\n\n```python\nclass YellowDB:\n \"\"\"Main database class for key-value operations.\"\"\"\n\n def __init__(self, data_directory: Optional[str] = None)\n def set(self, key: str, value: bytes) -> None\n def get(self, key: str) -> Optional[bytes]\n def delete(self, key: str) -> None\n def flush(self) -> None\n def compact(self) -> None\n def scan(self, start_key: Optional[str] = None) -> DatabaseIterator\n def range(self, start_key: str, end_key: str) -> RangeIterator\n def stats(self) -> Dict[str, Any]\n def is_closed(self) -> bool\n def close(self) -> None\n def destroy(self) -> None\n def __enter__(self) -> YellowDB\n def __exit__(self, *args) -> None\n```\n\n### Batch Class\n\n```python\nclass Batch:\n \"\"\"Atomic batch of database operations.\"\"\"\n\n def __init__(self, database: YellowDB)\n def put(self, key: str, value: bytes) -> None\n def delete(self, key: str) -> None\n def commit(self) -> None\n def __enter__(self) -> Batch\n def __exit__(self, *args) -> None\n```\n\n### Iterators\n\n```python\nclass DatabaseIterator:\n \"\"\"Iterator for scanning all entries in sorted order.\"\"\"\n def __iter__(self)\n def __next__(self) -> Tuple[str, bytes]\n\nclass RangeIterator:\n \"\"\"Iterator for range queries.\"\"\"\n def __iter__(self)\n def __next__(self) -> Tuple[str, bytes]\n```\n\n### Configuration\n\n```python\nclass Config:\n \"\"\"Singleton configuration class.\"\"\"\n\n @classmethod\n def reset(cls) -> None\n\n def set_data_directory(self, path: str) -> None\n def set_cache_size(self, size: int) -> None\n def set_memtable_size(self, size: int) -> None\n def set_compression_level(self, level: int) -> None\n```\n\n### Exceptions\n\nAll database errors inherit from `YellowDBError`:\n\n```python\nfrom yellowdb import (\n YellowDBError, # Base exception\n DatabaseClosedError, # Accessing closed database\n DatabaseCorruptedError, # Corruption detected\n InvalidKeyError, # Invalid key\n InvalidValueError, # Invalid value\n KeyNotFoundError, # Key not found\n CompactionError, # Compaction failed\n WALError, # Write-ahead log error\n SerializationError, # Serialization failed\n ConfigurationError, # Configuration error\n)\n```\n\n## \ud83d\udcca Performance Characteristics\n\n**Write Throughput**: ~50,000-100,000 operations/sec (depending on value size and configuration)\n\n**Read Throughput**: ~100,000+ operations/sec (with caching enabled)\n\n**Key-Value Size Limits**:\n- Keys: Maximum 1024 bytes\n- Values: Maximum 512 MB\n\n**Typical Memory Usage**:\n- Memtable: Configurable (default 64 MB)\n- Cache: Configurable (default 256 MB)\n- Per-entry overhead: ~50-100 bytes\n\n**Performance Tips**:\n- Enable caching for read-heavy workloads\n- Use batch operations for bulk writes\n- Tune memtable size based on available memory\n- Configure compression for I/O-bound workloads\n- Use concurrent memtables for very high write throughput\n\n## \ud83d\udee0\ufe0f Development\n\n### Prerequisites\n\n- Python 3.11+\n- `pip` package manager\n\n### Install Development Dependencies\n\n```bash\npip install -e \".[dev]\"\n```\n\n### Linting and Formatting\n\nThe project uses `ruff` for code quality:\n\n```bash\n# Check code style\nruff check .\n\n# Format code\nruff format .\n```\n\n### Running Examples\n\n```bash\n# Session storage example\npython examples/session_store.py\n\n# Caching layer example\npython examples/cache_layer.py\n```\n\n### Cleanup\n\n```bash\n# Remove test databases created by examples\nrm -rf session_db cache_db yellowdb_data\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! To contribute:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run linting (`ruff check . && ruff format .`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 Arshia Ahmadzadeh\n\n## \ud83d\udcd6 Documentation & Resources\n\n- **Repository**: [github.com/arshia-ahmadzadeh/yellowdb](https://github.com/arshia-ahmadzadeh/yellowdb)\n- **Bug Tracker**: [GitHub Issues](https://github.com/arshia-ahmadzadeh/yellowdb/issues)\n- **Examples**: [examples/README.md](examples/README.md)\n- **PyPI**: [pypi.org/project/yellowdb](https://pypi.org/project/yellowdb/)\n\n## \ud83c\udf93 Learning Resources\n\n- **LSM-Trees**: [Original LSM-Tree Paper](https://citeseer.ist.psu.edu/viewdoc/download?doi=10.1.1.44.2782&rep=rep1&type=pdf)\n- **Log-Structured Storage**: [RocksDB Documentation](https://github.com/facebook/rocksdb/wiki)\n- **Python Best Practices**: [PEP 8](https://www.python.org/dev/peps/pep-0008/)\n\n---\n\n**Built with \u2764\ufe0f in Python** | MIT Licensed | v1.0.0\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Arshia Ahmadzadeh\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A high-performance LSM-tree based key-value database written in Python",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/arshia-ahmadzadeh/yellowdb/issues",
"Documentation": "https://github.com/arshia-ahmadzadeh/yellowdb#readme",
"Homepage": "https://github.com/arshia-ahmadzadeh/yellowdb",
"Repository": "https://github.com/arshia-ahmadzadeh/yellowdb.git"
},
"split_keywords": [
"database",
" key-value",
" lsm-tree",
" storage",
" in-memory",
" performance",
" embedded"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b69caeb1f8e0d3cd1bd32ecfd88b315238bdbaf320f1aac8f2062c5a45101e9e",
"md5": "937e9e8c09a1c117c60c2fc044aa89be",
"sha256": "7ea24b327702e7eb73ad0bae593b742730972f141865eb0cb81b132c1037b52a"
},
"downloads": -1,
"filename": "yellowdb-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "937e9e8c09a1c117c60c2fc044aa89be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 51816,
"upload_time": "2025-10-24T21:07:33",
"upload_time_iso_8601": "2025-10-24T21:07:33.922104Z",
"url": "https://files.pythonhosted.org/packages/b6/9c/aeb1f8e0d3cd1bd32ecfd88b315238bdbaf320f1aac8f2062c5a45101e9e/yellowdb-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c7d19e92411676e0d16c5180a1497b63da4ae9058cb4402fcf20ba9b16f75406",
"md5": "99cd00ef2f0242ea0d48f73813ec6d72",
"sha256": "8a0a51cbfa35e4b511a0172ce5249f8a33f8762199bf87845b30abc98877713e"
},
"downloads": -1,
"filename": "yellowdb-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "99cd00ef2f0242ea0d48f73813ec6d72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 46539,
"upload_time": "2025-10-24T21:07:35",
"upload_time_iso_8601": "2025-10-24T21:07:35.029780Z",
"url": "https://files.pythonhosted.org/packages/c7/d1/9e92411676e0d16c5180a1497b63da4ae9058cb4402fcf20ba9b16f75406/yellowdb-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 21:07:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arshia-ahmadzadeh",
"github_project": "yellowdb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "yellowdb"
}
