initial release of hdhelpers on pypi

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/check_pull_request.yml

@@ -0,0 +1,67 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Check pull requests
+
+# Controls when the workflow will run
+on:
+  # Triggers the workflow on push or pull request events but only for the "develop" branch
+  pull_request:
+    branches: [ "develop", "main" ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+
+jobs:
+  build:
+    name: test_pypy_version
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv and set the Python version
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Display Python version
+        run: python -c "import sys; print(sys.version)"
+
+      - name: Sync dependencies and run checks
+        run: |
+          set -e
+          echo "Installing hdhelpers"
+          uv sync --locked --all-extras --dev
+          echo "Running tests..."
+          ./run test
+
+
+  check_lint_format_mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Info
+        run: echo "Applying checks"
+
+      - name: Sync dependencies and run checks
+        run: |
+          set -e
+          echo "Installing hdhelpers"
+          uv sync --locked --all-extras --dev
+          echo "Running checks..."
+          ./run check --no-tests

.gitignore

@@ -0,0 +1,30 @@
+# quality checks
+.coverage
+.pytest_cache
+.mypy_cache
+.ruff_cache
+coverage*
+
+# documentation
+sphinx/build
+
+# venv
+.venv
+.env
+
+# packaging
+dist/*
+
+# generals
+__pycache__
+*.pyc
+*.pyo
+
+# other stuff
+launch.json
+requirements*.txt
+requirements*.in
+todo
+untracked
+Dockerfile
+docker-compose.yaml

.vscode/settings.json

@@ -0,0 +1,33 @@
+{
+    "search.exclude": {
+        "**/__pycache__": true,
+        "**/.git": true,
+        "**/.venv": true,
+        ".tmp": true,
+        "**/.mypy_cache": true,
+        "**/.pytest_cache": true,
+        "**/.coverage": true,
+        "**/.ruff_cache": true
+    },
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/.venv": true,
+        ".tmp": true,
+        "**/.mypy_cache": true,
+        "**/.pytest_cache": true,
+        "**/.coverage": true,
+        "**/.ruff_cache": true
+    },
+    "editor.formatOnSave": true,
+    "editor.indentSize": "tabSize",
+    "editor.detectIndentation": false,
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports.ruff": "explicit"
+        },
+    },
+    "python.defaultInterpreterPath": ".venv/bin/python",
+    "python.languageServer": "Default",
+
+}

CHANGELOG.md

@@ -0,0 +1,8 @@
+## [0.0.2] - 2026-XX-XX
+- Include helpers for metadata
+- Include helper function for modify timezone
+- Publish sphinx documentation on GitHub Pages
+
+## [0.0.1] - 2025-09-11
+- Test upload on pypi of hdhelpers
+- Note: No tagging used as it was only a test upload on pypi

LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 fuseki GmbH
+
+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.

README.md

