[7/17] Improve periods module doctests, documentation, and type hints

[bonjourmauko]

Part of #1061

[bonjourmauko]

@benjello My idea to abstract date units from periods, so to facilitate their extension (weeks and so on), based on indexed enums. What do you think?

[bonjourmauko]

If these were int rather than str, we could use bitwise operations, I guess that could help vectorize period operations?

[bonjourmauko]

This has two benefits:

1. We consolidate the definition of date units in just one place, instead of using literals everywhere.

2. We can, at some point, use DateUnit.Day.index instead of day or DateUnit.value. So to be able to pass from:

if period.unit == "eternity"
period.unit in ["eternirty", ...]

To :

allowed_periods = DateUnit.DAY | DateUnit.MONTH

definition_period = [0, 1, 0, 0]

isperiod = definition_period[allowed_periods]

[bonjourmauko]

Superseded by #1138 and #1139