3.0.1

Welcome to DBase documentation. For the latest documentation, visit our GitHub repository.

Quick Links

• Full Documentation
• API Reference
• Examples
• Changelog

Installation

pip install dbase

Basic Example

from dbase import DataBase

# Create or open a database
db = DataBase(file_path="data.json")

# Store data
db["name"] = "Alice"
db.score = 95

# Retrieve data
print(db["name"])  # Alice
print(db.score)    # 95

# Use as context manager
with DataBase(file_path="session.json") as session:
    session.user = "admin"
    session.timestamp = "2024-01-01"

API Reference

DataBase Class

class DataBase(file_path=None, show_logs=True, is_temp=False)

Parameters:

• file_path (str, optional): Path to JSON file for persistent storage
• show_logs (bool): Enable/disable logging (default: True)
• is_temp (bool): Create temporary in-memory database (default: False)

Methods:

• get(key, default=None): Get value with fallback
• pop(key, default=None): Remove and return value
• update(**kwargs): Update multiple values
• clear(): Remove all data
• items(): Return key-value pairs
• keys(): Return all keys
• values(): Return all values

Examples

Example 1: Basic CRUD Operations

db = DataBase("users.json")

# Create
db["user1"] = {"name": "Alice", "age": 30}

# Read
user = db["user1"]

# Update
db["user1"]["age"] = 31

# Delete
del db["user1"]

Example 2: Configuration Storage

config = DataBase("config.json")

# Set configuration
config.database.host = "localhost"
config.database.port = 5432
config.app.debug = True

# Get configuration
host = config.database.host

Example 3: Temporary Data

# Temporary in-memory database
cache = DataBase(is_temp=True)

# Store temporary data
cache.session_token = "abc123"
cache.timestamp = "2024-01-01T12:00:00"

# Data is lost when program ends

Best Practices

1. Use context managers for automatic cleanup:

   with DataBase("data.json") as db:
       # Work with database

2. Handle missing keys safely:

   value = db.get("missing_key", default="default_value")

3. Use appropriate storage:

   • Persistent files for long-term storage
   • Temporary databases for caching

4. Enable logging during development:

   db = DataBase("data.json", show_logs=True)

Troubleshooting

Common Issues

1. File not found errors: Ensure the directory exists before creating database
2. Permission errors: Check file permissions
3. JSON decode errors: Verify file contains valid JSON
4. Type errors: Ensure you're using string keys

Getting Help

• Check the GitHub Issues
• Review the source code
• Submit a bug report with reproduction steps

License

MIT License - see LICENSE file for details.

Support

This project is maintained by Daniil Alekseev. For support, please open an issue on GitHub.

Full Changelog: https://github.com/Danex-Exe/dbase/commits/3.0.0

3.0.0

Welcome to DBase documentation. For the latest documentation, visit our GitHub repository.

Quick Links

• Full Documentation
• API Reference
• Examples
• Changelog

Installation

pip install dbase

Basic Example

from dbase import DataBase

# Create or open a database
db = DataBase(file_path="data.json")

# Store data
db["name"] = "Alice"
db.score = 95

# Retrieve data
print(db["name"])  # Alice
print(db.score)    # 95

# Use as context manager
with DataBase(file_path="session.json") as session:
    session.user = "admin"
    session.timestamp = "2024-01-01"

API Reference

DataBase Class

class DataBase(file_path=None, show_logs=True, is_temp=False)

Parameters:

• file_path (str, optional): Path to JSON file for persistent storage
• show_logs (bool): Enable/disable logging (default: True)
• is_temp (bool): Create temporary in-memory database (default: False)

Methods:

• get(key, default=None): Get value with fallback
• pop(key, default=None): Remove and return value
• update(**kwargs): Update multiple values
• clear(): Remove all data
• items(): Return key-value pairs
• keys(): Return all keys
• values(): Return all values

Examples

Example 1: Basic CRUD Operations

db = DataBase("users.json")

# Create
db["user1"] = {"name": "Alice", "age": 30}

# Read
user = db["user1"]

# Update
db["user1"]["age"] = 31

# Delete
del db["user1"]

Example 2: Configuration Storage

config = DataBase("config.json")

# Set configuration
config.database.host = "localhost"
config.database.port = 5432
config.app.debug = True

# Get configuration
host = config.database.host

