cronspell 0.3.0

Date-expression domain specific language parsing. A neat way to express things like "First Saturday of any year", or "3rd thursdays each month" and such

Cronspell Python Package / CLI Tool

Chronometry Spelled Out

Details
Features

Date-expression domain specific language (DSL) parsing. A neat way to express things like "First Saturday of any year", or "3rd thursdays each month" and such.

DSL Example

To get the last saturday of last month:

"now /m -1d /sat"

The same, more verbose:

"now /month -1day /sat"

Test for Upcoming Occurrences

Find upcoming dates beginning of every 3rd calendar week using the upcoming module and its moments generator.

---

from collections.abc import Generator

import time_machine

from cronspell.upcoming import moments as upcoming


cw3: Generator = upcoming("@cw 3")

# given the current Calendar week is in 2024-W51 ... 2025-W02
assert next(cw3).strftime("%G-W%V") == "2025-W03"
assert next(cw3).strftime("%G-W%V") == "2025-W06"
assert next(cw3).strftime("%G-W%V") == "2025-W09"

Installation

Python module

If you need just the python function to parse cronspell expressions:

pip install cronspell

from cronspell import parse

date_of_interest = parse("now /m -1d /sat")

Command Line Interface

If you like to use it in your command line:

pip install 'cronspell[cli]'

cronspell parse "now /m -1d /sat"

Features

Python

Cronspell is heavily inspired by Grafana's relative Date picker user interface. It shines when configuration is needed to reflect irregular date-distances such as in the example below.

cronspell lets you express relative dates such as "last saturday of last month" and converts it to a date object for use in your python project.

from cronspell import parse

# Cronspell's purpose is mostly to parse configuration files written in yaml
# and therein express relative date times in a human friendly manner.

# here is but a simple demo:
last_saturday = parse("now/sat")
...

Cli

The same interface, exposed to the command line. Formatted via isodate by default -- which is open for configuration using the --format option.

This is how you get the last saturday of the current month, for example:

cronspell parse "now /month + 34 days /m -1d /sat"

Pre-Commit Hook: Validation

Cronspell comes with a pre-commit hook that validates configured date-expressions based on yamlpath.

Check out the documentation for detailed instructions.

Credits

• Domain-Specific-Language Parser: TextX
• This package was created with The Hatchlor project template.