Metadata-Version: 2.4
Name: odata-query
Version: 0.11.0
Summary: An OData query parser and transpiler.
Keywords: OData,Query,Parser
Author: Oliver Hofkens
Author-email: Oliver Hofkens <oliver@gorilla.co>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: SQL
Classifier: Topic :: Database
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Software Development :: Compilers
Requires-Dist: python-dateutil>=2.8.1
Requires-Dist: sly>=0.4,<0.5
Requires-Dist: django>=5.2 ; extra == 'django'
Requires-Dist: sqlalchemy>=1.4,<2 ; extra == 'sqlalchemy'
Requires-Python: >=3.11
Provides-Extra: django
Provides-Extra: sqlalchemy
Description-Content-Type: text/x-rst

OData-Query
===========

.. image:: https://readthedocs.org/projects/odata-query/badge/?version=latest
    :alt: Documentation Status
    :target: https://odata-query.readthedocs.io/en/latest/?badge=latest

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
    :alt: Ruff
    :target: https://github.com/astral-sh/ruff


``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:

.. code-block:: bash

    pip install odata-query
    # OR
    uv add 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.


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

.. code-block:: bash

    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:

.. code-block:: python

    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:

.. code-block:: python

    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:

.. code-block:: python

    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()

.. splitinclude-1

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.

.. splitinclude-2

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.


.. _odata v4: https://www.odata.org/
.. _django queries: https://docs.djangoproject.com/en/3.2/topics/db/queries/
.. _sqlalchemy queries: https://docs.sqlalchemy.org/en/14/orm/loading_objects.html
.. _documentation: https://odata-query.readthedocs.io/en/latest
.. _Gorillini NV: https://gorilla.co/
.. _contributing guidelines: ./CONTRIBUTING.rst
