Metadata-Version: 2.1
Name: WeDroid
Version: 1.3.4
Summary: A weather announcement agent that summarises weather in realtime using OpenWeatherMaps; Features additional support for Android devices using Termux & Tasker.
Home-page: https://oddineers.co.uk/applications/wedroid
Author: Steven
Author-email: steven@oddineers.co.uk
Project-URL: Documentation, https://oddineers.co.uk/applications/wedroid#docs
Project-URL: Say Thanks!, https://oddineers.co.uk/applications/wedroid#donate
Project-URL: Source, https://gitlab.com/oddineers-public/wedroid
Project-URL: Tracker, https://gitlab.com/oddineers-public/wedroid/-/issues
Keywords: weather development
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Classifier: License :: Other/Proprietary License
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2024.7.4
Requires-Dist: chardet>=5.2.0
Requires-Dist: charset-normalizer>=3.3.2
Requires-Dist: geojson>=2.5.0
Requires-Dist: idna>=3.8
Requires-Dist: pyowm>=3.3.0
Requires-Dist: PySocks>=1.7.1
Requires-Dist: requests>=2.32.3
Requires-Dist: setuptools>=74.0.0
Requires-Dist: urllib3>=2.2.2

# WeDroid Python 3 Package

The weather announcement assistant. We(ather)Droid; for more information please visit: [WeDroid Download](https://oddineers.co.uk/wedroid/).

## 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 distributable and/or wheel:
Build the distributable:
```commandline
python setup.py sdist 
```
Building the wheel:
```commandline
python setup.py bdist_wheel
```
Clean build directory, build the distributable and wheel:
```commandline
python setup.py clean sdist bdist_wheel
```

Cleaning build directory:
```
python setup.py clean --all
```

Example for installing the wheel:
```commandline
pip install WeDroid-1.x.x-py3-none-any
pip install <path_to_file>\wedroid\dist\WeDroid-1.x.x-py3-none-any
pip install Z:\git\python3\wedroid\dist\WeDroid-1.x.x-py3-none-any.whl
```

## 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:

```json
{
    "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
}
```

## Usage as an `package`
When initiating `WeDroid`; pass the newly created configuration file:

Example:
```python
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:
```python
# A Forecast for 4 results split by a 3h interval
message = weather.generate_forecast_announcement("3h", "4")
```

```python
# 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:
  - ```json
      "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
  - ```json
      "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`:

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

## Tasker - Android

Requirements
- 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](https://openweathermap.org/api).

Upon first run the following Tasker variables are created:

```text
%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

### Regenerating documentation
Change to docs directory
```commandline
cd docs
```
Building docs
```commandline
sphinx-apidoc -f -o source/ ../wedroid
make clean
make html
```
Linux one-liner
```commandline
sphinx-apidoc -f -o source/ ../wedroid && make clean && make html
```

Windows one-liner
```commandline
sphinx-apidoc -f -o source/ ../wedroid & make clean & make html
```
