WeDroid Python 3 Package

The weather announcement assistant. We(ather)Droid; for more information please visit: WeDroid Download.

Sphinx autogenerated source documentation available at: oddineers-public.gitlab.io/wedroid

Configuration

You will need an Open Weather Map API key to use this script.

You defined the configuration settings for WeDroid as a dictionary. You can either define this dictionary in the file calling the WeDroid class or you can optionally define it as a separate file.

An example for storing the settings in an optional file; create a new file for example: settings.json and insert the following:

{
    "run_type": "tasker",
    "intercept_task_name": "WeDroid Received",
    "owm_api_key": "<own-api-key>",
    "announce_temp": true,
    "announce_time": true,
    "announce_humidty": false,
    "announce_wind": false,
    "announce_sun": true,
    "sl4a_gtts": false,
    "bot_name": "WeDroid",
    "mattermost_url": "<web-hook-url>",
    "device_location": true,
    "longitude": -3.0,
    "latitude": 53.0,
    "log_level": "DEBUG",       // Value can be: INFO, DEBUG, ERROR
    "location_provider": "gps", // Value can be: gps, network, passive
    "location_request": "once"  // Value can be: once, last, updates
}

Working with WeDroid as a package

When initiating WeDroid; pass the newly created configuration file:

From the CLI

This assumes that you have Python 3 (minimum 3.9) installed.

Installation

pip install wedroid

Forecast styled report

wedroid -t "forecast" -i "3h" -l 12 

Observation styled report

wedroid  -t "observation" -lt "14.0" -lc 812

Observation styled report with custom configuration

wedroid  -t "observation" -lt "14.0" -lc 812 -c "/path/to/some/where/settings.json"

In your own custom projects

WeDroid can be utilised in your own projects, example:

import os
from wedroid.core import WeDroid

custom_config = "./settings.json"
if os.path.isfile(custom_config):
  # Pass in to WeDroid
  weather = WeDroid(custom_config)

From here you can access functions:

# A Forecast for 4 results split by a 3h interval
message = weather.generate_forecast_announcement("3h", "4")

# A weather observation now (compares previously values)
message = weather.generate_weather_announcement()

Customising messages and weather statuses

The messages and weather responses can be customised under ./wedroid/translations/* if working with the source directly:

• annoucements.json contains various message part that make-up a report, example:

  •   "sunrise-future": "The Sun will rise in {}.",
      "sunset-past": "The Sun set {} ago.",
      "sunset-future": "The Sun will set in {}.",
    

• weather.json contains a dict where the weather status codes map to a: title, icon, description, example

  •   "781": {
        "title": "Tornado",
        "icon": "50d",
        "description": "tornado"
      }
    

As a package you can pass the path the translations directory as follows, ensure that it contains announcements.json & weather.json:

wedroid = WeDroid(translation_path="./some/where/translations")

Working with the source code

cd ~/Downloads
git clone git@gitlab.com:oddineers-public/wedroid.git

Fetching weather reports

WeDroid can run either observation or forecasts styled reports.

• Observations include a summary of the weather, temperature, time.
• Forecasts return the weather status for a given interval + limit; for example 3h as the interval and 4 as the limit. Would produce a report with 4 observations with 3 hours intervals.

Forecast styled report

python3 launcher.py -t "forecast" -i "3h" -l 12 

Observation styled report

python3 launcher.py  -t "observation" -lt "14.0" -lc 812

Observation styled report with custom configuration

python3 launcher.py  -t "observation" -lt "14.0" -lc 812 -c "/path/to/some/where/settings.json"

Building the module:

Install build by build.pypa.io.

pip install build

Then build the distributable:

python -m build -n

Example for installing the wheel:

pip install WeDroid-1.x.x-py3-none-any.whl
pip install <path_to_file>\wedroid\dist\WeDroid-1.x.x-py3-none-any.whl

Tasker - Android

NOTE: This section will make more sense once the examples are ready and Tasker Profiles + Tasks made available.

Requirements (Android):

• Tasker
• Termux (other shells are likely supported where you can install Python 3)
• Termux:API
• Termux Tasker plugin
• Termux requirements:
  • Termux configured to access local storage
  • Termux:API configured to allow GPS access (if you intend to let WeDroid access the devices location)

These instructions are somewhat vague at the moment and will be expanded soon in greater details in ReadTheDocs.

When used with Tasker on Android you can define a task and/or profile which can run the WeDroid announcement service.

To run the script ensure the following:

• Python 3 via the Termux.
  • Termux is installed.
  • Python 3 package is installed.
  • The Task in Tasker is specifically "Run Termux Script" & the script to run is called launcher.py enabled and pass the following variables: %WD_LAST_TEMP, %WD_LAST_CODE.
• In Tasker assign the value 0 to%WD_LAST_TEMP, %WD_LAST_CODE.
• Run script to finish configuration and create default configuration.
• Open settings.json and add your OWM API key, create one here.

Upon first run the following Tasker variables are created:

%WD_LAST_CODE
%WD_SUNRISE
%WD_SUNSET
%WD_LAST_TEMP
%WD_LAST_TIME
%WD_LAST_WIND_SPEED
%WD_LAST_WIND_DIRECTION
%WD_LAST_HUMIDITY
%WD_DAY_STATE
# The main announcement
%WD_ANNOUNCEMENT
# Announcement parts separated
%WD_TIME_MSG
%WD_WEATHER_MSG
%WD_TEMP_MSG
%WD_WIND_MSG
%WD_SUN_MSG
%WD_HUMIDITY_MSG

At this point the configuration aspect is complete, but we need to configure a run schedule within Tasker.

Tasker Profile Creation

The simplest method is to create a Tasker Profile using the Time profile.

1. Create new profile > Time > Define range and re-occurrence.
2. Next link the profile to a new task "Run Termux Script" as defined earlier.

Documentation from source

Generating documentation

Ensure sphinx is install with:

pip install sphinx

Change to docs directory

cd docs

Building docs

sphinx-apidoc -f -o source/ ../wedroid
make clean
make html

Regenerate the Sphinx readme.rst from the project README.md (requires pandoc):

pandoc --from=markdown --to=rst --output=source/readme.rst ../README.md

Linux one-liner

sphinx-apidoc -f -o source/ ../wedroid && make clean && make html

Windows one-liner

sphinx-apidoc -f -o source/ ../wedroid & make clean & make html