Metadata-Version: 2.4
Name: titiler-pgstac
Version: 2.1.0
Summary: Connect PgSTAC and TiTiler.
Project-URL: Homepage, https://stac-utils.github.io/titiler-pgstac/
Project-URL: Documentation, https://stac-utils.github.io/titiler-pgstac/
Project-URL: Issues, https://github.com/stac-utils/titiler-pgstac/issues
Project-URL: Source, https://github.com/stac-utils/titiler-pgstac
Project-URL: Changelog, https://stac-utils.github.io/titiler-pgstac/release-notes/
Author-email: Vincent Sarago <vincent@developmentseed.com>, David Bitner <david@developmentseed.com>
License: MIT License
        
        Copyright (c) Microsoft Corporation and other contributors.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: COG,Dynamic tile server,Fastapi,MosaicJSON,STAC,pgSTAC
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Requires-Dist: cql2>=0.3.6
Requires-Dist: pydantic-settings~=2.0
Requires-Dist: pydantic<3.0,>=2.4
Requires-Dist: stac-pydantic<4,>=3.5.0
Requires-Dist: titiler-core<1.3,>=1.2
Requires-Dist: titiler-extensions<1.3,>=1.2
Requires-Dist: titiler-mosaic<1.3,>=1.2
Provides-Extra: psycopg
Requires-Dist: psycopg[pool]; extra == 'psycopg'
Provides-Extra: psycopg-binary
Requires-Dist: psycopg[binary,pool]; extra == 'psycopg-binary'
Provides-Extra: psycopg-c
Requires-Dist: psycopg[c,pool]; extra == 'psycopg-c'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api; extra == 'telemetry'
Requires-Dist: opentelemetry-exporter-otlp; extra == 'telemetry'
Requires-Dist: opentelemetry-instrumentation-fastapi; extra == 'telemetry'
Requires-Dist: opentelemetry-instrumentation-logging; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk; extra == 'telemetry'
Description-Content-Type: text/markdown

<p align="center">
  <img width="500" src="https://github.com/stac-utils/titiler-pgstac/assets/10407788/24a64ea9-fede-4ee8-ab8d-625c9e94db44"/>
  <p align="center">Connect PgSTAC and TiTiler.</p>
</p>

<p align="center">
  <a href="https://github.com/stac-utils/titiler-pgstac/actions?query=workflow%3ACI" target="_blank">
      <img src="https://github.com/stac-utils/titiler-pgstac/workflows/CI/badge.svg" alt="Test">
  </a>
  <a href="https://codecov.io/gh/stac-utils/titiler-pgstac" target="_blank">
      <img src="https://codecov.io/gh/stac-utils/titiler-pgstac/branch/main/graph/badge.svg" alt="Coverage">
  </a>
  <a href="https://pypi.org/project/titiler.pgstac" target="_blank">
      <img src="https://img.shields.io/pypi/v/titiler.pgstac?color=%2334D058&label=pypi%20package" alt="Package version">
  </a>
  <a href="https://github.com/stac-utils/titiler-pgstac/blob/main/LICENSE" target="_blank">
      <img src="https://img.shields.io/github/license/stac-utils/titiler-pgstac.svg" alt="License">
  </a>
</p>

---

**Documentation**: <a href="https://stac-utils.github.io/titiler-pgstac/" target="_blank">https://stac-utils.github.io/titiler-pgstac/</a>

**Source Code**: <a href="https://github.com/stac-utils/titiler-pgstac" target="_blank">https://github.com/stac-utils/titiler-pgstac</a>

---

**TiTiler-PgSTAC** is a [TiTiler](https://github.com/developmentseed/titiler) extension that connects to a [PgSTAC](https://github.com/stac-utils/pgstac) database to create dynamic **mosaics** based on [search queries](https://github.com/radiantearth/stac-api-spec/tree/master/item-search).

## Installation

To install from PyPI and run:

```bash
# Make sure to have pip up to date
python -m pip install -U pip

# Install `psycopg` or `psycopg["binary"]` or `psycopg["c"]`
python -m pip install psycopg["binary"]

python -m pip install titiler.pgstac
```

To install from sources and run for development:

We recommand using [`uv`](https://docs.astral.sh/uv) as project manager for development.

See https://docs.astral.sh/uv/getting-started/installation/ for installation 

```
git clone https://github.com/stac-utils/titiler-pgstac.git
cd titiler-pgstac

uv sync --extra psycopg 
```

### `PgSTAC` version

`titiler.pgstac` depends on `pgstac >=0.3.4` (https://github.com/stac-utils/pgstac/blob/main/CHANGELOG.md#v034).

In theory, pgstac version `>=0.3.4` should be supported by titiler-pgstac but `old` version might fail or require old Postgres version (see https://github.com/stac-utils/titiler-pgstac/issues/252). 

Here are the versions **officially** (tested) supported:

| titiler-pgstac Version  |      pgstac |
|                       --|           --|
|                    <1.0 | >=0.7,<0.8  |
|              >=1.0,<2.1 | >=0.8,<0.10 |
|                   >=2.1 | >=0.9,<0.10 |

### `psycopg` requirement

`titiler.pgstac` depends on the `psycopg` library. Because there are three ways of installing this package (`psycopg` or , `psycopg["c"]`, `psycopg["binary"]`), the user must install this separately from `titiler.pgstac`.

- `psycopg`: no wheel, pure python implementation. It requires the `libpq` installed in the system.
- `psycopg["binary"]`: binary wheel distribution (shipped with libpq) of the `psycopg` package and is simpler for development. It requires development packages installed on the client machine.
- `psycopg["c"]`: a C (faster) implementation of the libpq wrapper. It requires the `libpq` installed in the system.

`psycopg[c]` or `psycopg` are generally recommended for production use.

In `titiler.pgstac` setup.py, we have added three options to let users choose which psycopg install to use:

- `python -m pip install titiler.pgstac["psycopg"]`: pure python
- `python -m pip install titiler.pgstac["psycopg-c"]`: use the C wrapper (requires development packages installed on the client machine)
- `python -m pip install titiler.pgstac["psycopg-binary"]`: binary wheels

## Launch

You'll need to have `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `PGHOST`, `PGPORT` variables set in your environment pointing to your Postgres database where pgstac has been installed.

```
export PGUSER=username
export PGPASSWORD=password
export PGDATABASE=postgis
export PGHOST=database
export PGPORT=5432
```

```
$ python -m pip install uvicorn
$ uvicorn titiler.pgstac.main:app --reload
```

### Using Docker

```
$ git clone https://github.com/stac-utils/titiler-pgstac.git
$ cd titiler-pgstac
$ docker compose up --build tiler
# or
$ docker compose up --build tiler-uvicorn
```

## Contribution & Development

See [CONTRIBUTING.md](https://github.com//stac-utils/titiler-pgstac/blob/main/CONTRIBUTING.md)

## License

See [LICENSE](https://github.com//stac-utils/titiler-pgstac/blob/main/LICENSE)

## Authors

See [contributors](https://github.com/stac-utils/titiler-pgstac/graphs/contributors) for a listing of individual contributors.

## Changes

See [CHANGES.md](https://github.com/stac-utils/titiler-pgstac/blob/main/CHANGES.md).