@@ -0,0 +1,108 @@
+# Welcome to hdhelpers
+
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/hetida/hdhelpers/graphs/commit-activity)
+[![build](https://github.com/hetida/hdhelpers/actions/workflows/check_pull_request.yml/badge.svg)](https://github.com/hetida/hdhelpers/actions/workflows/check_pull_request.yml)
+![python](https://img.shields.io/badge/python-%203.12%20|%203.13|%203.14%20-blue)
+[![PyPI version](https://badge.fury.io/py/hdhelpers.svg)](https://badge.fury.io/py/hdhelpers)
+![PyPI - License](https://img.shields.io/pypi/l/hdhelpers)
+[![Downloads](https://pepy.tech/badge/hdhelpers)](https://pepy.tech/project/hdhelpers)
+
+## What is hdhelpers?
+hdhelpers is a package designed for and included in the standard installation of the [hetida
+designer](https://github.com/hetida/hetida-designer).
+
+Currently, the package provides functions to retrieve metadata from Pandas objects (stored in the `attr` of the Pandas object). Pandas objects are the standard for processing time series data in the hetida designer. Additionally, a function is provided to handle time zone information. In the future, the package is planned to be expanded, for example by providing functions to facilitate visualization.
+
+The documentation of the package is a [GitHub page](https://hetida.github.io/hdhelpers/), on which the functions of the package are described and some tips for getting started with using the package are given.
+
+## Getting Started with hdhelpers
+Since version >0.13.10 the hetida designer runtime comes with an installed version of hdhelpers. To start the hetida designer we recommend following the [hetida designer setup guide](https://github.com/hetida/hetida-designer/blob/release/README.md#getting-started-with-hetida-designer).
+
+An example is given in [GitHub page](https://hetida.github.io/hdhelpers/first_steps.html#how-to-get-metadata-with-hdhelpers) of how to use functionalities of hdhelpers inside a hetida designer component. Furthermore the base component [Single Time Series Plot](https://github.com/hetida/hetida-designer/blob/release/runtime/transformations/components/visualization) uses hdhelpers to demonstrate the usage (since version >0.13.10).
+
+## Developing for hdhelpers
+For dependency management and venv setup, building and publishing, [uv](https://docs.astral.sh/uv/) is used.
+
+### Setting up a Development Environment
+#### Python environment
+1) Create a virtual environment with `uv venv`. This will create a hidden `.venv` directory.
+2) Activate the virtual environment via `source .venv/bin/activate`
+3) Run `uv sync` to install all dependencies given in pyproject.toml.
+4) In case you need to add a new dependency, do so via `uv add <new_dependency>`. That way, uv finds versions of all
+   dependencies that are compatible with each other.
+5) In case you need a new requirement for development purposes please use `uv add --dev <new_dependency>`
+
+Note: To install hdhelpers in editable mode in your venv please run `uv pip install -e .`
+
+#### hetida designer with hdhelpers
+To test designer images with current hdhelpers version please save a copy of [docker-compose.yml](https://github.com/hetida/hetida-designer/blob/release/docker-compose.yml) from the hetida designer repository.
+
+Then write a `Dockerfile` to install the current hdhelpers version in the required designer backend.
+```yaml
+FROM hetida/designer-backend:<<hd_version>>
+
+USER root
+
+RUN pip install .
+
+USER hd_app
+
+CMD ["bash", "/app/start.sh"]
+```
+
+Then modify the docker-compose.yml to work with the backend version defined by the modified Dockerfile.
+```yaml
+...
+  hetida-designer-backend:
+    build:
+      context: .
+      dockerfile: Dockerfile
+...
+```
+
+
+use docker-compose.yaml, e.g. via
+`docker compose -f 'docker-compose.yaml' up -d --build`. This compose setup loads the current
+hetida designer images and installs the hdhelpers package in the runtime. Thus, you can use functions of hdhelpers
+writing component code.
+
+### Code Quality
+Once you are done writing your code, including unit tests, use `./run check` to see if your code quality is sufficient.
+
+### Documentation
+Fr documentation we use the tool sphinx. Please apply `./run build_docs` to create the current state of documentation. It will be stored in **docs**. You can open the documentation by opening `docs/index.html`, e.g. with your browser.
+
+### Build, Release and Publish
+The first step for publishing a new package version is creating and merging a pull request from develop to main.
+In detail the following steps should be executed beforehand:
+
+1) Please execute `./run build_package <version_nr>` where version number should follow [semantic versioning](https://semver.org/).
+This will:
+- Runs `uv sync --frozen` to upgrade dependencies.
+- Update version in pyproject.toml
+- Update \_\_version__ in \_\_init__.py
+- Builds wheels of hdhelpers in ./dist
+
+2) Ensure that listed `classifiers` in `pyproject.toml`are up to date. If not
+- Update `pyproject.toml` accordingly
+- Update `./run test-py-versions` accordingly for local testing using uv
+- Update `check_pull_request.yml` accordingly for automated pipeline execution of checks
+- Update badge in this file for Python versions above
+
+3) Update CHANGELOG.md manually following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+When the PR is accepted, the package can be **published** in a second step.
+To **publish** the build from the `dist` subdirectory to PyPI,
+
+1) tag your main branch with the specified package version
+
+2) use `uv publish --index testpypi --token <API-token>`. You need a (Test-)PyPI account with a token and you need maintainer/owner access to the [hdhelpers (Test-)PyPI project](https://pypi.org/project/hdhelpers/).
+
+3) After publishing please communicate to the hetida designer team so upgrade there dependencies.
+The hetida designer docker compose setup installs hdhelpers from [PyPI](https://pypi.org) as it does with any dependency listed in `runtime/requirements.in`.
+
+### Notes
+- Please ensure that dependencies specified for hdhelpers do work in current designer versions.
+- If you want to upgrade dependencies please run `uv lock --upgrade`
+- to install hdhelpers from testpypi you can use:
+`uv pip install --extra-index-url https://test.pypi.org/simple/ --index-url https://pypi.org/simple --refresh --index-strategy unsafe-best-match hdhelpers`