chore: updated README.md (#53)

Co-authored-by: Jacob Coffee <jacob@z7x.org>
litestar-org · Oct 15, 2023 · 406d83a · 406d83a
1 parent c93f17e
commit 406d83a
Show file tree

Hide file tree

Showing 6 changed files with 356 additions and 301 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -39,7 +39,7 @@ repos:
       - id: black
         args: [--config=./pyproject.toml]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.5.1"
+    rev: "v1.6.0"
     hooks:
       - id: mypy
         exclude: "docs"
@@ -70,6 +70,6 @@ repos:
             "litestar[cli]",
           ]
   - repo: https://github.com/sphinx-contrib/sphinx-lint
-    rev: "v0.6.8"
+    rev: "v0.7.0"
     hooks:
       - id: sphinx-lint
diff --git a/README.md b/README.md
@@ -44,25 +44,92 @@ offering features such as:
 
 ## Usage
 
+### Installation
+
+```shell
+pip install advanced-alchemy
+```
+
 > [!IMPORTANT]\
 > Check out [the installation guide][install-guide] in our official documentation!
 
-### Litestar
+### Repositories
+
+Advanced Alchemy includes a set of asynchronous and synchronous repository classes for easy CRUD operations on your SQLAlchemy models.
 
 ```python
-from advanced_alchemy.extensions.litestar.plugins import SQLAlchemyPlugin
-from advanced_alchemy.extensions.litestar.plugins.init.config import SQLAlchemyAsyncConfig
+from advanced_alchemy.base import UUIDBase
+from advanced_alchemy.repository import SQLAlchemySyncRepository
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Mapped, Session, sessionmaker
+
+class User(UUIDBase):
+    # you can optionally override the generated table name by manually setting it.
+    __tablename__ = "user_account"  # type: ignore[assignment]
+    email: Mapped[str]
+    name: Mapped[str]
+
+class UserRepository(SQLAlchemySyncRepository[User]):
+    """User repository."""
+
+    model_type = User
+
+# use any compatible sqlalchemy engine.
+engine = create_engine("duckdb:///:memory:")
+session_factory = sessionmaker(engine, expire_on_commit=False)
+
+with session_factory() as db_session:
+  repo = UserRepository(session=db_session)
+  bulk_users = [
+    {email: 'cody@advanced-alchemy.dev','name': 'Cody'},
+    {email: 'janek@advanced-alchemy.dev','name': 'Janek'},
+    {email: 'peter@advanced-alchemy.dev','name': 'Peter'},
+    {email: 'jacob@advanced-alchemy.dev','name': 'Jacob'}
+  ]
+  objs = repo.add_many([User(**raw_user) for raw_user in bulk_users])
+  db_session.commit()
+  print(f"Created {len(objs)} new objects.")
+
+  # 2) Select paginated data and total row count.  Pass additional filters as kwargs
+  created_objs, total_objs = repo.list_and_count(name="Cody", LimitOffset(limit=10, offset=0))
+  print(f"Selected {len(created_objs)} records out of a total of {total_objs}.")
+
+  # 3) Let's remove the batch of records selected.
+  deleted_objs = repo.delete_many([new_obj.id for new_obj in created_objs])
+  print(f"Removed {len(deleted_objs)} records out of a total of {total_objs}.")
+
+  # 4) Let's count the remaining rows
+  remaining_count = repo.count()
+  print(f"Found {remaining_count} remaining records after delete.")
+```
 
-from litestar import Litestar
+For a full standalone example, see the sample [here][standalone-example]
+
+### Web Frameworks
+
+Advanced Alchemy works with nearly all Python web frameworks. Several helpers for popular libraries are included, and additional PRs to support others are welcomed.
 
