diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..284ff7f --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,84 @@ +# GitHub Actions workflow to build, test and publish Python packages to PyPI everytime a new release is created. + +name: Publish release + +on: + release: + types: + - published + +jobs: + build: + name: Build package + runs-on: ubuntu-24.04 + + steps: + - uses: actions/checkout@v4 + + # We use Python 3.8 here because it's the minimum Python version supported by this library. + - name: Setup Python 3.8 + uses: actions/setup-python@v5 + with: + python-version: 3.8 + + - name: Install dependencies + run: pip install --upgrade pip build + + - name: Build package + run: python -m build + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: dist_packages + path: dist/ + + test: + # This job tests the built package by installing it via pip and running unit tests (without tox). + name: Test package + needs: build + runs-on: ubuntu-24.04 + + steps: + - uses: actions/checkout@v4 + + - name: Setup Python 3.8 + uses: actions/setup-python@v5 + with: + python-version: 3.8 + + - name: Download build artifacts + uses: actions/download-artifact@v4 + with: + name: dist_packages + path: dist/ + + - name: Install built package with testing dependencies + run: pip install "$(find dist/ -name 'validataclass-search-queries-*.whl')[testing]" + + - name: Run unit tests + run: python -m pytest + + publish: + name: Publish package + needs: test + runs-on: ubuntu-24.04 + + steps: + - name: Download build artifacts + uses: actions/download-artifact@v4 + with: + name: dist_packages + path: dist/ + + - name: Upload package to GitHub release assets + uses: AButler/upload-release-assets@v3.0 + with: + files: dist/* + repo-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Publish package to PyPI + uses: pypa/gh-action-pypi-publish@v1.12.4 + with: + user: __token__ + password: ${{ secrets.PYPI_API_TOKEN }} diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..9cca518 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,82 @@ +# GitHub Actions workflow for running unit tests (using tox, pytest and flake8) on each push or pull request to main. + +name: Unit tests + +# TODO: Remove dev-mypy after merging it into main. +on: + push: + branches: + - main + - dev-mypy + pull_request: + branches: + - main + - dev-mypy + +jobs: + test: + name: Run unit tests (Python ${{ matrix.python-version }}, SQLAlchemy ${{ matrix.sqlalchemy-version }}) + runs-on: ubuntu-24.04 + + strategy: + fail-fast: false + matrix: + python-version: + - '3.8' + - '3.9' + - '3.10' + - '3.11' + - '3.12' + sqlalchemy-version: + - '1.4' + - '2.0' + + steps: + - uses: actions/checkout@v4 + + - name: Setup Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies + run: pip install --upgrade pip tox + + - name: Run test suite with tox + # Run tox using the version of Python in `PATH` + run: tox run -e clean,py-sqlalchemy${{ matrix.sqlalchemy-version }},report,flake8 -- --junit-xml=reports/pytest_${{ matrix.python-version }}_sqlalchemy${{ matrix.sqlalchemy-version }}.xml + + - name: Upload test result artifacts + uses: actions/upload-artifact@v4 + if: success() || failure() + with: + name: pytest-results-${{ matrix.python-version }}-sqlalchemy${{ matrix.sqlalchemy-version }} + path: reports/pytest_${{ matrix.python-version }}_sqlalchemy${{ matrix.sqlalchemy-version }}.xml + + report: + name: Publish unit test reports + runs-on: ubuntu-24.04 + + # Job depends on test results + needs: test + + # Do not run this job in pull requests from a forked repository (because the test-reporter would fail) + if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository + + steps: + - uses: actions/checkout@v4 + + - name: Download test result artifacts + uses: actions/download-artifact@v4 + with: + path: reports/ + pattern: pytest-results-* + merge-multiple: true + + - name: Publish unit test reports + uses: dorny/test-reporter@v2.1.1 + if: success() || failure() + with: + name: Pytest Report + path: reports/pytest_*.xml + reporter: java-junit diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 2e4b097..0000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,69 +0,0 @@ -stages: - - build - - test - - publish - -default: - image: python:3.10 - cache: - key: - files: - - setup.cfg - paths: - - .pip/ - -variables: - PIP_CACHE_DIR: "$CI_PROJECT_DIR/.pip" - -# Build package -build: - stage: build - artifacts: - paths: - - dist/ - before_script: - - pip install build - script: - - python -m build - -# Run unit tests -test-unit: - stage: test - parallel: - matrix: - - PYTHON_VERSION: - - '3.8' - - '3.9' - - '3.10' - - '3.11' - - '3.12' - SQLALCHEMY_VERSION: - - '1.4' - - '2.0' - image: python:${PYTHON_VERSION} - artifacts: - when: always - reports: - junit: reports/pytest_*.xml - coverage_report: - coverage_format: cobertura - path: reports/coverage.xml - coverage: '/TOTAL .* (\d+%)/' - before_script: - - pip install --upgrade pip tox - script: - # Run tests using tox with the package that was built in the build stage - - tox run --installpkg dist/*.whl -e clean,py,flake8,report,sqlalchemy${SQLALCHEMY_VERSION} -- --junit-xml=reports/pytest_${PYTHON_VERSION}_${SQLALCHEMY_VERSION}.xml - -# Publish package -publish: - stage: publish - rules: - # Only publish when a tag is created - - if: $CI_COMMIT_TAG - before_script: - - pip install twine - - export TWINE_USERNAME=gitlab-ci-token - - export TWINE_PASSWORD=${CI_JOB_TOKEN} - script: - - python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/* diff --git a/CHANGELOG.md b/CHANGELOG.md index c11d6ca..f7d0e31 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,12 +6,16 @@ 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://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.5.0...HEAD) +## [Unreleased](https://github.com/binary-butterfly/validataclass-search-queries/compare/0.5.1...HEAD) + +### General + +- Migrate project from our company GitLab to GitHub and [PyPI](https://pypi.org/). -## [0.5.1](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.5.1) - 2024-08-12 +## [0.5.1](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.5.1) - 2024-08-12 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.5.0...0.5.1) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.5.0...0.5.1) This release only adds compatibility with validataclass 0.11.0. @@ -19,13 +23,13 @@ This release only adds compatibility with validataclass 0.11.0. - Add compatibility for [validataclass 0.11.0]. [!17] -[!17]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/17 +[!17]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/17 [validataclass 0.11.0]: https://github.com/binary-butterfly/validataclass/releases/tag/0.11.0 -## [0.5.0](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.5.0) - 2024-05-15 +## [0.5.0](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.5.0) - 2024-05-15 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.4.2...0.5.0) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.4.2...0.5.0) This release mostly updates the dependency on validataclass to version 0.10.0. @@ -44,14 +48,14 @@ Also, this library is now licensed under an MIT license to be compatible with FO - Change project license to MIT. [!15] -[!13]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/13 -[!14]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/14 -[!15]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/15 +[!13]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/13 +[!14]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/14 +[!15]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/15 -## [0.4.2](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.4.2) - 2023-08-21 +## [0.4.2](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.4.2) - 2023-08-21 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.4.1...0.4.2) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.4.1...0.4.2) Add support for SQLAlchemy 2.0. @@ -60,12 +64,12 @@ Add support for SQLAlchemy 2.0. - Update dependencies to support SQLAlchemy 2.0. [!11] - Update build pipeline to test with both SQLAlchemy 1.4 and 2.0. [!11] -[!11]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/11 +[!11]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/11 -## [0.4.1](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.4.1) - 2023-05-24 +## [0.4.1](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.4.1) - 2023-05-24 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.4.0...0.4.1) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.4.0...0.4.1) This release provides compatibility for [validataclass 0.9](https://github.com/binary-butterfly/validataclass/releases/tag/0.9.0) and thus adds official support for Python 3.11. @@ -76,12 +80,12 @@ and thus adds official support for Python 3.11. - This adds support for Python 3.11. - Update local test environment for tox 4. [!10] -[!10]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/10 +[!10]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/10 -## [0.4.0](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.4.0) - 2022-11-30 +## [0.4.0](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.4.0) - 2022-11-30 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.3.0...0.4.0) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.3.0...0.4.0) This release provides compatibility for [validataclass 0.8](https://github.com/binary-butterfly/validataclass/releases/tag/0.8.0). @@ -95,13 +99,13 @@ This release provides compatibility for [validataclass 0.8](https://github.com/b instead of abstract properties. [!9] - This solves typing/linting problems when manually assigning values to these attributes in a dataclass instance. -[!8]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/8 -[!9]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/9 +[!8]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/8 +[!9]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/9 -## [0.3.0](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.3.0) - 2022-11-22 +## [0.3.0](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.3.0) - 2022-11-22 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.2.2...0.3.0) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.2.2...0.3.0) ### Added @@ -116,24 +120,24 @@ This release provides compatibility for [validataclass 0.8](https://github.com/b - Type hint for `SearchQueryRepositoryMixin.model_cls` is now `Type[T_Model]` instead of just `Type`. [!7] -[!6]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/6 -[!7]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/7 +[!6]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/6 +[!7]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/7 -## [0.2.2](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.2.2) - 2022-10-27 +## [0.2.2](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.2.2) - 2022-10-27 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.2.1...0.2.2) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.2.1...0.2.2) ### Added - `MultiSelectAnyOfValidator` and `MultiSelectEnumValidator`: Add (missing) parameter `case_insensitive`. [!5] -[!5]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/5 +[!5]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/5 -## [0.2.1](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.2.1) - 2022-09-29 +## [0.2.1](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.2.1) - 2022-09-29 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.2.0...0.2.1) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.2.0...0.2.1) This release improves type hinting, based on validataclass 0.7.2. @@ -143,12 +147,12 @@ This release improves type hinting, based on validataclass 0.7.2. which improves the type hinting for validataclasses and the `DataclassValidator`. [!4] - Improved type hinting for `@search_query_dataclass` decorator analogous to `@validataclass`. [!4] -[!4]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/4 +[!4]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/4 -## [0.2.0](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.2.0) - 2022-09-22 +## [0.2.0](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.2.0) - 2022-09-22 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/compare/0.1.0...0.2.0) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/compare/0.1.0...0.2.0) This release is an upgrade to validataclass 0.7.0. @@ -161,12 +165,12 @@ The previous release is not compatible to this version of validataclass, and vic - MultiSelectValidators now have better type-hinting thanks to `ListValidator` and `EnumValidator` being generic now. - `BaseSearchQuery`: Search filters that are set to `UnsetValue` are now discarded (same as `None`). [!3] -[!3]: https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/merge_requests/3 +[!3]: https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/merge_requests/3 -## [0.1.0](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/releases/0.1.0) - 2022-08-22 +## [0.1.0](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/releases/0.1.0) - 2022-08-22 -[Full changelog](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/commits/0.1.0) +[Full changelog](https://git.binary-butterfly.de/public_libraries/validataclass-search-queries/-/commits/0.1.0) This is the first non-alpha release of validataclass-search-queries. diff --git a/README.md b/README.md index e768ddd..b1d4ee1 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,42 @@ # validataclass Search Queries -**NOTE: This is an internal library used by our company, not intended to be used outside of our projects.** +[![Unit tests](https://github.com/binary-butterfly/validataclass-search-queries/actions/workflows/tests.yml/badge.svg) +](https://github.com/binary-butterfly/validataclass-search-queries/actions/workflows/tests.yml) 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 is supported). +database queries (currently only SQLAlchemy 1.4 and 2.0 are supported). +**Status:** Beta. -## Installation -The library can be installed with `pip` like other libraries. However, since it's an internal library, it can only be -retrieved from our [internal package registry](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/packages). +## Installation -### requirements.txt +validataclass-search-queries is available on [PyPI](https://pypi.org/project/validataclass-search-queries/). -To install the library using a regular `requirements.txt` file, add the following lines to it: +To install it using [pip](https://pip.pypa.io/en/stable/getting-started/), just run: +```shell +pip install validataclass-search-queries ``` -# binary butterfly shared libraries (https://git.sectio-aurea.org/public_libraries) ---extra-index-url https://git.sectio-aurea.org/api/v4/groups/262/-/packages/pypi/simple -validataclass-search-queries~=0.5.0 + +If you add the package to your dependencies, it is recommended to use +[compatible release](https://www.python.org/dev/peps/pep-0440/#compatible-release) version specifiers to make sure you +always get the latest version of the library but without running into breaking changes: + +```shell +pip install validataclass-search-queries~=0.5.0 ``` -(**Note:** The `--extra-index-url` parameter will be used for the whole `requirements.txt` file. If you're using -multiple libraries from the same package registry, you only need to specify the parameter once.) +However, keep in mind that the library is still in its beta phase (as indicated by the major version of 0). There can +and will be smaller breaking changes between 0.x minor versions, but we will try to keep them at a minimum and save the +big breaking changes for the release of version 1.0.0. ## Usage -See [docs](https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/blob/main/docs/index.md) for +See [docs](https://github.com/binary-butterfly/validataclass-search-queries/blob/main/docs/index.md) for the documentation, including a quick tutorial on how to use this library. @@ -47,5 +54,8 @@ dependencies. Unit tests can be run using `make tox` or by directly executing `tox`. +For this to work you need to either be inside the virtualenv (see above) or have [tox](https://tox.wiki/en/latest/) +installed in your system locally. + Take a look at the `Makefile` for more ways to run the unit tests (e.g. inside a Docker container to test for specific Python versions). diff --git a/setup.cfg b/setup.cfg index 1fcb620..0a03e19 100644 --- a/setup.cfg +++ b/setup.cfg @@ -2,15 +2,28 @@ name = validataclass_search_queries author = binary butterfly GmbH author_email = lexi.stelter@binary-butterfly.de -description = Shared Python library for search queries (filters, pagination, sorting) based on validataclass. +description = Python library for search queries in REST APIs (filters, pagination, sorting) based on validataclass and SQLAlchemy. long_description = file: README.md long_description_content_type = text/markdown license = MIT -url = https://git.sectio-aurea.org/common/validataclass-search-queries +url = https://github.com/binary-butterfly/validataclass-search-queries project_urls = - Documentation = https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/blob/main/docs/index.md - Changelog = https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/blob/main/CHANGELOG.md - Issue Tracker = https://git.sectio-aurea.org/public_libraries/validataclass-search-queries/-/issues + Documentation = https://github.com/binary-butterfly/validataclass-search-queries/blob/main/docs/index.md + Changelog = https://github.com/binary-butterfly/validataclass-search-queries/blob/main/CHANGELOG.md + Issue Tracker = https://github.com/binary-butterfly/validataclass-search-queries/issues +classifiers = + Development Status :: 4 - Beta + Intended Audience :: Developers + Operating System :: OS Independent + Programming Language :: Python :: 3 + Programming Language :: Python :: 3.8 + Programming Language :: Python :: 3.9 + Programming Language :: Python :: 3.10 + Programming Language :: Python :: 3.11 + Programming Language :: Python :: 3.12 + Programming Language :: Python :: Implementation :: CPython + Topic :: Software Development :: Libraries :: Python Modules + Topic :: Utilities [options] package_dir =