bdew_datetimes 0.12.0__py3-none-any.whl

_bdew_datetimes_version.py

@@ -0,0 +1 @@
+version = "0.12.0"

bdew_datetimes/__init__.py

@@ -0,0 +1,29 @@
+"""
+bdew_datetimes is a package that models the BDEW holiday, which is relevant for German utilities
+"""
+
+from .calendar import BdewDefinedHolidays, create_bdew_calendar
+from .german_time_zone import GERMAN_TIME_ZONE
+from .models import Period
+from .periods import (
+    add_frist,
+    get_next_working_day,
+    get_nth_working_day_of_month,
+    get_previous_working_day,
+    is_bdew_working_day,
+)
+from .utils import get_all_bdew_non_working_days, get_all_bdew_working_days
+
+__all__ = [
+    "create_bdew_calendar",
+    "BdewDefinedHolidays",
+    "Period",
+    "is_bdew_working_day",
+    "get_next_working_day",
+    "get_previous_working_day",
+    "add_frist",
+    "get_nth_working_day_of_month",
+    "get_all_bdew_working_days",
+    "get_all_bdew_non_working_days",
+    "GERMAN_TIME_ZONE",
+]

bdew_datetimes/calendar.py

@@ -0,0 +1,104 @@
+"""
+contains the business logic (namely the BDEW calendar information)
+
+"""
+
+from datetime import date
+from typing import Any
+
+from holidays import HolidayBase, HolidaySum
+from holidays.constants import DEC, JUN  # type: ignore[attr-defined]
+from holidays.countries.germany import Germany
+
+
+class BdewDefinedHolidays(HolidayBase):
+    """
+    Special holidays considered by the BDEW, excluding nationwide or state specific holidays.
+
+    To get a full calendar with all holidays use the function `create_bdew_calendar`.
+
+    Currently, in Germany there are no observed holidays e.g. a Holiday is
+    moved to the next Workday, if it's on Sunday.
+
+    """
+
+    def __init__(self, observed: bool = False, **kwargs: Any) -> None:
+        super().__init__(observed=observed, **kwargs)
+
+    def _populate(self, year: int) -> None:
+        self[date(year, DEC, 24)] = "Heiligabend"
+        self[date(year, DEC, 31)] = "Silvester"
+        if year == 2025:
+            self[date(2025, JUN, 6)] = (
+                "Sonderfeiertag"
+                # Anlässlich der (verschobenen) Einführung des 24h Lieferantenwechsels
+            )
+
+
+_relevant_subdivisions: list[str] = [
+    "BB",  # Brandenburg.
+    "BE",  # Berlin.
+    "BW",  # Baden-Württemberg.
+    "BY",  # Bayern.
+    "HB",  # Bremen.
+    "HE",  # Hessen.
+    "HH",  # Hamburg.
+    "MV",  # Mecklenburg-Vorpommern.
+    "NI",  # Niedersachsen.
+    "NW",  # Nordrhein-Westfalen.
+    "RP",  # Rheinland-Pfalz.
+    "SH",  # Schleswig-Holstein.
+    "SL",  # Saarland.
+    "SN",  # Sachsen.
+    "ST",  # Sachsen-Anhalt.
+    "TH",  # Thüringen.
+    # This list contains an explicit list of all BDEW calendar relevant Germany subdivisions.
+    # It does _not_ include the 'Augsburg' subdivision which has been added in holidays v0.78.
+    # https://github.com/vacanza/holidays/commit/feab68b4377369ad52eeee9e98fc8316ec0c6f86
+]
+
+
+def create_bdew_calendar() -> HolidaySum:
+    """Creates a calendar containing all days considered by the BDEW.
+
+    Currently, in Germany there are no observed holidays e.g. a Holiday is
+    moved to the next Workday, if it's on Sunday.
+
+    "Nach GPKE und GeLi Gas sind alle jene Tage Werktage, die weder Sonnabend,
+    Sonntag oder gesetzlicher Feiertag sind. Generell gelten der 24.12. und
+    der 31.12. als Feiertage. Angaben ohne Gewähr."
+
+    https://www.bdew.de/media/documents/GPKE-GeLiGas-Feiertagskalender-2022-Version-1-1_Uu1w6UQ.pdf
+
+    [Accessed 2022-11-02]``
+
+    Returns
+    -------
+    holidays.HolidaySum
+        dict-like holiday calendar, to check if a date/datetime is a holiday
+    """
+
+    # First we need the BDEW specific holidays.
+    calendar = BdewDefinedHolidays(language="de")
+
+    # the type is wrong at assignment but correct after the first loop iteration
+    result: HolidaySum = calendar  # type: ignore[assignment]
+    original_language_before_adding_subdivisions = result.language
+    # If a day is holiday in any subdivision, the holiday is valid nationwide.
+    # Therefore, we add all subdivisions of Germany to the BDEW specific holidays.
+    # Currently, in Germany holidays are not observed.
+    for subdivision in _relevant_subdivisions:
+        # the method __add__ expects a Union[int, "HolidayBase", "HolidaySum"] as `other`
+        # here, we're dealing with a child instance of HolidayBase
+        result += Germany(subdiv=subdivision, observed=False, language="de")  # type: ignore[assignment]
+    if result.language is None:
+        # This is a workaround to a problem in holidays 0.20-0.53 (at least):
+        # When adding the subdivisions, the language attribute is lost,
+        # although holiday base and subdivision share the same language.
+        # The problem happens here:
+        # https://github.com/vacanza/python-holidays/blob/v0.53/holidays/holiday_base.py#L1164
+        result.language = original_language_before_adding_subdivisions
+    return result
+
+
+__all__ = ["BdewDefinedHolidays", "create_bdew_calendar"]

