Requirements BinaryDB has minimal requirements:
Python 3.10+ (uses modern type hints like str | Path)Standard library only - No external dependencies required
The following standard library modules are used:
pickle - For object serializationpathlib - For file system operationstyping - For type annotations
Getting BinaryDB BinaryDB is currently distributed as source code. You can get it from the GitHub repository and integrate it into your project.
Clone the repository
Clone the BinaryDB repository from GitHub: git clone https://github.com/Raul-Novo/BinaryDB.git
Copy to your project
Copy the binarydb directory to your project: cp -r binarydb/binarydb /path/to/your/project/
Your project structure should now look like: your-project/ ├── binarydb/ │ ├── __init__.py │ ├── database.py │ ├── errors.py │ ├── cache.py │ ├── index.py │ ├── lock.py │ ├── transaction.py │ ├── utils.py │ └── wal.py └── your_code.py
Import and use
Import the Database class in your Python code: from binarydb.database import Database # You're ready to go! db = Database( "./data/mydb" )
Repository Structure The BinaryDB package is organized as follows:
binarydb/ ├── __init__.py # Package initialization ├── database.py # Core Database class (main implementation) ├── errors.py # Custom exception classes ├── cache.py # Cache utilities (in development) ├── index.py # Indexing structures (planned) ├── lock.py # Concurrency control (planned) ├── transaction.py # Transaction helpers (planned) ├── utils.py # Utility functions (planned) └── wal.py # Write-ahead logging (planned)
Some modules are currently empty or in development. The core functionality is implemented in database.py and errors.py.
Verifying Installation To verify that BinaryDB is correctly installed, try importing it:
try : from binarydb.database import Database from binarydb.errors import DatabaseError print ( "BinaryDB imported successfully!" ) except ImportError as e: print ( f "Import failed: { e } " )
If the import succeeds, you’re ready to use BinaryDB!
Development Setup If you’re planning to contribute to BinaryDB or run tests, you may want to install it in development mode:
Clone the repository
git clone https://github.com/Raul-Novo/BinaryDB.git cd BinaryDB
Create a virtual environment (optional)
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
Install in development mode
Add the repository directory to your Python path, or install it in editable mode if you have a setup.py: # Option 1: Add to PYTHONPATH export PYTHONPATH = " $PWD : $PYTHONPATH " # Option 2: Install in editable mode (if setup.py exists) pip install -e .
Common Issues Import Errors If you get ModuleNotFoundError: No module named 'binarydb', make sure:
The binarydb directory is in your project root or in your Python path
The directory contains an __init__.py file
You’re running Python from the correct directory
Python Version BinaryDB uses modern Python type hints like str | Path (PEP 604). If you get syntax errors, ensure you’re using Python 3.10 or later:
python --version # Should be 3.10 or higher
Permission Errors If you encounter permission errors when creating database files, ensure your application has write access to the directory where you’re storing the database:
import os # Create the data directory if it doesn't exist os.makedirs( "./data" , exist_ok = True ) db = Database( "./data/mydb" )
Alternative: Standalone File For simple projects, you can use just the core files:
Copy database.py and errors.py to your project
Remove the relative imports if needed
Import directly: from database import Database
This approach works for simple use cases but may cause issues if you later want to use additional BinaryDB features. We recommend keeping the full package structure.
Next Steps Now that BinaryDB is installed, learn how to use it:
Quick Start Guide Build your first BinaryDB application with step-by-step examples