-plugin = SQLAlchemyPlugin(config=SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///test.sqlite"))
+#### Litestar
 
+Advanced Alchemy is the official SQLAlchemy integration for Litsetar.
 
-app = Litestar(plugins=[plugin])
+In addition to installed with `pip install advanced-alchemy`, it can also be installed installed as a Litestar extra with `pip install litestar[sqlalchemy]`.
 
+```python
+from advanced_alchemy.extensions.litestar.plugins import SQLAlchemyPlugin
+from advanced_alchemy.extensions.litestar.plugins.init.config import SQLAlchemyAsyncConfig
+
+from litestar import Litestar
+
+alchemy = SQLAlchemyPlugin(
+  config=SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///test.sqlite"),
+)
+app = Litestar(plugins=[alchemy])
 ```
 
-### FastAPI
+For a full Litestar example, check [here][litestar-example]
+
+#### FastAPI
 
 ```python
 from fastapi import FastAPI
@@ -76,7 +143,9 @@ alchemy = StarletteAdvancedAlchemy(
 )
 ```
 
-### Starlette
+For a full CRUD example, see [here][fastapi-example]
+
+#### Starlette
 
 ```python
 from starlette.applications import Starlette
@@ -90,7 +159,7 @@ alchemy = StarletteAdvancedAlchemy(
 )
 ```
 
-### Sanic
+#### Sanic
 
 ```python
 from sanic import Sanic
@@ -132,3 +201,6 @@ or the [project-specific GitHub discussions page][project-discussions].
 [project-discussions]: https://github.com/jolt-org/advanced-alchemy/discussions
 [project-docs]: https://docs.advanced-alchemy.jolt.rs
 [install-guide]: https://docs.advanced-alchemy.jolt.rs/latest/#installation
+[fastapi-example]: https://github.com/jolt-org/advanced-alchemy/blob/main/examples/fastapi.py
+[litestar-example]: https://github.com/jolt-org/advanced-alchemy/blob/main/examples/litestar.py
+[standalone-example]: https://github.com/jolt-org/advanced-alchemy/blob/main/examples/standalone.py
diff --git a/advanced_alchemy/repository/_sync.py b/advanced_alchemy/repository/_sync.py
@@ -152,11 +152,11 @@ def add(
         Args:
             data: Instance to be added to the collection.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_refresh: Refresh object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_refresh <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_refresh <SQLAlchemyAsyncRepository>`
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
 
         Returns:
             The added instance.
@@ -179,9 +179,9 @@ def add_many(
         Args:
             data: list of Instances to be added to the collection.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
 
         Returns:
             The added instances.
@@ -205,9 +205,9 @@ def delete(
         Args:
             item_id: Identifier of instance to be deleted.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
             id_attribute: Allows customization of the unique identifier to use for model fetching.
                 Defaults to `id`, but can reference any surrogate or candidate key for the table.
 
@@ -237,9 +237,9 @@ def delete_many(
         Args:
             item_ids: Identifier of instance to be deleted.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
             id_attribute: Allows customization of the unique identifier to use for model fetching.
                 Defaults to `id`, but can reference any surrogate or candidate key for the table.
             chunk_size: Allows customization of the ``insertmanyvalues_max_parameters`` setting for the driver.
@@ -355,9 +355,9 @@ def get(
         Args:
             item_id: Identifier of the instance to be retrieved.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             id_attribute: Allows customization of the unique identifier to use for model fetching.
                 Defaults to `id`, but can reference any surrogate or candidate key for the table.
 
@@ -386,9 +386,9 @@ def get_one(
 
         Args:
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             **kwargs: Identifier of the instance to be retrieved.
 
         Returns:
@@ -415,9 +415,9 @@ def get_one_or_none(
 
         Args:
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             **kwargs: Identifier of the instance to be retrieved.
 
         Returns:
@@ -455,11 +455,11 @@ def get_or_create(
                 dictionary containing flags to indicate a more specific set of
                 FOR UPDATE flags for the SELECT
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_refresh: Refresh object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_refresh <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_refresh <SQLAlchemyAsyncRepository>`
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
             **kwargs: Identifier of the instance to be retrieved.
 
         Returns:
@@ -502,11 +502,11 @@ def get_or_upsert(
                 dictionary containing flags to indicate a more specific set of
                 FOR UPDATE flags for the SELECT
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_refresh: Refresh object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_refresh <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_refresh <SQLAlchemyAsyncRepository>`
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
             **kwargs: Identifier of the instance to be retrieved.
 
         Returns:
@@ -555,7 +555,7 @@ def count(
         Args:
             *filters: Types for specific filtering operations.
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             **kwargs: Instance attribute value filters.
 
         Returns:
@@ -591,11 +591,11 @@ def update(
                 dictionary containing flags to indicate a more specific set of
                 FOR UPDATE flags for the SELECT
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_refresh: Refresh object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_refresh <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_refresh <SQLAlchemyAsyncRepository>`
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
             id_attribute: Allows customization of the unique identifier to use for model fetching.
                 Defaults to `id`, but can reference any surrogate or candidate key for the table.
 
@@ -640,9 +640,9 @@ def update_many(
             data: A list of instances to update.  Each should have a value for `self.id_attribute` that exists in the
                 collection.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
 
         Returns:
             The updated instances.
@@ -691,9 +691,9 @@ def list_and_count(
         Args:
             *filters: Types for specific filtering operations.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             force_basic_query_mode: Force list and count to use two queries instead of an analytical window function.
             **kwargs: Instance attribute value filters.
 
@@ -744,9 +744,9 @@ def _list_and_count_window(
         Args:
             *filters: Types for specific filtering operations.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             **kwargs: Instance attribute value filters.
 
         Returns:
@@ -780,9 +780,9 @@ def _list_and_count_basic(
         Args:
             *filters: Types for specific filtering operations.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             **kwargs: Instance attribute value filters.
 
         Returns:
@@ -831,11 +831,11 @@ def upsert(
                 dictionary containing flags to indicate a more specific set of
                 FOR UPDATE flags for the SELECT
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_refresh: Refresh object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_refresh <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_refresh <SQLAlchemyAsyncRepository>`
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
 
         Returns:
             The updated or created instance.
@@ -890,11 +890,11 @@ def upsert_many(
                 existing instance exists is the value of an attribute on ``data`` named as value of
                 :attr:`~advanced_alchemy.repository.AbstractAsyncRepository.id_attribute`.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`.
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`.
             auto_commit: Commit objects before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
             no_merge: Skip the usage of optimized Merge statements
-                :class:`SQLAlchemySyncRepository.auto_commit <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_commit <SQLAlchemyAsyncRepository>`
 
         Returns:
             The updated or created instance.
@@ -944,9 +944,9 @@ def list(
         Args:
             *filters: Types for specific filtering operations.
             auto_expunge: Remove object from session before returning. Defaults to
-                :class:`SQLAlchemySyncRepository.auto_expunge <SQLAlchemySyncRepository>`
+                :class:`SQLAlchemyAsyncRepository.auto_expunge <SQLAlchemyAsyncRepository>`
             statement: To facilitate customization of the underlying select query.
-                Defaults to :class:`SQLAlchemySyncRepository.statement <SQLAlchemySyncRepository>`
+                Defaults to :class:`SQLAlchemyAsyncRepository.statement <SQLAlchemyAsyncRepository>`
             **kwargs: Instance attribute value filters.
 
         Returns: