# ZFDB
A lightweight, pure Python library for file-based database operations with encryption support. ZFDB provides a secure and easy way to store and manage data in a local file system using ZIP archives.
## Features
- 🔒 Password-based encryption
- 📁 ZIP-based storage with compression
- 🔍 Record search capabilities
- 🏷️ Metadata support
- ✅ Data integrity validation
- 🔄 Automatic compaction
- 💾 Backup functionality
- 📝 JSON support
- 🐍 Pure Python (no external dependencies)
## Installation
Clone the repository or install the package using `pip`:
```bash
pip install zfdb
# or
git clone https://github.com/semolex/zfdb.git
cd zfdb
```
## Quick Start
```python
from zfdb import Database, DatabaseConfig
from pathlib import Path
# Create a database configuration
config = DatabaseConfig(
name="mydb",
path=Path("mydb.zip"),
password="secret123", # Optional
compression_level=9
)
# Initialize database
db = Database(config)
# Insert records
db.insert(
"user1",
'{"name": "John Doe", "email": "john@example.com"}',
metadata={"type": "user"}
)
# Read records
record = db.get("user1")
if record:
user_data = record.json # Parse as JSON
print(f"User: {user_data['name']}")
print(f"Record created: {record.metadata['created_at']}")
# Search records
results = db.search("user")
print(f"Found records: {results}")
# Create backup
db.backup("mydb_backup.zip")
```
## Detailed Usage
### Configuration
```python
from zfdb import DatabaseConfig
from pathlib import Path
config = DatabaseConfig(
name="mydb", # Database name
path=Path("mydb.zip"), # Database file path
password="secret123", # Optional encryption password
compression_level=6, # ZIP compression level (0-9)
max_size=1024 * 1024 * 100, # Maximum database size (100MB)
auto_compact=True, # Enable automatic compaction
version="1.0.0" # Database version
)
```
### Working with Records
#### Insert Records
```python
# Insert JSON data
db.insert(
"config1",
'{"setting": "value"}',
metadata={"type": "configuration"}
)
# Insert text data
db.insert(
"note1",
"This is a text note",
metadata={"type": "note"}
)
# Insert binary data
db.insert(
"binary1",
b"\x00\x01\x02\x03",
metadata={"type": "binary"}
)
```
#### Read Records
```python
# Get record
record = db.get("config1")
# Access data in different formats
raw_data = record.raw # bytes
text_data = record.text # str
json_data = record.json # parsed JSON
# Access metadata
created_at = record.metadata['created_at']
record_size = record.metadata['size']
```
#### Update Records
```python
db.update(
"note1",
"Updated content",
metadata={"updated_at": datetime.utcnow().isoformat()}
)
```
#### Delete Records
```python
db.delete("note1")
```
### Database Management
#### List Records
```python
all_records = db.list_records()
```
#### Search Records
```python
# Search by name pattern
notes = db.search("note")
configs = db.search("config")
```
#### Database Maintenance
```python
# Compact database (remove deleted records)
db.compact()
# Create backup
db.backup("backup.zip")
```
## Data Security
ZFDB provides several security features:
1. **Password Protection**: Database contents are encrypted using a password-derived key
2. **Data Integrity**: Each record includes a SHA-256 checksum
3. **Size Limits**: Configurable database size limits
4. **Validation**: Automatic data integrity checking
## Best Practices
1. **Regular Backups**: Use the `backup()` method regularly
2. **Error Handling**: Always handle potential exceptions:
```python
try:
record = db.get("key")
except DatabaseError as e:
logger.error(f"Database error: {e}")
```
3. **Resource Management**: Close database when done:
```python
try:
# Use database
finally:
db.compact() # Optional cleanup
```
## Limitations
- Not a real database
- Not suitable for concurrent access
- No built-in indexing
- Limited query capabilities
- Not recommended for very large datasets
- Simple encryption (not suitable for highly sensitive data)
## Testing and linting
```bash
poetry run black zfdb/
poetry run isort zfdb/
poetry run mypy zfdb/
poetry run pytest tests/
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/yourfeature`)
3. Commit your changes (`git commit -m 'Add some yourfeature'`)
4. Push to the branch (`git push origin feature/yourfeature`)
5. Open a Pull Request
6. Use `isort`, `mypy` and `black` for code formatting and type checking
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Created to be used in local applications to persists data in case there is no other database available
- Inspired by simple key-value stores
- Built using Python standard library components
- Designed for simplicity and ease of use
Raw data
{
"_id": null,
"home_page": "https://github.com/semolex/zfdb",
"name": "zfdb",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "db, key-value, zip, python, database, filesystem, file, storage, zipfile-database, zipfile-db, zip-db, zip-database, zipfile-storage, zip-storage",
"author": "Oleksii",
"author_email": "semolex@live.com",
"download_url": "https://files.pythonhosted.org/packages/c2/1a/28e32e383e4d968ca955606da03690653b20000f47288bb08c1e118c42bc/zfdb-0.1.1.tar.gz",
"platform": null,
"description": "# ZFDB\n\nA lightweight, pure Python library for file-based database operations with encryption support. ZFDB provides a secure and easy way to store and manage data in a local file system using ZIP archives.\n\n## Features\n\n- \ud83d\udd12 Password-based encryption\n- \ud83d\udcc1 ZIP-based storage with compression\n- \ud83d\udd0d Record search capabilities\n- \ud83c\udff7\ufe0f Metadata support\n- \u2705 Data integrity validation\n- \ud83d\udd04 Automatic compaction\n- \ud83d\udcbe Backup functionality\n- \ud83d\udcdd JSON support\n- \ud83d\udc0d Pure Python (no external dependencies)\n\n## Installation\n\nClone the repository or install the package using `pip`:\n```bash\npip install zfdb\n# or\ngit clone https://github.com/semolex/zfdb.git\ncd zfdb\n```\n\n## Quick Start\n\n```python\nfrom zfdb import Database, DatabaseConfig\nfrom pathlib import Path\n\n# Create a database configuration\nconfig = DatabaseConfig(\n name=\"mydb\",\n path=Path(\"mydb.zip\"),\n password=\"secret123\", # Optional\n compression_level=9\n)\n\n# Initialize database\ndb = Database(config)\n\n# Insert records\ndb.insert(\n \"user1\",\n '{\"name\": \"John Doe\", \"email\": \"john@example.com\"}',\n metadata={\"type\": \"user\"}\n)\n\n# Read records\nrecord = db.get(\"user1\")\nif record:\n user_data = record.json # Parse as JSON\n print(f\"User: {user_data['name']}\")\n print(f\"Record created: {record.metadata['created_at']}\")\n\n# Search records\nresults = db.search(\"user\")\nprint(f\"Found records: {results}\")\n\n# Create backup\ndb.backup(\"mydb_backup.zip\")\n```\n\n## Detailed Usage\n\n### Configuration\n\n```python\nfrom zfdb import DatabaseConfig\nfrom pathlib import Path\n\nconfig = DatabaseConfig(\n name=\"mydb\", # Database name\n path=Path(\"mydb.zip\"), # Database file path\n password=\"secret123\", # Optional encryption password\n compression_level=6, # ZIP compression level (0-9)\n max_size=1024 * 1024 * 100, # Maximum database size (100MB)\n auto_compact=True, # Enable automatic compaction\n version=\"1.0.0\" # Database version\n)\n```\n\n### Working with Records\n\n#### Insert Records\n```python\n# Insert JSON data\ndb.insert(\n \"config1\",\n '{\"setting\": \"value\"}',\n metadata={\"type\": \"configuration\"}\n)\n\n# Insert text data\ndb.insert(\n \"note1\",\n \"This is a text note\",\n metadata={\"type\": \"note\"}\n)\n\n# Insert binary data\ndb.insert(\n \"binary1\",\n b\"\\x00\\x01\\x02\\x03\",\n metadata={\"type\": \"binary\"}\n)\n```\n\n#### Read Records\n```python\n# Get record\nrecord = db.get(\"config1\")\n\n# Access data in different formats\nraw_data = record.raw # bytes\ntext_data = record.text # str\njson_data = record.json # parsed JSON\n\n# Access metadata\ncreated_at = record.metadata['created_at']\nrecord_size = record.metadata['size']\n```\n\n#### Update Records\n```python\ndb.update(\n \"note1\",\n \"Updated content\",\n metadata={\"updated_at\": datetime.utcnow().isoformat()}\n)\n```\n\n#### Delete Records\n```python\ndb.delete(\"note1\")\n```\n\n### Database Management\n\n#### List Records\n```python\nall_records = db.list_records()\n```\n\n#### Search Records\n```python\n# Search by name pattern\nnotes = db.search(\"note\")\nconfigs = db.search(\"config\")\n```\n\n#### Database Maintenance\n```python\n# Compact database (remove deleted records)\ndb.compact()\n\n# Create backup\ndb.backup(\"backup.zip\")\n```\n\n## Data Security\n\nZFDB provides several security features:\n\n1. **Password Protection**: Database contents are encrypted using a password-derived key\n2. **Data Integrity**: Each record includes a SHA-256 checksum\n3. **Size Limits**: Configurable database size limits\n4. **Validation**: Automatic data integrity checking\n\n## Best Practices\n\n1. **Regular Backups**: Use the `backup()` method regularly\n2. **Error Handling**: Always handle potential exceptions:\n ```python\n try:\n record = db.get(\"key\")\n except DatabaseError as e:\n logger.error(f\"Database error: {e}\")\n ```\n3. **Resource Management**: Close database when done:\n ```python\n try:\n # Use database\n finally:\n db.compact() # Optional cleanup\n ```\n\n## Limitations\n- Not a real database\n- Not suitable for concurrent access\n- No built-in indexing\n- Limited query capabilities\n- Not recommended for very large datasets\n- Simple encryption (not suitable for highly sensitive data)\n\n## Testing and linting\n\n```bash\npoetry run black zfdb/\npoetry run isort zfdb/\npoetry run mypy zfdb/\npoetry run pytest tests/\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/yourfeature`)\n3. Commit your changes (`git commit -m 'Add some yourfeature'`)\n4. Push to the branch (`git push origin feature/yourfeature`)\n5. Open a Pull Request\n6. Use `isort`, `mypy` and `black` for code formatting and type checking\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Created to be used in local applications to persists data in case there is no other database available\n- Inspired by simple key-value stores\n- Built using Python standard library components\n- Designed for simplicity and ease of use",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple interface to the ZIP files to use them as a database",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/semolex/zfdb",
"Repository": "https://github.com/semolex/zfdb"
},
"split_keywords": [
"db",
" key-value",
" zip",
" python",
" database",
" filesystem",
" file",
" storage",
" zipfile-database",
" zipfile-db",
" zip-db",
" zip-database",
" zipfile-storage",
" zip-storage"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "98f6755440237b183ea48e71c0a8559d3bc564b02e3cbf74f2713af05bedfabd",
"md5": "94b41924bb3c8fc39341de6c92946664",
"sha256": "d94555e4a6c8c1b501149c20735d3de6caca519f04f2c0d9dfa573d6367b737b"
},
"downloads": -1,
"filename": "zfdb-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94b41924bb3c8fc39341de6c92946664",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 7302,
"upload_time": "2024-11-14T16:06:34",
"upload_time_iso_8601": "2024-11-14T16:06:34.401079Z",
"url": "https://files.pythonhosted.org/packages/98/f6/755440237b183ea48e71c0a8559d3bc564b02e3cbf74f2713af05bedfabd/zfdb-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c21a28e32e383e4d968ca955606da03690653b20000f47288bb08c1e118c42bc",
"md5": "11dc815c2c3d21e20e87d58602414a72",
"sha256": "dbab8dbc80716be8e45e2ea542d4c5c41e542dc8e91d5e70dcb345c304fd0e91"
},
"downloads": -1,
"filename": "zfdb-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "11dc815c2c3d21e20e87d58602414a72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 6919,
"upload_time": "2024-11-14T16:06:35",
"upload_time_iso_8601": "2024-11-14T16:06:35.397399Z",
"url": "https://files.pythonhosted.org/packages/c2/1a/28e32e383e4d968ca955606da03690653b20000f47288bb08c1e118c42bc/zfdb-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 16:06:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "semolex",
"github_project": "zfdb",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "zfdb"
}
JSON
