Metadata-Version: 2.4
Name: sentineltoolbox
Version: 0.9.0
Author: ACRI-ST
License-Expression: Apache-2.0
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 :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools>=68.2.2
Requires-Dist: dask>=2023.11.0
Requires-Dist: distributed>=2023.11.0
Requires-Dist: xarray>=2024.11.0
Requires-Dist: numpy
Requires-Dist: zarr<4,>=2.18
Requires-Dist: numcodecs
Requires-Dist: fsspec[s3]>=2023.10.0
Requires-Dist: toml>=0.10.2
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: tomli
Requires-Dist: colorlog
Requires-Dist: pandas
Requires-Dist: h5netcdf
Requires-Dist: h5py
Requires-Dist: eccodes>=1.7.1
Requires-Dist: ecmwflibs>=0.6.3
Requires-Dist: cfgrib>=0.9.10.4
Requires-Dist: geopandas
Requires-Dist: dacite
Requires-Dist: netcdf4>=1.7.2
Requires-Dist: rioxarray>=0.15.5
Requires-Dist: rasterio>=1.3.10
Requires-Dist: overrides
Requires-Dist: deepdiff
Requires-Dist: bs4
Requires-Dist: packaging
Requires-Dist: defusedxml
Requires-Dist: cql2
Provides-Extra: zarr-v2
Requires-Dist: zarr<3,>=2.18; extra == "zarr-v2"
Provides-Extra: zarr-v3
Requires-Dist: zarr<4,>=3; extra == "zarr-v3"
Provides-Extra: converter-v2
Requires-Dist: eopf<3.0.0,>=2.6.0; extra == "converter-v2"
Requires-Dist: zarr<3,>=2.18; extra == "converter-v2"
Provides-Extra: converter
Requires-Dist: eopf>=3.0.0rc4; python_version >= "3.13" and extra == "converter"
Provides-Extra: cluster-plugin
Requires-Dist: dask-jobqueue>=0.8.2; extra == "cluster-plugin"
Requires-Dist: dask-gateway>=2023.1.1; extra == "cluster-plugin"
Provides-Extra: tests
Requires-Dist: pytest<8; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: hypothesis; extra == "tests"
Requires-Dist: pytest-error-for-skips; extra == "tests"
Requires-Dist: geopandas; extra == "tests"
Requires-Dist: dacite; extra == "tests"
Requires-Dist: lxml; extra == "tests"
Requires-Dist: jupytext; extra == "tests"
Requires-Dist: nbmake; extra == "tests"
Provides-Extra: linter
Requires-Dist: flake8; extra == "linter"
Provides-Extra: typing
Requires-Dist: mypy; extra == "typing"
Requires-Dist: types-python-dateutil; extra == "typing"
Requires-Dist: types-pytz; extra == "typing"
Requires-Dist: types-setuptools; extra == "typing"
Requires-Dist: types-toml; extra == "typing"
Requires-Dist: types-PyYAML; extra == "typing"
Requires-Dist: types-click; extra == "typing"
Requires-Dist: types-jinja2; extra == "typing"
Requires-Dist: types-colorama; extra == "typing"
Provides-Extra: formatter
Requires-Dist: black; extra == "formatter"
Requires-Dist: isort; extra == "formatter"
Provides-Extra: security
Requires-Dist: bandit; extra == "security"
Requires-Dist: safety; extra == "security"
Provides-Extra: notebook
Requires-Dist: jupyter>=1.0.0; extra == "notebook"
Requires-Dist: Jinja2>=3.1.2; extra == "notebook"
Requires-Dist: fonttools>=4.43.0; extra == "notebook"
Requires-Dist: matplotlib>=3.7.1; extra == "notebook"
Requires-Dist: itables; extra == "notebook"
Provides-Extra: doc
Requires-Dist: sphinx>=5.3.0; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints>=1.22; extra == "doc"
Requires-Dist: sphinx_needs==5.1.0; extra == "doc"
Requires-Dist: jupyter-sphinx>=0.4.0; extra == "doc"
Requires-Dist: sphinx-book-theme>=1.0.1; extra == "doc"
Requires-Dist: sphinx-togglebutton>=0.3.2; extra == "doc"
Requires-Dist: sphinx-inline-tabs>=2023.4.21; extra == "doc"
Requires-Dist: sphinx-panels>=0.4.1; extra == "doc"
Requires-Dist: sphinx-test-reports==1.3.0; extra == "doc"
Requires-Dist: sqlalchemy>=2.0.0b1; extra == "doc"
Requires-Dist: myst-nb>=0.17.2; extra == "doc"
Requires-Dist: linkify-it-py>=2.0.0; extra == "doc"
Requires-Dist: numpydoc>=1.5.0; extra == "doc"
Requires-Dist: jupytext>=1.14.5; extra == "doc"
Requires-Dist: urllib3>=1.26.17; extra == "doc"
Requires-Dist: breathe>=4.35.0; extra == "doc"
Requires-Dist: pytest; extra == "doc"
Requires-Dist: sphinxcontrib-apidoc>=0.3.0; extra == "doc"
Requires-Dist: sphinxcontrib-spelling>=8.0.0; extra == "doc"
Requires-Dist: sphinxcontrib.plantuml; extra == "doc"
Requires-Dist: sphinxcontrib.mermaid; extra == "doc"
Requires-Dist: sphinx_copybutton>=0.5.2; extra == "doc"
Requires-Dist: GitPython>=3.1.41; extra == "doc"
Requires-Dist: nbsphinx>=0.9.1; extra == "doc"
Requires-Dist: mdutils>=1.6.0; extra == "doc"
Requires-Dist: tomark>=0.1.4; extra == "doc"
Requires-Dist: sphinxcontrib.mermaid; extra == "doc"
Provides-Extra: complexity
Requires-Dist: xenon>=0.9.1; extra == "complexity"
Provides-Extra: doc-cov
Requires-Dist: docstr-coverage>=2.2.0; extra == "doc-cov"
Provides-Extra: dev
Requires-Dist: pre-commit>=3.5.0; extra == "dev"
Requires-Dist: sentineltoolbox[zarr-v3]; extra == "dev"
Requires-Dist: sentineltoolbox[complexity,doc-cov,tests]; extra == "dev"
Requires-Dist: sentineltoolbox[formatter,linter,typing]; extra == "dev"
Requires-Dist: sentineltoolbox[doc,notebook,security]; extra == "dev"
Requires-Dist: sentineltoolbox[cluster-plugin]; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Dynamic: license-file

