| Name | WeDroid JSON |
| Version |
1.4.1
JSON |
| download |
| home_page | https://oddineers.co.uk/applications/wedroid |
| Summary | A weather announcement agent that summarises weather in realtime using OpenWeatherMaps; Features additional support for Android devices using Termux & Tasker. |
| upload_time | 2024-09-09 22:10:21 |
| maintainer | None |
| docs_url | None |
| author | Steven |
| requires_python | None |
| license | None |
| keywords |
weather development
owm
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# WeDroid Python 3 Package
The weather announcement assistant. We(ather)Droid; for more information please visit: [WeDroid Download](https://oddineers.co.uk/wedroid/).
Sphinx autogenerated source documentation available at: [oddineers-public.gitlab.io/wedroid](https://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:
1. First the current running directory is checked.
2. 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](https://openweathermap.org/api).
```json
{
"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:
```python
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:
```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")
```
## Working with the WeDroid source code
```
cd ~/Downloads
git clone git@gitlab.com: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](https://build.pypa.io/en/stable/) by build.pypa.io.
```
pip install build
```
Then build the distributable:
```commandline
python -m build -n
```
Example for installing the wheel:
```commandline
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](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
### 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
```
Raw data
{
"_id": null,
"home_page": "https://oddineers.co.uk/applications/wedroid",
"name": "WeDroid",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "weather development, owm",
"author": "Steven",
"author_email": "steven@oddineers.co.uk",
"download_url": "https://files.pythonhosted.org/packages/16/db/009abc74ec897e4a5077dddc16be335d180f0b5bd2974883edaa48f1a646/wedroid-1.4.1.tar.gz",
"platform": null,
"description": "# WeDroid Python 3 Package\n\nThe weather announcement assistant. We(ather)Droid; for more information please visit: [WeDroid Download](https://oddineers.co.uk/wedroid/).\n\nSphinx autogenerated source documentation available at: [oddineers-public.gitlab.io/wedroid](https://oddineers-public.gitlab.io/wedroid/)\n\n## Weather reports\nWeDroid can run either observation or forecasts styled reports.\n- Observations include a summary of the weather, temperature, time.\n- Forecasts return the weather status for a given interval + limit; for example 3h as the interval and 4 as the limit.\nWould produce a report with 4 observations with 3 hours intervals. \n\n## Configuration\nWeDroid will try to load its configuration from `wedroid_settings.json` using the following logic:\n1. First the current running directory is checked.\n2. If no configuration in current directory it checks the users home directory (_cross-platform is supported_).\n\nThis behaviour can be overridden by passing in the path to a configuration: `-c \"/path/to/some/where/wedroid_settings.json\"`\n\nAn example for storing the settings in an optional file; create a new file for example: `wedroid_settings.json` and insert the following:\n\n> **Note**: You will need an Open Weather Map API key to use this script; [register at openweathermap.org](https://openweathermap.org/api).\n\n```json\n{\n \"run_type\": \"tasker\",\n \"intercept_task_name\": \"WeDroid Received\", // Tasker Task name that will process the data passed to it\n \"owm_api_key\": \"<own-api-key>\",\n \"announce_temp\": true,\n \"announce_time\": true,\n \"announce_humidity\": false,\n \"announce_wind\": false,\n \"announce_sun\": true,\n \"sl4a_gtts\": false,\n \"bot_name\": \"WeDroid\",\n \"mattermost_url\": \"<web-hook-url>\",\n \"device_location\": true,\n \"longitude\": -3.0,\n \"latitude\": 53.0,\n \"log_level\": \"DEBUG\", // OPTIONAL: Value can be: INFO, DEBUG, ERROR\n \"log_gps_coords\": true, // OPTIONAL: true or false, enables or disables GPS co-ordinate inclusion in log files.\n \"location_provider\": \"gps\", // Value can be: gps, network, passive\n \"location_request\": \"once\" // Value can be: once, last, updates\n}\n```\n\n## Working with WeDroid as a `package`\nInstallation:\n```\npip install wedroid\n```\n\nDouble check your configuration; the file should be named: `wedroid_settings.json`.\n\n### Running from the CLI\nThis assumes that you have Python 3 (_minimum 3.9_) installed.\n\n#### Optional - Generate a template `wedroid_settings.json` file\n\n```\nwedroid -d\n```\n\n#### Forecast styled report\n```\nwedroid -t \"forecast\" -i \"3h\" -l 12 \n```\n\n#### Observation styled report\n```\nwedroid -t \"observation\" -lt \"14.0\" -lc 812\n```\n\n#### Observation styled report with custom configuration\n```\nwedroid -t \"observation\" -lt \"14.0\" -lc 812 -c \"/path/to/some/where/wedroid_settings.json\"\n```\n\n### Integrating with your own custom projects\nWeDroid can be utilised in your own projects, example:\n\n```python\nimport os\nfrom wedroid.core import WeDroid\n\ncustom_config = \"./wedroid_settings.json\"\nif os.path.isfile(custom_config):\n # Pass in to WeDroid\n weather = WeDroid(custom_config)\n```\n\nFrom here you can access functions:\n```python\n# A Forecast for 4 results split by a 3h interval\nmessage = weather.generate_forecast_announcement(\"3h\", \"4\")\n```\n\n```python\n# A weather observation now (compares previously values)\nmessage = weather.generate_weather_announcement()\n```\n\n### Customising messages and weather statuses\n\nThe messages and weather responses can be customised under `./wedroid/translations/*` if working with the source directly:\n- `annoucements.json` contains various message part that make-up a report, example:\n - ```json\n \"sunrise-future\": \"The Sun will rise in {}.\",\n \"sunset-past\": \"The Sun set {} ago.\",\n \"sunset-future\": \"The Sun will set in {}.\",\n ```\n- `weather.json` contains a dict where the weather status codes map to a: `title, icon, description`, example\n - ```json\n \"781\": {\n \"title\": \"Tornado\",\n \"icon\": \"50d\",\n \"description\": \"tornado\"\n }\n ```\n\nAs a package you can pass the path the translations directory as follows, ensure that it contains `announcements.json` & `weather.json`:\n\n```python\nwedroid = WeDroid(translation_path=\"./some/where/translations\")\n```\n\n## Working with the WeDroid source code\n\n```\ncd ~/Downloads\ngit clone git@gitlab.com:oddineers-public/wedroid.git\n```\n\n### Using launcher.py to get started\nForecast styled report\n```\npython3 launcher.py -t \"forecast\" -i \"3h\" -l 12 \n```\n\nObservation styled report\n```\npython3 launcher.py -t \"observation\" -lt \"14.0\" -lc 812\n```\n\nObservation styled report with custom configuration\n```\npython3 launcher.py -t \"observation\" -lt \"14.0\" -lc 812 -c \"/path/to/some/where/wedroid_settings.json\"\n```\n\n#### Building the module:\n\nInstall [build](https://build.pypa.io/en/stable/) by build.pypa.io.\n```\npip install build\n```\n\nThen build the distributable:\n```commandline\npython -m build -n\n```\n\nExample for installing the wheel:\n```commandline\npip install WeDroid-1.x.x-py3-none-any.whl\npip install <path_to_file>/wedroid/dist/WeDroid-1.x.x-py3-none-any.whl\n```\n\n## Tasker - Android\n**NOTE: This section will make more sense once the examples are ready and Tasker Profiles + Tasks made available.**\n\nRequirements (_Android_):\n- Tasker\n- Termux (_other shells are likely supported where you can install Python 3_)\n- Termux:API\n- Termux Tasker plugin\n- Termux requirements:\n - Termux configured to access local storage\n - Termux:API configured to allow GPS access (_if you intend to let WeDroid access the devices location_)\n\nThese instructions are somewhat vague at the moment and will be expanded soon in greater details in ReadTheDocs.\n\nWhen used with Tasker on Android you can define a task and/or profile which can run the WeDroid announcement service.\n \nTo run the script ensure the following:\n- Python 3 via the Termux.\n - Termux is installed.\n - Python 3 package is installed.\n - 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`.\n- In Tasker assign the value 0 to`%WD_LAST_TEMP, %WD_LAST_CODE`.\n- Run script to finish configuration and create default configuration.\n- Open `wedroid_settings.json` and add your OWM API key, [create one here](https://openweathermap.org/api).\n\nUpon first run the following Tasker variables are created:\n\n```text\n%WD_LAST_CODE\n%WD_SUNRISE\n%WD_SUNSET\n%WD_LAST_TEMP\n%WD_LAST_TIME\n%WD_LAST_WIND_SPEED\n%WD_LAST_WIND_DIRECTION\n%WD_LAST_HUMIDITY\n%WD_DAY_STATE\n# The main announcement\n%WD_ANNOUNCEMENT\n# Announcement parts separated\n%WD_TIME_MSG\n%WD_WEATHER_MSG\n%WD_TEMP_MSG\n%WD_WIND_MSG\n%WD_SUN_MSG\n%WD_HUMIDITY_MSG\n```\n\nAt this point the configuration aspect is complete, but we need to configure a run schedule within Tasker. \n\n### Tasker Profile Creation\nThe simplest method is to create a Tasker Profile using the Time profile.\n\n1. Create new profile > Time > Define range and re-occurrence.\n2. Next link the profile to a new task \"Run Termux Script\" as defined earlier.\n\n## Documentation from source\n\n### Generating documentation\n\nEnsure `sphinx` is install with:\n```\npip install sphinx\n```\nChange to docs directory\n```\ncd docs\n```\nBuilding docs\n```\nsphinx-apidoc -f -o source/ ../wedroid\nmake clean\nmake html\n```\nRegenerate the Sphinx readme.rst from the project README.md (_requires pandoc_):\n```\npandoc --from=markdown --to=rst --output=source/readme.rst ../README.md\n```\n\nLinux one-liner\n```\nsphinx-apidoc -f -o source/ ../wedroid && make clean && make html\n```\n\nWindows one-liner\n```\nsphinx-apidoc -f -o source/ ../wedroid & make clean & make html\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A weather announcement agent that summarises weather in realtime using OpenWeatherMaps; Features additional support for Android devices using Termux & Tasker.",
"version": "1.4.1",
"project_urls": {
"Documentation": "https://oddineers.co.uk/applications/wedroid#docs",
"Homepage": "https://oddineers.co.uk/applications/wedroid",
"Say Thanks!": "https://oddineers.co.uk/applications/wedroid#donate",
"Source": "https://gitlab.com/oddineers-public/wedroid",
"Tracker": "https://gitlab.com/oddineers-public/wedroid/-/issues"
},
"split_keywords": [
"weather development",
" owm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1d6b83bf17688835e4aca07593bf922e157a004f665260c604a5de04f7e8c14",
"md5": "0bf4993df69a8635dc867b8c9e5fd793",
"sha256": "db757d8a91b6877f4c43fd06c0251d89212762cc9efe2456a5730b9250708de3"
},
"downloads": -1,
"filename": "WeDroid-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0bf4993df69a8635dc867b8c9e5fd793",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 31120,
"upload_time": "2024-09-09T22:10:19",
"upload_time_iso_8601": "2024-09-09T22:10:19.721972Z",
"url": "https://files.pythonhosted.org/packages/f1/d6/b83bf17688835e4aca07593bf922e157a004f665260c604a5de04f7e8c14/WeDroid-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16db009abc74ec897e4a5077dddc16be335d180f0b5bd2974883edaa48f1a646",
"md5": "1586e6b7205358e846d659c894ee6fd2",
"sha256": "c12cc5f50b0dbaea6737b2ad29c8724f4be9de820f152639c426a2f2226e91a8"
},
"downloads": -1,
"filename": "wedroid-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "1586e6b7205358e846d659c894ee6fd2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28454,
"upload_time": "2024-09-09T22:10:21",
"upload_time_iso_8601": "2024-09-09T22:10:21.571869Z",
"url": "https://files.pythonhosted.org/packages/16/db/009abc74ec897e4a5077dddc16be335d180f0b5bd2974883edaa48f1a646/wedroid-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-09 22:10:21",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "oddineers-public",
"gitlab_project": "wedroid",
"lcname": "wedroid"
}