Example 3: Temporary Data

# Temporary in-memory database
cache = DataBase(is_temp=True)

# Store temporary data
cache.session_token = "abc123"
cache.timestamp = "2024-01-01T12:00:00"

# Data is lost when program ends

Best Practices

1. Use context managers for automatic cleanup:

   with DataBase("data.json") as db:
       # Work with database

2. Handle missing keys safely:

   value = db.get("missing_key", default="default_value")

3. Use appropriate storage:

   • Persistent files for long-term storage
   • Temporary databases for caching

4. Enable logging during development:

   db = DataBase("data.json", show_logs=True)

Troubleshooting

Common Issues

1. File not found errors: Ensure the directory exists before creating database
2. Permission errors: Check file permissions
3. JSON decode errors: Verify file contains valid JSON
4. Type errors: Ensure you're using string keys

Getting Help

• Check the GitHub Issues
• Review the source code
• Submit a bug report with reproduction steps

License

MIT License - see LICENSE file for details.

Support

This project is maintained by Daniil Alekseev. For support, please open an issue on GitHub.

Full Changelog: https://github.com/Danex-Exe/dbase/commits/3.0.0

2.0.6

🗃️ DBase - Secure Database Library with Encryption

English Русский

DBase is a Python library for simplified file management and synchronization with built-in encryption support. It provides an intuitive interface for creating, reading, writing, and deleting databases while maintaining security through Fernet symmetric encryption.

---

✨ Features

• Multiple Database Formats: Support for .txt, .json, and encrypted .dbase files
• Military-Grade Encryption: AES-128 CBC mode via Fernet for sensitive data
• Comprehensive Error Handling: 30+ specialized error classes for all scenarios
• Logging System: Customizable logger with file rotation and formatting
• Temporary Databases: In-memory databases for ephemeral operations
• Password Protection: Secure password hashing with SHA-256
• Atomic Operations: Safe data modification with automatic backups

---

⚙️ Installation

pip install git+https://github.com/Danex-Exe/dbase.git

---

🚀 Quick Start

Basic Text Database

from dbase import DataBase

db = DataBase('data.txt')
db.create()
db.write('Hello World!')
print(db.read())  # Output: Hello World!
db.delete()

JSON Database

db = DataBase('config.json')
db.create()
db.set(key='theme', value='dark')
db.set(data=[('timeout', 30), ('notifications', True)])
print(db.get('theme'))  # Output: dark
db.delete()

Encrypted Database (.dbase)

db = DataBase('secrets.dbase')
db.create(password="MyStrongP@ssw0rd")
db.open()  # Creates secure session

db.set(key='api_key', value='#sensitive_data')  # Auto-hashes values starting with #
print(db.get('api_key'))  # Returns hashed value

db.delete(password="MyStrongP@ssw0rd")

---

📝 Logger Configuration

db = DataBase('app.log')
db.logger.title = 'APP_LOGGER'
db.logger.log_file = 'application.log'
db.logger.time_format = '%Y-%m-%d %H:%M:%S'
db.logger.format = '[{time}] [{level}] - {message}'
db.logger.log_dir = 'app_logs'

---

🧪 Testing

Run tests with pytest:

pytest tests/

Test coverage includes:

• Database creation/deletion
• Encryption/decryption workflows
• Error handling scenarios
• Temporary database operations
• Cross-format compatibility

---

🔮 Future Roadmap

1. Database Refactor:

   • Support for external connections
   • Client-server architecture
   • SQL-like query interface

2. Enhanced Error Handling:

   • Contextual error messages
   • Recovery mechanisms
   • Detailed error codes

3. Logger Improvements:

   • Asynchronous logging
   • Compression/rotation
   • Cloud integration

4. Additional Features:

   • Role-based access control
   • Audit trails
   • Schema validation

---

📜 License

Free for non-commercial use - See LICENSE for details. Commercial use requires explicit permission.

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📧 Contact

Daniil Alekseev
Email: dan.d.alekseev@gmail.com
GitHub: @Danex-Exe

2.0.5

🗃️ DBase - Secure Database Library with Encryption

English Русский

DBase is a Python library for simplified file management and synchronization with built-in encryption support. It provides an intuitive interface for creating, reading, writing, and deleting databases while maintaining security through Fernet symmetric encryption.

---

✨ Features

