loads of doc!

Author: csparpa

sphinx/v3/utilities-usage-examples.md

@@ -0,0 +1,247 @@
+# PyOWM utility functions usage example
+
+PyOWM provides a few packages that contain utility functions. 
+
+Some of them are specifically designed to be used by the core PyOWM classes but others you can use to make your life
+easier when operating PyOWM!
+
+All utility modules live inside the `pyowm.utils` package
+
+Here are most useful modules:
+
+  * `config`: handling of PyOWM configuration
+  * `formatting`: formatting of timestamp entities (Python native types, UNIX epochs and ISO-8601 strings)
+  * `geo`: handling of geographic entities such as points, polygons and their geoJSON representation
+  * `measureables`: conversions among physical units (eg. temperature, wind)
+  * `timestamps`: human friendly timestamps generation
+  
+  
+## `config` module
+```python
+from pyowm.utils.config import get_default_config, get_default_config_for_subscription_type, \ 
+    get_default_config_for_proxy, get_config_from 
+
+config_dict = get_default_config()                                       # loads the default config dict
+config_dict = get_default_config_for_subscription_type('professional')   # loads the config dict for the specified subscription type
+config_dict = get_config_from('/path/to/configfile.json')                # loads the config dict from the  specified JSON file
+config_dict = get_default_config_for_proxy('http_url', 'https_url')      # loads the config dict to be used behind a proxy whose URLs are specified
+```
+
+## `formatting` module
+```python
+from datetime import datetime as dt
+from pyowm.utils import formatting
+
+unix_value = formatting.timeformat(dt.today(), 'unix')        # from datetime to UNIX
+iso_str_value = formatting.timeformat(dt.today(), 'iso')      # from datetime to ISO-8601 string
+datetime_value = formatting.timeformat(1590100263, 'date')    # from UNIX to datetime
+iso_str_value = formatting.timeformat(1590100263, 'iso')      # from UNIX to ISO-8601 string
+datetime_value = formatting.timeformat('2020-05-21 22:31:03+00', 'date') # from ISO-8601 string to datetime
+unix_value = formatting.timeformat('2020-05-21 22:31:03+00', 'unix') # from ISO-8601 string to UNIX
+```
+
+## `geo` module
+
+The module provides classes to represent geometry features:
+  - `Point`
+  - `Multipoint` (aka point set)
+  - `Polygon`
+  - `Multipolygon` (aka polygon set)
+
+Geometry features are used eg. in OWM Alert API to provide geographical boundaries for alert setting.
+
+PyOWM uses standard geometry types defined by the [GeoJSON Format Specification - RFC 7946](https://tools.ietf.org/html/rfc7946) data interchange format.  
+
+### Common geometry methods
+
+All geometry types can be dumped to a GeoJSON string and to a Python `dict`
+
+```python
+from pyowm.utils import geo
+point = geo.Point(20.8, 30.9)
+point.geojson()  # '{"type": "Point", "coordinates": [20.8, 30.9]}'
+point.to_dict()  #  {'type': 'Point', 'coordinates': [20.8, 30.9]}
+```
+
+All geometry types also feature a static factory method: you provide the dictionary and the factory returns the object
+instance
+
+```python
+from pyowm.utils.geo import Point
+point_dict = {'type': 'Point', 'coordinates': [20.8, 30.9]}
+point = Point.from_dict(point_dict)
+```
+
+Please refer to the GeoJSON specification about how to properly format the dictionaries to be given the factory methods 
+
+
+### `Point` class
+
+A point is a couple of geographic coordinates: longitude and latitude
+
+```python
+from pyowm.utils import geo
+lon = 20.8
+lat = 30.9
+point = geo.Point(lon, lat)
+coords = point.lon, point.lat  # 20.8, 30.9 
+```
+
+As circle shapes are not part of the GeoJSON specification, you can approximate the circle having a specific `Point` instance
+at its center with a square polygon: we call it bounding square polygon. You just need to provide the radius of the
+circle you want to approximate (in kms):
+
+```python
+from pyowm.utils import geo
+point = geo.Point(20.8, 30.9)
+polygon = point.bounding_square_polygon(inscribed_circle_radius_km=2.0)   # default radius: 10 km
+```
+
+Please, notice that if you specify big values for the radius you need to take care about the projection of geographic
+coordinates on a proper geoid: this means that if you don't, the polygon will only _approximate_ a square.
+
+
+### From City IDs to `Point` objects
+
+The City ID Registry class can return the geopoints that correspond to one or more named cities:
+
+```python
+import pyowm
+owm = pyowm.OWM('your-API-key')
+reg = owm.city_id_registry()
+list_of_geopoints = reg.geopoints_for('London', country='GB')
+```
+
+This, in combination with the `bounding_square_polygon` method, makes it possible to easily get polygons to cover large 
+squared areas centered on largely spread city areas - such as London,GB itself: 
+
+```python
+london_city_centre = geopoints[0]
+london_city_bounding_polygon = london_city_centre.bounding_square_polygon(inscribed_circle_radius_km=12)
+```
+
+### `MultiPoint` class
+
+A `MultiPoint` object represent a set of `Point` objects
+
+```python
+from pyowm.utils.geo import Point, MultiPoint
+point_1 = Point(20.8, 30.9)
+point_2 = Point(1.2, 0.4)
+
+# many ways to instantiate
+multipoint = MultiPoint.from_points([point_1, point_2])
+multipoint = MultiPoint([20.8, 30.9], [1.2, 0.4])
+
+multipoint.longitudes  # [20.8, 1.2]
+multipoint.latitudes   # [30.9, 0.4]
+```
+
+
+### `Polygon` class
+
+A `Polygon` object represents a shape made by a set of geopoints, connected by lines. Polygons are allowed to have "holes".
+Each line of a polygon must be closed upon itself: this means that the last geopoint defined for the line _must_ coincide 
+with its first one.
+
+```python
+from pyowm.utils.geo import Polygon, Point
+point_1_coords = [2.3, 57.32]
+point_2_coords = [23.19, -20.2]
+point_3_coords = [-120.4, 19.15]
+point_1 = Point(point_1_coords)
+point_2 = Point(point_2_coords)
+point_3 = Point(point_3_coords)
+
+
+# many ways to instantiate
+line = [point_1_coords, point_2_coords, point_3_coords , point_1_coords]  # last point equals the first point
+polygon = Polygon([line])
+line = [point_1, point_2, point_3, point_1]  # last point equals the first point
+polygon = Polygon.from_points([line])
+```
+
+# `MultiPolygon` class
+
+A `MultiPolygon` object represent a set of `Polygon` objects
+Same philosophy here as for `MultiPoint` class, polygons can cross:
+
+```python
+from pyowm.utils.geo import Point, Polygon, MultiPolygon
+point_1 = Point(20.8, 30.9)
+point_2 = Point(1.2, 0.4)
+point_3 = Point(49.9, 17.4)
+point_4 = Point(178.4, 78.3)
+polygon_1 = Polygon.from_points([point_1, point_2, point_3, point_1])
+polygon_2 = Polygon.from_points([point_3, point_4, point_2, point_3])
+
+multipoint = MultiPolygon.from_polygons([polygon_1, polygon_2])
+```
+
+### Building geometries
+
+There is a useful factory method for geometry types, which you can use to turn a geoJSON-formatted dictionary into the
+corresponding topology type:
+
+```python
+from pyowm.utils.geo import GeometryBuilder
+point_dict = {
+    "type": "Point",
+    "coordinates": [53, 37]
+}
+point = GeometryBuilder.build(point_dict)      # this is a `Point` instance
+
+wrongly_formatted_dict = {"a": 1, "b": 99}
+GeometryBuilder.build(wrongly_formatted_dict)  # you get an exception
+```
+
+
+## `measurables` module
+This module provides utilities numeric conversions
+
+### Temperature
+You have a `dict` whose values represent temperature units in Kelvin: you can convert them to Fahrenheit and Celsius.
+
+```python
+from pyowm.utils import measurables
+
+fahrenheit_temperature_dict = measurables.kelvin_dict_to(kelvin_temperature_dict, 'fahrenheit')
+celsius_temperature_dict = measurables.kelvin_dict_to(kelvin_temperature_dict, 'celsius')
+```
+
+### Wind
+On the same line as temperatures, you can convert wind values among meters/sec, kilometers/hour, miles/hour, knots and
+the Beaufort scale. The pivot unit of measure for wind is meters/sec
+
+
+```python
+from pyowm.utils import measurables
+
+kmhour_wind_dict = measurables.metric_wind_dict_to_km_h(msec_wind_dict)
+mileshour_wind_dict = measurables.metric_wind_dict_to_imperial(msec_wind_dict)
+knots_wind_dict = measurables.metric_wind_dict_to_knots(msec_wind_dict)
+beaufort_wind_dict = measurables.metric_wind_dict_to_beaufort(msec_wind_dict)
+```
+
+
+## `timestamps` module
+```python
+from pyowm.utils import timestamps
+
+timestamps.now()                                         # Current time in `datetime.datetime` object (default)
+timestamps.now('unix')                                   # epoch
+timestamps.now('iso')                                    # ISO8601-formatted str (YYYY-MM-DD HH:MM:SS+00)
+
+timestamps.tomorrow()                                    # Tomorrow at this time
+timestamps.tomorrow(18, 7)                               # Tomorrow at 6:07 PM
+timestamps.yesterday(11, 27)                             # Yesterday at 11:27 AM
+
+timestamps.next_three_hours()                            # 3 hours from now
+timestamps.last_three_hours(date=timestamps.tomorrow())  # tomorrow but 3 hours before this time
+
+timestamps.next_hour()
+timestamps.last_hour(date=timestamps.yesterday())        # yesterday but 1 hour before this time
+
+
+# And so on with: next_week/last_week/next_month/last_month/next_year/last_year
+```