Metadata-Version: 2.4
Name: af_db_teach
Version: 0.1.0
Summary: Core SQLite ORM with separate educational modules
Home-page: https://github.com/abbasfaramarzi/af_db_teach
Author: Abbas Faramarzi Filabadi
Author-email: Abbas Faramarzi Filabadi <abbasfaramarzi@068gmail.com>
License: MIT License
Project-URL: Homepage, https://github.com/abbasfaramarzi/af_db_teach
Project-URL: Bug Reports, https://github.com/abbasfaramarzi/af_db_teach/issues
Project-URL: Source, https://github.com/abbasfaramarzi/af_db_teach
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

```markdown
# af_db_teach

A simple, educational ORM for SQLite in Python.  
This package allows you to work with an SQLite database without writing raw SQL queries.  
Designed for small projects and learning ORM concepts.

## Features

- Define models using Python classes and simple attributes
- Automatic CRUD operations (Create, Read, Update, Delete)
- Automatic table management (create, update schema, drop)
- Support for default data (`_default_data`)
- Helper methods like search, borrow/return (in the library example)
- Export all tables and data as a dictionary with `db_deeep_interface`

## Installation

```bash
pip install af_db_teach
```

> **Note:** This package will be published on PyPI soon. You can also use it directly from the GitHub repository.

## Quick Start

### 1. Define a Model

```python
from af_db_teach import Model

class Product(Model):
    _primary_key = "id"
    id = 0
    name = ""
    price = 0.0
    in_stock = 1
```

- The table name is automatically derived from the class name (lowercase): `product`
- Fields are defined as class attributes.
- Data types (INTEGER, REAL, TEXT) are inferred from the example values (`int`, `float`, `str`).

### 2. Work with the Database

```python
# Connect and create the table
db = Product("shop.db")

# Insert a row
new_id = db.insert_one(name="Python Book", price=25000, in_stock=1)

# Get all records
all_products = db.get_all()

# Get a single record by primary key
product = db.get_one(1)

# Update a record
db.update(1, price=27000)

# Delete a record
db.delete(1)

# Drop the entire table
db.delete_table()
```

### 3. Default Data

You can define `_default_data` in your model class to insert initial records:

```python
class Category(Model):
    id = 0
    title = ""

    _default_data = [
        (1, "Electronics"),
        (2, "Books"),
        (3, "Clothing"),
    ]
```

> Note: The order of values must match the order of fields returned by `table_fields()`.

## Model Methods

| Method | Description |
|--------|-------------|
| `insert_one(**kwargs)` | Insert a new row. Returns `lastrowid`. |
| `get_all(where="", params=())` | Get all rows (optional WHERE clause). |
| `get_one(row_id)` | Get a single row by primary key. |
| `update(row_id, **kwargs)` | Update specified fields. |
| `delete(row_id)` | Delete a row by primary key. |
| `delete_table(table_name=None)` | Drop the entire table. |
| `db_deeep_interface()` | Return a dictionary of all tables and their contents. |

## Complete Example: Library Management

The file `library_orm_demo.py` provides a practical library system example:

```python
from af_db_teach import Model
from datetime import date

class Book(Model):
    _primary_key = "id"
    id = 0
    title = ""
    author = ""
    year = 2000
    is_available = 1

    def borrow(self, book_id):
        book = self.get_one(book_id)
        if book and book['is_available'] == 1:
            return self.update(book_id, is_available=0)
        return False

    def return_book(self, book_id):
        book = self.get_one(book_id)
        if book and book['is_available'] == 0:
            return self.update(book_id, is_available=1)
        return False

# Usage
book_db = Book("library.db")
book_db.insert_one(title="Thus Spoke Zarathustra", author="Nietzsche", year=1885)
book_db.borrow(1)       # borrow the book
book_db.return_book(1)  # return it
```

Run the full demo:

```bash
python library_orm_demo.py
```

## Advanced Notes

### 1. Ignoring a Table

The `Keywords` class contains a list `ignores_table_name_list`. If a table name is in this list, `create_table` will not create it. You can extend this list:

```python
from af_db_teach import Keywords
Keywords.ignores_table_name_list.append("my_temp_table")
```

### 2. Base Class `TableBase`

If you need a model without direct database connection (just the table structure), you can inherit from `TableBase`.

### 3. Connecting to an Existing Database

```python
db = Model("my_database.db")
```

If the database file does not exist, it will be created.

## License

This project is released under the MIT License.

## Author

Abbas Faramarzi  
[Email](mailto:abbasfaramarzi@068gmail.com)  
[GitHub Repository](https://github.com/abbasfaramarzi/af_db_teach)

---

**af_db_teach** – A simple tool for learning and using ORM in small Python projects.
```
