These two scripts, iridium-calendar and iss-calendar, scrape satellite viewing information from the Heavens Above website and add it to iCal. Their purpose is to give you notice of good satellite viewing opportunities (weather permitting).

Both scripts require

1. That you are a registered Heavens Above user with a username and password.

2. That you have set an observing site (a latitude/longitude pair) at Heavens Above.

3. That you've created a .heavens-above dotfile in your home directory. The contents of the file should consist of one line of text with your username and password, separated by a colon. For example:

    drdrang:p455w0rd
   

   A single .heavens-above dotfile works for both scripts.

4. Two non-standard Python libraries: Kenneth Reitz's envoy, and Crummy Software's Beautiful Soup.

The iridium-calendar script gets a week's worth of Iridium satellite flares. These are brief, bright reflections off the polished antennas of one of the 66 Iridium communications satellites.

The iss-calendar script gets a week's worth of International Space Station passes. These are bright but otherwise conventional satellite passes that last a few minutes.

Each script has a personalization section in which the user can set parameters that filter out less interesting (e.g., less bright) events and can tell the script which iCal calendar to put the notices in.

An alarm is set for 15 minutes before the event, giving the user time to get outside.

The scripts are intended to be run automatically each week via OS X's launchd mechanism or cron.

If you simply want a list of the next week's worth of events, you can run the scripts from the command line with the -p option. This will print the dates, times, location, and brightness for each event, one per line.