bdew_datetimes/enums.py

@@ -0,0 +1,68 @@
+"""enums used inside the package"""
+
+from enum import Enum, StrEnum
+
+
+class Division(Enum):
+    """
+    Allows to distinguish divisions used by German utilities, German "Sparte".
+    """
+
+    STROM = 1  #: electricity
+    GAS = 2  #: gas
+
+
+class DayType(StrEnum):
+    """
+    An enum to differentiate between calendar days and working days.
+    """
+
+    WORKING_DAY = "WT"  #: working day, German "Werktag"
+    CALENDAR_DAY = "KT"  #: calendar day, German "Kalendertag"
+
+
+class EndDateType(Enum):
+    """
+    An enum to distinguish inclusive and exclusive end dates.
+    """
+
+    INCLUSIVE = 1
+    """
+    If a contract ends with the year 2022 and the end date is denoted as "2022-12-31",
+    then the end date is inclusive. Most dates in human (spoken) communication are meant
+    inclusively.
+    """
+
+    EXCLUSIVE = 2
+    """
+    If a contract ends with the year 2022 and the end date is denoted as "2023-01-01",
+    then the end date is exclusive. Most end dates handled by technical systems are meant
+    exclusively.
+    """
+
+
+class MonthType(Enum):
+    """
+    When calculating periods defined as 'nth working day of a month' the
+    BNetzA regulations distinguish between two types of month which are
+    modelled in this enum.
+    Some periods refer to the "Liefermonat", others to the "Fristenmonat".
+    """
+
+    LIEFERMONAT = 1
+    """
+    The "Liefermonat" is the month in which the supply starts.
+    """
+    FRISTENMONAT = 2
+    """
+    The grid operators prefer a key date based handling of supply contracts.
+    The key date in these cases is usually expressed as a specific working day
+    in the so called "Fristenmonat".
+    The "Fristenmonat" starts at the first day of the month
+    _before_ the "Liefermonat".
+    Quote: 'Nach der Festlegung BK6-06-009 (GPKE) der Monat vor dem Liefermonat.'
+    """
+    # source: https://www.bundesnetzagentur.de/DE/Beschlusskammern/1_GZ/BK6-GZ/_bis_2010/2006/BK6-06-009/BK6-06-009_Beschluss_download.pdf?__blob=publicationFile&v=5
+
+
+__all__ = ["Division", "EndDateType", "MonthType", "DayType"]

bdew_datetimes/german_strom_and_gas_tag.py

