pytimeline

Pytimeline

pytimeline is a command line tool for the creation of SVG timelines from JSON.

[!NOTE] This is a rewrite of the old timeline script from Jason Reisman and full credits go to him for most of the work. I have merely cleaned it up and made it into a package with a command line interface.

Install

The package is compatible with Python 3.9+ and can be installed in your current environment with pip:

python -m pip install pytimeline

Usage

When the package is installed in your activated environment, it can be called through python -m pytimeline. Detailed usage goes as follows:

Usage: python -m pytimeline [OPTIONS]

Options:
  --inputfile PATH                Path to the input JSON file with the
                                  timeline data.  [required]
  --outputfile PATH               Path at which to write the output SVG file.
                                  [default: timeline.svg]
  --logging [trace|debug|info|warning|error|critical]
                                  Sets the logging level.  [default: info]
  --help                          Show this message and exit.

The script will parse your input file and export the SVG document in the provided output folder or, if not provided, in the same directory as the input file.

One can otherwise import the high-level object from the package and use it directly:

from pytimeline import Timeline

timeline = Timeline(inputfile="your_input.json")
timeline.build()
timeline.save("timeline.svg")

Input Data Format

The input file is a JSON document that describes the start and end points of the timeline, tickmarks along the main axis, as well as callouts to specifc dates/times, and eras which highlight temporal periods.

All date fields can be described in several common date formats and may optionally also include a time of day (e.g. "3/14/15 9:26am"). Datetime parsing is handled by the pendulum package, and one can find all the accepted date formats in the relevant documentation.

Required and Optional Fields

The required fields are width, start, and end. All other fields are optional.

Required:

• width describes the width, in pixels, of the output SVG document, and the height will be determined automatically.
• start is the date/time of the leftmost date/time on the axis.
• end is the date/time of the rightmost date/time on the axis.

Optional:

• num_ticks contols the number of tickmarks along the axis between the start and end date/times (inclusive). If this field is not present, no tickmarks will be generated except for those at the start and end dates.
• tick_format describes the string format of the tickmarks along the axis. See the valid formats for the pendulum package.

Special Fields

Callouts

Callouts along the axis are described in the callouts list, in which each entry is also a list with two to three string values:

• The first value is the description of the callout (e.g., "Pi Day"). It is required.
• The second value is the date/time of the callout (e.g., "3/14/15 9:26am"). It is required.
• The third value can specify a color for the callout, either as a hexcode or a valid SVG color alias. It is optional.

Callout examples:

["Ultimate Pi Day", "3/14/15 9:26am"]

Or, with a custom callout color:

["Ultimate Pi Day", "3/14/15 9:26am", "#CD3F85"]

Eras

Eras are highlighted temporal periods and are described in the eras list. Like the callouts list, each entry in the eras list is itself a list with either three or four string values:

• The first value is the description of the era (e.g., "Summer"). It is required.
• The second value is the start date/time of the era (e.g., "6/21/15 12am"). It is required.
• The third value is the end date/time of the era (e.g. "9/20/15 11:59pm"). It is required.
• The fourth value can specify a color for the era, either as a hexcode or a valid SVG color alias. It is optional.

Era examples:

["Summer 2015", "6/21/15 12am", "9/20/15 11:59pm"]

Or, with a custom era color:

["Summer 2015", "6/21/15 12am", "9/20/15 11:59pm", "Orange"]

Simple Example

The JSON input for the example timeline at the top of this README is:

{
    "width" : 750,
    "start" : "Oct 8 2015",
    "end" : "Oct 15 2015",
    "num_ticks" : 14,
    "tick_format" : "%b %d, %Y - %I:%M%p",
    "callouts" : [
        ["ABC easy as 123", "Oct 14, 2015 3pm"],
        ["Midnight Event A", "12am Oct 10, 2015", "#DD0000"],
        ["Noon Event A", "12pm Oct 10, 2015"],
        ["5pm Event A", "5pm Oct 10, 2015"],
        ["Something amazing happening", "Oct 11, 2015"],
        ["Awesome Event B", "Oct 12, 2015", "#DD0000"],
        ["C", "Oct 13, 2015"],
        ["Event E", "Oct 14, 2015"]
    ],
    "eras" : [
        ["Era 1", "12pm Oct 8, 2015", "3am Oct 12, 2015", "#CD3F85"],
        ["Era 2", "8am Oct 12, 2015", "12am Oct 15, 2015", "#C0C0FF"]
    ]
}