Merge branch 'develop'

.github/workflows/ci.yml

@@ -27,9 +27,5 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - name: Install dependencies
-        run: pip install mkdocs-material mike
-      - name: Build site
-        run: mike deploy --push --update-aliases ${{ github.ref_name }} latest
-      - name: Set latest as default version
-        run: mike set-default --push latest
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -36,6 +36,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+htmlcov/
 
 # Environments
 .env

README.md

@@ -43,6 +43,9 @@ Documentation: https://daireto.github.io/sqlactive/
     - [5. Perform Queries](#5-perform-queries)
     - [6. Manage Timestamps](#6-manage-timestamps)
   - [Testing](#testing)
+    - [Unit Tests](#unit-tests)
+    - [Coverage](#coverage)
+    - [Lint](#lint)
   - [Documentation](#documentation)
   - [Contributing](#contributing)
   - [License](#license)
@@ -71,9 +74,18 @@ pip install sqlactive
 
 ### 1. Define the Models
 
-The `ActiveRecordBaseModel` class provides a base class for your models. It inherits from
-[`ActiveRecordMixin`](https://daireto.github.io/sqlactive/latest/pages/active_record_mixin/overview/)
-and [`TimestampMixin`](https://daireto.github.io/sqlactive/latest/pages/timestamp_mixin/).
+The `ActiveRecordBaseModel` class provides a base class for your models.
+
+It inherits from:
+
+* [`ActiveRecordMixin`](https://daireto.github.io/sqlactive/latest/pages/active_record_mixin/overview/): Provides a set of ActiveRecord-like
+    helper methods for interacting with the database.
+* [`TimestampMixin`](https://daireto.github.io/sqlactive/latest/pages/timestamp_mixin/): Adds the `created_at` and `updated_at` timestamp columns.
+* [`SerializationMixin`](https://daireto.github.io/sqlactive/latest/pages/serialization_mixin/): Provides serialization and deserialization methods.
+
+It is recommended to define a `BaseModel` class that inherits from
+`ActiveRecordBaseModel` and use it as the base class for all models
+as shown in the following example:
 
 ```python
 from sqlalchemy import String, ForeignKey
@@ -121,6 +133,10 @@ class Comment(BaseModel):
     user: Mapped['User'] = relationship(back_populates='comments')
 ```
 
+> [!WARNING]
+> When defining a `BaseModel` class, don't forget to set `__abstract__` to `True`
+> in the base class to avoid creating tables for the base class.
+
 > [!NOTE]
 > The models can directly inherit from the `ActiveRecordBaseModel` class:
 > ```python
@@ -130,14 +146,18 @@ class Comment(BaseModel):
 >     __tablename__ = 'users'
 >     # ...
 > ```
+> However, it is recommended to create a base class for your models and
+> inherit from it.
 
 > [!TIP]
-> If you don't want to implement automatic timestamps, your base model can inherit
-> from `ActiveRecordMixin` directly:
+> Your `BaseModel` class can also inherit directly from the mixins.
+> For example, if you don't want to implement automatic timestamps don't inherit
+> from `ActiveRecordBaseModel` class. Instead, inherit from `ActiveRecordMixin`
+> and/or `SerializationMixin`:
 > ```python
-> from sqlactive import ActiveRecordMixin
+> from sqlactive import ActiveRecordMixin, SerializationMixin
 >
-> class BaseModel(ActiveRecordMixin):
+> class BaseModel(ActiveRecordMixin, SerializationMixin):
 >     __abstract__ = True
 > ```
 
@@ -290,6 +310,8 @@ print(users)
 Perform simple and complex queries, eager loading, and dictionary serialization:
 
 ```python
+from sqlactive import JOINED, SUBQUERY
+
 user = await User.filter(name='John Doe').first()
 print(user)
 # <User #1>
@@ -389,6 +411,8 @@ print(user.updated_at)
 
 ## Testing
 
+### Unit Tests
+
 To run the tests, simply run the following command from the root directory:
 
 ```bash
@@ -401,12 +425,48 @@ To run a specific test, use the following command:
 python -m unittest tests.<test_name>
 ```
 
-Available tests:
+**Available tests:**
 - `test_active_record`
 - `test_inspection`
-- `test_base_model`
+- `test_serialization`
 - `test_smart_query`
 
+### 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 .
+python -m coverage report -m
+```
+
+To generate the coverage report, run the following command:
+
+```bash
+python -m coverage run -m unittest discover -s tests -t .
+python -m coverage html -d htmlcov
+```
+
+### Lint
+
+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/).

docs/contributing.md

@@ -34,10 +34,15 @@ a smooth collaboration process.
 - Write **NumPy-style docstrings** for all public functions, classes, attributes,
   and properties.
 - Commit messages and pull requests must follow specific prefixes:
-    - `fix:` for bug fixes.
-    - `feat:` for new features.
-    - `docs:` for documentation changes.
     - `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.
 
 ## Your First Pull Request
 
@@ -63,7 +68,7 @@ If this is your first pull request:
     ```bash
     pip install -r requirements.txt
     ```
-5. Install `Ruff`:
+5. Install `ruff`:
     ```bash
     pip install ruff
     ```
@@ -146,10 +151,15 @@ To suggest a feature:
 ### Commit Message Format
 
 - Use a prefix to categorize your commit:
-    - `fix: ` for bug fixes.
-    - `feat: ` for new features.
-    - `docs: ` for documentation changes.
-    - `ci: ` for CI/CD changes.
+    - `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.
 - Example:
     ```
     feat: add support for PostgreSQL database connections

docs/index.md

@@ -66,7 +66,17 @@ pip install sqlactive
 ### 1. Define the Models
 
 The `ActiveRecordBaseModel` class provides a base class for your models.
-It inherits from [`ActiveRecordMixin`](pages/active_record_mixin/overview.md) and [`TimestampMixin`](pages/timestamp_mixin.md).
+
+It inherits from:
+
+* [`ActiveRecordMixin`](https://daireto.github.io/sqlactive/latest/pages/active_record_mixin/overview/): Provides a set of ActiveRecord-like
+    helper methods for interacting with the database.
+* [`TimestampMixin`](https://daireto.github.io/sqlactive/latest/pages/timestamp_mixin/): Adds the `created_at` and `updated_at` timestamp columns.
+* [`SerializationMixin`](https://daireto.github.io/sqlactive/latest/pages/serialization_mixin/): Provides serialization and deserialization methods.
+
+It is recommended to define a `BaseModel` class that inherits from
+`ActiveRecordBaseModel` and use it as the base class for all models
+as shown in the following example:
 
 ```python
 from sqlalchemy import String, ForeignKey
@@ -114,6 +124,11 @@ class Comment(BaseModel):
     user: Mapped['User'] = relationship(back_populates='comments')
 ```
 
+!!! warning
+
+    When defining a `BaseModel` class, don't forget to set `__abstract__` to `True`
+    in the base class to avoid creating tables for the base class.
+
 !!! note
 
     The models can directly inherit from the `ActiveRecordBaseModel` class:
@@ -125,14 +140,19 @@ class Comment(BaseModel):
         # ...
     ```
 
+    However, it is recommended to create a base class for your models and
+    inherit from it.
+
 !!! tip
 
-    If you don't want to implement automatic timestamps, your base model can inherit
-    from [`ActiveRecordMixin`](pages/active_record_mixin/overview.md) directly:
+    Your `BaseModel` class can also inherit directly from the mixins.
+    For example, if you don't want to implement automatic timestamps don't inherit
+    from `ActiveRecordBaseModel` class. Instead, inherit from `ActiveRecordMixin`
+    and/or `SerializationMixin`:
 
     ```python
-    from sqlactive import ActiveRecordMixin
-    class BaseModel(ActiveRecordMixin):
+    from sqlactive import ActiveRecordMixin, SerializationMixin
+    class BaseModel(ActiveRecordMixin, SerializationMixin):
         __abstract__ = True
     ```
 
@@ -294,6 +314,8 @@ print(users)
 Perform simple and complex queries, eager loading, and dictionary serialization:
 
 ```python
+from sqlactive import JOINED, SUBQUERY
+
 user = await User.filter(name='John Doe').first()
 print(user)
 # <User #1>