Metadata-Version: 2.4
Name: dpyb
Version: 0.1.1
Summary: A simple file-based Python database
Author: darkstarshine2011
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/darkstarshine2011/dpyb
Project-URL: Repository, https://github.com/darkstarshine2011/dpyb
Keywords: database,file-based,simple,python,dpyb
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# d-py-b

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

`d-py-b` 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

```bash
pip install dpyb
```

---

## Quick start

```python
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:

```python
# 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:

```python
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.

```python
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.

```python
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.

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

### `AddRow(DataBaseFile, TableName, Rows)`
Adds a new row to the table. The row ID is assigned automatically.

```python
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`.

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

### `ReadData(DataBaseFile, TableName, Row, Column)`
Returns the value of a single cell.

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

### `WriteData(DataBaseFile, TableName, Row, Column, Value)`
Writes a value into a single cell.

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

### `DeleteRow(DataBaseFile, TableName, Row)`
Deletes a row from the table.

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

### `DeleteColumn(DataBaseFile, TableName, Column)`
Deletes a column from every row of the table.

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

### `DeleteTable(DataBaseFile, TableName)`
Deletes an entire table from the database.

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

### `ListTables(DataBaseFile)`
Returns a list of all table names.

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

### `GetTable(DataBaseFile, TableName)`
Returns the entire table as a Python dictionary.

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

---

## Examples

### Iterating over a table

```python
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

```python
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](LICENSE) file for the full text.

---

## Author

Made by **darkstarshine2011**

[![PyPI version](https://badge.fury.io/py/dpyb.svg)](https://pypi.org/project/dpyb/)