• Multiple Database Formats: Support for .txt, .json, and encrypted .dbase files
• Military-Grade Encryption: AES-128 CBC mode via Fernet for sensitive data
• Comprehensive Error Handling: 30+ specialized error classes for all scenarios
• Logging System: Customizable logger with file rotation and formatting
• Temporary Databases: In-memory databases for ephemeral operations
• Password Protection: Secure password hashing with SHA-256
• Atomic Operations: Safe data modification with automatic backups

---

⚙️ Installation

pip install git+https://github.com/Danex-Exe/dbase.git

---

🚀 Quick Start

Basic Text Database

from dbase import DataBase

db = DataBase('data.txt')
db.create()
db.write('Hello World!')
print(db.read())  # Output: Hello World!
db.delete()

JSON Database

db = DataBase('config.json')
db.create()
db.set(key='theme', value='dark')
db.set(data=[('timeout', 30), ('notifications', True)])
print(db.get('theme'))  # Output: dark
db.delete()

Encrypted Database (.dbase)

db = DataBase('secrets.dbase')
db.create(password="MyStrongP@ssw0rd")
db.open()  # Creates secure session

db.set(key='api_key', value='#sensitive_data')  # Auto-hashes values starting with #
print(db.get('api_key'))  # Returns hashed value

db.delete(password="MyStrongP@ssw0rd")

---

📝 Logger Configuration

db = DataBase('app.log')
db.logger.title = 'APP_LOGGER'
db.logger.log_file = 'application.log'
db.logger.time_format = '%Y-%m-%d %H:%M:%S'
db.logger.format = '[{time}] [{level}] - {message}'
db.logger.log_dir = 'app_logs'

---

🧪 Testing

Run tests with pytest:

pytest tests/

Test coverage includes:

• Database creation/deletion
• Encryption/decryption workflows
• Error handling scenarios
• Temporary database operations
• Cross-format compatibility

---

🔮 Future Roadmap

1. Database Refactor:

   • Support for external connections
   • Client-server architecture
   • SQL-like query interface

2. Enhanced Error Handling:

   • Contextual error messages
   • Recovery mechanisms
   • Detailed error codes

3. Logger Improvements:

   • Asynchronous logging
   • Compression/rotation
   • Cloud integration

4. Additional Features:

   • Role-based access control
   • Audit trails
   • Schema validation

---

📜 License

Free for non-commercial use - See LICENSE for details. Commercial use requires explicit permission.

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📧 Contact

Daniil Alekseev
Email: dan.d.alekseev@gmail.com
GitHub: @Danex-Exe

2.0.4

Documentation

English Русский

Installation

pip install git+https://github.com/Danex-Exe/dbase.git

Usage