@@ -0,0 +1,99 @@
+"""
+A module to evaluate datetimes and whether they are "on the edge"
+of a German "Stromtag" or "Gastag" respectively
+"""
+
+from datetime import datetime, time
+from typing import Callable
+
+# The problem with the stdlib zoneinfo is, that the availability of timezones
+# via ZoneInfo(zone_key) depends on the OS and system on which you're running
+# it. In some cases "Europe/Berlin" might be available, but generally it's not,
+# and it's PITA to manually define timezones. So we're using pytz as a
+# datasource for timezone information.
+from pytz import utc
+
+from bdew_datetimes.enums import Division
+
+from .german_time_zone import GERMAN_TIME_ZONE
+
+
+def _get_german_local_time(date_time: datetime) -> time:
+    """
+    Returns the current german local time for the given datetime object.
+    """
+    german_local_datetime = date_time.astimezone(GERMAN_TIME_ZONE)
+    return german_local_datetime.time()
+
+
+def has_no_utc_offset(date_time: datetime) -> bool:
+    """
+    Returns true if and only if date_time has an explicit offset to UTC.
+    If the UTC-offset is 0, it is exactly "+00:00".
+    """
+    # the name of the function contains a negation because in German
+    # market communication it often matters that the UTC offset is 0.
+    original_time = date_time.time()
+    utc_time = date_time.astimezone(tz=utc).time()
+    return (
+        utc_time == original_time
+        and utc_time.hour == 0
+        and utc_time.minute == 0
+        and utc_time.second == 0
+    )
+
+
+def is_stromtag_limit(
+    date_time: datetime,
+) -> bool:  # the name is not as speaking as I'd like it to be
+    """
+    Returns true if and only if the given date_time is the inclusive
+    start or exclusive end of a german "Stromtag".
+    The "Stromtag" is the balancing relevant day in the German electricity
+    market.
+    It starts and ends at midnight in German local time which can be
+    either 23:00 h or 22:00 h in UTC (depending on the daylight saving time in Germany).
+    """
+    german_local_time = _get_german_local_time(date_time)
+    return (
+        german_local_time.hour == 0
+        and german_local_time.minute == 0
+        and german_local_time.second == 0
+    )
+
+
+def is_gastag_limit(
+    date_time: datetime,
+) -> bool:  # the name is not as speaking as I'd like it to be
+    """
+    Returns true if and only if the given date_time is the inclusive start
+    or exclusive end of a german "Gastag".
+    The "Gastag" is the balancing relevant day in the German gas market.
+    It starts and ends at 6am in German local time which can be either
+    04:00 h or 05:00 h in UTC (depending on the daylight saving time in Germany).
+    """
+    german_local_time = _get_german_local_time(date_time)
+    return (
+        german_local_time.hour == 6
+        and german_local_time.minute == 0
+        and german_local_time.second == 0
+    )
+
+
+def is_xtag_limit(date_time: datetime, division: Division) -> bool:
+    """
+    Evaluates if it is the start/end of a provided division.
+    """
+    xtag_evaluator: Callable[[datetime], bool]
+    if division == Division.STROM:
+        xtag_evaluator = is_stromtag_limit
+    elif division == Division.GAS:
+        xtag_evaluator = is_gastag_limit
+    else:
+        raise NotImplementedError(
+            f"The division must either be 'Strom' or 'Gas': '{division}'"
+        )
+    return xtag_evaluator(date_time)
+
+
+__all__ = ["is_gastag_limit", "is_stromtag_limit"]

bdew_datetimes/german_time_zone.py

@@ -0,0 +1,6 @@
+"""static timezone object for Berlin/Germany"""
+
+from pytz import timezone
+
+GERMAN_TIME_ZONE = timezone("Europe/Berlin")
+__all__ = ["GERMAN_TIME_ZONE"]

bdew_datetimes/models.py

@@ -0,0 +1,57 @@
+"""model classes used in this package"""
+
+from dataclasses import dataclass
+from typing import Literal, Union
+
+from bdew_datetimes.enums import DayType, EndDateType
+
+_DayTyp = Union[DayType, Literal["WT", "KT"]]
+
+
+@dataclass
+class Period:
+    """
+    A period is a German "Frist": A tuple that consists of a number of days and a day type.
+    """
+
+    number_of_days: int
+    """
+    number of days (might be any value <0, >0 or ==0)
+    """
+    day_type: DayType
+    """
+    the kind of days to add/subtract
+    """
+
+    def __init__(
+        self,
+        number_of_days: int,
+        day_type: _DayTyp,
+        end_date_type: EndDateType = EndDateType.EXCLUSIVE,
+    ):
+        """
+        Initialize the Period by providing a number of days and a day_type which define the period.
+
+        """
+        self.number_of_days = number_of_days
+        # If the Period is about something ending (e.g. a contract), then the user may
+        # provide an end_date_type.
+        # Internally we handle all end dates as exclusive, because:
+        # https://hf-kklein.github.io/exclusive_end_dates.github.io/
+        if end_date_type == EndDateType.INCLUSIVE:
+            if self.number_of_days > 0:
+                self.number_of_days = self.number_of_days - 1
+            elif self.number_of_days < 0:
+                self.number_of_days = self.number_of_days + 1
+        if isinstance(day_type, DayType):
+            pass
+        elif isinstance(day_type, str):
+            day_type = DayType(day_type)
+        else:
+            raise ValueError(
+                f"'{day_type}' is not an allowed value; Check the typing"
+            )
+        self.day_type: DayType = day_type
+
+
+__all__ = ["Period"]

bdew_datetimes/periods.py

