From 9b8cfcc17db619481c37f00786368872195875db Mon Sep 17 00:00:00 2001 From: Alexander Pozhidaev Date: Wed, 30 Jul 2025 10:28:45 +0300 Subject: [PATCH 1/2] add docs for QSet filters --- docs/filters_usage.md | 109 ++++++++++++++++++++++++++++++++++++ docs/img/author_db_data.png | Bin 0 -> 34736 bytes docs/img/book_db_data.png | Bin 0 -> 72194 bytes mkdocs.yml | 1 + 4 files changed, 110 insertions(+) create mode 100644 docs/filters_usage.md create mode 100644 docs/img/author_db_data.png create mode 100644 docs/img/book_db_data.png diff --git a/docs/filters_usage.md b/docs/filters_usage.md new file mode 100644 index 0000000..6094f05 --- /dev/null +++ b/docs/filters_usage.md @@ -0,0 +1,109 @@ +## Introduction +Once you’ve created your data models, **Supadantic** automatically gives you a database-abstraction API that lets you create, retrieve, update and delete objects with filters. + +Throughout this guide we’ll refer to the following models: +```python +from supadantic.models import BaseSBModel + +class Author(BaseSBModel): + name: str + surname: str + age: int + nationality: str + + +class Book(BaseSBModel): + name: str + genre: str + count_pages: int | None = None + author_id: int +``` + +And the following data for: + +**Author** +![Author DB data](img/author_db_data.png) +**Book** +![Book DB data](img/book_db_data.png) + +If you don't know how to create the data via **supadantic**, check it out [here](https://makridenko.github.io/supadantic/models/base_sb_model/?h=save#supadantic.models.BaseSBModel.save). + +## Retrieving objects +To retrieve objects from your database, construct a [QuerySet](https://makridenko.github.io/supadantic/q_set/) on your model class. + +A [QuerySet](https://makridenko.github.io/supadantic/q_set/) represents a collection of objects from your database. **It can have zero, one or many filters**. + +### Retrieving all objects +```python +authors = Author.objects.all() +``` + +### Retrieving a single object with `get()` method +```python +jack_london = Author.objects.get(name="Jack London") +``` + +### Retrieving specific objects with `filter()` and `exclude()` methods +If you want to select only a subset of the complete set of objects, you refine the initial [QuerySet](https://makridenko.github.io/supadantic/q_set/), adding filter conditions. The two most common ways to refine a [QuerySet](https://makridenko.github.io/supadantic/q_set/) are: + +- **filter(\*\*kwargs)** — returns a new [QuerySet](https://makridenko.github.io/supadantic/q_set/) containing objects that **match the given lookup parameters**. +- **exclude(\*\*kwargs)** — returns a new [QuerySet](https://makridenko.github.io/supadantic/q_set/) containing objects that **do not match the given lookup parameters**. + +The lookup parameters (**\*\*kwargs** in the above function definitions) should be in the following format `field__lookuptype=value` (**double-underscore**), for example: +```python +authors = Author.objects.filter(age__gt=50) +``` + +#### `Equal` and `Not Equal` filters +```python +books = Book.objects.filter(name="The Idiot") +``` +> Note that the **non-equality filter** is implemented through the `exclude` method. + +```python +books = Book.objects.exclude(name="The Idiot") +``` + +#### `Greater Than` and `Greater Than Or Equal` filters +```python +books = Book.objects.filter(count_pages__gt=600) # 600 is not included + +books = Book.objects.filter(count_pages__gte=600) # 600 is included +``` + +`Exclude` method will be the opposite of this methods: +```python +books = Book.objects.exclude(count_pages__gt=600) # it will have the logic of lte (less than or equal) filter + +books = Book.objects.exclude(count_pages__gte=600) # it will have the logic of lt (less than) filter +``` + +#### `Less Than` and `Less Than Or Equal` filters +```python +authors = Author.objects.filter(id__lt=6) # 6 is not included + +authors = Author.objects.filter(id__lte=6) # 6 is included +``` + +`Exclude` method will be the opposite of this methods: +```python +authors = Author.objects.exclude(id__lt=6) # it will have the logic of gte (greater than or equal) filter + +authors = Author.objects.exclude(id__lte=6) # it will have the logic of gt (greater than) filter +``` + +#### `Include` filter +```python +books = User.objects.filter(genre__in=["Novel", "Poems"]) +``` + +### Chaining filters +The result of refining a [QuerySet](https://makridenko.github.io/supadantic/q_set/) is itself a [QuerySet](https://makridenko.github.io/supadantic/q_set/), so it’s possible to chain refinements together. For example: +```python +books = ( + Book.objects + .filter(genre="Novel") + .filter(count_pages__gt=600) + .filter(author_id=5) +) +``` diff --git a/docs/img/author_db_data.png b/docs/img/author_db_data.png new file mode 100644 index 0000000000000000000000000000000000000000..84b5af3f12fc06723f71a98784a71f42f21979e4 GIT binary patch literal 34736 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 literal 0 HcmV?d00001 diff --git a/docs/img/book_db_data.png b/docs/img/book_db_data.png new file mode 100644 index 0000000000000000000000000000000000000000..e2c5d10dfbe90ecbb7c7710a28448887cb6fc491 GIT binary patch literal 72194 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�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 IIe+8-0so{3%K!iX literal 0 HcmV?d00001 diff --git a/mkdocs.yml b/mkdocs.yml index eb6a9d8..d7e1b4d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,6 +8,7 @@ nav: - Home: - Overview: index.md - FastAPI Example: fast_api_usage.md + - Filters Usage: filters_usage.md - API Documentation: - Clients: - BaseClient: clients/base.md From f1f57e44b0bb48dc8ec17d73b31f30e4303ceb91 Mon Sep 17 00:00:00 2001 From: Alexander Pozhidaev Date: Tue, 5 Aug 2025 19:22:21 +0300 Subject: [PATCH 2/2] add docs for QSet filters --- docs/filters_usage.md | 13 +++++++++++++ supadantic/q_set.py | 4 ++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/filters_usage.md b/docs/filters_usage.md index 6094f05..b065ac4 100644 --- a/docs/filters_usage.md +++ b/docs/filters_usage.md @@ -42,6 +42,8 @@ authors = Author.objects.all() ```python jack_london = Author.objects.get(name="Jack London") ``` +>**Pay attention💡** +[get()](https://makridenko.github.io/supadantic/q_set/#supadantic.q_set.QSet.get) should return **one object**, otherwise it will raise `DoesNotExist` or `MultipleObjectsReturned` exceptions. ### Retrieving specific objects with `filter()` and `exclude()` methods If you want to select only a subset of the complete set of objects, you refine the initial [QuerySet](https://makridenko.github.io/supadantic/q_set/), adding filter conditions. The two most common ways to refine a [QuerySet](https://makridenko.github.io/supadantic/q_set/) are: @@ -96,6 +98,8 @@ authors = Author.objects.exclude(id__lte=6) # it will have the logic of gt (grea ```python books = User.objects.filter(genre__in=["Novel", "Poems"]) ``` +>**Pay attention💡** +`__in` filter supports any `Iterable` object e.g. `list`, `tuple`, `set`. ### Chaining filters The result of refining a [QuerySet](https://makridenko.github.io/supadantic/q_set/) is itself a [QuerySet](https://makridenko.github.io/supadantic/q_set/), so it’s possible to chain refinements together. For example: @@ -107,3 +111,12 @@ books = ( .filter(author_id=5) ) ``` +We also can combine `filter()` and `exclude()` methods: +```python +books = ( + Book.objects + .filter(genre="Novel") + .filter(count_pages__gt=600) + .exclude(author_id__lt=2) +) +``` diff --git a/supadantic/q_set.py b/supadantic/q_set.py index 9b7710a..18e0ad0 100644 --- a/supadantic/q_set.py +++ b/supadantic/q_set.py @@ -118,7 +118,7 @@ def filter(self, **filters: Any) -> 'QSet[_M]': Returns a QSet filtered by the given keyword arguments. Each keyword argument represents a field name and its desired value. - Multiple filters are combined with AND logic. + Multiple filters are combined with AND logic. [Usage example](https://makridenko.github.io/supadantic/filters_usage/). # noqa: E501 Args: **filters: Keyword arguments representing the filter criteria. @@ -157,7 +157,7 @@ def exclude(self, **filters: Any) -> 'QSet[_M]': Excludes objects based on the provided keyword arguments. This method adds non-equality filters to the query. Only objects that do - not match any of the provided filters will be included in the resulting QSet. + not match any of the provided filters will be included in the resulting QSet. [Usage example](https://makridenko.github.io/supadantic/filters_usage/). # noqa: E501 Args: **filters: Keyword arguments representing the filters to apply.