ptr-editor 0.3.0
Utilities to edit PTR files.
Requires Python: <4.0,>=3.11

# Ptr Editor

[![PyPI](https://img.shields.io/pypi/v/ptr-editor?style=flat-square)](https://pypi.python.org/pypi/ptr-editor/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ptr-editor?style=flat-square)](https://pypi.python.org/pypi/ptr-editor/)
[![PyPI - License](https://img.shields.io/pypi/l/ptr-editor?style=flat-square)](https://pypi.python.org/pypi/ptr-editor/)
[![Coookiecutter - Wolt](https://img.shields.io/badge/cookiecutter-Wolt-00c2e8?style=flat-square&logo=cookiecutter&logoColor=D4AA00&link=https://github.com/woltapp/wolt-python-package-cookiecutter)](https://github.com/woltapp/wolt-python-package-cookiecutter)


---

**Documentation**: [https://juice-soc-public.io.esa.int/python/ptr-editor/main/](https://juice-soc-public.io.esa.int/python/ptr-editor/main/)

**Source Code**: [https://juice-soc-public.io.esa.int/python/ptr-editor/main/](https://gitlab.esa.int/juice-soc-public/python/ptr-editor)

**PyPI**: [https://pypi.org/project/ptr-editor/](https://pypi.org/project/ptr-editor/)

---



## Installation

### Basic Installation

```sh
pip install ptr-editor
```

### Optional Features

#### CLI Module

To use the command-line interface (optional), install with CLI dependencies:

```sh
pip install "ptr-editor[cli]"
```

Then you can use commands like:
```sh
ptr-editor validate path/to/file.ptx
```


## Configuration

### Logging

By default, logging is disabled in non-Jupyter environments and set to WARNING level in Jupyter notebooks. You can configure the log level using a `.env` file:

1. Copy the example environment file:
   ```sh
   cp .env.example .env
   ```

2. Edit `.env` and set your desired log level:
   ```
   PTR_EDITOR_LOG_LEVEL=INFO
   ```

Valid log levels are: `TRACE`, `DEBUG`, `INFO`, `SUCCESS`, `WARNING`, `ERROR`, `CRITICAL`

Alternatively, you can set the environment variable directly:
```sh
export PTR_EDITOR_LOG_LEVEL=DEBUG
```

Or in Python before importing ptr_editor:
```python
import os
os.environ["PTR_EDITOR_LOG_LEVEL"] = "DEBUG"
import ptr_editor
```

## Development

* Clone this repository
* Requirements:
  * [uv](https://docs.astral.sh/uv/)
  * Python 3.10+
* Create a virtual environment and install the dependencies, by:

```sh
cd ptr-editor
uv sync --all-groups
```

## Running

The package is mainly intended to be used as a library within jupyter notebooks or python scripts.

To quickly start a jupyter notebook with the package installed, you can use:

```sh
uv run jupyter lab tutorial
```

note: for this to work you need to have installed the package with uv as above.


### Testing

```sh
uv run pytest
```

### Documentation

Documentation is currently available [here](https://juice-soc-public.io.esa.int/python/ptr-editor/main/), as part of the tutorials verion.

> to be updated:
>The documentation is automatically generated from the content of the [docs directory](https://github.com/luca-penasa/ptr-editor/tree/master/docs) and from the docstrings
 of the public signatures of the source code. The documentation is updated and published as a [Github Pages page](https://pages.github.com/) automatically as part each release.

### Tutorials

A collection of example notebooks is available in the [`tutorial`](tutorial/) folder and distributed in [Gitlab Pages](#) though the CI. They can be rebuild them locally with:

```bash
uv run --group tutorials jupyter book start
```


### Releasing

#### Manual release

Releases are done with the command, e.g. incrementing patch:

```bash
uv run just bump patch
# also push, of course:
git push origin main --tags
```

this will update the changelog, commit it, and make a corresponding tag.

as the CI is not yet configured for publish on pypi it can be done by hand:

```bash
uv build
uv publish --build path/to/wheel
```
#### Automatic release - to be fixed


Trigger the [Draft release workflow](https://github.com/luca-penasa/ptr-editor/actions/workflows/draft_release.yml)
(press _Run workflow_). This will update the changelog & version and create a GitHub release which is in _Draft_ state.

Find the draft release from the
[GitHub releases](https://github.com/luca-penasa/ptr-editor/releases) and publish it. When
 a release is published, it'll trigger [release](https://github.com/luca-penasa/ptr-editor/blob/master/.github/workflows/release.yml) workflow which creates PyPI
 release and deploys updated documentation.

### Updating with copier

To update the skeleton of the project using copier:
```sh
uvx copier update --defaults
```

### Pre-commit

Pre-commit hooks run all the auto-formatting (`ruff format`), linters (e.g. `ruff` and `mypy`), and other quality
 checks to make sure the changeset is in good shape before a commit/push happens.

You can install the hooks with (runs for each commit):

```sh
pre-commit install
```

Or if you want them to run only for each push:

```sh
pre-commit install -t pre-push
```

Or if you want e.g. want to run all checks manually for all files:

```sh
pre-commit run --all-files
```

## Development Tools

This project was developed with assistance from AI tools, particularly **Claude Sonnet 3.5**, which was used extensively for:

- Initial boilerplate code creation
- Bootstrapping the test suite
- General text file editing and modification
- Code refactoring and improvements

While AI tools provided significant assistance in accelerating development, all code has been reviewed, tested, and integrated by human developers.

---

This project was generated using [a fork](https://github.com/luca-penasa/wolt-python-package-cookiecutter) of the [wolt-python-package-cookiecutter](https://github.com/woltapp/wolt-python-package-cookiecutter) template.