@@ -0,0 +1,142 @@
+"""
+periods is a module that helps to calculate statutory periods
+("gesetzliche Fristen") in the German energy market.
+It is based on the chapter "Fristenberechnung" in the GPKE.
+"""
+
+import datetime
+from datetime import date
+from typing import Optional
+
+from dateutil.relativedelta import relativedelta
+from holidays import SAT, SUN  # type: ignore[attr-defined]
+
+from bdew_datetimes.calendar import create_bdew_calendar
+from bdew_datetimes.enums import DayType, EndDateType, MonthType
+from bdew_datetimes.german_time_zone import GERMAN_TIME_ZONE
+from bdew_datetimes.models import Period
+
+# https://www.bundesnetzagentur.de/DE/Beschlusskammern/1_GZ/BK6-GZ/2020/BK6-20-160/Mitteilung_Nr_2/Leseversion_GPKE.pdf
+# pages 15 onwards
+
+_bdew_calendar = create_bdew_calendar()
+"""
+a static calendar object that is used (module) internally
+"""
+
+
+def is_bdew_working_day(candidate: date) -> bool:
+    """
+    Returns true if and only if the given candidate is a day relevant for the period calculation.
+    Returns false if the given candidate is either a BDEW holiday, a saturday or sunday.
+    """
+    if candidate in _bdew_calendar:
+        return False
+    return candidate.weekday() not in (SAT, SUN)
+
+
+def get_next_working_day(start_date: date) -> date:
+    """
+    If start_date is a working day, the next (+1) working day is returned.
+    If this day is a BDEW holiday or falls on a weekend, the next working day
+    is returned.
+    """
+    result = start_date + datetime.timedelta(
+        days=1
+    )  # in any case the calculation starts at least at the next day
+    while not is_bdew_working_day(result):
+        # if the next day is a holiday, then we add days until we find a working day
+        result += datetime.timedelta(days=1)
+    return result
+
+
+def get_previous_working_day(start_date: date) -> date:
+    """
+    If start_date is a working day, the previous (-1) working day is returned.
+    If this day is a BDEW holiday or falls on a weekend, the previous working day
+    is returned.
+    """
+    result = start_date - datetime.timedelta(
+        days=1
+    )  # in any case the calculation starts at least at the next day
+    while not is_bdew_working_day(result):
+        # if the previous day is a holiday, then we subtract days until we find a working day
+        result -= datetime.timedelta(days=1)
+    return result
+
+
+def add_frist(start: date, period: Period) -> date:
+    """
+    Returns the date that is period after start.
+    """
+    result: date = start
+    if period.number_of_days >= 0:
+        # the period calculation starts at the next working day, even if the number_of_days == 0
+        result = get_next_working_day(result)
+    # result is now the "Beginndatum" of the Fristenberechnung
+    if period.day_type == DayType.CALENDAR_DAY:
+        return result + datetime.timedelta(days=period.number_of_days)
+    # day_type is working day
+    if period.number_of_days == 0:
+        return result
+    if period.number_of_days > 0:
+        days_added = 0
+        while days_added < period.number_of_days:
+            result += datetime.timedelta(days=1)
+            if is_bdew_working_day(result):
+                # it's a usual working day; those are considered for the period calculation
+                days_added += 1
+    else:  # implicitly: elif period.number_of_days < 0:
+        days_subtracted = 0
+        while days_subtracted <= abs(period.number_of_days):
+            result -= datetime.timedelta(days=1)
+            if is_bdew_working_day(result):
+                days_subtracted += 1
+    return result
+
+
+def get_nth_working_day_of_month(
+    number_of_working_day_in_month: int,
+    month_type: MonthType = MonthType.LIEFERMONAT,
+    start: Optional[date] = None,
+) -> date:
+    """
+    Returns the nth working of the month, starting at start.
+    If start is None, then we use the local date/start of month in Germany.
+    Only year and month of the provided start date are taken into account.
+    The date.day is always discarded.
+
+    This function is useful if you're dealing with statutory periods from the
+    GPKE/MaBiS that are defined as "working days since start of month".
+    """
+    if start is None:
+        start = GERMAN_TIME_ZONE.localize(datetime.datetime.utcnow()).date()
+    if month_type == MonthType.LIEFERMONAT:
+        # returns the "nter Werktag des Liefermonats"
+        start = get_previous_working_day(start.replace(day=1))
+        period = Period(
+            number_of_days=number_of_working_day_in_month,
+            day_type=DayType.WORKING_DAY,
+            end_date_type=EndDateType.INCLUSIVE,
+        )
+        result = add_frist(start, period)
+    elif month_type == MonthType.FRISTENMONAT:
+        # returns the "nter Werktag des Fristenmonats"
+        start_of_next_month = start.replace(day=1) + relativedelta(months=1)
+        result = get_nth_working_day_of_month(
+            number_of_working_day_in_month,
+            month_type=MonthType.LIEFERMONAT,
+            start=start_of_next_month,
+        )
+    else:
+        raise ValueError(f"Unhandled month_type {month_type}")
+    return result
+
+
+__all__ = [
+    "is_bdew_working_day",
+    "get_next_working_day",
+    "get_previous_working_day",
+    "add_frist",
+    "get_nth_working_day_of_month",
+]

