opening-hours 2.1.2

# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405

import builtins
import datetime
import enum
import typing
import zoneinfo

__all__ = [
    "OpeningHours",
    "State",
    "validate",
]

@typing.final
class OpeningHours:
    r"""
    Parse input opening hours description.

    ## Parameters

    - oh: Opening hours expression as defined in OSM (eg. "24/7"). See
      https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification
    - timezone: Timezone where the physical place attached to these opening hours lives in. When
      specified, operations on this expression will return dates attached to this timezone and
      input times in other timezones will be converted.
    - country: ISO code of the country this physical place lives in. This will be used to load a
      calendar of local public holidays.
    - coords: (latitude, longitude) of this place. When this is specified together with a timezone
      sun events will be accurate (sunrise, sunset, dusk, dawn). By default, this will be used to
      automatically detect the timezone and a country code.
    - auto_country: If set to `True`, the country code will automatically be inferred from
      coordinates when they are specified.
    - auto_timezone: If set to `True`, the timezone will automatically be inferred from coordinates
      when they are specified.
    - max_interval_days: If specified, any change that is longer than the number of specified days
      will be considered infinite. This may be useful if you need to evaluate a large amount of
      complicated expressions and performance is critical. Even setting a value of a full year (366)
      is worth it.

    ## Raises

    SyntaxError
        Given string is not in valid opening hours format.

    ## Examples

    >>> oh = OpeningHours("24/7")
    >>> oh.is_open()
    True

    >>> dt = datetime.fromisoformat("2024-07-14 15:00")
    >>> oh = OpeningHours("sunrise-sunset ; PH off", country="FR", coords=(48.8535, 2.34839))
    >>> assert oh.is_closed(dt)
    >>> assert oh.next_change(dt).replace(tzinfo=None) == datetime.fromisoformat("2024-07-15 06:03")
    """
    @property
    def warnings(self) -> builtins.list[builtins.str]:
        r"""
        The list of warnings that were emited while parsing the expression.
        """
    def __new__(
        cls,
        oh: builtins.str,
        timezone: typing.Optional[zoneinfo.ZoneInfo] = None,
        country: typing.Optional[builtins.str] = None,
        coords: typing.Optional[tuple[builtins.float, builtins.float]] = None,
        auto_country: typing.Optional[builtins.bool] = True,
        auto_timezone: typing.Optional[builtins.bool] = True,
        max_interval_days: typing.Optional[builtins.int] = None,
    ) -> OpeningHours: ...
    def normalize(self) -> OpeningHours:
        r"""
        Convert the expression into a normalized form. It will not affect the meaning of the
        expression and might impact the performance of evaluations.

        ## Examples

        >>> OpeningHours("24/7 ; Su closed").normalize()
        OpeningHours("Mo-Sa")

        # Motivation

        Normalization attempts to transform an expression into a minimal sequence of
        _non-overlapping_, normal rules. The goal is _not_ to make the expression
        shorter but instead to make as readable as possible. For example, the
        additional operator `,` is less known and can be mistaken with any other kind
        of sequence (eg. in a day selector `Mo,Fr`).

        Normalization is [_idempotent_][wiki-idempotence], which means that normalizing
        an already normalized expression won't change the result.

        ## Examples

        | input                                          | normalized                                                                  |
        | ---------------------------------------------- | --------------------------------------------------------------------------- |
        | `Mo-Su 00:00-24:00`                            | `24/7`                                                                      |
        | `24/7 ; Su closed`                             | `Mo-Sa`                                                                     |
        | `Mo-Su 10:00-12:00, Mo-Fr 14:00-18:00`         | `Mo-Fr 10:00-12:00,14:00-18:00; Sa-Su 10:00-12:00`                          |
        | `10:00-18:00; Jul-Aug 10:00-22:00`             | `Jan-Jun,Sep-Dec 10:00-18:00; Jul-Aug 10:00-22:00`                          |
        | `Mo-Fr,Su 10:00-18:00; Jul-Aug Su 10:00-22:00` | `Mo-Fr 10:00-18:00; Jan-Jun,Sep-Dec Su 10:00-18:00; Jul-Aug Su 10:00-22:00` |

        ## Unsupported syntax

        Not all syntax can be normalized, but this library will still do some best
        effort by normalizing the longest prefix possible and keeping all rules after
        the first unsupported one unchanged.

        Here is an exhausting list of the kind of syntax you can't expect to see
        normalized by current implementation:

        | kind                                                    | behavior                   | example (1)                  |
        | ------------------------------------------------------- | -------------------------- | ---------------------------- |
        | [fallback rule][spec-fallback]                          | stop normalization (2)     | `Mo-Fr \|\| unknown`         |
        | any range with steps                                    | stop normalization (2)     | `2000-3000/5`                |
        | [monthday range][spec-monthday-range] with fixed dates  | stop normalization (2)     | `Mar31-Jun01`                |
        | [monthday range][spec-monthday-range] with year         | stop normalization (2)     | `2025Jun-Aug`                |
        | [weekday range][spec-weekday-range] with index in month | stop normalization (2)     | `Mo[2]`, `Mo[2] +1 days`     |
        | [weekday range][spec-weekday-range] with a holiday      | stop normalization (2)     | `easter`                     |
        | time that overlaps with next day                        | stop normalization (2)     | `22:00-06:00`, `22:00-28:00` |
        | time with a solar event                                 | no time simplification (3) | `sunrise-18:00`              |
        | time with an open end                                   | no time simplification (3) | `12:00-16:00+`               |
        | time with repetition                                    | no time simplification (3) | `12:00-16:00/02:00`          |

        Notes :

        1. All the examples above contain a single rule, so they would be left
           unchanged by the normalization.
        2. This rule and any following rule won't be treated.
        3. This won't halt normalization but the algorithm won't try to merge this time
           range with others.

        If a feature is not implemented I may have considered it to be too niche for
        the effort. Feel free to [open an issue][gh-issues] on Github or open a merge
        request if you disagree!

        # How it works

        ## Build a canonical time table

        First, create a "canonical" time table over 4 dimensions (year, month, weeknum,
        daynum), each cell keeps track of time ranges recorded for a single combination
        of intervals over those 4 dimensions. Cells are always non-overlapping and can
        be split while processing the expression if necessary.

        For example, the resulting structure looks like this (simplified to 2
        dimensions for obvious reasons):

        ```text
            Mo    Sa  Su
        Jan ╆━━━━━┪───┢━━━┪     Expression:
            ┃ (1) ┃   ┃(1)┃     Mo-Fr,Su 10:00-18:00; Jul-Aug Su 10:00-22:00
        Jul ┨╌╌╌╌╌┃───┣━━━┫
            ┃ (1) ┃   ┃(2)┃     Time rules:
        Sep ┨╌╌╌╌╌┃───┣━━━┫     (1) 10:00-18:00
            ┃ (1) ┃   ┃(1)┃     (2) 10:00-22:00
            ┗━━━━━┛───┗━━━┛
        ```

        ## Extract covering rectangles out of the table

        Second, the algorithm will extract maximal rectangle in the table with all
        inner cells equal to the same value.

        ```text
        Step 1: extracted a rectangle
        - weekday: Mo-Fr
        - month: Jan-Dec
        - time: 10:00-18:00

            Mo    Sa  Su
        Jan ╆━━━━━┪───┢━━━┓     Expression:
            ┃▚▚▚▚▚┃   ┃(1)┃     Mo-Fr,Su 10:00-18:00; Jul-Aug Su 10:00-22:00
        Jul ┨▚▚▚▚▚┃───┣━━━┫
            ┃▚▚▚▚▚┃   ┃(2)┃     Time rules:
        Sep ┨▚▚▚▚▚┃───┣━━━┫     (1) 10:00-18:00
            ┃▚▚▚▚▚┃   ┃(1)┃     (2) 10:00-22:00
            ┗━━━━━┛───┗━━━┛

        Step 2: extracted a rectangle
        - weekday: Su
        - month: Jan-Jun,Sep-Dec
        - time: 10:00-18:00

            Mo        Su
        Jan ┼─────────┢━━━┓     Expression:
            │         ┃▚▚▚┃     Mo-Fr,Su 10:00-18:00; Jul-Aug Su 10:00-22:00
        Jul ┤         ┣━━━┫
            │         ┃(2)┃     Time rules:
        Sep ┤         ┣━━━┫     (1) 10:00-18:00
            │         ┃▚▚▚┃     (2) 10:00-22:00
            └─────────┗━━━┛

        Step 3: extracted a rectangle
        - weekday: Su
        - month: Jul-Aug
        - time: 10:00-22:00

            Mo        Su
            ├─────────┼───┐     Expression:
            │         │   │     Mo-Fr,Su 10:00-18:00; Jul-Aug Su 10:00-22:00
        Jul ┤         ┏━━━┓
            │         ┃▚▚▚┃     Time rules:
        Sep ┤         ┗━━━┛     (1) 10:00-18:00
            │         │   │     (2) 10:00-22:00
            └─────────┴───┘
        ```

        The result is then the concatenation : `Mo-Fr 10:00-18:00; Jan-Jun,Sep-Dec Su
        10:00-18:00; Jul-Aug Su 10:00-22:00`.

        [gh-issues]: https://github.com/remi-dupre/opening-hours-rs/issues
        [spec-fallback]: https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification#fallback_rule_separator
        [spec-monthday-range]: https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification#monthday_range
        [spec-weekday-range]: https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification#weekday_range
        [wiki-idempotence]: https://en.wikipedia.org/wiki/Idempotence
        """
    def state(
        self, time: typing.Optional[datetime.datetime] = None
    ) -> tuple[State, builtins.str]:
        r"""
        Get current state of the time domain together with current comment. The state can be either
        "open", "closed" or "unknown".

        ## Parameters

        - time: Base time for the evaluation, current time will be used if it is not specified.

        ## Examples

        >>> OpeningHours("24/7 off").state()
        (State.CLOSED, '')
        """
    def is_open(self, time: typing.Optional[datetime.datetime] = None) -> builtins.bool:
        r"""
        Check if current state is open.

        ## Parameters

        - time: Base time for the evaluation, current time will be used if it is not specified.

        ## Examples

        >>> OpeningHours("24/7").is_open()
        True
        """
    def is_closed(
        self, time: typing.Optional[datetime.datetime] = None
    ) -> builtins.bool:
        r"""
        Check if current state is closed.

        ## Parameters

        - time: Base time for the evaluation, current time will be used if it is not specified.

        ## Examples

        >>> OpeningHours("24/7 off").is_closed()
        True
        """
    def is_unknown(
        self, time: typing.Optional[datetime.datetime] = None
    ) -> builtins.bool:
        r"""
        Check if current state is unknown.

        ## Parameters

        - time: Base time for the evaluation, current time will be used if it is not specified.

        ## Examples

        >>> OpeningHours("24/7 unknown").is_unknown()
        True
        """
    def next_change(
        self, time: typing.Optional[datetime.datetime] = None
    ) -> typing.Optional[datetime.datetime]:
        r"""
        Get the date for next change of state.
        If the date exceed the limit date, returns None.

        ## Parameters

        - time: Base time for the evaluation, current time will be used if it is not specified.

        ## Examples

        >>> OpeningHours("24/7").next_change() # None
        >>> OpeningHours("2099Mo-Su 12:30-17:00").next_change()
        datetime.datetime(2099, 1, 1, 12, 30)
        """
    def intervals(
        self,
        start: typing.Optional[datetime.datetime] = None,
        end: typing.Optional[datetime.datetime] = None,
    ) -> typing.Iterator[
        builtins.tuple[datetime.datetime, datetime.datetime, State, builtins.str]
    ]:
        r"""
        Give an iterator that yields successive time intervals of consistent
        state.

        ## Parameters

        - start: Initial time for the iterator, current time will be used if it is not specified.
        - end: Maximal time for the iterator, the iterator will continue until year 9999 if it no
          max is specified.

        ## Examples

        >>> intervals = OpeningHours("2099Mo-Su 12:30-17:00").intervals()
        >>> next(intervals)
        (..., datetime.datetime(2099, 1, 1, 12, 30), State.CLOSED, '')
        >>> next(intervals)
        (datetime.datetime(2099, 1, 1, 12, 30), datetime.datetime(2099, 1, 1, 17, 0), State.OPEN, '')
        """
    def __str__(self) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class State(enum.Enum):
    r"""
    Specify the state of an opening hours interval.
    """

    OPEN = ...
    r"""
    Currently open
    """
    CLOSED = ...
    r"""
    Currently closed
    """
    UNKNOWN = ...
    r"""
    May be open depending on context
    """

def validate(oh: builtins.str) -> builtins.bool:
    r"""
    Validate that input string is a correct opening hours description.

    ## Examples

    >>> opening_hours.validate("24/7")
    True
    >>> opening_hours.validate("24/24")
    False
    """