Merge branch 'main' into dependabot-conf

.github/workflows/ci.yml

@@ -51,9 +51,9 @@ jobs:
         with:
           fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
       - name: Download Artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
-          name: coverage-xml
+          name: coverage-data
 
       - name: Fix coverage file for sonarcloud
         run: sed -i "s/home\/runner\/work\/advanced-alchemy\/advanced-alchemy/github\/workspace/g" coverage.xml
@@ -119,7 +119,7 @@ jobs:
         run: echo $PR_NUMBER > .pr_number
 
       - name: Upload artifact
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: docs-preview
           path: |
@@ -137,7 +137,7 @@ jobs:
           python-version: "3.12"
 
       - name: Download Artifacts
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: coverage-data
 
@@ -148,7 +148,7 @@ jobs:
           python -Im coverage xml -i
 
       - name: Fix coverage file name
-        run: sed -i "s/home\/runner\/work\/litestar\/advanced-alchemy/github\/workspace/g" coverage.xml
+        run: sed -i "s/home\/runner\/work\/advanced-alchemy\/advanced-alchemy/github\/workspace/g" coverage.xml
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v4

Makefile

@@ -175,3 +175,7 @@ docs-serve: docs-clean 								## Serve the docs locally
 docs: docs-clean 									## Dump the existing built docs and rebuild them
 	@echo "=> Building documentation"
 	@$(ENV_PREFIX)sphinx-build -M html docs docs/_build/ -E -a -j auto --keep-going
+
+changelog:
+	@echo "=> Generating changelog"
+	@$(ENV_PREFIX)git-cliff -c pyproject.toml -o docs/changelog.rst --github-repo litestar-org/advanced-alchemy --github-token $(GITHUB_TOKEN)

advanced_alchemy/base.py

@@ -219,7 +219,11 @@ def to_dict(self, exclude: set[str] | None = None) -> dict[str, Any]:
             dict[str, Any]: A dict representation of the model
         """
         exclude = {"sa_orm_sentinel", "_sentinel"}.union(self._sa_instance_state.unloaded).union(exclude or [])  # type: ignore[attr-defined]
-        return {field.name: getattr(self, field.name) for field in self.__table__.columns if field.name not in exclude}
+        return {
+            field: getattr(self, field)
+            for field in self.__mapper__.columns.keys()  # noqa: SIM118
+            if field not in exclude
+        }
 
 
 @declarative_mixin

advanced_alchemy/types/guid.py

@@ -17,7 +17,7 @@
 UUID_UTILS_INSTALLED = find_spec("uuid_utils")
 
 
-class GUID(TypeDecorator):
+class GUID(TypeDecorator[UUID]):
     """Platform-independent GUID type.
 
     Uses PostgreSQL's UUID type (Postgres, DuckDB, Cockroach),

docs/conf.py

@@ -2,17 +2,21 @@
 from __future__ import annotations
 
 import os
+import warnings
 from datetime import datetime
 from functools import partial
 from typing import TYPE_CHECKING, Any
 
+from sqlalchemy.exc import SAWarning
+
 from advanced_alchemy.__metadata__ import __project__, __version__
 
 if TYPE_CHECKING:
     from sphinx.addnodes import document
     from sphinx.application import Sphinx
 
 # -- Environmental Data ------------------------------------------------------
+warnings.filterwarnings("ignore", category=SAWarning)
 
 # -- Project information -----------------------------------------------------
 current_year = datetime.now().year  # noqa: DTZ005
@@ -183,9 +187,9 @@
             "title": "Release notes",
             "children": [
                 {
-                    "title": "1.x Changelog",
+                    "title": "Changelog",
                     "url": "changelog",
-                    "summary": "All changes in the 2.x series",
+                    "summary": "All changes for Advanced Alchemy",
                 },
             ],
         },

docs/getting-started.rst