<!--
  Copyright 2024-2026 ACRI-ST

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->

# sentineltoolbox

[![Code Style][black-badge]][black-link]
[![Documentation][doc-badge]][doc-link]

**sentineltoolbox** (stb) is a Python library for manipulating Copernicus Sentinel satellite products.
It provides I/O, conversion, documentation generation, validation and convenience utilities
on top of `xarray.DataTree`.

Sentinel products are described in the [Copernicus Programme documentation](https://sentiwiki.copernicus.eu/web/).

## Stable API

API stability is a core principle of sentineltoolbox: users must be able to
upgrade to a newer version without rewriting any code.

All symbols exported by {obj}`sentineltoolbox.api` and {obj}`sentineltoolbox.typedefs` are stable. Stability is
All other modules are internal and must not be used directly.
See {doc}`overview` for the full feature list.

## Installation

```bash
pip install eopf-cpm>=2.6
pip install sentineltoolbox
```

For development (editable install):

```bash
git clone <repository_url>
pip install -e ".[dev]"
```

### uv

This project can use [uv](https://docs.astral.sh/uv/) for dependency locking. The lockfile
(`uv.lock`) resolves optional extras separately when they have incompatible requirements
(see `tool.uv.conflicts` in `pyproject.toml`).

**Runtime-only install** (zarr v3, no eopf — default):

```bash
uv sync
```

**Runtime-only with zarr v2** (no eopf). Cannot be combined with `dev` or `zarr-v3`:

```bash
uv sync --extra zarr-v2
```

**Runtime-only with an explicit zarr v3 pin** (same outcome as plain `uv sync`, no eopf):

```bash
uv sync --extra zarr-v3
```

**Full development environment** (zarr v3, no eopf, plus linters, tests, docs, etc.):

```bash
uv sync --extra dev
```

**With eopf 2.x** (>=2.6.0, zarr v2). Use a dedicated environment; this
extra cannot be combined with `dev` or `zarr-v3`:

```bash
uv sync --extra converter-v2 --no-dev
```

**With eopf 3.x** (pre-release, Python 3.13+, zarr v3 compatible). Cannot be combined
with `converter-v2`:

```bash
uv sync --extra converter --prerelease=allow --python 3.13
```

Optional extras:

| Extra            | Purpose                                                                   |
| ---------------- | ------------------------------------------------------------------------- |
| `zarr-v2`        | Pin zarr to v2 without eopf                                               |
| `zarr-v3`        | Explicitly pin zarr to v3 (included in `dev`; same as plain `uv sync`)    |
| `converter-v2`   | eopf 2.x (>=2.6.0) for legacy conversion workflows (includes zarr v2 pin) |
| `converter`      | eopf 3.x for conversion workflows                                         |
| `cluster-plugin` | Dask cluster integration                                                  |

> **Note — eopf 2.x (`converter-v2`) on Python 3.13**
>
> eopf 2.x pins `rasterio==1.3.10`, which has no Python 3.13 wheel and cannot be
> built from source in practice. The `converter-v2` extra is therefore *a priori*
> incompatible with Python 3.13 when using `pip`.
>
> **`uv` on Python 3.13**: installation works using `uv` because `tool.uv.override-dependencies`
> in `pyproject.toml` relaxes the rasterio pin to `>=1.3.11`.
>
> **`pip` on Python 3.11 or 3.12**: use the `converter-v2` extra directly:
>
> ```bash
> pip install ".[converter-v2]"
> ```

## Quick start

```python
from sentineltoolbox.api import open_datatree, display

xdt = open_datatree("path/to/product.zarr")
display(xdt)
```

## Features

### Open products, ADFs and other data files

Open DPR Zarr, JSON, or legacy SAFE/SEN3 data as `DataTree` or `Dataset`:

- `open_datatree`, `load_datatree` — open/load a product as `xarray.DataTree`
- `open_json` — open JSON
- `load_metadata` load only metadata (very quick) from zarr and replace arrays with 1 element fake arrays.

### Generate HTML documentation for products

Create rich interactive HTML summaries of DPR products directly in Jupyter or Sphinx:

- `display` — render a `DataTree` as an HTML table with metadata, flags, and structure
- `print_summary` — compact text summary

### Convert legacy products

Convert original S2/S3 products (`.SAFE`, `.SEN3`) and ADF to DPR Zarr format (`.zarr`):

- Supported products (via eopf-cpm mappings): S3 OLCI (EFR, ERR, LFR), S3 SLSTR (RBT, FRP, LST),
  S3 SYNERGY (AOD, SYN, VG1, VGP, VGK, V10), S2 MSI (L1A, L1B, L1C, L2A)
- Supported ADF (internal converters): S3 OLCI, SLSTR, SYNERGY
- CLI: `stb_convert_products`, `stb_eop_convert_products`

### Flag operations

Bitwise operations on CF-convention flag arrays:

- `create_flag_array` — create a flag array with a given shape and bit depth
- `update_flag` — set or clear individual flags
- `get_flag` — extract a boolean mask for a given flag

### Parse and generate product file names

- `ProductFileNameGenerator`, `AdfFileNameGenerator` — build DPR-compliant file names from legacy names
- `detect_filename_pattern`, `filename_generator` — detect product and ADF filename patterns (legacy, dpr) and instantiate generators

### DataTree utilities

- `AttributeHandler` — set, extract, and fix product attributes
- `DataTreeHandler` — high-level wrapper for product metadata and attributes (derived from `AttributeHandler`)
- `get_array`, `get_datatree` — type-safe node access (no mypy errors)
- `convert_to_datatree` — convert `dict`, `Dataset`, or `EOProduct` to `DataTree`
- `validate_datatree` — validate structure, dtypes and attributes against a schema
- `patch_datatree` — apply patches to a `DataTree`

### Check processor inputs

Verify consistency of input products and ADFs before processing:

- `check_processor_inputs`, `check_adfs`

### Filesystem and credentials

Browse local or S3 filesystems transparently:

- `get_universal_path`, `get_fsspec_filesystem`, `get_url_and_credentials`
- `S3BucketCredentials`

### Sentinel metadata databases

Cached, extensible JSON/TOML databases of product metadata, properties,
naming conventions, and namespaces.

### Environment and logging

- `init`, `init_jupyter_env` — set up logging, xarray display, IPython formatters
- `LoggerSuppressor`, `WarningsSuppressor` — context managers for quiet execution

### Command Line Tools

- `stb_convert_products` — convert SAFE/SEN3 ADF and products (deprecated) to DPR Zarr
- `stb_eop_convert_products` — same using EOPF/CPM mappings
- `stb_compare_products` — compare two products and summarize differences
- `stb_dump_product` — dump product summary

## API stability

Only symbols re-exported from `sentineltoolbox.api` are considered **stable**.
All other modules are internal and may change without notice.

## Documentation

Full documentation: https://DPR-ACR.pages.eopf.copernicus.eu/sentineltoolbox

## License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

## Copyright

Copyright 2024-2026 ACRI-ST.

[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
[black-link]: https://black.readthedocs.io/en/stable/
[doc-badge]: https://img.shields.io/badge/documentation-passed-blue.svg
[doc-link]: https://DPR-ACR.pages.eopf.copernicus.eu/sentineltoolbox
