dpyb

A simple, dependency-free, file-based Python database.

dpyb is a lightweight database that stores all its data in a single Python-readable file with the .dpyb.py extension. Every table is a plain Python dictionary, so you can read, inspect, and even version-control your database with Git.

• Zero dependencies — only Python standard library
• Human-readable format — data is stored as plain Python dicts
• Automatic backups — every write operation creates a timestamped backup
• Simple API — 13 functions, no classes to learn

---

Requirements

• Python 3.12 or newer

---

Installation

pip install dpyb

---

Quick start

import dpyb

# Create a new database
dpyb.CreateDataBase("mydb")

# Add a table
dpyb.AddTableToDataBase("mydb", "users")

# Add rows
dpyb.AddRow("mydb", "users", {1: "Ali", 2: 25})
dpyb.AddRow("mydb", "users", {1: "Sara", 2: 30})

# Read a cell
print(dpyb.ReadData("mydb", "users", 1, 1))   # "Ali"

# Write a cell
dpyb.WriteData("mydb", "users", 1, 2, 26)

The file mydb.dpyb.py will look like this:

# a d-py-b database file, DO NOT EDIT THIS FILE
# d-py-b, a simple python database by darkstarshine2011

# ---

users = {1: {1: 'Ali', 2: 26}, 2: {1: 'Sara', 2: 30}}

---

Data model

A d-py-b database is a set of tables. Each table is a dictionary:

Table = {
    RowID: { ColumnID: Value, ColumnID: Value, ... },
    RowID: { ColumnID: Value, ColumnID: Value, ... },
}

Example:

users = {
    1: {1: "Ali",  2: 25, 3: "Tehran"},
    2: {1: "Sara", 2: 30, 3: "Shiraz"},
    3: {1: "Reza", 2: 40, 3: "Mashhad"},
}

• Row IDs and Column IDs are integers.
• Values can be any Python literal (str, int, float, bool, None, list, dict, tuple).

---

API Reference

GetDataBaseName(DataBaseFile)

Normalizes a database filename. Adds the .dpyb.py extension if missing.

dpyb.GetDataBaseName("mydb")        # "mydb.dpyb.py"
dpyb.GetDataBaseName("mydb.dpyb")   # "mydb.dpyb.py"

CreateDataBase(DataBaseFile)

Creates a new, empty database file. Overwrites the file if it already exists.

dpyb.CreateDataBase("mydb")

CreateBackup(DataBaseFile)

Creates a timestamped backup of the database in the Backup/ folder.

This is called automatically by every write operation, so you rarely need to call it manually.

AddTableToDataBase(DataBaseFile, TableName)

Adds a new empty table to the database. Does nothing if the table already exists.

dpyb.AddTableToDataBase("mydb", "users")

AddRow(DataBaseFile, TableName, Rows)

Adds a new row to the table. The row ID is assigned automatically.

dpyb.AddRow("mydb", "users", {1: "Ali", 2: 25, 3: "Tehran"})

AddColumn(DataBaseFile, TableName, DefaultValue="")

Adds a new column to every row of the table, filled with DefaultValue.

dpyb.AddColumn("mydb", "users", "unknown")

ReadData(DataBaseFile, TableName, Row, Column)

Returns the value of a single cell.

Name = dpyb.ReadData("mydb", "users", 1, 1)   # "Ali"

WriteData(DataBaseFile, TableName, Row, Column, Value)

Writes a value into a single cell.

dpyb.WriteData("mydb", "users", 1, 2, 26)

DeleteRow(DataBaseFile, TableName, Row)

Deletes a row from the table.

dpyb.DeleteRow("mydb", "users", 2)

DeleteColumn(DataBaseFile, TableName, Column)

Deletes a column from every row of the table.

dpyb.DeleteColumn("mydb", "users", 3)

DeleteTable(DataBaseFile, TableName)

Deletes an entire table from the database.

dpyb.DeleteTable("mydb", "users")

ListTables(DataBaseFile)

Returns a list of all table names.

dpyb.ListTables("mydb")   # ["users", "posts"]

GetTable(DataBaseFile, TableName)

Returns the entire table as a Python dictionary.

Users = dpyb.GetTable("mydb", "users")

---

Examples

Iterating over a table

import dpyb

dpyb.CreateDataBase("mydb")
dpyb.AddTableToDataBase("mydb", "users")
dpyb.AddRow("mydb", "users", {1: "Ali", 2: 25})
dpyb.AddRow("mydb", "users", {1: "Sara", 2: 30})

Users = dpyb.GetTable("mydb", "users")

for RowID in Users:
    Name = Users[RowID][1]
    Age = Users[RowID][2]
    print(f"Row {RowID}: {Name}, age {Age}")

Adding a column and filling it

dpyb.AddColumn("mydb", "users", 0)   # new column filled with 0

Users = dpyb.GetTable("mydb", "users")
for RowID in Users:
    dpyb.WriteData("mydb", "users", RowID, 3, "active")

---

Backups

Every write operation (AddRow, WriteData, DeleteRow, DeleteColumn, DeleteTable, AddTableToDataBase, AddColumn) creates a timestamped backup inside a Backup/ folder next to your script.

Backup/
├── 20261005_120000_123456.dpyb.py.backup
├── 20261005_120015_654321.dpyb.py.backup
└── ...

Read operations (ReadData, GetTable, ListTables) do not create backups.

---

Notes

• Database files use the .dpyb.py extension and should not be edited by hand. They are valid Python files, but a wrong edit can break the parser.
• d-py-b has zero external dependencies.
• Not designed for concurrent writes. If multiple processes write to the same database at the same time, data loss may occur.
• Not designed for large datasets. Every write reads and rewrites the entire file.

---

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for the full text.

---

Author

Made by darkstarshine2011