Merge branch 'develop'

Author: daireto

CONTRIBUTING.md

@@ -20,8 +20,6 @@ a smooth collaboration process.
 - Adhere to **clean code principles**, such as **SOLID**, **DRY**, and
   **KISS**. Avoid unnecessary complexity.
 - Use **Active Record** patterns for database interactions where applicable.
-- Limit the use of classes unless strictly necessary; prefer functions when
-  simpler and sufficient.
 - Keep contributions small and focused. One feature or fix per pull request.
 - Discuss significant changes or enhancements transparently by opening an
   issue first.
@@ -33,16 +31,8 @@ a smooth collaboration process.
 - Use **Ruff** as the linter and formatter (**Black** could be an alternative).
 - Write **NumPy-style docstrings** for all public functions, classes, attributes,
   and properties.
-- Commit messages and pull requests must follow specific prefixes:
-    - `ci:` for CI/CD changes.
-    - `test:` Update tests/* files.
-    - `dist:` Changes to dependencies, e.g. `requirements.txt`.
-    - `minor:` Small changes.
-    - `docs:` Updates to documentation. `doc` is also a valid prefix.
-    - `fix:` Bug fixes.
-    - `refactor:` Refactor of existing code.
-    - `nit:` Small code review changes mainly around style or syntax.
-    - `feat:` New features.
+- Commit messages and pull requests must follow specific prefixes described
+  [here](#commit-message-format).
 
 ## Your First Pull Request
 
@@ -185,4 +175,5 @@ Before submitting a pull request:
 5. Provide a clear and descriptive pull request title and description.
 
 Pull requests titles should be short and descriptive, and should not exceed
-72 characters. Also, must follow the specified commit message format.
+72 characters. Also, must follow the specified
+[commit message format](#commit-message-format).

README.md

@@ -26,9 +26,9 @@
 <!-- omit in toc -->
 # SQLActive
 
-SQLActive is a lightweight and asynchronous ActiveRecord-style wrapper for
-SQLAlchemy. Bring Django-like queries, automatic timestamps, nested eager
-loading, and serialization/deserialization for SQLAlchemy models.
+A lightweight and asynchronous ActiveRecord-style wrapper for SQLAlchemy.
+Brings Django-like queries, automatic timestamps, nested eager loading, and
+serialization/deserialization for SQLAlchemy models.
 
 Heavily inspired by
 [sqlalchemy-mixins](https://github.com/absent1706/sqlalchemy-mixins/).
@@ -40,18 +40,14 @@ Visit the [documentation website](https://daireto.github.io/sqlactive/).
 - [Features](#features)
 - [Requirements](#requirements)
 - [Installation](#installation)
-- [Usage](#usage)
-  - [1. Define the Models](#1-define-the-models)
-  - [2. Initialize the Database](#2-initialize-the-database)
-  - [3. Perform CRUD Operations](#3-perform-crud-operations)
-  - [4. Perform Bulk Operations](#4-perform-bulk-operations)
-  - [5. Perform Queries](#5-perform-queries)
-  - [6. Manage Timestamps](#6-manage-timestamps)
-  - [7. Serialization and Deserialization](#7-serialization-and-deserialization)
-- [Testing and Linting](#testing-and-linting)
-  - [Unit Tests](#unit-tests)
-  - [Coverage](#coverage)
-  - [Linting](#linting)
+- [Quick Start](#quick-start)
+    - [1. Define the Models](#1-define-the-models)
+    - [2. Initialize the Database](#2-initialize-the-database)
+    - [3. Perform CRUD Operations](#3-perform-crud-operations)
+    - [4. Perform Bulk Operations](#4-perform-bulk-operations)
+    - [5. Perform Queries](#5-perform-queries)
+    - [6. Manage Timestamps](#6-manage-timestamps)
+    - [7. Serialization and Deserialization](#7-serialization-and-deserialization)
 - [Documentation](#documentation)
 - [Contributing](#contributing)
 - [License](#license)
@@ -71,8 +67,9 @@ Visit the [documentation website](https://daireto.github.io/sqlactive/).
 
 ## Requirements
 
-- Python 3.10+
-- sqlalchemy 2.0+
+- `Python>=3.10`
+- `SQLAlchemy>=2.0.0`
+- `typing_extensions>=4.5.0 (for Python<3.11)`
 
 ## Installation
 
@@ -83,7 +80,7 @@ You can simply install sqlactive from
 pip install sqlactive
 ```
 
-## Usage
+## Quick Start
 
 ### 1. Define the Models
 
@@ -447,71 +444,6 @@ user = User.from_json(user_json)
 user.name  # John Doe
 ```
 
-## Testing and Linting
-
-### Unit Tests
-
-To run the tests, simply run the following command from the root directory:
-
-```bash
-python -m unittest discover -s tests -t .
-```
-
-To run a specific test, use the following command:
-
-```bash
-python -m unittest tests.<test_name>
-```
-
-**Available tests**
-- `test_active_record.py`
-- `test_async_query.py`
-- `test_db_connection.py`
-- `test_execute.py`
-- `test_inspection.py`
-- `test_serialization.py`
-- `test_smart_query.py`
-
-### Coverage
-
-First, install the `coverage` package:
-
-```bash
-pip install coverage
-```
-
-To check the coverage, run the following command:
-
-```bash
-python -m coverage run -m unittest discover -s tests -t .
-```
-
-To generate the coverage report, run the following command:
-
-```bash
-python -m coverage report -m
-```
-
-To generate the HTML report, run the following command:
-
-```bash
-python -m coverage html -d htmlcov
-```
-
-### Linting
-
-First, install the `ruff` package:
-
-```bash
-pip install ruff
-```
-
-To check the code style, run the following command:
-
-```bash
-python -m ruff check .
-```
-
 ## Documentation
 
 Find the complete documentation [here](https://daireto.github.io/sqlactive/).
@@ -522,7 +454,8 @@ Please read the [contribution guidelines](CONTRIBUTING.md).
 
 ## License
 
-This project is licensed under the [MIT License](LICENSE).
+This project is licensed under the MIT License - see the [LICENSE](LICENSE)
+file for details.
 
 ## Support
 

docs/about/contributing.md

@@ -20,8 +20,6 @@ a smooth collaboration process.
 - Adhere to **clean code principles**, such as **SOLID**, **DRY**, and
   **KISS**. Avoid unnecessary complexity.
 - Use **Active Record** patterns for database interactions where applicable.
-- Limit the use of classes unless strictly necessary; prefer functions when
-  simpler and sufficient.
 - Keep contributions small and focused. One feature or fix per pull request.
 - Discuss significant changes or enhancements transparently by opening an
   issue first.
@@ -33,16 +31,8 @@ a smooth collaboration process.
 - Use **Ruff** as the linter and formatter (**Black** could be an alternative).
 - Write **NumPy-style docstrings** for all public functions, classes, attributes,
   and properties.
-- Commit messages and pull requests must follow specific prefixes:
-    - `ci:` for CI/CD changes.
-    - `test:` Update tests/* files.
-    - `dist:` Changes to dependencies, e.g. `requirements.txt`.
-    - `minor:` Small changes.
-    - `docs:` Updates to documentation. `doc` is also a valid prefix.
-    - `fix:` Bug fixes.
-    - `refactor:` Refactor of existing code.
-    - `nit:` Small code review changes mainly around style or syntax.
-    - `feat:` New features.
+- Commit messages and pull requests must follow specific prefixes described
+  [here](#commit-message-format).
 
 ## Your First Pull Request
 
@@ -185,4 +175,5 @@ Before submitting a pull request:
 5. Provide a clear and descriptive pull request title and description.
 
 Pull requests titles should be short and descriptive, and should not exceed
-72 characters. Also, must follow the specified commit message format.
+72 characters. Also, must follow the specified
+[commit message format](#commit-message-format).

docs/api/async-query.md

@@ -226,14 +226,14 @@ async def execute() -> Result[Any]
 #### scalars
 
 ```python
-async def scalars() -> ScalarResult[_T]
+async def scalars() -> ScalarResult[T]
 ```
 
 > Returns a `sqlalchemy.engine.ScalarResult` instance containing all rows.
 
 > **Returns**
 
-> - `sqlalchemy.engine.ScalarResult[_T]`: Result instance containing
+> - `sqlalchemy.engine.ScalarResult[T]`: Result instance containing
 > all scalars.
 
 > **Examples**
@@ -256,7 +256,7 @@ async def scalars() -> ScalarResult[_T]
 #### first
 
 ```python
-async def first(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
+async def first(scalar: bool = True) -> T | Row[tuple[Any, ...]] | None
 ```
 
 > Fetches the first row or `None` if no results are found.
@@ -265,12 +265,12 @@ async def first(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
 
 > **Parameters**
 
-> - `scalar`: If `True`, returns a scalar value (`_T`),
+> - `scalar`: If `True`, returns a scalar value (`T`),
 > otherwise returns a row (default: `True`).
 
 > **Returns**
 
-> - `_T`: Instance for method chaining (scalar).
+> - `T`: Instance for method chaining (scalar).
 > - `sqlalchemy.engine.Row[tuple[Any, ...]]`: Row.
 > - `None`: If no result is found.
 
@@ -302,7 +302,7 @@ async def first(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
 #### one
 
 ```python
-async def one(scalar: bool = True) -> _T | Row[tuple[Any, ...]]
+async def one(scalar: bool = True) -> T | Row[tuple[Any, ...]]
 ```
 
 > Fetches one row or raises a `sqlalchemy.exc.NoResultFound` exception
@@ -315,12 +315,12 @@ async def one(scalar: bool = True) -> _T | Row[tuple[Any, ...]]
 
 > **Parameters**
 
-> - `scalar`: If `True`, returns a scalar value (`_T`),
+> - `scalar`: If `True`, returns a scalar value (`T`),
 > otherwise returns a row (default: `True`).
 
 > **Returns**
 
-> - `_T`: Instance for method chaining (scalar).
+> - `T`: Instance for method chaining (scalar).
 > - `sqlalchemy.engine.Row[tuple[Any, ...]]`: Row.
 
 > **Raises**
@@ -368,7 +368,7 @@ async def one(scalar: bool = True) -> _T | Row[tuple[Any, ...]]
 #### one_or_none
 
 ```python
-async def one_or_none(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
+async def one_or_none(scalar: bool = True) -> T | Row[tuple[Any, ...]] | None
 ```
 
 > Fetches one row or `None` if no results are found.
@@ -380,12 +380,12 @@ async def one_or_none(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
 
 > **Parameters**
 
-> - `scalar`: If `True`, returns a scalar value (`_T`),
+> - `scalar`: If `True`, returns a scalar value (`T`),
 > otherwise returns a row (default: `True`).
 
 > **Returns**
 
-> - `_T`: Instance for method chaining (scalar).
+> - `T`: Instance for method chaining (scalar).
 > - `sqlalchemy.engine.Row[tuple[Any, ...]]`: Row.
 > - `None`: If no result is found.
 
@@ -434,7 +434,7 @@ async def one_or_none(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
 #### all
 
 ```python
-async def all(scalars: bool = True) -> Sequence[_T] | Sequence[Row[tuple[Any, ...]]]
+async def all(scalars: bool = True) -> Sequence[T] | Sequence[Row[tuple[Any, ...]]]
 ```
 
 > Fetches all rows.
@@ -443,12 +443,12 @@ async def all(scalars: bool = True) -> Sequence[_T] | Sequence[Row[tuple[Any, ..
 
 > **Parameters**
 
-> - `scalars`: If `True`, returns scalar values (`Sequence[_T]`),
+> - `scalars`: If `True`, returns scalar values (`Sequence[T]`),
 > otherwise returns rows (default: `True`).
 
 > **Returns**
 
-> - `Sequence[_T]`: Instances (scalars).
+> - `Sequence[T]`: Instances (scalars).
 > - `Sequence[sqlalchemy.engine.Row[tuple[Any, ...]]]`: Rows.
 
 > **Examples**
@@ -501,7 +501,7 @@ async def count() -> int
 #### unique
 
 ```python
-async def unique(scalars: bool = True) -> ScalarResult[_T] | Result[tuple[Any, ...]]
+async def unique(scalars: bool = True) -> ScalarResult[T] | Result[tuple[Any, ...]]
 ```
 
 > Similar to [`scalars()`](#scalars) but applies unique filtering to
@@ -525,7 +525,7 @@ async def unique(scalars: bool = True) -> ScalarResult[_T] | Result[tuple[Any, .
 
 > **Returns**
 
-> - `sqlalchemy.engine.ScalarResult[_T]`: Result instance containing
+> - `sqlalchemy.engine.ScalarResult[T]`: Result instance containing
 > all scalars.
 > - `sqlalchemy.engine.Result[tuple[Any, ...]]`: Result instance containing
 > all rows.
@@ -546,7 +546,7 @@ async def unique(scalars: bool = True) -> ScalarResult[_T] | Result[tuple[Any, .
 #### unique_first
 
 ```python
-async def unique_first(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
+async def unique_first(scalar: bool = True) -> T | Row[tuple[Any, ...]] | None
 ```
 
 > Similar to [`first()`](#first) but applies unique filtering to
@@ -565,7 +565,7 @@ async def unique_first(scalar: bool = True) -> _T | Row[tuple[Any, ...]] | None
 #### unique_one
 
 ```python
-async def unique_one(scalar: bool) -> _T | Row[tuple[Any, ...]]
+async def unique_one(scalar: bool) -> T | Row[tuple[Any, ...]]
 ```
 
 > Similar to [`one()`](#one) but applies unique filtering to
@@ -584,7 +584,7 @@ async def unique_one(scalar: bool) -> _T | Row[tuple[Any, ...]]
 #### unique_one_or_none
 
 ```python
-async def unique_one_or_none(scalar: bool) -> _T | Row[tuple[Any, ...]] | None
+async def unique_one_or_none(scalar: bool) -> T | Row[tuple[Any, ...]] | None
 ```
 
 > Similar to [`one_or_none()`](#one_or_none) but applies unique filtering to
@@ -604,7 +604,7 @@ async def unique_one_or_none(scalar: bool) -> _T | Row[tuple[Any, ...]] | None
 #### unique_all
 
 ```python
-async def unique_all(scalars: bool) -> Sequence[_T] | Sequence[Row[tuple[Any, ...]]]
+async def unique_all(scalars: bool) -> Sequence[T] | Sequence[Row[tuple[Any, ...]]]
 ```
 
 > Similar to [`all()`](#all) but applies unique filtering to
@@ -1116,7 +1116,7 @@ def top(top: int) -> Self
 
 ```python
 def join(
-    *paths: EagerLoadPath, model: type[_T] | None = None
+    *paths: EagerLoadPath, model: type[T] | None = None
 ) -> Self
 ```
 
@@ -1170,7 +1170,7 @@ def join(
 
 ```python
 def with_subquery(
-    *paths: EagerLoadPath, model: type[_T] | None = None
+    *paths: EagerLoadPath, model: type[T] | None = None
 ) -> Self
 ```