bdew_datetimes 0.12.0__tar.gz

bdew_datetimes-0.12.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "uv" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    cooldown:
+      default-days: 7

bdew_datetimes-0.12.0/.github/release.yml

@@ -0,0 +1,4 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot[bot]

bdew_datetimes-0.12.0/.github/workflows/dependabot_automerge.yml

@@ -0,0 +1,29 @@
+name: Dependabot auto-approve / -merge
+on: pull_request
+
+permissions: {}
+
+jobs:
+  dependabot:
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      PR_URL: ${{github.event.pull_request.html_url}}
+      GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Verify commit signature.
+        run: |
+          curl -s https://github.com/web-flow.gpg | gpg --import
+          echo "Imported GitHub keys."
+          
+          echo "Verifying signature of commit: $GITHUB_SHA"
+          git verify-commit "$GITHUB_SHA"
+      - name: Approve a PR
+        run: gh pr review --approve "$PR_URL"
+      - name: Enable auto-merge for Dependabot PRs
+        run: gh pr merge --auto --squash "$PR_URL"

bdew_datetimes-0.12.0/.github/workflows/format.yml

@@ -0,0 +1,28 @@
+name: "Format"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+env:
+  UV_LOCKED: true
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: "3.15"
+      - name: ruff ci-format
+        run: |
+          make ci-format

bdew_datetimes-0.12.0/.github/workflows/linters.yml