bdew_datetimes/py.typed

@@ -0,0 +1,2 @@
+# This file marks the package as PEP561 compatible.
+# Further reading: https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages

bdew_datetimes/utils.py

@@ -0,0 +1,47 @@
+"""
+helper functions
+"""
+
+from datetime import date, timedelta
+
+from bdew_datetimes.calendar import create_bdew_calendar
+
+_bdew_calendar = create_bdew_calendar()
+
+
+def _get_all(is_working_day: bool, year: int) -> list[date]:
+    """
+    Returns a list of all BDEW working days or non-working days in the given year.
+    """
+    days = []
+    current_date = date(year, 1, 1)
+    end_date = date(year, 12, 31)
+    while current_date <= end_date:
+        if _bdew_calendar.is_working_day(current_date) == is_working_day:
+            days.append(current_date)
+        current_date += timedelta(days=1)
+
+    return days
+
+
+def get_all_bdew_working_days(year: int) -> list[date]:
+    """
+    Returns a list of all BDEW working days in the given year.
+    This includes all weekdays except saturday and sunday that are not BDEW holidays.
+    """
+    return _get_all(is_working_day=True, year=year)
+
+
+def get_all_bdew_non_working_days(
+    year: int, include_weekends: bool
+) -> list[date]:
+    """
+    Returns a list of all BDEW working days in the given year.
+    """
+    non_working_days = _get_all(is_working_day=False, year=year)
+    if include_weekends:
+        return non_working_days
+    return [d for d in non_working_days if d.weekday() not in (5, 6)]
+
+
+__all__ = ["get_all_bdew_working_days", "get_all_bdew_non_working_days"]

bdew_datetimes-0.12.0.dist-info/METADATA

@@ -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)

bdew_datetimes-0.12.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+_bdew_datetimes_version.py,sha256=0d_eblF-LMXh1_mZw-q2DqmmX_vZj5tYDy8MONmqkNU,19
+bdew_datetimes/__init__.py,sha256=w-ffQrLFd9YWeky7keRjLoujBIyhFgiF3OSlWewX2_U,793
+bdew_datetimes/calendar.py,sha256=a8SasRInjEXHZqDjLw-CvnkeFBrgtrcDlSTcW1F5IDo,3957
+bdew_datetimes/enums.py,sha256=le--wNy25T3RsvIkMP0Nkyx2iNk3ju3DygojLSJWyrQ,2054
+bdew_datetimes/german_strom_and_gas_tag.py,sha256=j_PBZBf4W_kRgteIcH-NpS9Dfwzwn7vw3k95Ecf54aM,3399
+bdew_datetimes/german_time_zone.py,sha256=fBWU6SAkZsGQ9FSlxVUa8zssyRQ0xtjAk7p0nnmBJII,152
+bdew_datetimes/models.py,sha256=73cUvResRAST0XEXYZdfyOCBy404avZWcLg8gTJx0n4,1697
+bdew_datetimes/periods.py,sha256=p_Eh0EoWPd5Zbzpfs8SUeYoiMciSGyfA9QP5QLpRZko,5238
+bdew_datetimes/py.typed,sha256=UMj6hnFihehUfxt0cdFZhinH-WhK5OI0ZC4Hxa6eiY0,170
+bdew_datetimes/utils.py,sha256=RWD1gRxxARBgv_235nLzxm4ooQjQ1cS4FeiU2xtbGOg,1328
+bdew_datetimes-0.12.0.dist-info/METADATA,sha256=PViXPJECHQNhhNPVaYL4q3mAcEMOBW7BRhNZfmA6_rE,9003
+bdew_datetimes-0.12.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bdew_datetimes-0.12.0.dist-info/licenses/LICENSE,sha256=5CQf-Y46R5vjfkEM6aIIq3LD2TtKDQeane0hR0shJCA,1063
+bdew_datetimes-0.12.0.dist-info/RECORD,,

bdew_datetimes-0.12.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

bdew_datetimes-0.12.0.dist-info/licenses/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.