From ecc8a0a0682e093347749d9bc83ffbe61853f623 Mon Sep 17 00:00:00 2001 From: Lexi Stelter Date: Wed, 15 Apr 2026 14:58:03 +0200 Subject: [PATCH 1/2] Documentation: Add guide on how to use the mypy plugin --- docs/04-mypy-plugin.md | 39 +++++++++++++++++++++++++++++++++++++++ docs/index.md | 3 +++ 2 files changed, 42 insertions(+) create mode 100644 docs/04-mypy-plugin.md diff --git a/docs/04-mypy-plugin.md b/docs/04-mypy-plugin.md new file mode 100644 index 0000000..db5afb8 --- /dev/null +++ b/docs/04-mypy-plugin.md @@ -0,0 +1,39 @@ +# 4. Type checking with mypy + +To allow proper type checking of validataclasses and search queries with mypy, you need to use the mypy plugin provided +by validataclass and configure it correctly to recognize search queries as a variant of validataclasses. + +Please refer to the [validataclass docs](https://github.com/binary-butterfly/validataclass/blob/main/docs/07-mypy-plugin.md) +for more details. + +## How to enable and configure the validataclass mypy plugin + +The mypy plugin is included in validataclass, but you need to enable it explicitly in your mypy configuration. You also +need to configure the plugin itself so that it recognizes the `@search_query_dataclass` decorator as a validataclass +decorator. The plugin also needs to know to ignore the `SearchParam` objects in a validataclass. + +If you're using a `pyproject.toml` file (which is the recommended way nowadays to configure Python projects and tools), +this is an example configuration for mypy and the validataclass mypy plugin: + +```toml +[tool.mypy] +# These lines are just an example and might not be needed or need to be adjusted in your project: +files = ["src/"] +mypy_path = "src/" +explicit_package_bases = true + +# This is the important part to enable the plugin: +plugins = ["validataclass.mypy.plugin"] + +# This is the configuration for the plugin itself: +[tool.validataclass_mypy] +# Declare @search_query_dataclass as a decorator that creates validataclasses +custom_validataclass_decorators = [ + "validataclass_search_queries.search_queries.search_query_dataclass.search_query_dataclass", +] + +# Ignore SearchParam objects in validataclass field definitions +ignore_custom_types_in_fields = [ + "validataclass_search_queries.filters.search_params.base_search_param.SearchParam", +] +``` diff --git a/docs/index.md b/docs/index.md index 9351d9a..c920cf4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,3 +15,6 @@ This is the index of the documentation. 3. [Reference of search filter types](03-search-param-reference.md) - List of all types of search filters (`SearchParam` classes) + +4. [Type checking with mypy](04-mypy-plugin.md) + - How to use the validataclass mypy plugin together with this library From 16a73d59e40f0f0322606f9422dd4e893b88cba9 Mon Sep 17 00:00:00 2001 From: Lexi Stelter Date: Wed, 15 Apr 2026 14:59:10 +0200 Subject: [PATCH 2/2] Update changelog and readme to prepare release of 0.6.0 --- CHANGELOG.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++-- README.md | 4 +- 2 files changed, 106 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f7d0e31..9fc883b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,11 +6,112 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased](https://github.com/binary-butterfly/validataclass-search-queries/compare/0.5.1...HEAD) +## [Unreleased](https://github.com/binary-butterfly/validataclass-search-queries/compare/0.6.0...HEAD) + + +## [0.6.0](https://github.com/binary-butterfly/validataclass-search-queries/releases/tag/0.6.0) - 2026-04-15 + +[Full changelog](https://github.com/binary-butterfly/validataclass-search-queries/compare/0.5.1...0.6.0) + +This is the companion release to [validataclass 0.12.0], which improves typing and adds proper support for type checking +with [mypy](https://mypy-lang.org/) using a custom mypy plugin. + +Please also read the release notes for validataclass 0.12.0 for further information on potential breaking changes and +how to update. + +To enable the mypy plugin and configure it for compatibility with validataclass-search-queries, have a look at +[`docs/04-mypy-plugin.md`](https://github.com/binary-butterfly/validataclass-search-queries/blob/main/docs/04-mypy-plugin.md). + +This is also the first officially public release of the library. Previously, this project was hosted on our company's +internal GitLab (even though publically accessible), because it was originally meant for internal use only. We decided +to migrate the project to GitHub and publish official releases on PyPI, though, to allow easier integration into other +public projects. + +This version drops support for Python 3.8 and 3.9 and adds support for Python 3.13 and 3.14. + +Additionally, support for SQLAlchemy 1.4 is deprecated now, you should upgrade to SQLAlchemy 2.0 if you haven't done so +already. This version still *works* with SQLAlchemy 1.4, however, proper typing is not supported, so there might be +several type errors in this library if you use that version of SQLAlchemy. ### General -- Migrate project from our company GitLab to GitHub and [PyPI](https://pypi.org/). +- Migrate project from our company GitLab to GitHub and [PyPI](https://pypi.org/). [#1] + +### Added + +- Add support for Python 3.13. [#6] +- Add support for Python 3.14. [#6] +- Add `py.typed` file to make the package PEP 561 compatible. [#6] +- Add support for type checking using the validataclass mypy plugin. [#6] + +### Changed + +- Generic-based typing for validator classes. [#6] + - Validators have been updated to be compatible with the generic-based typing in validataclass 0.12.0. + - The `MultiSelectValidator` is a generic class now where the type parameter specifies the type of list items + (similar to the `ListValidator`). Its subclasses are updated similarly. + - The `PaginationLimitValidator` is a `Validator[int | None]`. This is because it can return None when pagination is + optional. The typing might be improved in the future, possibly by splitting up the validator into one that enforces + pagination and one where it's optional. If you need more precise typing, you can use a regular `IntegerValidator`. +- Restructure files for `MultiSelectValidator` and subclasses. [#4] + - The `MultiSelectValidator` and its subclasses (`MultiSelectEnumValidator`, etc.) are now defined in separate files. + - This implies a small **breaking change** if the validators are imported directly from the original module, i.e. from + `validataclass_search_queries.validators.multi_select_validator`. It is recommended to import them from the parent + package `validataclass_search_queries.validators` instead. +- Use `DataclassValidatorFieldException` in `@search_query_dataclass` decorator. [#5] + - Previously, a different type of exception was used. This was inconsistent with the `@validataclass` decorator. + - This shouldn't break any code, because those exceptions are only raised when your search query dataclass definitions + are incorrect, so your code isn't valid anyway. + - Some error messages from the decorator have also been changed for consistency. +- `PaginatedResult.map()` always returns another `PaginatedResult` now, even when subclassed. [#6] + - Previously, the method used `self.__class__()` to instantiate a new object of the same type as `self` (e.g. a + subclass). However, this isn't really compatible with generic typing, since the subclass might not actually be + compatible with the mapped type. + +### Deprecated + +- Deprecate support for SQLAlchemy 1.4. Support may be dropped in the near future, possibly the next release. + - There should be no problems with SQLAlchemy 1.4 at runtime with this version. However, typing is not supported since + SQLAlchemy didn't have good typing prior to 2.0. Type errors in this library related to SQLAlchemy 1.4 are expected. +- Deprecate reusing TypeVars from the library by removing them from `__all__`. [#6] + +### Removed + +- Drop support for Python 3.8. [#3] +- Drop support for Python 3.9. [#3] + +### Fixed + +- Fix incorrect short-circuiting of substring search filters. [#6] + - Previously, substring search filters like `SearchParamContains` had a condition to "short-circuit" if the search + value was empty. The idea was that a condition like `col LIKE "%%"` is always true, so the clause could be + simplified. However, the functions simply returned the column itself and not a clause. This didn't seem correct and + also just unnecessary, so this short-circuiting mechanism was removed. + +### Dependencies + +- Change required version of validataclass to 0.12.0 or higher, but below 0.13.0. [#6] + +### Testing / CI + +- Use GitHub Actions instead of GitLab CI. [#1] +- Add more unit tests. [#5] +- Enable mypy type checking with strict mode and extra rules. [#6] +- Update testing dependencies and pin them to minor versions. [#7] +- Fix tox configuration to run unit tests with both SQLAlchemy 1.4 and 2.0. [#7] + +### Miscellaneous + +- Various code modernizations after dropping support for Python 3.8 and 3.9. [#3] +- Various refactoring, typing improvements and fixes. [#6] + +[validataclass 0.12.0]: https://github.com/binary-butterfly/validataclass/releases/tag/0.12.0 +[#1]: https://github.com/binary-butterfly/validataclass-search-queries/pull/1 +[#3]: https://github.com/binary-butterfly/validataclass-search-queries/pull/3 +[#4]: https://github.com/binary-butterfly/validataclass-search-queries/pull/4 +[#5]: https://github.com/binary-butterfly/validataclass-search-queries/pull/5 +[#6]: https://github.com/binary-butterfly/validataclass-search-queries/pull/6 +[#7]: https://github.com/binary-butterfly/validataclass-search-queries/pull/7 ## [0.5.1](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.5.1) - 2024-08-12 @@ -37,7 +138,7 @@ Also, this library is now licensed under an MIT license to be compatible with FO ### Changed -- `MultiSelectValidator`: Empty strings are now parsed as empty lists. [!13] +- `MultiSelectValidator`: Empty strings are now parsed as empty lists. [!13] ### Dependencies diff --git a/README.md b/README.md index b1d4ee1..38f86f5 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Shared Python library for search queries based on [validataclass](https://github.com/binary-butterfly/validataclass). Implements search filters, pagination and sorting using dataclasses and validators, and provides helpers to work with -database queries (currently only SQLAlchemy 1.4 and 2.0 are supported). +database queries (currently SQLAlchemy 1.4 and 2.0 are supported, however, support for SQLAlchemy 1.4 is deprecated now). **Status:** Beta. @@ -26,7 +26,7 @@ If you add the package to your dependencies, it is recommended to use always get the latest version of the library but without running into breaking changes: ```shell -pip install validataclass-search-queries~=0.5.0 +pip install validataclass-search-queries~=0.6.0 ``` However, keep in mind that the library is still in its beta phase (as indicated by the major version of 0). There can