WeDroid 1.4.1

Description:

WeDroid 1.4.1

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
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.

Configuration
WeDroid will try to load its configuration from wedroid_settings.json using the following logic:

First the current running directory is checked.
If no configuration in current directory it checks the users home directory (cross-platform is supported).

This behaviour can be overridden by passing in the path to a configuration: -c "/path/to/some/where/wedroid_settings.json"
An example for storing the settings in an optional file; create a new file for example: wedroid_settings.json and insert the following:

Note: You will need an Open Weather Map API key to use this script; register at openweathermap.org.

{
"run_type": "tasker",
"intercept_task_name": "WeDroid Received", // Tasker Task name that will process the data passed to it
"owm_api_key": "<own-api-key>",
"announce_temp": true,
"announce_time": true,
"announce_humidity": 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", // OPTIONAL: Value can be: INFO, DEBUG, ERROR
"log_gps_coords": true, // OPTIONAL: true or false, enables or disables GPS co-ordinate inclusion in log files.
"location_provider": "gps", // Value can be: gps, network, passive
"location_request": "once" // Value can be: once, last, updates
}

Working with WeDroid as a package
Installation:
pip install wedroid

Double check your configuration; the file should be named: wedroid_settings.json.
Running from the CLI
This assumes that you have Python 3 (minimum 3.9) installed.
Optional - Generate a template wedroid_settings.json file
wedroid -d

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/wedroid_settings.json"

Integrating with your own custom projects
WeDroid can be utilised in your own projects, example:
import os
from wedroid.core import WeDroid

custom_config = "./wedroid_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 WeDroid source code
cd ~/Downloads
git clone [email protected]:oddineers-public/wedroid.git

Using launcher.py to get started
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/wedroid_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 wedroid_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.

Create new profile > Time > Define range and re-occurrence.
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