include modified weatherapi, use forcast, use worst rain detection

2023-06-09 01:09:59 +02:00
parent 0b973f8201
commit a201193d58
20 changed files with 3175 additions and 76 deletions
--- a/client/openweathermap/README.md
+++ b/client/openweathermap/README.md
@@ -0,0 +1,141 @@
+# openweathermap [![Rust](https://github.com/fightling/openweathermap/actions/workflows/rust.yml/badge.svg)](https://github.com/fightling/openweathermap/actions/workflows/rust.yml)
+
+...is a *rust crate* which lets you easily access current weather data from [OpenWeatherMap](https://openweathermap.org/). This is an *unofficial* extension I have made to learn *rust* a little but I hope you have fun with it.
+
+## Contents
+
+<!-- MDTOC maxdepth:6 firsth1:2 numbering:0 flatten:0 bullets:1 updateOnSave:1 -->
+
+- [Contents](#contents)   
+- [How to use](#how-to-use)   
+   - [Get continuous weather updates](#get-continuous-weather-updates)   
+      - [First: Start polling](#first-start-polling)   
+      - [Then: Get weather updates](#then-get-weather-updates)   
+         - [Nothing New: `None`](#nothing-new-none)   
+         - [Weather Update: `CurrentWeather`](#weather-update-currentweather)   
+         - [Some Error: `Err`](#some-error-err)   
+   - [Get weather just once](#get-weather-just-once)   
+- [Reference Documentation](#reference-documentation)   
+- [Links](#links)   
+   - [Website](#website)   
+   - [*github* repository](#github-repository)   
+   - [on *crates.io*](#on-cratesio)   
+- [License](#license)   
+
+<!-- /MDTOC -->
+
+## How to use
+
+First add this crate to your dependencies in you `Cargo.toml` file:
+
+```toml
+[dependencies]
+openweathermap = "0.2.4"
+```
+### Get continuous weather updates
+
+Then use the crate in your rust source file by calling `openweathermap::init()` which returns a receiver object.
+You can then use this receiver object to call `openweathermap::update()` to get weather updates like in the following example:
+
+```rust
+extern crate openweathermap;
+
+use openweathermap::{init,update};
+
+fn main() {
+    // start our observatory via OWM
+    let receiver = &init("Berlin,DE", "metric", "en", "<APIKEY>", 10);
+    loop {
+        match update(receiver) {
+            Some(response) => match response {
+                Ok(current) => println!(
+                    "Today's weather in {} is {}",
+                    current.name.as_str(),
+                    current.weather[0].main.as_str()
+                ),
+                Err(e) => println!("Could not fetch weather because: {}", e),
+            },
+            None => (),
+        }
+    }
+}
+```
+
+#### First: Start polling
+
+`init()` spawns a thread which then will periodically poll *OpenWeatherMap* for the latest current weather report.
+You then can use `update()` to ask for it.
+
+#### Then: Get weather updates
+
+There are three possible kinds of result you get from `update()` which you will have to face:
+
+##### Nothing New: `None`
+
+`update()` returns `None` if there is currently no new update available.
+Which means: **You wont get any update twice!**
+In other words: `update()` is not caching the last weather update for you.
+
+##### Weather Update: `CurrentWeather`
+
+If a new update was downloaded by the polling thread `update()` returns some `CurrentWeather` object.
+`CurrentWeather` is a nested `struct` with the already parsed json properties.
+Those are well described [here](https://openweathermap.org/current#parameter).
+
+##### Some Error: `Err`
+On error `update()` returns some `String` object which includes a brief error description.
+
+Errors may occur...
+- initially while **there is no update yet** you will get an `Err` which includes exactly the String `"loading..."` (predefined in `openweathermap::LOADING`).
+- if a **server error** response was received (e.g. `401 Unauthorized` if an **invalid API key** was used).
+- on **json errors** while parsing the response from *OpenWeatherMap*.
+
+### Get weather just once
+
+If you need the weather just once you may use the method `weather()` which envelopes `init()` and `update()` into one single synchronous or asynchronous call.
+After the first successful weather update the spawned thread will stop immediately and you get the result in return.
+
+```rust
+extern crate openweathermap;
+use openweathermap::blocking::weather;
+
+fn main() {
+    // start our observatory via OWM
+    match &weather("Berlin,DE", "metric", "en", "<APIKEY>") {
+        Ok(current) => println!(
+            "Today's weather in {} is {}",
+            current.name.as_str(),
+            current.weather[0].main.as_str()
+        ),
+        Err(e) => println!("Could not fetch weather because: {}", e),
+    }
+}
+
+```
+
+There is a *blocking* and a *non-blocking* variant of `weather()`:
+
+- The above example uses the synchronous (*blocking*) variant `openweathermap::blocking::weather` which wont return until there is a new update.
+- If you like to deal with the returned *future* by yourself just use `openweathermap::weather` and asynchronously await the result until there is any.
+
+## Reference Documentation
+
+Beside this introduction there is a reference documentation which can be found [here](https://docs.rs/openweathermap).
+
+## Links
+
+### Website
+
+This README tastes better at [openweathermap.thats-software.com](https://openweathermap.thats-software.com).
+
+### *github* repository
+
+For the source code see [this repository](https://github.com/fightling/openweathermap) at *github.com*.
+
+### on *crates.io*
+
+Published at [*crates.io*](https://crates.io/crates/openweathermap).
+
+## License
+
+openweathermap is licensed under the *MIT license* (LICENSE-MIT or http://opensource.org/licenses/MIT)