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_, which means that normalizing an already normalized expression won't change the result.

Examples

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:

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

    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.

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.

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, '')

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

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

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

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)

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, '')

The list of warnings that were emited while parsing the expression.