@@ -0,0 +1,41 @@
+name: "Linters"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+env:
+  UV_LOCKED: true
+
+jobs:
+  linters:
+    name: Python Code Quality and Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        linter-env: ["linting", "type_check", "spell_check"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: "3.15"
+      - name: Run linting
+        if: matrix.linter-env == 'linting'
+        run: |
+          make lint
+      - name: Run type_check
+        if: matrix.linter-env == 'type_check'
+        run: |
+          make typing
+      - name: Run spell_check
+        if: matrix.linter-env == 'spell_check'
+        run: |
+          make spell-check

bdew_datetimes-0.12.0/.github/workflows/packaging_test.yml

@@ -0,0 +1,35 @@
+name: "Packaging Test"
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+env:
+  UV_LOCKED: true
+
+jobs:
+  test_packaging:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Build the package
+        run: |
+          make build
+      - name: Check the built distributions
+        run: |
+          make build-check

bdew_datetimes-0.12.0/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+# This GitHub workflow is only needed for python package releases which are supposed to be published on pypi.
+# It requires the Github "environments" feature (see instructions below) it might not be available for private free accounts (but works for public or organization repos).
+# After creating the "release" environment in the Github repo settings, you need to enter your Github organization/username + repo name + "release.yml" workflow file name in the PyPI UI to make this work.
+
+# This workflow uploads a Python Package using uv when a release is created.
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [created, edited]
+
+permissions: {}
+
+env:
+  UV_LOCKED: true
+
+jobs:
+  tests:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: "3.15"
+          enable-cache: false # avoid cache poisoning
+      - name: Run the tests
+        run: |
+          make tests
+      - name: Run the type checks
+        run: |
+          make typing
+      - name: Run the linter
+        run: |
+          make lint
+      - name: Run the formatters (check only)
+        run: |
+          make ci-format
+      - name: Run the spell check
+        run: |
+          make spell-check
+
+  build-n-publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Specifying a GitHub environment, # Specifying a GitHub environment, which is strongly recommended by PyPI: https://docs.pypi.org/trusted-publishers/adding-a-publisher/
+    # you have to create an environment in your repository settings and add the environment name here
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    needs: tests
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: "3.15"
+          enable-cache: false # # avoid cache poisoning
+      - name: Build wheel and source distributions
+        run: |
+          make build
+      - name: Publish distribution 📦 to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          make release

bdew_datetimes-0.12.0/.github/workflows/unittests.yml

@@ -0,0 +1,31 @@
+name: "Unittests"
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+env:
+  UV_LOCKED: true
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v7.0.1
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run the Unit Tests
+        run: |
+          make tests

bdew_datetimes-0.12.0/.gitignore

@@ -0,0 +1,60 @@
+# Python artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+sdist/
+
+# Test artifacts
+.coverage
+.coverage.*.*
+.prefect-results
+.pytest_cache/
+
+# Type checking artifacts
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+
+# IPython
+profile_default/
+ipython_config.py
+*.ipynb_checkpoints/*
+
+# Profiling
+/prof
+
+# Environments
+.env
+.venv
+env/
+venv/
+
+# Documentation artifacts
+docs/api-ref/schema.json
+site/
+.cache/
+
+# UI artifacts
+src/prefect/orion/ui/*
+**/node_modules
+
+# Databases
+*.db
+
+# MacOS
+.DS_Store
+
+# Dask
+dask-worker-space/
+
+# Editors
+.idea/
+.vscode/
+*.code-workspace
+
+src/_bdew_datetimes_version.py

bdew_datetimes-0.12.0/.python-version

@@ -0,0 +1 @@
+3.15

bdew_datetimes-0.12.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 mj0nez
+
+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.

bdew_datetimes-0.12.0/Makefile

@@ -0,0 +1,43 @@
+
+dev:
+	uv sync
+.PHONY: dev
+
+build:
+	uv build
+.PHONY: build
+
+
+build-check:
+	uv publish --dry-run -t _token_ dist/*
+.PHONY: build-check
+
+release:
+	uv publish
+.PHONY: release
+
+tests:
+	uv run pytest tests
+.PHONY: tests
+
+typing:
+	uv run mypy --strict src/bdew_datetimes tests
+.PHONY: typing
+
+lint:
+	uv run ruff check .
+.PHONY: lint
+
+format:
+	uv run ruff format .
+.PHONY: format
+
+spell-check:
+	uv run codespell --ignore-words=domain-specific-terms.txt src/bdew_datetimes README.md
+.PHONY: spell-check
+
+# ci-only targets
+ci-format:
+	uv run ruff format --check .
+	uv run ruff check --select I .
+.PHONY: format

bdew_datetimes-0.12.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: bdew_datetimes
+Version: 0.12.0
+Summary: Generate and work with holidays of the BDEW-Calendar for power and gas in Germany
+Project-URL: Changelog, https://github.com/mj0nez/bdew-datetimes/releases
+Project-URL: Homepage, https://github.com/mj0nez/bdew-datetimes/
+Author: Konstantin Klein
+Author-email: Marcel Johannesmann <mj0nez@fn.de>
+License: MIT
+License-File: LICENSE
+Keywords: bdew,edi@energy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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 :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.11
+Requires-Dist: holidays>=0.84; python_version >= '3.10'
+Requires-Dist: python-dateutil
+Requires-Dist: pytz>=2022.7.1
+Description-Content-Type: text/markdown
+
+# bdew_datetimes
+
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mj0nez/bdew-datetimes/packaging_test.yml?style=plastic)![PyPI - Python Version](https://img.shields.io/pypi/pyversions/bdew-datetimes?style=plastic)![PyPI - License](https://img.shields.io/pypi/l/bdew-datetimes?style=plastic)![PyPI](https://img.shields.io/pypi/v/bdew-datetimes?style=plastic)
+
+A collection of utils to work with datetimes and holidays in the German energy
+market and is based on the [python-holiday](https://github.com/vacanza/holidays) package.
+
+The implementation considers the publications of the **BDEW** (Bundesverband der Energie- und Wasserwirtschaft e. V.) and **EDI@Energy**, which provide boundaries and guidance for the data exchange on the german energy market.
+
+### Current highlights:
+
+- BDEW-holiday calendar
+  - allows dict like evaluation of dates and datetimes and contains all holidays considered by the BDEW
+- Statutory Periods ("_Gesetzliche Fristen_")
+  - calculate dates of the kind "_x Werktage ab Stichtag_"
+  - calculate dates of the kind "_nter Werktag des Fristen- bzw. Liefermonats_"
+- Gas-Day / Market Day evaluation
+
+### Future Scope:
+
+- providing subdivision holiday calendars to allow granular load profiles
+
+## Quick Start and Examples
+
+Install the package from [pypi](https://pypi.org/project/bdew-datetimes/):
+
+```bash
+pip install bdew-datetimes
+```
+
+### Check if a date is a _specific_ BDEW Holidays
+
+> [!NOTE]  
+> By "specific" we mean: Holidays that are neither nation- nor statewide holidays (those are defined in the [upstream package holidays](https://github.com/vacanza/holidays)) but defined by the BDEW directly.
+> In 2025 those are: Sonderfeiertag 24h Lieferantenwechsel, Heiligabend and Silvester only.
+
+The `HolidaySum` returned by `create_bdew_calendar` contains the BDEW specific holidays.
+This means it contains those holidays which are _defined_ by BDEW which includes Heiligabend and Silvester as well as special days without Marktkommunikation but _not_ the local or nationwide holidays in Germany and its states.
+
+```python
+from datetime import date
+from bdew_datetimes import create_bdew_calendar
+
+bdew_holidays = create_bdew_calendar()  # this behaves like a dict
+
+assert date(2022, 12, 31) in bdew_holidays # Silvester is a BDEW holiday
+assert date(2022, 8, 8) in bdew_holidays is False # Augsburger Friedensfest is _not_ a BDEW holiday (but a holiday in Augsburg only)
+assert date(2022, 12, 2) in bdew_holidays is False # The 12th of February is not a BDEW holiday
+
+print(bdew_holidays.get('2022-01-01'))  # prints "Neujahr"
+```
+
+The **union** (type `HolidaySum`) of both nation and state wide holidays **and** the BDEW holidays (only the latter is returned by `create_bdew_calendar`) is the relevant calendar for German utilities.
+
+### Check if a given Date is a BDEW Working Day
+
+BDEW working days are those days taken into account for the "Fristenberechnung".
+The function `is_bdew_working_day` considers both national **and** state wide holidays **and** BDEW holidays:
+
+```python
+from datetime import date
+
+from bdew_datetimes import is_bdew_working_day
+
+assert is_bdew_working_day(date(2023, 1, 1)) is False  # Neujahr (national holiday)
+assert is_bdew_working_day(date(2023, 1, 2)) is True  # regular weekday
+assert is_bdew_working_day(date(2023, 1, 6)) is False  # Heilige Drei Könige (local holiday in parts of Germany)
+assert is_bdew_working_day(date(2023, 4, 7)) is False  # Karfreitag (national holiday, but based on an astronomical calendar)
+assert is_bdew_working_day(date(2023, 12, 24)) is False  # Heiligabend (BDEW holiday)
+```
+
+You can also get the next or previous working day for any date:
+
+```python
+from datetime import date
+
+from bdew_datetimes import get_next_working_day, get_previous_working_day
+
+assert get_next_working_day(date(2023, 1, 1)) == date(2023, 1, 2)  # the next working day after Neujahr
+assert get_previous_working_day(date(2023, 1, 1)) == date(2022, 12, 30)  # the last working day of 2022
+assert get_next_working_day(date(2023, 1, 20)) == date(2023, 1, 23)  # the next working day after a friday is the next monday
+```
+
+### Calculate Statutory Periods
+
+Statutory periods define the maximum time between e.g. the EDIFACT message for the "Anmeldung" and the actual start of supply ("Lieferbeginn").
+
+```python
+from datetime import date
+
+from bdew_datetimes import add_frist
+from bdew_datetimes import Period
+from bdew_datetimes.enums import DayType, EndDateType
+
+# Eingang der Anmeldung des LFN erfolgt am 04.07.2016. Der Mindestzeitraum von zehn WT
+# beginnt am 05.07.2016 und endet am 18.07.2016. Frühestes zulässiges Anmeldedatum
+# ist damit der 19.07.2016, sodass die Marktlokation dem LFN frühestens zum Beginn
+# des vorgenannten Tages zugeordnet wird.
+eingang_der_anmeldung = date(2016, 7, 4)
+gesetzliche_frist = Period(
+  10,
+  DayType.WORKING_DAY,
+  end_date_type=EndDateType.EXCLUSIVE
+  # lieferbeginn is the exclusive end of the previous supply contract
+)
+fruehest_moeglicher_lieferbeginn = add_frist(eingang_der_anmeldung, gesetzliche_frist)
+assert fruehest_moeglicher_lieferbeginn == date(2016, 7, 19)
+```
+
+### Calculate "Liefer- and Fristenmonate"
+
+Liefer- and Fristenmonat are concepts used in MaBiS and GPKE:
+
+```python
+from datetime import date
+
+from bdew_datetimes import get_nth_working_day_of_month
+from bdew_datetimes.enums import MonthType
+
+# returns the 18th working day of the current month in Germany
+get_nth_working_day_of_month(18)
+
+# the 18th working day of November 2023
+assert get_nth_working_day_of_month(18, start=date(2023, 11, 1)) == date(2023, 11, 28)
+
+# the 42th working day of Fristenmonat July 2023
+assert get_nth_working_day_of_month(42, month_type=MonthType.FRISTENMONAT, start=date(2023, 7, 1)) == date(2023, 9, 29)
+```
+
+## Notes
+
+The BDEW considers all days as holidays, which are nationwide holidays and days, which are a holiday in at least one state.
+Furthermore, the 24. and the 31. December are holidays as well.
+Therefore, this package utilizes the composition of all available german holiday calendars and adds the two additional days.
+
+Shifting holidays to the next weekday if they fall on a weekend is currently not considered.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management & tooling and a [GNU Makefile](https://makefiletutorial.com/) to standardize common development commands. If you want to avoid `make` you can run each command manually, in this case please still refer to the [Makefile](./Makefile).
+
+After installing uv & make, set up the development environment with:
+
+```bash
+make dev
+```
+
+Run the tests and the individual tooling via the corresponding target:
+
+```bash
+make tests
+
+make typing
+
+make lint
+
+make format
+
+make spell-check
+```
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management and tooling.
+After installing uv, set up the development environment with:
+```bash
+uv sync --group dev
+```
+
+Run the tests and the individual tooling via the corresponding dependency groups:
+```bash
+uv run --group tests pytest
+uv run --group type_check mypy --strict src/bdew_datetimes tests
+uv run --group linting ruff check .
+uv run --group linting ruff format .
+uv run --group spell_check codespell --ignore-words=domain-specific-terms.txt src/bdew_datetimes README.md
+```
+
+## License
+
+This library is licensed under the _MIT_ license, see the [LICENSE file](LICENSE).
+
+## Users
+
+This library is used by the following projects:
+
+- [Hochfrequenz Fristenkalender](https://fristenkalender.hochfrequenz.de); the respective backend is also available [online](https://fristenkalender-api.happyfield-64ecc075.westeurope.azurecontainerapps.io/docs) and as [Docker image](https://github.com/Hochfrequenz/fristenkalender-functions/pkgs/container/fristenkalender-functions)