Skip to content

Cronspell Python Package / CLI Tool

Chronometry Spelled Out

Github Pages
Details Tests License - MIT
Features linting - Ruff types - mypy test - pytest Pre-Commit docs - mkdocs

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.

Status

CronSpell is currently in Beta. While it is considered well tested and stable for most use cases, there may still be some edge cases and bugs that need to be addressed. The maintainer encourages users to try it out and provide feedback to help improving the library.

Your contributions and bug reports are highly appreciated.

Features

Cronspell is heavily inspired by Grafana's relative Date picker user interface. It was designed for the cases when configuration is needed to reflect irregular date-distances.

Use it within your Python project or via command line interface.

Python

Installation: pip install cronspell

Cli

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

Installation with cli-specific dependencies: pip install cronspell[cli]

Syntax

Comments

// a comment

/*
    multi-line
    comment ...
*/

Datetime Designators

/m -1d /sat

The same, more verbose:

/month -1day /sat

Datetime Designator Sets

By enclosing a set in curly braces ({}), a comma seperated list of datetime designators is evaluated.

// here comes a set of datetime designators
{
    // first saturday of the month:
    /m -1d /sat + 7d,

    // sunday of every second calendar week:
    @cw 2 + 6d
}

Timezone Designation

// `now` is the default anchor for subsequent designators.
// passing a timezone name to get the results with the same timezone:

now[Europe/Berlin] {
    // first saturday of the month:
    /m -1d /sat + 7d,

    // sunday of every second calendar week:
    @cw 2 + 6d
}

pre-commit hook

This package comes with a pre-commit hook that allows for automated preflight checks on yaml files serving as sources for cronspell expressions.

Put this in your .pre-commit-config.yaml and adjust according to your needs:

repos:
  - repo: https://github.com/iilei/cronspell
    rev: 8b455b10109b62d050bec9509649565ae8057ae8   # v0.4.0
    hooks:
      - id: cronspell
        files: .*\/cfg\.ya?ml$
        args: ["--yamlpath", "/*/*date*" ]

Credits

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

Documentation for specific MAJOR.MINOR versions can be chosen by using the dropdown on the top of every page. The dev version reflects changes that have not yet been released. Shortcuts can be used for navigation, i.e. ,/p and ./n for previous and next page, respectively, as well as //s for searching.