@@ -0,0 +1,55 @@
+===============
+Getting Started
+===============
+
+Advanced Alchemy is a carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy,
+offering useful and easy-to-use features for your database projects.
+
+.. seealso:: It is built on:
+
+    * `SQLAlchemy <https://www.sqlalchemy.org/>`_
+    * `msgspec <https://jcristharif.com/msgspec/>`_
+    * `Alembic <https://alembic.sqlalchemy.org/en/latest/>`_
+    * `Typing Extensions <https://typing-extensions.readthedocs.io/en/latest/>`_
+
+Installation
+------------
+
+Installing ``advanced-alchemy`` is as easy as calling your favorite Python package manager:
+
+.. tab-set::
+
+    .. tab-item:: pip
+        :sync: key1
+
+        .. code-block:: bash
+            :caption: Using pip
+
+            python3 -m pip install advanced-alchemy
+
+    .. tab-item:: pipx
+        :sync: key2
+
+        .. code-block:: bash
+            :caption: Using `pipx <https://pypa.github.io/pipx/>`_
+
+            pipx install advanced-alchemy
+
+    .. tab-item:: pdm
+
+        .. code-block:: bash
+            :caption: Using `PDM <https://pdm.fming.dev/>`_
+
+            pdm add advanced-alchemy
+
+    .. tab-item:: Poetry
+
+        .. code-block:: bash
+            :caption: Using `Poetry <https://python-poetry.org/>`_
+
+            poetry add advanced-alchemy
+
+Usage
+-----
+
+.. todo:: Add usage instructions

docs/index.rst

@@ -1,70 +1,152 @@
-================
-Advanced Alchemy
-================
+:layout: landing
+:description: Advanced Alchemy is a carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy, offering useful and easy-to-use features for your database projects.
 
-Advanced Alchemy is a carefully crafted, thoroughly tested, optimized companion library for SQLAlchemy,
-offering useful and easy-to-use features for your database projects.
+.. container::
+    :name: home-head
 
-.. seealso:: It is built on:
+    .. image:: https://raw.githubusercontent.com/litestar-org/branding/main/assets/Branding%20-%20SVG%20-%20Transparent/Badge%20-%20Blue%20and%20Yellow.svg
+        :alt: Litestar - Advanced Alchemy
+        :width: 400
+        :height: 400
 
-    * `SQLAlchemy <https://www.sqlalchemy.org/>`_
-    * `msgspec <https://jcristharif.com/msgspec/>`_
-    * `Alembic <https://alembic.sqlalchemy.org/en/latest/>`_
-    * `Typing Extensions <https://typing-extensions.readthedocs.io/en/latest/>`_
+    .. container::
 
-Installation
-------------
+        .. raw:: html
 
-Installing ``advanced-alchemy`` is as easy as calling your favorite Python package manager:
+            <h1>Advanced Alchemy</h1>
 
-.. tab-set::
+        .. container:: badges
+           :name: badges
 
-    .. tab-item:: pip
-        :sync: key1
+            .. image:: https://img.shields.io/github/actions/workflow/status/litestar-org/advanced-alchemy/publish.yml?labelColor=202235&logo=github&logoColor=edb641&label=Release
+               :alt: GitHub Actions Latest Release Workflow Status
 
-        .. code-block:: bash
-            :caption: Using pip
+            .. image:: https://img.shields.io/github/actions/workflow/status/litestar-org/advanced-alchemy/ci.yml?labelColor=202235&logo=github&logoColor=edb641&label=Tests%20And%20Linting
+               :alt: GitHub Actions CI Workflow Status
 
-            python3 -m pip install advanced-alchemy
+            .. image:: https://img.shields.io/github/actions/workflow/status/litestar-org/advanced-alchemy/docs.yml?labelColor=202235&logo=github&logoColor=edb641&label=Docs%20Build
+               :alt: GitHub Actions Docs Build Workflow Status
 
-    .. tab-item:: pipx
-        :sync: key2
+            .. image:: https://img.shields.io/codecov/c/github/litestar-org/advanced-alchemy?labelColor=202235&logo=codecov&logoColor=edb641&label=Coverage
+               :alt: Coverage
 
-        .. code-block:: bash
-            :caption: Using `pipx <https://pypa.github.io/pipx/>`_
+            .. image:: https://img.shields.io/pypi/v/advanced-alchemy?labelColor=202235&color=edb641&logo=python&logoColor=edb641
+               :alt: PyPI Version
 
-            pipx install advanced-alchemy
+            .. image:: https://img.shields.io/pypi/dm/advanced-alchemy?logo=python&label=advanced-alchemy%20downloads&labelColor=202235&color=edb641&logoColor=edb641
+               :alt: PyPI Downloads
 
