gorilla-co / odata-query

An OData v4 query parser and transpiler for Python

OData-Query

odata-query is a library that parses OData v4 filter strings, and can convert them to other forms such as Django Queries, SQLAlchemy Queries, or just plain SQL.

Installation

odata-query is available on pypi, so can be installed with the package manager of your choice:

pip install odata-query
# OR
poetry add odata-query
# OR
pipenv install odata-query

The package defines the following optional extra's:

• django: If you want to pin a compatible Django version.
• sqlalchemy: If you want to pin a compatible SQLAlchemy version.

The following extra's relate to the development of this library:

• linting: The linting and code style tools.
• testing: Packages for running the tests.
• docs: For building the project documentation.

You can install extra's by adding them between square brackets during installation:

pip install odata-query[sqlalchemy]

Quickstart

The most common use case is probably parsing an OData query string, and applying it to a query your ORM understands. For this purpose there is an all-in-one function: apply_odata_query.

Example for Django:

from odata_query.django import apply_odata_query

orm_query = MyModel.objects  # This can be a Manager or a QuerySet.
odata_query = "name eq 'test'"  # This will usually come from a query string parameter.

query = apply_odata_query(orm_query, odata_query)
results = query.all()

Example for SQLAlchemy ORM:

from odata_query.sqlalchemy import apply_odata_query

orm_query = select(MyModel)  # This is any form of Query or Selectable.
odata_query = "name eq 'test'"  # This will usually come from a query string parameter.

query = apply_odata_query(orm_query, odata_query)
results = session.execute(query).scalars().all()

Example for SQLAlchemy Core:

from odata_query.sqlalchemy import apply_odata_core

core_query = select(MyTable)  # This is any form of Query or Selectable.
odata_query = "name eq 'test'"  # This will usually come from a query string parameter.

query = apply_odata_core(core_query, odata_query)
results = session.execute(query).scalars().all()

Advanced Usage

Not all use cases are as simple as that. Luckily, odata-query is modular and extendable. See the documentation for advanced usage or extending the library for other cases.

Contact

Got any questions or ideas? We'd love to hear from you. Check out our contributing guidelines for ways to offer feedback and contribute.

License

Copyright © Gorillini NV. All rights reserved.

Licensed under the MIT License.