Pytide

Pytide is designed to email a tide report to users for the tide stations they care about. This could be useful for fishing, sailing, surfing, or any other case where tide data is important. Configuration is handled simply in a single file, and the application can be scheduled to run using a task scheduler like cron, systemd, or whatever else to send reports when the user desires.

The application is packaged as a standard Python command-line tool and can be run:

• Directly with Python
• As an installed console script (pytide)
• Optionally using modern tooling such as uv or Docker

Requirements

• Google Maps Static API key

Configuration

Pytide uses a single INI-style configuration file (config.ini). The file is not bundled with the package and must be supplied by the user.

By default, Pytide looks for the configuration file in the following locations, in order:

• Path provided via the --config-file command-line option
• Path specified by the PYTIDE_CONFIG_FILE environment variable
• ./config.ini (current working directory)
• ~/.config/pytide/config.ini
• /etc/pytide/config.ini

Stations

You can find tide stations near you by using the NOAA's Tides & Currents page.

Enter the station IDs in your configuration file. You can also specify names for the stations. The idea is that it may be more useful to use "Bob's beach house" as a descriptor than whatever the station's actual name is.

Follow the instructions in config.ini.

Recipients

Enter the email addresses for each recipient that should receive a copy of the email. These emails will be sent individually. There will not be a single email with multiple recipients CC'd on it.

Follow the instructions in config.ini.

Email server settings

An email server is not provided with this application. You will need to use your own email address and find its SMTP server settings. A stubbed example has been provided, and there are slightly more detailed notes for Gmail users in the configuration file.

Follow the instructions in config.ini.

Google maps

Normal interactive maps are not embeddable in emails. This project uses Google's Maps Static API to to provide the images. However, an API key is not provided with this application. You must sign up for the service and provide your own API key in order to retrieve map images.

This is not a free service. However, for personal use cases, you are very unlikely to make enough API queries to get charged. Last I checked, you are permitted 10,000 map images retrieved before charges are incurred. That's ~322 requests per day.

Follow the instructions in config.ini.

Alternatively, the API key may be provided through the command line using the --maps-api-key command line option or by specifying a PYTIDE_MAPS_API_KEY environment variable.

Usage

uv (Recommended)

1. Install the dependencies.

   uv sync --no-dev

2. Run the application.

   uv run pytide

3. Optionally, pass a configuration file explicitly.

   uv run pytide --config-file /path/to/config.ini

System Python

1. (Recommended): Create and activate a virtual environment.

   • Linux or macOS

     python3 -m venv .venv
     source .venv/bin/activate
     python -m pip install --upgrade pip

   • Windows (PowerShell)

     python -m venv .venv
     ./.venv/Scripts/Activate.ps1
     python -m pip install --upgrade pip

   • Windows (Command Prompt)

     python -m venv .venv
     .venv\Scripts\activate
     python -m pip install --upgrade pip

2. Install the package.

   pip install .

3. Run the application using the default configuration file.

   pytide

4. Optionally, pass a configuration file explicitly.

   pytide --config-file /path/to/config.ini

You may also run pytide as a module.

python -m pytide

License

This project is licensed under the terms of the BSD 3-Clause License. See LICENSE.md for details.