Metadata-Version: 2.4
Name: py-pilecore
Version: 2.5.1
Summary: Public python SDK for the CEMS PileCore web-API.
License: MIT License
        
        Copyright (c) 2023 CEMS
        
        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.
        
Project-URL: repository, https://github.com/cemsbv/py-pilecore
Keywords: API,PileCore,CEMS,CRUX
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anywidget<0.10,>=0.9.18
Requires-Dist: cems-nuclei[client]<4,>=3.2.1
Requires-Dist: dash<4,>=3.0.2
Requires-Dist: ipywidgets<9,>=8.1.5
Requires-Dist: matplotlib<4,>=3.10.1
Requires-Dist: natsort<9,>=8.4.0
Requires-Dist: numpy<3,>=2.2.4
Requires-Dist: pandas<3,>=2.2.3
Requires-Dist: plotly-geo<2,>=1.0.0
Requires-Dist: plotly<7,>=6.0.1
Requires-Dist: pygef<=0.14.0,>=0.12.0
Requires-Dist: scipy<2,>=1.15.2
Requires-Dist: shapely<3,>=2.1.0
Requires-Dist: tqdm[notebook]<5,>=4.67.1
Requires-Dist: typing-extensions<5,>=4.5.0
Provides-Extra: test
Requires-Dist: coveralls; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: openapi-core; extra == "test"
Provides-Extra: docs
Requires-Dist: Sphinx==8.2.3; extra == "docs"
Requires-Dist: asteroid-sphinx-theme==0.0.3; extra == "docs"
Requires-Dist: ipython==9.7.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints==3.5.2; extra == "docs"
Requires-Dist: sphinx_rtd_theme==3.0.2; extra == "docs"
Provides-Extra: lint
Requires-Dist: ansible-lint==26.4.0; extra == "lint"
Requires-Dist: black==26.5.1; extra == "lint"
Requires-Dist: cfn-lint==1.51.5; extra == "lint"
Requires-Dist: cpplint==2.0.2; extra == "lint"
Requires-Dist: flake8==7.3.0; extra == "lint"
Requires-Dist: isort==8.0.1; extra == "lint"
Requires-Dist: mypy==2.1.0; extra == "lint"
Requires-Dist: sqlfluff==4.2.2; extra == "lint"
Requires-Dist: yq==3.4.3; extra == "lint"
Dynamic: license-file

# py-pilecore
Public python SDK for the CEMS PileCore web-API

[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
[![Coverage Status](https://coveralls.io/repos/github/cemsbv/py-pilecore/badge.svg)](https://coveralls.io/github/cemsbv/py-pilecore)


This repository is created by [CEMS BV](https://cemsbv.nl/) and is a public python wrapper around the CEMS [PileCore web-API](https://nuclei.cemsbv.io/#/pilecore/api).

# Installation

To install a package in this repository run:

`$ pip install py-pilecore`

Or, in a [uv](https://docs.astral.sh/uv/) project:

`$ uv add py-pilecore`


## ENV VARS

To use `py-pilecore` add the follow ENV vars to your environment. Or provide them when asked.

```
* NUCLEI_TOKEN
    - Your NUCLEI user token
```

You can obtain your `NUCLEI_TOKEN` on [NUCLEI](https://nuclei.cemsbv.io/#/). 
Go to `personal-access-tokens` and create a new user token.

# Contribution

## Environment

This project uses [uv](https://docs.astral.sh/uv/) for dependency management. The
pinned dependency set lives in `uv.lock`, which is committed to the repository.

Create the development environment (a `.venv` in the repository root) with every
optional dependency group installed:

```bash
uv sync --all-extras
```

That installs the project itself in editable mode as well. Prefix commands with
`uv run` to run them inside that environment without activating it, or activate it
the usual way with `source .venv/bin/activate`.

The test matrix covers Python 3.11 through 3.13. `uv` picks an interpreter that
satisfies `requires-python` automatically; pass `--python 3.11` to `uv sync` to
develop against the oldest supported version.

## Documentation

Build the docs:

```bash
uv sync --extra docs
uv run sphinx-build -b html docs public
```

## Format

We format our code with black and isort.

```bash
uv run black --config "pyproject.toml" src/pypilecore tests notebooks
uv run isort --settings-path "pyproject.toml" src/pypilecore tests notebooks
```

## Lint

To maintain code quality we use the [GitHub super-linter](https://github.com/super-linter/super-linter).

### Reproduce the full CI lint job (Docker)

The CI lint job runs the super-linter Docker image. To reproduce it exactly,
run the `run_super_linter.sh` bash script from the root directory (requires
Docker):

```bash
./run_super_linter.sh
```

Like CI, this lints only the files changed against `main` and auto-fixes
black/isort formatting in place.

### Run the Python linters without Docker

The active Python linters are pinned in the `lint` optional-dependency group.
CI lints only the Python files changed against `main` (and excludes `tests/`),
so collect that file list first, then run each linter against it:

```bash
uv sync --extra lint
FILES=$(git diff --name-only main...HEAD -- '*.py' | grep -v '^tests/')

uv run black --check --config "pyproject.toml" $FILES
uv run isort --check-only --settings-path "pyproject.toml" $FILES
uv run flake8 --config ".flake8" $FILES
```

`mypy` needs a caveat: super-linter runs it **without installing the project**,
so unresolved third-party imports (matplotlib, numpy, pandas) become `Any` and
their errors disappear. Reproduce that with a throwaway environment that has
only `mypy` in it:

```bash
uv run --isolated --no-project --with mypy==2.1.0 \
  mypy --config-file "pyproject.toml" --no-install-types $FILES
```

Running `mypy` in a fully-installed environment reports extra import-related
errors that CI does not, so the Docker script above remains authoritative.

## UnitTest

Test the software with the use of coverage:

```bash
uv sync --extra test
uv run coverage run -m pytest
```

## Dependencies

Direct dependencies and their version ranges are declared in `pyproject.toml`.
The fully resolved set is locked in `uv.lock`, which is committed and must stay
in sync with `pyproject.toml`.

Refresh the lock file after editing `pyproject.toml`:

```bash
uv lock
```

Update everything to the newest versions allowed by the declared ranges:

```bash
uv lock --upgrade
```

Update a single package:

```bash
uv lock --upgrade-package <name>
```

Install exactly what the lock file says, failing if it is out of date (this is
what CI does):

```bash
uv sync --locked --all-extras
```

Renovate also maintains `uv.lock` automatically: it bumps the ranges in
`pyproject.toml` and refreshes the lock in the same pull request, and
`lockFileMaintenance` periodically refreshes transitive dependencies.
