Metadata-Version: 2.5
Name: luciole-toolbox
Version: 1.0.0
Summary: Data preparation and formatting utilities for Swiss fauna observation data.
Author-email: Kim Biloni <kim.biloni@infofauna.ch>, Jules Gottraux <jules.gottraux@infofauna.ch>
License-Expression: LGPL-3.0-or-later
License-File: COPYING
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: pyproj>=3.6.1
Requires-Dist: requests>=2.32.5
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == 'dev'
Requires-Dist: ruff>=0.16.3; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.7.7; extra == 'docs'
Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=1.0.6; extra == 'docs'
Description-Content-Type: text/markdown

# luciole-toolbox

[![CI](https://github.com/info-fauna/luciole-toolbox/actions/workflows/ci.yml/badge.svg)](https://github.com/info-fauna/luciole-toolbox/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/luciole-toolbox.svg)](https://pypi.org/project/luciole-toolbox/)
[![License](https://img.shields.io/pypi/l/luciole-toolbox.svg)](LICENSE)

Python utility library from info-fauna for preparing and standardizing Swiss
fauna observation data — coordinate conversion, formatting, and lookups
against Swiss reference geodata. Built for data producers (biologists,
cantonal monitoring staff, naturalists, and partner organizations) and for
use in ETL pipelines and internal systems that load this data into a
database.

Currently ships a `geo` module for Swiss coordinates: CRS detection
(WGS84/LV03/LV95), conversion between them, CKM2/CNHA grid codes, and
commune/canton lookup via the swisstopo API.

## Installation

```bash
pip install luciole-toolbox
```

## Usage

```python
from luciole_toolbox.geo import convert_coordinates, get_location_info, CRSType

convert_coordinates("46.9480", "7.4474", target=CRSType.LV95)
get_location_info("46.9480", "7.4474")
```

Full API reference: <https://info-fauna.github.io/luciole-toolbox/>

## Development

```bash
pip install -e ".[dev]"
```

### Testing

```bash
pytest                      # all tests, incl. calls to swisstopo/pyproj CDN
pytest -m "not integration" # skip tests hitting real network endpoints
```

### Docs

```bash
pip install -e ".[docs]"
mkdocs serve # preview locally at http://127.0.0.1:8000
```

## Versioning & releases

The version is derived from git tags via `hatch-vcs` — there is no version
string to hand-edit. Notable changes are tracked in
[CHANGELOG.md](CHANGELOG.md).

To cut a release:

1. Move the `[Unreleased]` entries in [CHANGELOG.md](CHANGELOG.md) under a
   new `## [x.y.z] - YYYY-MM-DD` heading and commit it to `main`.
2. Tag that commit and push the tag:

   ```bash
   git tag v0.1.0
   git push origin v0.1.0
   ```

This triggers the `release` workflow, which builds the package, publishes
it to PyPI, and creates a matching GitHub Release.

## Contributing

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for
setup, testing, and PR guidelines, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
for expected behavior in this project's spaces.

## Security

To report a vulnerability, see [SECURITY.md](SECURITY.md) — please don't
open a public issue for security reports.

## License

LGPL-3.0-or-later. See [LICENSE](LICENSE) for the LGPL terms and
[COPYING](COPYING) for the GPL terms it incorporates by reference.