.txt (text handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database
db.create() # Create the database (ignored if already exists)

db.write('123') # Write data
data = db.read() # Read data
print(data) # Output data

.txt, .json (JSON handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Call the function (.json can be used instead of .txt)
db.create() # Create the database (ignored if already exists)

db.set(data=[
      ('a', '123'),
      ('b', '456')
]) # Write multiple variables in one call
db.set(key='a', value='123') # Write a single element
db.set('b', '456') # Write a second element
# it's possible to combine writing multiple and single elements

db.setdefault(data=[], key='', value='') # Works the same way, but only if the variable(s) don't exist

db.get(key='a') # Returns the value of the variable, or None if it doesn't exist

db.rename(last_key='a', new_key='c') # Renames a variable

db.remove(key='c') # Deletes a variable

db.delete() # Deletes the database

.dbase (encrypted database)

from dbase import DataBase # Import the module

db = DataBase('test.dbase') # Call the function (.json can be used instead of .txt)
db.create(password="SECRET_PASSWORD") # Create the database (ignored if already exists), the password is hashed and stored in the database
db.open(key='SECURITY_KEY.key') # Creates a secure session, enabling interaction with the database. Other functions won't work without this.

# All the aforementioned JSON functions also apply to this database, but here they are automatically encoded
# The .read() and .write() functions do not work with .dbase
db.delete(password="SECRET_PASSWORD") # Checks the database password and deletes it if it matches

Logger configuration

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database

db.logger.title = 'Logger title'
db.logger.log_file = 'Path to the log file'
db.logger.time_format = 'Time format'
db.logger.format = 'Log format'
db.logger.log_dir = 'Logs directory'

2.0.3

Documentation

English Русский

Installation

pip install git+https://github.com/Danex-Exe/dbase.git

Usage

.txt (text handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database
db.create() # Create the database (ignored if already exists)

db.write('123') # Write data
data = db.read() # Read data
print(data) # Output data

.txt, .json (JSON handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Call the function (.json can be used instead of .txt)
db.create() # Create the database (ignored if already exists)

db.set(data=[
      ('a', '123'),
      ('b', '456')
]) # Write multiple variables in one call
db.set(key='a', value='123') # Write a single element
db.set('b', '456') # Write a second element
# it's possible to combine writing multiple and single elements

db.setdefault(data=[], key='', value='') # Works the same way, but only if the variable(s) don't exist

db.get(key='a') # Returns the value of the variable, or None if it doesn't exist

db.rename(last_key='a', new_key='c') # Renames a variable

db.remove(key='c') # Deletes a variable

db.delete() # Deletes the database

.dbase (encrypted database)

from dbase import DataBase # Import the module

db = DataBase('test.dbase') # Call the function (.json can be used instead of .txt)
db.create(password="SECRET_PASSWORD") # Create the database (ignored if already exists), the password is hashed and stored in the database
db.open(key='SECURITY_KEY.key') # Creates a secure session, enabling interaction with the database. Other functions won't work without this.

# All the aforementioned JSON functions also apply to this database, but here they are automatically encoded
# The .read() and .write() functions do not work with .dbase
db.delete(password="SECRET_PASSWORD") # Checks the database password and deletes it if it matches

Logger configuration

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database

db.logger.title = 'Logger title'
db.logger.log_file = 'Path to the log file'
db.logger.time_format = 'Time format'
db.logger.format = 'Log format'
db.logger.log_dir = 'Logs directory'

2.0.2

Documentation

English Русский

Installation

pip install git+https://github.com/Danex-Exe/dbase.git

Usage

.txt (text handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database
db.create() # Create the database (ignored if already exists)

db.write('123') # Write data
data = db.read() # Read data
print(data) # Output data

.txt, .json (JSON handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Call the function (.json can be used instead of .txt)
db.create() # Create the database (ignored if already exists)

db.set(data=[
      ('a', '123'),
      ('b', '456')
]) # Write multiple variables in one call
db.set(key='a', value='123') # Write a single element
db.set('b', '456') # Write a second element
# it's possible to combine writing multiple and single elements

db.setdefault(data=[], key='', value='') # Works the same way, but only if the variable(s) don't exist

db.get(key='a') # Returns the value of the variable, or None if it doesn't exist

db.rename(last_key='a', new_key='c') # Renames a variable

db.remove(key='c') # Deletes a variable

db.delete() # Deletes the database

.dbase (encrypted database)

from dbase import DataBase # Import the module

db = DataBase('test.dbase') # Call the function (.json can be used instead of .txt)
db.create(password="SECRET_PASSWORD") # Create the database (ignored if already exists), the password is hashed and stored in the database
db.open(key='SECURITY_KEY.key') # Creates a secure session, enabling interaction with the database. Other functions won't work without this.

# All the aforementioned JSON functions also apply to this database, but here they are automatically encoded
# The .read() and .write() functions do not work with .dbase
db.delete(password="SECRET_PASSWORD") # Checks the database password and deletes it if it matches

Logger configuration

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database

db.logger.title = 'Logger title'
db.logger.log_file = 'Path to the log file'
db.logger.time_format = 'Time format'
db.logger.format = 'Log format'
db.logger.log_dir = 'Logs directory'

2.0.1

Documentation

English Русский

Installation

pip install git+https://github.com/Danex-Exe/dbase.git

Usage

.txt (text handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database
db.create() # Create the database (ignored if already exists)

db.write('123') # Write data
data = db.read() # Read data
print(data) # Output data

.txt, .json (JSON handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Call the function (.json can be used instead of .txt)
db.create() # Create the database (ignored if already exists)

db.set(data=[
      ('a', '123'),
      ('b', '456')
]) # Write multiple variables in one call
db.set(key='a', value='123') # Write a single element
db.set('b', '456') # Write a second element
# it's possible to combine writing multiple and single elements

db.setdefault(data=[], key='', value='') # Works the same way, but only if the variable(s) don't exist

db.get(key='a') # Returns the value of the variable, or None if it doesn't exist

db.rename(last_key='a', new_key='c') # Renames a variable

db.remove(key='c') # Deletes a variable

db.delete() # Deletes the database

.dbase (encrypted database)

from dbase import DataBase # Import the module

db = DataBase('test.dbase') # Call the function (.json can be used instead of .txt)
db.create(password="SECRET_PASSWORD") # Create the database (ignored if already exists), the password is hashed and stored in the database
db.open(key='SECURITY_KEY.key') # Creates a secure session, enabling interaction with the database. Other functions won't work without this.

# All the aforementioned JSON functions also apply to this database, but here they are automatically encoded
# The .read() and .write() functions do not work with .dbase
db.delete(password="SECRET_PASSWORD") # Checks the database password and deletes it if it matches

Logger configuration

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database

db.logger.title = 'Logger title'
db.logger.log_file = 'Path to the log file'
db.logger.time_format = 'Time format'
db.logger.format = 'Log format'
db.logger.log_dir = 'Logs directory'

2.0.0

Documentation

English Русский

Installation

pip install git+https://github.com/Danex-Exe/dbase.git

Usage

.txt (text handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database
db.create() # Create the database (ignored if already exists)

db.write('123') # Write data
data = db.read() # Read data
print(data) # Output data

.txt, .json (JSON handling)

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Call the function (.json can be used instead of .txt)
db.create() # Create the database (ignored if already exists)

db.set(data=[
      ('a', '123'),
      ('b', '456')
]) # Write multiple variables in one call
db.set(key='a', value='123') # Write a single element
db.set('b', '456') # Write a second element
# it's possible to combine writing multiple and single elements

db.setdefault(data=[], key='', value='') # Works the same way, but only if the variable(s) don't exist

db.get(key='a') # Returns the value of the variable, or None if it doesn't exist

db.rename(last_key='a', new_key='c') # Renames a variable

db.remove(key='c') # Deletes a variable

db.delete() # Deletes the database

.dbase (encrypted database)

from dbase import DataBase # Import the module

db = DataBase('test.dbase') # Call the function (.json can be used instead of .txt)
db.create(password="SECRET_PASSWORD") # Create the database (ignored if already exists), the password is hashed and stored in the database
db.open(key='SECURITY_KEY.key') # Creates a secure session, enabling interaction with the database. Other functions won't work without this.

# All the aforementioned JSON functions also apply to this database, but here they are automatically encoded
# The .read() and .write() functions do not work with .dbase
db.delete(password="SECRET_PASSWORD") # Checks the database password and deletes it if it matches

Logger configuration

from dbase import DataBase # Import the module

db = DataBase('test.txt') # Initialize the database

db.logger.title = 'Logger title'
db.logger.log_file = 'Path to the log file'
db.logger.time_format = 'Time format'
db.logger.format = 'Log format'
db.logger.log_dir = 'Logs directory'

v1.0.2

Usage

DataFile(name, type, encode, path, logs, logger)

    name - Название файла
    type - Расширение файла (default - json)
    encode - Кодировка файла (default - utf-8)
    path - Путь до файла (default - .)
    logs - Показывать/Скрывать логи (default - False)
    logger - Логер (default - None)

    .create() - создает файл и, при необходимости, создает папку
    .read() - чтение файла (если файл - json, то автоматическое переобразование в словарь)
    .write(data) - запись данных в файл (если файл - json, то автоматическое переобразование в строчку)
    .delete() - удаление файла
    .rename(new_name) - переименование файла
    .info() - возвращает информацию о файле (родительская папка, путь, размер, название, дата последнего изменения)

DataBaze(path, logs, logger)

    path - путь до папки (default - .)
    logs - Показывать/Скрывать логи (default - False)
    logger - Логер (default - None)

    .file(name, type, encode) - обьявляет файл
    .delete() - удаляет все файлы в базе данных

Application

from DataBaze import DataBaze


DATABAZE = DataBaze()
CONFIG_FILE = DATABAZE.file('config')
CONFIG_FILE.create() # if not created


data = {
        "users": ["User1", "User2"],
        "admins": ["User1"]
}


data_file.write(data)
print(data_file.read()['admins']) # ["User1"]