KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #codex #typescript #ai-agents #ai-agent #cli #claude-code #open-source #deepseek-harness #dsh-plugin #python #mcp

longview

★ 111 Open GitHub ↗

Long View is a utility written in Python for generating long-spanning timelines from CSV-formatted data.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Introduction

![Screen Shot](https://github.com/longnow/longview/raw/master/screenshot.png)

Long View is a utility written in Python for generating timelines from CSV-formatted data. It's part of the [Long Server](http://longserver.org/) project.

## Requirements

* Python 2.3 or Higher
* Python [GD module](http://newcenturycomputers.net/projects/gdmodule.html)

## Installation

### Installing the GD Python Module

Ubuntu/Debian and other users of the apt-get system can install the GD Python Module with ``sudo apt-get install python-gd`` (Tested on Ubuntu 10.04 LTS (lucid)). Several dependencies will be installed along with it.
   
### Installing Long View

Long View is packaged with the standard python ``Distutils``. This means that the simplest way to install it is with the following command:

python setup.py install
    
Alternatively, you can run ``./longviews.py`` directly from this directory.

# How to use

The simplest thing to do is copy one of the examples.  Find the "examples" directory in your install. If you did the simple installation, chances are good that this will be either ``/usr/longview/examples`` or ``/usr/share/longview/examples``. Copy the ``biotech-*`` files somewhere where you can easily edit and modify them. You'll probably want to rename them to something more appropriate for your purpose.

## Running the script

Execute
     
     longview.py parameter-file-name

from a command-line prompt to generate the HTML for your timeline into
a subdirectory of the current directory named ``html``.  See the output
of
     
     longview.py

for a listing of options that are supported.

## Parameter File

The first thing to edit is the params file in a spreadsheet.  Make
sure the ``TIMELINE.datafile`` and ``TIMELINE.templatefile`` parameters point
to the new names, if you've changed them.

In Long View, dates (and durations, unless otherwise noted) are
generally written as ``YYYYY/MM``.  However, for ease of data entry, they
can be abbreviated: leading 0s can be dropped, and it is not necessary
to specify the month (January is assumed).  So the dates "01940/01"
and "1940" are considered equivalent.  To specify a year before the
year 0, append "BCE" or "BC", as in "8000BCE".

Most parameters present in the examples are required.

## Parameters

Many of the parameters are fairly self-explanatory, but some are not
quite so obvious. Some notes:

All sizes (eg margins, widths, heights) are specified in pixels.

A color is specified as 3 hexadecimal numbers representing its red,
green, and blue components.

``TIMELINE.nowdate``: if you specify this parameter (rather than letting
the script calculate the nowdate based on the current system clock),
it MUST be the first parameter specified in the file.

``TIMELINE.5digityears``: Set this to True if years in the HTML should
be zero-padded so that they are always five digits long.

``TIMELINE.section``: The set of section parameters describes all the
sections of the timeline.  One section is needed for each chunk of
time that has a different number of years per horizontal interval of
``TIMELINE.intervalsize`` pixels.  This allows long spans of time where
not much happens to appear condensed down to a visually palatable
size.  The three parameters for this are start-date, end-date, and
interval.  Interval is the number of years per intervalsize pixels.
The end-date is normally given as a date, but, in the case of the
end-date of the last section on the graph, may also be specified as
the string "Ongoing".  This indicates that the graph should end two
intervals past the now date.

The parameters with "diamond" in the name refer to the diamond that is
drawn in an eventbar to represent a subitem.

``TIMELINE.navcell``: The set of navcell parameters define the pieces of
the navigation bar displayed above the timeline.  Each cell takes
three parameters: the first is the name of the year in the timeline
that it should jump the viewer to.  The second is whether it should
jump the viewer to the top or the bottom of the page.  And the third
is for only the navcell that represents the chunk of time where
``TIMELINE.nowdate`` is being rendered, as it is visually slightly
different from the other cells.  Note that if no navcells are specified,
the script will generate them automatically.

``TIMELINE.resolutioninmonths`` tells how much time a specific date is
intended to represent.  Values usually will be either "1" for a month,
or "12" for a year.  Note that this parameter does NOT apply to
notifications and interest data, both of which are always assumed to
have a resolution of 1 month.

``TIMELINE.labelresolution`` can be either "months" or "years".  It
dictates whether date labels on the timline are written as
"year/month" or just "year".

``TIMELINE.staticimage`` allows extra images (such as might be used by
template HTML or CSS) to be placed in the generated tree.  The first
parameter is the original filename, and the second is the name that
the file should have in the img-static sub-directory of the generated
tree.

## Template File

The template file is actually a file containing Python code.  The only
two things that MUST be specified in the template file are the
popupTemplate variable (which contains the templated HTML for the
popup), and the stylesheets variable (which contains all the
stylesheets used by the page).  Most fonts and colors used in the HTML
can be set by editing the stylesheets.  Additionally, any of the
variables or functions that are present in lvhtml.py can be overridden
simply by supplying a new value or define here.

The popupTemplate can contain a number of "escape sequences" that have
special meaning to the code that generates the HTML:

%n is the nodeId of a particular item.  This must be used at least
once in each popup to generate an HTML node with an id attribute so
that the specific popup can be referenced from JavaScript.

%t is the title of the popup.

%d is a string representing the date or dates that this item covers.

The rest of the arguments (%1 through %9) are simply extra arguments
that will be supplied for each item in the datafile, allowing for the
HTML to be arbitrarily customized.

The notifyTemplate is used for popups over the diamonds used to
display notifications. It can be customized in the same way that the
popupTemplate can.

## Data File

Like the parameter file, this file will typically be created or edited
using a spreadsheet.  Each line in the data file represents a single
eventbar item or subitem.

The fields for an item are, in order:

item-number, start-date, end-date, clickthrough-link, title, template-argument, [...]

Note that the string "?" can be used as an end-date, and will cause
the event bar to end at the "now date", and will render in popups as
"?".

If the item-number is blank, this line is assumed to contain a subitem
of the most recently specified item.  Eventbar subitems are specific
events that happen during (and as part of) a particular eventbar item.
They are drawn as diamonds inside the eventbar of their parent item
(which is assumed to be the most recently specified item).  Their
fields are, in order:

(empty), date, clickthrough-link, template-argument, [...]

The first template argument given as part of any item or sub-itemline
is assigned the escape sequence %1. The next: %2, and so forth.  Each
template argument is substituted into the popup HTML template in place
of the appropriate escape sequence.

## Notifications File

Long View can optionally provide notifications about specific events.
By providing several NOTIFY parameters in the param file (see the
biotech example for the exact parameters), you can cause Long View to
read through a data file each time it runs, and send out a
notification for each line in the file that matches the current date.

Note that the data file itself and the directory the data file lives
in must be writable by the user running the ``longview.py`` script.  The
script re-writes the file each time it runs to keep track of which
notifications have already been sent, so they don't get sent out
multiple times (since the date resolution for notification in Long
View is a month).

The notifications data file is a CSV file.  Each line in the file has
up to five fields.  They are, in order:

item-id, date, email-addrs-to-notify, notification-text[, status]

item-id is the ID of the item in the timeline data file that this notification
corresponds to ("None" is a valid value).  Notifications will be displayed
as diamonds with popups in the timeline bar of the corresponding item.

email-addrs-to-notify is a double-quoted, comma-separated list

notification text is sent in the body of the notification email

status begins with one of "Sent", "Unsent", or "Retrying".  If an
attempt to send a notification fails, a warning is printed to stdout,
and "Retrying will be written to the status field so that the script
tries again on the next run.  If status is not specified, "Unsent" is
assumed.

The notification classes can be overridden or inherited from by using
the ``NOTIFY.hookfile`` parameter to execute the given file in the ``lvnotify``
module namespace.  ``NOTIFY.notifierclass`` and ``NOTIFY.notificationclass``
can be used to override those things.

## Interest File

By providing ``TIMELINE.interestfile``, ``EVENTBAR.nocolor``,
``EVENTBAR.yescolor``, and ``EVENTBAR.saturation`` parameters in the parameter
file, Long View can be made to generate discussion data for Long Bets
timelines in visual form.  It colors slices of the eventbar such that
height of the bottom part of each slice represents the number of NO
votes, the height of the top part represents the number of YES votes,
and the darkness of the entire slice represents the intensity of
discussion.  The interest file is a CSV file.  Each line represents a
single month's worth of discussion and votes, using the following fields:

item-Id, date, yes-vote-count, no-vote-count, discussion-post-count

The itemId assigns a given line to a specific event bar on the
timeline.

The date is expected to be in year/month format and represents a
single month.

The rest of the fields should be fairly self-explanatory.

## Other Hooks

If you need to override one or more functions in ``longview.py``, simply
specify a ``TIMELINE.hookfile`` in the param file.  This is simply a
python file that will be read in near the beginning of execution, and
any symbols will override those with the same name in longview.py.

## Licensing

These files can be redistributed and/or modified under a BSD-style license
(included in the accompanying ``LICENSE`` file).

## Questions/Feedback

Questions and/or feedback should be posted on [GitHub](https://github.com/longnow/longview/issues).

longview

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README