opening_hours

A library for parsing and working with OSM's opening hours field. You can find its specification here and the reference JS library here.

Note that the specification is quite messy and that the JS library takes liberty to extend it quite a lot. This means that most of the real world data don't actually comply to the very restrictive grammar detailed in the official specification. This library tries to fit with the real world data while remaining as close as possible to the core specification.

The main structure you will have to interact with is OpeningHours, which represents a parsed definition of opening hours.

1from .opening_hours import *
2
3__doc__ = opening_hours.__doc__
4if hasattr(opening_hours, "__all__"):
5    __all__ = opening_hours.__all__
class InvalidCoordinatesError(builtins.Exception):

Input coordinates are not valid.

class ParserError(builtins.Exception):

The opening hours expression has an invalid syntax.

See https://wiki.openstreetmap.org/wiki/Key:opening_hours/specification for a specification.

class UnknownCountryError(builtins.Exception):

The provided country code is not known.

See https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes.

def validate(oh, /):

Validate that input string is a correct opening hours description.

Examples
>>> opening_hours.validate("24/7")
True
>>> opening_hours.validate("24/24")
False
class State:

Specify the state of an opening hours interval.

OPEN = State.OPEN
CLOSED = State.CLOSED
UNKNOWN = State.UNKNOWN
class OpeningHours:

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.
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")
def normalize(self, /):

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")
def state(self, /, time=None):

Get current state of the time domain, 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=None):

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

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

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

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=None, end=None):

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, [])