Metadata-Version: 2.4
Name: ohsome-filter-to-sql
Version: 0.1.0
Summary: Translate ohsome API filter to SQL WHERE clause ready to be used with ohsomeDB
Author: HeiGIT ohsome team
Author-email: HeiGIT ohsome team <ohsome@heigit.org>
License-Expression: LGPL-3.0-only
License-File: COPYING
License-File: COPYING.LESSER
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
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: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: antlr4-python3-runtime>=4.13.2
Requires-Python: >=3.11, <3.14
Project-URL: Documentation, https://github.com/GIScience/ohsome-filter-to-sql/blob/main/README.md
Project-URL: Homepage, https://ohsome.org/
Project-URL: Issues, https://github.com/GIScience/ohsome-filter-to-sql/issues
Project-URL: Repository, https://github.com/GIScience/ohsome-filter-to-sql
Description-Content-Type: text/markdown

# ohsome filter to SQL

[![Build Status](https://jenkins.heigit.org/buildStatus/icon?job=ohsome-filter/main)](https://jenkins.heigit.org/job/ohsome-filter/job/main/)
[![Sonarcloud Status](https://sonarcloud.io/api/project_badges/measure?project=ohsome-filter-to-sql&metric=alert_status)](https://sonarcloud.io/dashboard?id=ohsome-filter-to-sql)
[![LICENSE](https://img.shields.io/github/license/GIScience/ohsome-filter-to-sql)](COPYING)
[![status: active](https://github.com/GIScience/badges/raw/master/status/active.svg)](https://github.com/GIScience/badges#active)

## Try it out

```sh
$ uvx --from git+https://github.com/GIScience/ohsome-filter-to-sql.git ohsome-filter-to-sql
natural = tree and leaftype = broadleaf  # type in ohsome filter and hit enter
tags @> '{"natural": "tree"}' AND tags @> '{"leaftype": "broadleaf"}'  # result
```

## Installation

```sh
uv add git+https://github.com/GIScience/ohsome-filter-to-sql.git
```

## Usage

### Python Library

```python
from ohsome_filter_to_sql.main import ohsome_filter_to_sql

sql_query = ohsome_filter_to_sql("natural = tree")
```

### Command Line Interface (CLI)

```sh
uv run ohsome-filter-to-sql
```

## Development Setup

```sh
uv run pytest
```

To install pre-commit hooks run:
```sh
uv run pre-commit install
```

To develop new features you will need a local instance of the [ohsomeDB](https://gitlab.heigit.org/giscience/big-data/ohsome/ohsomedb/ohsomedb/-/tree/main/local_setup).


### How to play around with the grammar?

Execute `antlr4-parse`, type in an ohsome filter and press ctlr+d.

```sh
antlr4-parse OFL.g4 root -tree
buildings=yes
(root:1 (expression:8 (tagMatch:1 (string:1 buildings) = (string:1 yes))) <EOF>)
```

[ANTLR Lab](http://lab.antlr.org/) can also be used to try out the grammar.


### How to generating parser code?

When the grammar file has change generate new Python code with `antlr4` and move genrated files to `ohsome_filter_to_sql/`.

```sh
uv run antlr4 -Dlanguage=Python3 OFL.g4 && mv *.py ohsome_filter_to_sql/
```


### Release

This project uses [SemVer](https://semver.org/).

To make a new release run `./scripts/release.sh <version number>`.


## Resources

- [ohsome filter documentation](https://docs.ohsome.org/ohsome-api/v1/filter.html) and [oshdb-filter](https://github.com/GIScience/oshdb/tree/main/oshdb-filter)
- [ANTLR with Python - Introduction](https://yetanotherprogrammingblog.medium.com/antlr-with-python-974c756bdb1b)
- [ANTLR Listeners](https://github.com/antlr/antlr4/blob/master/doc/listeners.md)
- [ohsomeDB schema](https://gitlab.heigit.org/giscience/big-data/ohsome/ohsomedb/ohsomedb/-/blob/main/create-schema.sql)
