diff --git a/docs/Introduction.md b/docs/Introduction.md new file mode 100644 index 0000000..8e86e7d --- /dev/null +++ b/docs/Introduction.md @@ -0,0 +1,81 @@ +# Introduction to AbarORM + + +## What is AbarORM? +**AbarORM** is a lightweight and easy-to-use Object-Relational Mapping (ORM) library designed for SQLite databases in Python. It provides a simple and intuitive interface for managing database models and interactions, making it easier for developers to work with databases without needing to write raw SQL queries. + +## Key Features + +- **Simplicity**: AbarORM is designed to be straightforward and easy to use. With a clean API, you can define your database models and interact with your database using Python objects. +- **Automatic Schema Management**: The library handles the creation and management of the database schema automatically, so you don't have to worry about writing migration scripts. +- **CRUD Operations**: It supports all basic CRUD (Create, Read, Update, Delete) operations, allowing you to perform database operations with minimal code. +- **Relationships**: AbarORM supports foreign key relationships between models, making it easier to manage complex data structures. +- **Custom Fields**: You can define custom field types with validation and constraints to suit your specific needs. + + +## Why Choose AbarORM? + +### Django ORM-Like Experience + +If you're familiar with **Django ORM**, you'll find AbarORM's approach to database modeling and interactions quite familiar. AbarORM follows many of the same principles and patterns found in Django ORM, such as: + +- **Model Definition**: Just like in Django ORM, you define your database tables using Python classes. Each class represents a table, and class attributes define the columns of the table. +- **Field Types**: AbarORM uses similar field types to Django ORM (e.g., `CharField`, `DateTimeField`, `ForeignKey`), making it easy for Django users to adapt to AbarORM. +- **Automatic Schema Management**: Similar to Django's migrations, AbarORM handles schema creation and updates automatically based on your model definitions. + + +## Ease of Use + +AbarORM aims to reduce the complexity associated with database interactions. By abstracting away the details of SQL queries and database management, it allows developers to focus more on writing application logic rather than dealing with database intricacies. + +## Flexibility + +While it is lightweight, AbarORM is flexible enough to handle various use cases. Whether you're working on a small personal project or a more complex application, AbarORM can adapt to your needs. + +## Pythonic Approach + +The library follows Pythonic principles, offering a seamless integration with Python's data structures and object-oriented features. This approach ensures that working with your database feels natural and intuitive. + +## Getting Started + +To get started with AbarORM, follow these steps: + +1. **Installation**: Install the library via pip: + ```bash + pip install abarorm + ``` +**Setup:** Configure your database connection and define your models by inheriting from `SQLiteModel` or `MySQLModel` depending on your database type. + +**Define Models:** Create Python classes that represent your database tables. Use built-in field types to define the attributes of each model. + +**Create Tables:** Use the create_table method to initialize your database schema. + +**Perform Operations:** Use the methods provided by AbarORM to perform CRUD operations, manage relationships, and query your data. + +For detailed instructions and examples, refer to the [Basic Usage](basic_usage.md) section of the documentation. + +# Example +Here's a quick example of defining a simple model with AbarORM on SQLite: +```python +from abarorm import SQLiteModel +from abarorm.fields import CharField, DateTimeField + +DATABASE_CONFIG = { + 'sqlite': { + 'db_name': 'example.db', + } +} + +class Category(SQLiteModel): + table_name = 'categories' + title = CharField(max_length=200, unique=True) + + def __init__(self, **kwargs): + super().__init__(db_config=DATABASE_CONFIG['sqlite'], **kwargs) + +# Create the table in the database +Category.create_table() + +# Add a new category +Category.create(title='Movies') +``` \ No newline at end of file diff --git a/docs/api_refrence.md b/docs/api_refrence.md new file mode 100644 index 0000000..3090ac5 --- /dev/null +++ b/docs/api_refrence.md @@ -0,0 +1,156 @@ +# API Reference for AbarORM + +This page provides a detailed reference for the classes and methods available in the AbarORM library. The API reference is intended for developers who need a comprehensive understanding of how to use AbarORM's features. + +## Classes + +### 1. `SQLiteModel` + +The `SQLiteModel` class is the base class for defining models that interact with an SQLite database. + +#### Methods + +- **`__init__(self, db_config, **kwargs)`** + - **Description**: Initializes the model with the given database configuration. + - **Parameters**: + - `db_config`: Dictionary containing the database configuration. + - `**kwargs`: Additional keyword arguments. + +- **`create_table(cls)`** + - **Description**: Creates the table in the SQLite database based on the model definition. + - **Parameters**: None + +- **`drop_table(cls)`** + - **Description**: Drops the table from the SQLite database. + - **Parameters**: None + +- **`save(self)`** + - **Description**: Saves the current instance to the database. If it’s a new record, it will be inserted; if it exists, it will be updated. + - **Parameters**: None + +- **`delete(self)`** + - **Description**: Deletes the current instance from the database. + - **Parameters**: None + +- **`get(cls, id)`** + - **Description**: Retrieves a single record by its ID. + - **Parameters**: + - `id`: The ID of the record to retrieve. + +- **`all(cls)`** + - **Description**: Retrieves all records from the table. + - **Parameters**: None + +- **`filter(cls, **kwargs)`** + - **Description**: Retrieves records that match the specified criteria. + - **Parameters**: + - `**kwargs`: Criteria for filtering records. + +### 2. `MySQLModel` + +The `MySQLModel` class is similar to `SQLiteModel` but designed for MySQL databases. It provides the same methods as `SQLiteModel` but interacts with MySQL instead. + +#### Methods + +The methods for `MySQLModel` are identical to those for `SQLiteModel`, with differences primarily in how they interact with the MySQL database. + +## Fields + +### 1. `CharField` + +- **Description**: Represents a text field with a maximum length. +- **Parameters**: + - `max_length`: Maximum number of characters allowed. + - `unique`: Whether the field must contain unique values. + - `null`: Whether the field can be `NULL`. + - `default`: Default value if none is provided. + +### 2. `DateTimeField` + +- **Description**: Represents a date and time value. +- **Parameters**: + - `auto_now`: Automatically set to the current date and time on updates. + +### 3. `ForeignKey` + +- **Description**: Represents a many-to-one relationship between models. +- **Parameters**: + - `to`: The model this field points to. + - `on_delete`: Behavior when the referenced record is deleted. + +### 4. `BooleanField` + +- **Description**: Represents a Boolean value. +- **Parameters**: + - `default`: Default value if none is provided. + - `null`: Whether the field can be `NULL`. + +### 5. `IntegerField` + +- **Description**: Represents an integer value. +- **Parameters**: + - `default`: Default value if none is provided. + - `null`: Whether the field can be `NULL`. + +### 6. `FloatField` + +- **Description**: Represents a floating-point number. +- **Parameters**: + - `default`: Default value if none is provided. + - `null`: Whether the field can be `NULL`. + +### 7. `EmailField` + +- **Description**: Represents an email address. +- **Parameters**: + - `max_length`: Maximum number of characters allowed. + - `unique`: Whether the field must contain unique values. + +### 8. `URLField` + +- **Description**: Represents a URL. +- **Parameters**: + - `max_length`: Maximum number of characters allowed. + +### 9. `TextField` + +- **Description**: Represents a large text field for storing long texts. +- **Parameters**: + - `null`: Whether the field can be `NULL`. + +### 10. `DecimalField` + +- **Description**: Represents a decimal number with fixed precision. +- **Parameters**: + - `max_digits`: Maximum number of digits allowed. + - `decimal_places`: Number of decimal places to store. + - `default`: Default value if none is provided. + +## Query Methods + +### 1. `create(cls, **kwargs)` + +- **Description**: Creates a new record with the specified data. +- **Parameters**: + - `**kwargs`: Data for the new record. + +### 2. `update(cls, id, **kwargs)` + +- **Description**: Updates an existing record with new data. +- **Parameters**: + - `id`: ID of the record to update. + - `**kwargs`: New data for the record. + +### 3. `delete(cls, id)` + +- **Description**: Deletes a record by its ID. +- **Parameters**: + - `id`: ID of the record to delete. + +## Summary + +This API reference provides an overview of the core classes, methods, and fields available in AbarORM. For more detailed examples and use cases, refer to the [Basic Usage](basic_usage.md) section. + +If you have any questions or need further assistance, please check the [Documentation](index.md) or reach out to the community via our [GitHub repository](https://github.com/prodbygodfather/abarorm). + +Happy coding with AbarORM! diff --git a/docs/basic_usage.md b/docs/basic_usage.md new file mode 100644 index 0000000..d63e5a6 --- /dev/null +++ b/docs/basic_usage.md @@ -0,0 +1,114 @@ +# Basic Usage of AbarORM + +## Overview + +In this section, we will cover the basic usage of AbarORM, including how to define models, create tables, and perform basic CRUD operations. This guide assumes you have already installed AbarORM and are familiar with Python. + +## Step 1: Define Your Models + +To start using AbarORM, you first need to define your database models. Each model corresponds to a table in your database. Here’s how you can define a simple model: + +### Example: Defining Models + +```python +from abarorm import SQLiteModel +from abarorm.fields import CharField, DateTimeField, ForeignKey + +# Database configuration +DATABASE_CONFIG = { + 'sqlite': { + 'db_name': 'example.db', # Name of the SQLite database file + } +} + +# Define the Category model +class Category(SQLiteModel): + table_name = 'categories' + title = CharField(max_length=200, unique=True) + + def __init__(self, **kwargs): + super().__init__(db_config=DATABASE_CONFIG['sqlite'], **kwargs) + +# Define the Post model +class Post(SQLiteModel): + table_name = 'posts' + title = CharField(max_length=100, unique=True) + create_time = DateTimeField(auto_now=True) + category = ForeignKey(Category) + + def __init__(self, **kwargs): + super().__init__(db_config=DATABASE_CONFIG['sqlite'], **kwargs) +``` +In the example above: + +**Category** and Post are two models representing database tables. +Each class inherits from `SQLiteModel` and defines fields using AbarORM’s built-in field types. + +## Step 2: Create Tables +After defining your models, you need to create the corresponding tables in the database. Use the create_table method provided by AbarORM. +```python +# Create tables in the database +if __name__ == "__main__": + Category.create_table() + Post.create_table() +``` +This script will create the tables `categories` and `posts` in the example.db `SQLite` database file. + +## Step 3: Perform CRUD Operations +Once your tables are created, you can perform CRUD (Create, Read, Update, Delete) operations on your models. + +### Create Records +To add new records to the database, use the `create` method: +```python +# Add a new category +Category.create(title='Movies') + +# Add a new post +category = Category.get(id=1) # Fetch the category with ID 1 +if category: + Post.create(title='Godfather', category=category.id) +``` +### Read Records +To retrieve records from the database, use the `all`, `get`, or `filter` methods: +```python +# Retrieve all posts +all_posts = Post.all() +print("All Posts:", [(post.title, post.category) for post in all_posts]) + +# Retrieve a specific post +post_data = Post.get(id=1) +if post_data: + print("Post with ID 1:", post_data.title, post_data.category) + +# Filter posts by category +filtered_posts = Post.filter(category=category.id) +print("Filtered Posts:", [(post.title, post.category) for post in filtered_posts]) +``` +### Update Records +To update existing records, use the `update` method: +```python +# Update a post +Post.update(id=1, title='The Godfather Part II') +``` +### Delete Records +To delete records, use the `delete` method: +```python +# Delete a post +Post.delete(1) +``` +### Handling Relationships +Handling Relationships +AbarORM supports foreign key relationships between models. In the example provided, the `Post` model has a foreign key relationship with the `Category` model. This allows you to create complex data structures and manage related data efficiently. + +### Example: Accessing Related Data +```python +# Access the category of a post +post = Post.get(id=1) +if post: + category = Category.get(id=post.category) + print("Post Category:", category.title) +``` + +## Summary + +This guide covered the basic usage of AbarORM, including model definition, table creation, and CRUD operations. For more advanced features and configurations, refer to the [Field Types](field_types.md) section. \ No newline at end of file diff --git a/docs/field_types.md b/docs/field_types.md new file mode 100644 index 0000000..9fd6415 --- /dev/null +++ b/docs/field_types.md @@ -0,0 +1,63 @@ +# Field Types in AbarORM + +In AbarORM, fields define the types of data stored in your database models. Each field type represents a specific kind of data and provides options for validation and constraints. This guide covers the available field types and their usage. + +## Basic Field Types + +### 1. CharField + +- **Description**: Represents a text field with a maximum length. +- **Parameters**: + - `max_length`: The maximum number of characters allowed. + - `unique`: If `True`, the field must contain unique values across the table. + - `null`: If `True`, the field can contain `NULL` values. + - `default`: The default value if none is provided. +- **Example**: + ```python + title = CharField(max_length=100, unique=True) + ``` +### 2. DateTimeField + +- **Description:** Represents a date and time value. +- **Parameters:** + - `auto_now:` If True, the field will be automatically set to the current date and time whenever the record is updated. +- **Example:** + ```python + create_time = DateTimeField(auto_now=True) + ``` +### 3. ForeignKey + +- **Description:** Represents a many-to-one relationship between models. +- **Parameters:** + - `to:` The model that this field points to. + - `on_delete:` Defines the behavior when the referenced record is deleted. Common options include: + - `CASCADE:` Automatically delete records that reference the deleted record. + - `SET NULL:` Set the field to NULL when the referenced record is deleted. + - `PROTECT:` Prevent deletion of the referenced record by raising an error. + - `SET_DEFAULT:` Set the field to a default value when the referenced record is deleted. + - `DO_NOTHING:` Do nothing and leave the field unchanged. + +- **Example:** + ```python + category = ForeignKey(Category, on_delete='CASCADE') + ``` + +### 4. BooleanField +- **Description:** Represents a Boolean value (`True` or `False`). +- **Parameters:** + - `default:` The default value for the field if none is provided. + - `null:` If True, the field can contain NULL values. +- **Example:** + ```python + is_active = BooleanField(default=True) + ``` + +### 5. IntegerField +- **Description:** Represents an integer value. +- **Parameters:** + - `default:` The default value for the field if none is provided. + - `null:` If True, the field can contain NULL values. +- **Example:** + ```python + age = IntegerField(default=0) + ``` \ No newline at end of file diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100755 index 0000000..e7d64b3 Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100755 index 0000000..1a75e08 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..61c7875 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,36 @@ +# Welcome to AbarORM + + +
+ abarorm is a lightweight and easy-to-use Object-Relational Mapping (ORM) library for SQLite databases in Python. It aims to provide a simple and intuitive interface for managing database models and interactions. +
+