Prepare release of version 0.6.0

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
 

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

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",
+]
+```

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