-    .. tab-item:: pdm
+            .. image:: https://img.shields.io/pypi/pyversions/advanced-alchemy?labelColor=202235&color=edb641&logo=python&logoColor=edb641
+               :alt: Supported Python Versions
 
-        .. code-block:: bash
-            :caption: Using `PDM <https://pdm.fming.dev/>`_
+.. rst-class:: lead
 
-            pdm add advanced-alchemy
+    Advanced Alchemy is a carefully crafted, thoroughly tested, optimized companion library for
+    :doc:`SQLAlchemy <sqlalchemy:index>`, offering useful and easy-to-use features for your database projects.
 
-    .. tab-item:: Poetry
+.. container:: buttons
 
-        .. code-block:: bash
-            :caption: Using `Poetry <https://python-poetry.org/>`_
+    :doc:`Get Started <getting-started>`
+    `Usage Docs <usage>`_
+    `API Docs <reference>`_
+    `Blog <https://blog.litestar.dev>`_
 
-            poetry add advanced-alchemy
+.. grid:: 1 1 2 2
+    :padding: 0
+    :gutter: 2
 
-Usage
------
+    .. grid-item-card:: :octicon:`versions` Changelog
+      :link: changelog
+      :link-type: doc
 
-.. todo:: Add usage instructions
+      The latest updates and enhancements to Advanced-Alchemy
+
+    .. grid-item-card:: :octicon:`comment-discussion` Discussions
+      :link: https://github.com/litestar-org/advanced-alchemy/discussions
+
+      Join discussions, pose questions, or share insights.
+
+    .. grid-item-card:: :octicon:`issue-opened` Issues
+      :link: https://github.com/litestar-org/advanced-alchemy/issues
+
+      Report issues or suggest new features.
+
+    .. grid-item-card:: :octicon:`beaker` Contributing
+      :link: contribution-guide
+      :link-type: doc
+
+      Contribute to Litestar's growth with code, docs, and more.
+
+Sponsors
+--------
+
+.. rst-class:: lead
+
+   Litestar is a community-driven, open-source initiative that thrives on the generous contributions of our sponsors,
+   enabling us to pursue innovative developments and continue our mission to provide exceptional tools and resources
+   to our users.
+
+
+A huge thank you to our current sponsors:
+
+.. container::
+   :name: sponsors-section
+
+   .. grid:: 3
+      :class-row: surface
+      :padding: 0
+      :gutter: 2
+
+      .. grid-item-card::
+         :link: https://github.com/scalar/scalar
+
+         .. image:: https://raw.githubusercontent.com/litestar-org/branding/main/assets/sponsors/scalar.svg
+            :alt: Scalar.com
+            :class: sponsor
+
+         `Scalar.com <https://github.com/scalar/scalar>`_
+
+      .. grid-item-card::
+         :link: https://telemetrysports.com/
+
+         .. image:: https://raw.githubusercontent.com/litestar-org/branding/main/assets/sponsors/telemetry-sports/unofficial-telemetry-whitebg.svg
+            :alt: Telemetry Sports
+            :class: sponsor
+
+         `Telemetry Sports <https://telemetrysports.com/>`_
+
+      .. grid-item-card::
+         :link: https://www.stok.kr/
+
+         .. image:: https://avatars.githubusercontent.com/u/144093421
+            :alt: Stok
+            :class: sponsor
+
+         `Stok <https://www.stok.kr/>`_
+
+We invite organizations and individuals to join our sponsorship program.
+By becoming a sponsor on platforms like `Polar <sponsor-polar_>`_, `GitHub <sponsor-github_>`_
+and `Open Collective <sponsor-oc_>`_, you can play a pivotal role in our project's growth.
+
+On top of regular sponsorship, we engage in pledge-based sponsorship opportunities through `Polar <sponsor-polar_>`_,
+where you can pledge an amount towards an issue or feature you would like to see implemented.
+
+.. _sponsor-github: https://github.com/sponsors/litestar-org
+.. _sponsor-oc: https://opencollective.com/litestar
+.. _sponsor-polar: https://polar.sh/litestar-org
 
 .. toctree::
     :titlesonly:
     :caption: Documentation
     :hidden:
 
+    getting-started
     usage/index
     reference/index
 
 .. toctree::
     :titlesonly:
-    :caption: Development
+    :caption: Contributing
     :hidden:
 
     changelog