Merge branch 'develop'

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <img src="https://raw.githubusercontent.com/Daireto/sqlactive/main/docs/images/logo.jpg" alt="SQLActive" />
+    <img src="docs/images/logo.png" alt="SQLActive" />
 </p>
 
 <p align="center">
@@ -12,12 +12,12 @@
     <a href="https://pypi.org/project/SQLAlchemy" target="_blank">
         <img src="https://img.shields.io/badge/SQLAlchemy-2.0%2B-orange" alt="Supported SQLAlchemy versions">
     </a>
-    <a href='https://coveralls.io/github/daireto/sqlactive?branch=main'>
-        <img src='https://coveralls.io/repos/github/daireto/sqlactive/badge.svg?branch=main' alt='Coverage Status' />
-    </a>
     <a href="[/LICENSE](https://github.com/astral-sh/ruff)" target="_blank">
         <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
     </a>
+    <a href='https://coveralls.io/github/daireto/sqlactive?branch=main'>
+        <img src='https://coveralls.io/repos/github/daireto/sqlactive/badge.svg?branch=main' alt='Coverage Status' />
+    </a>
     <a href="/LICENSE" target="_blank">
         <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
     </a>
@@ -44,7 +44,8 @@ Documentation: https://daireto.github.io/sqlactive/
     - [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)
+    - [6. Perform Native Queries](#6-perform-native-queries)
+    - [7. Manage Timestamps](#7-manage-timestamps)
   - [Testing](#testing)
     - [Unit Tests](#unit-tests)
     - [Coverage](#coverage)
@@ -198,14 +199,17 @@ async with async_engine.begin() as conn:
 The use of the `expire_on_commit` flag is explained in the warning of [this section](#4-perform-bulk-operations).
 
 > [!TIP]
-> Use the `DBConnection` class as a shortcut to initialize the database:
+> Use the `DBConnection` class as a shortcut to initialize the database.
+> The `DBConnection` class is a wrapper around the `async_engine`, `async_sessionmaker`
+> and `async_scoped_session` objects:
 > ```python
 > from sqlactive import DBConnection
 >
 > DATABASE_URL = 'sqlite+aiosqlite://'
 > conn = DBConnection(DATABASE_URL, echo=False)
 > await conn.init_db(BaseModel)
 > ```
+> See the [DB Connection Helper](https://daireto.github.io/sqlactive/latest/pages/db_connection_helper/) section for more information.
 
 ### 3. Perform CRUD Operations
 
@@ -390,7 +394,42 @@ for more details.
 > Check the [`ActiveRecordMixin` API Reference](https://daireto.github.io/sqlactive/latest/pages/active_record_mixin/api_reference/)
 > class to see all the available methods.
 
-### 6. Manage Timestamps
+### 6. Perform Native Queries
+
+Perform native SQLAlchemy queries using the `execute` method:
+
+```python
+    from sqlalchemy import select, func
+    from sqlactive import execute
+
+    query = select(User.age, func.count(User.id)).group_by(User.age)
+    result = await execute(query)
+    # [(20, 1), (22, 4), (25, 12)]
+```
+
+If your base model is not `ActiveRecordBaseModel` you must pass your base
+model class to the `base_model` argument of the `execute` method:
+
+```python
+    from sqlalchemy import select, func
+    from sqlactive import ActiveRecordBaseModel, execute
+
+    # Note that it does not matter if your base model
+    # inherits from `ActiveRecordBaseModel`, you still
+    # need to pass it to this method
+    class BaseModel(ActiveRecordBaseModel):
+        __abstract__ = True
+
+    class User(BaseModel):
+        __tablename__ = 'users'
+        # ...
+
+    query = select(User.age, func.count(User.id)).group_by(User.age)
+    result = await execute(query, BaseModel)
+    # [(20, 1), (22, 4), (25, 12)]
+```
+
+### 7. Manage Timestamps
 
 Timestamps (`created_at` and `updated_at`) are automatically managed:
 

docs/contributing.md

@@ -3,6 +3,26 @@
 Thank you for your interest in contributing to SQLActive! Please take a
 moment to review this document before submitting a pull request.
 
+**Table of Contents**
+
+- [Contributing Guidelines](#contributing-guidelines)
+  - [Why should you read these guidelines?](#why-should-you-read-these-guidelines)
+  - [Ground Rules](#ground-rules)
+    - [Responsibilities](#responsibilities)
+    - [Tools and Workflow](#tools-and-workflow)
+  - [Your First Pull Request](#your-first-pull-request)
+    - [Getting Started](#getting-started)
+    - [Setup Instructions](#setup-instructions)
+  - [Reporting Issues](#reporting-issues)
+    - [Security Issues](#security-issues)
+    - [Filing a Bug Report](#filing-a-bug-report)
+  - [Suggesting Features or Enhancements](#suggesting-features-or-enhancements)
+  - [Code Conventions](#code-conventions)
+    - [Code Style](#code-style)
+    - [Commit Message Format](#commit-message-format)
+    - [Pull Request Checklist](#pull-request-checklist)
+  - [Thank You!](#thank-you)
+
 ## Why should you read these guidelines?
 
 Following these guidelines ensures that your contributions align with
@@ -28,7 +48,7 @@ a smooth collaboration process.
 - Be respectful and welcoming. Follow the
   [Python Community Code of Conduct](https://www.python.org/psf/codeofconduct/).
 
-### Tools & Workflow
+### Tools and Workflow
 
 - Use **Ruff** as the linter and formatter (**Black** could be an alternative).
 - Write **NumPy-style docstrings** for all public functions, classes, attributes,

docs/index.md

@@ -1,5 +1,5 @@
 <p align="center">
-    <img src="https://raw.githubusercontent.com/Daireto/sqlactive/main/docs/images/logo.jpg" alt="SQLActive" />
+    <img src="images/logo.png" alt="SQLActive" />
 </p>
 
 <p align="center">
@@ -18,6 +18,9 @@
     <a href="[/LICENSE](https://github.com/astral-sh/ruff)" target="_blank">
         <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff">
     </a>
+    <a href='https://coveralls.io/github/daireto/sqlactive?branch=main'>
+        <img src='https://coveralls.io/repos/github/daireto/sqlactive/badge.svg?branch=main' alt='Coverage Status' />
+    </a>
     <a href="/LICENSE" target="_blank">
         <img src="https://img.shields.io/badge/License-MIT-green" alt="License">
     </a>
@@ -42,7 +45,8 @@ The source code for this project is available on [GitHub](https://github.com/dai
     - [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)
+    - [6. Perform Native Queries](#6-perform-native-queries)
+    - [7. Manage Timestamps](#7-manage-timestamps)
   - [License](#license)
 
 ## Features
@@ -194,7 +198,9 @@ The use of the `expire_on_commit` flag is explained in the warning of [this sect
 
 !!! tip
 
-    Use the `DBConnection` class as a shortcut to initialize the database:
+    Use the `DBConnection` class as a shortcut to initialize the database.
+    The `DBConnection` class is a wrapper around the `async_engine`, `async_sessionmaker`
+    and `async_scoped_session` objects:
 
     ```python
     from sqlactive import DBConnection
@@ -204,6 +210,8 @@ The use of the `expire_on_commit` flag is explained in the warning of [this sect
     await conn.init_db(BaseModel)
     ```
 
+    See the [DB Connection Helper](pages/db_connection_helper.md) section for more information.
+
 ### 3. Perform CRUD Operations
 
 ```python
@@ -395,7 +403,42 @@ See the [low-level SmartQueryMixin methods](pages/smart_query_mixin.md#api-refer
 
     Check the [`ActiveRecordMixin` API Reference](pages/active_record_mixin/api_reference.md) class to see all the available methods.
 
-### 6. Manage Timestamps
+### 6. Perform Native Queries
+
+Perform native SQLAlchemy queries using the `execute` method:
+
+```python
+    from sqlalchemy import select, func
+    from sqlactive import execute
+
+    query = select(User.age, func.count(User.id)).group_by(User.age)
+    result = await execute(query)
+    # [(20, 1), (22, 4), (25, 12)]
+```
+
+If your base model is not `ActiveRecordBaseModel` you must pass your base
+model class to the `base_model` argument of the `execute` method:
+
+```python
+    from sqlalchemy import select, func
+    from sqlactive import ActiveRecordBaseModel, execute
+
+    # Note that it does not matter if your base model
+    # inherits from `ActiveRecordBaseModel`, you still
+    # need to pass it to this method
+    class BaseModel(ActiveRecordBaseModel):
+        __abstract__ = True
+
+    class User(BaseModel):
+        __tablename__ = 'users'
+        # ...
+
+    query = select(User.age, func.count(User.id)).group_by(User.age)
+    result = await execute(query, BaseModel)
+    # [(20, 1), (22, 4), (25, 12)]
+```
+
+### 7. Manage Timestamps
 
 Timestamps (`created_at` and `updated_at`) are automatically managed: