Version 3.1 (#342)

* backport from master branch

* typo

* Add disclaimer about newer API keys getting Authorization errors back when calling OWM legacy endpoints

* Add timezone to all datetime objects and fix ISO format of time zone offset.

* switched place

* minor fixes

* more tests for timestamps offset awareness. update docs

* unused import

* Documentation fixes (#323)

* Fix documentation for accepted values for Weather.wind unit parameter

* Add missing single quotation marks in documentation for Weather methods

* Update reference link for OWM weather codes and icons

* Add One Call functionaly: (1) exclude parts and (2) set desired units

* Adding contributors from latest PRs

* fixes #324

* Add an FAQ documentation section to help people fixing common issues on PyOWM (which recently occur as repeated GitHub issues)

* added documentation to the code recipies; included unit test result

* adding results of tox unit tests and integration tests

* Update tox_integration_20200807.txt

* Update and fix errors

* Adding Ankur to contributors

* Delete tox_20200807.txt

* Delete tox_integration_20200807.txt

* more FAQs

* Added size argument  weatherapi25.weather.weather_icon_url (#337)

* Added size argument to weatherapi25.weather.weather_icon_url()

* Fixed unit tests for new OWM icons

* Fixed previous pushed unit test

* Add Wesley-Vos

* Exposed list of OWM supported languages

* Removed dependency version pinning, this should fix #334

* forgot

* This should address #332

* Documented workaround to install from the development branch, as stated in #341 (comment) and #318

* update docs (fixed typos)

* documentation improvements

* version dump

* fixed test

Co-authored-by: Miroslav Šedivý <6774676+eumiro@users.noreply.github.com>
Co-authored-by: Harmon <Harmon758@gmail.com>
Co-authored-by: jwmelvin <jwmelvin@gmail.com>
Co-authored-by: Wesley Vos <17592840+Wesley-Vos@users.noreply.github.com>

CONTRIBUTORS.md

@@ -6,25 +6,32 @@ Contributors will be shown in alphabetical order
 Code
 ----
   * [alechewitt](https://github.com/alechewitt)
+  * [camponez](https://github.com/camponez)
+  * [dev-iks](https://github.com/dev-iks)
   * [dphildebrandt](https://github.com/dphildebrandt)
   * [dstmar](https://github.com/dstmar)
   * [edenhaus](https://github.com/edenhaus)
+  * [eumiro](https://github.com/eumiro)
   * [ggstuart](https://github.com/ggstuart)
+  * [jwmelvin](https://github.com/jwmelvin)
   * [lardconcepts](https://github.com/lardconcepts)
   * [liato](https://github.com/liato)
   * [LukasBoersma](https://github.com/LukasBoersma)
+  * [Misiu](https://github.com/Misiu)
   * [Noid](https://github.com/n0id)
   * [titilambert](https://github.com/titilambert)
   * [txemi](https://github.com/txemi)
-  * [camponez](https://github.com/camponez)
-  * [dev-iks](https://github.com/dev-iks)
+
+  * [Wesley-Vos](https://github.com/Wesley-Vos)
 
 Docs
 ----
   * [EJEP](https://github.com/EJEP)
+  * [Harmon758](https://github.com/Harmon758)
 
 Testing
 -------
+  * [Ankur](https://github.com/Ankuraxz)
   * [Samuel Yap](https://github.com/samuelyap)
   * [Patrick Casbon](https://github.com/patcas)
   * [Tamas Magyar](https://github.com/tamasmagyar)
@@ -42,4 +49,4 @@ Wiki
 
 Logo
 ----
-  * [marlinmm](https://github.com/marlinmm)
+  * [marlinmm](https://github.com/marlinmm)

Pipfile

@@ -8,19 +8,19 @@ coverage = "*"
 coveralls = "*"
 Jinja2 = "*"
 pip = ">=18.0"
-pproxy = "==2.2.0"
+pproxy = ">=2.2.0,<3"
 pytest = "*"
 recommonmark = "*"
 Sphinx = "*"
-sphinx-readable-theme = ""==1.3.0"
+sphinx-readable-theme = "*"
 tox = "*"
 tox-travis = "*"
 virtualenv = "*"
 twine = "*"
 
 
 [packages]
-requests = "<3,==2.20.0"
-geojson = "<3,==2.3.0"
-PySocks = "<2,==1.7.1"
-requests[socks] = "*"
+requests = "<3,>=2.20.0"
+geojson = "<3,>=2.3.0"
+PySocks = "<2,>=1.7.1"
+"requests[socks]" = "*"

README.md

@@ -22,7 +22,7 @@ PyOWM runs on Python 3.7+
 
 **Former Dark Sky API users**: you can can use PyOWM to get [OpenWeatherMap's OneCall API](https://openweathermap.org/api/one-call-api) data as an easy replacement to Dark Sky
 
-### What kind of data do I get with PyOWM ?
+### What kind of data can I get with PyOWM ?
 With PyOWM you can integrate into your code any of the following OpenWeatherMap web APIs:
 
  - **Weather API v2.5** + **OneCall API**, providing current weather data, weather forecasts, weather history
@@ -47,38 +47,39 @@ With a free OWM API Key:
 
 ```python
 from pyowm import OWM
+from pyowm.utils import config
+from pyowm.utils import timestamps
 
-owm = OWM('your-API-key')  # You MUST provide a valid API key
+# ---------- FREE API KEY examples ---------------------
 
-# Search for current weather in London (Great Britain)
+owm = OWM('your free OWM API key')
 mgr = owm.weather_manager()
+
+
+# Search for current weather in London (Great Britain) and get details
 observation = mgr.weather_at_place('London,GB')
 w = observation.weather
-print(w)                  # <Weather - reference time=2013-12-18 09:20, status=Clouds>
 
-# Weather details
+w.detailed_status         # 'clouds'
 w.wind()                  # {'speed': 4.6, 'deg': 330}
 w.humidity                # 87
 w.temperature('celsius')  # {'temp_max': 10.5, 'temp': 9.7, 'temp_min': 9.0}
+w.rain                    # {}
+w.heat_index              # None
+w.clouds                  # 75
 
-# Search current weather observations in the surroundings of
-# lat=22.57W, lon=43.12S (Rio de Janeiro, BR)
-observation_list = mgr.weather_around_coords(-22.57, -43.12)
-```
+# Will it be clear tomorrow at this time in Milan (Italy) ?
+forecast = mgr.forecast_at_place('Milan,IT', 'daily')
+answer = forecast.will_be_clear_at(timestamps.tomorrow())
 
-With a paid OWM API key:
+# ---------- PAID API KEY example ---------------------
 
-```python
-from pyowm.owm import OWM
-from pyowm.utils import config
-from pyowm.utils import timestamps
 config_dict = config.get_default_config_for_subscription_type('professional')
-owm = OWM('your-paid-api-key', config_dict)
+owm = OWM('your paid OWM API key', config_dict)
 
-# Will it be clear tomorrow at this time in Milan (Italy) ?
-mgr = owm.weather_manager()
-forecast = mgr.forecast_at_place('Milan,IT', 'daily')
-forecast.will_be_clear_at(timestamps.tomorrow())  # The sun always shines on Italy, right? ;)
+# What's the current humidity in Berlin (Germany) ?
+one_call_object = mgr.one_call(lat=52.5244, lon=13.4105)
+one_call_object.current.humidity
 ```
 
 
@@ -92,18 +93,24 @@ $ pip install pyowm
 There are alternatives: _setuptools_, _Windows installers_ and common Linux package managers such as _Yaourt (Arch Linux)_
 _YaST/Zypper (OpenSuse)_ (please refer to the documentation for more detail)
 
-Eager to fetch the very latest updates to PyOWM? Install the development trunk (which might be unstable):
+Eager to fetch the very latest updates to PyOWM? Install the development trunk (which might be unstable). Eg on Linux:
 
 ```shell
-$ pip install git+https://github.com/csparpa/pyowm.git@develop
+$ git clone https://github.com/csparpa/pyowm.git
+$ cd pyowm && git checkout develop
+$ pip install -r requirements.txt && python setup.py install
 ```
 
 ## Documentation
 The library software API documentation is available on [Read the Docs](https://pyowm.readthedocs.io/en/latest/).
 
-Each release has its own [changelog](https://github.com/csparpa/pyowm/wiki/Changelog).
+The [Code recipes](https://pyowm.readthedocs.io/en/latest/v3/code-recipes.html) section comes in handy!
+
 
+## Help - PyOWM is giving me errors!
+Please read the [FAQ](https://pyowm.readthedocs.io/en/latest/v3/faq.html) section of the documentation before filing a new issue on GitHub!
 
+There are many common issues, therefore a fix for your issue might come easier than you think
 
 ## Community & Contributing
 

dev-requirements.txt

@@ -2,7 +2,7 @@ coverage
 coveralls
 Jinja2
 pip>=18.0
-pproxy<3
+pproxy>=2.2.0,<3
 pytest
 recommonmark
 Sphinx

pyowm/airpollutionapi30/coindex.py

@@ -50,7 +50,7 @@ def reference_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -66,7 +66,7 @@ def reception_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -114,7 +114,7 @@ def from_dict(cls, the_dict):
             raise exceptions.ParseAPIResponseError('Data is None')
         try:
             # -- reference time (strip away Z and T on ISO8601 format)
-            t = the_dict['time'].replace('Z', '+00').replace('T', ' ')
+            t = the_dict['time'].replace('Z', '+00:00').replace('T', ' ')
             reference_time = formatting.ISO8601_to_UNIXtime(t)
 
             # -- reception time (now)

pyowm/airpollutionapi30/no2index.py

@@ -50,7 +50,7 @@ def reference_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -66,7 +66,7 @@ def reception_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -114,7 +114,7 @@ def from_dict(cls, the_dict):
             raise exceptions.ParseAPIResponseError('Data is None')
         try:
             # -- reference time (strip away Z and T on ISO8601 format)
-            t = the_dict['time'].replace('Z', '+00').replace('T', ' ')
+            t = the_dict['time'].replace('Z', '+00:00').replace('T', ' ')
             reference_time = formatting.ISO8601_to_UNIXtime(t)
 
             # -- reception time (now)

pyowm/airpollutionapi30/ozone.py

@@ -48,7 +48,7 @@ def reference_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -64,7 +64,7 @@ def reception_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -98,7 +98,7 @@ def from_dict(cls, the_dict):
             raise exceptions.ParseAPIResponseError('Data is None')
         try:
             # -- reference time (strip away Z and T on ISO8601 format)
-            ref_t = the_dict['time'].replace('Z', '+00').replace('T', ' ')
+            ref_t = the_dict['time'].replace('Z', '+00:00').replace('T', ' ')
             reference_time = formatting.ISO8601_to_UNIXtime(ref_t)
 
             # -- reception time (now)

pyowm/airpollutionapi30/so2index.py

@@ -49,7 +49,7 @@ def reference_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -65,7 +65,7 @@ def reception_time(self, timeformat='unix'):
 
         :param timeformat: the format for the time value. May be:
             '*unix*' (default) for UNIX time
-            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00``
+            '*iso*' for ISO8601-formatted string in the format ``YYYY-MM-DD HH:MM:SS+00:00``
             '*date* for ``datetime.datetime`` object instance
         :type timeformat: str
         :returns: an int or a str
@@ -99,7 +99,7 @@ def from_dict(cls, the_dict):
             raise exceptions.ParseAPIResponseError('Data is None')
         try:
             # -- reference time (strip away Z and T on ISO8601 format)
-            t = the_dict['time'].replace('Z', '+00').replace('T', ' ')
+            t = the_dict['time'].replace('Z', '+00:00').replace('T', ' ')
             reference_time = formatting.ISO8601_to_UNIXtime(t)
 
             # -- reception time (now)

pyowm/alertapi30/alert.py

@@ -81,7 +81,7 @@ def from_dict(cls, the_dict):
             raise exceptions.ParseAPIResponseError('Data is None')
         try:
             alert_id = the_dict['_id']
-            t = the_dict['last_update'].split('.')[0].replace('T', ' ') + '+00'
+            t = the_dict['last_update'].split('.')[0].replace('T', ' ') + '+00:00'
             alert_last_update = formatting.ISO8601_to_UNIXtime(t)
             alert_trigger_id = the_dict['triggerId']
             alert_met_conds = [

pyowm/commons/enums.py

@@ -10,10 +10,10 @@ class SubscriptionTypeEnum:
 
     """
     FREE = SubscriptionType('free', 'api', False)
-    STARTUP = SubscriptionType('startup', 'pro', True)
-    DEVELOPER = SubscriptionType('developer', 'pro', True)
-    PROFESSIONAL = SubscriptionType('professional', 'pro', True)
-    ENTERPRISE = SubscriptionType('enterprise', 'pro', True)
+    STARTUP = SubscriptionType('startup', 'api', True)
+    DEVELOPER = SubscriptionType('developer', 'api', True)
+    PROFESSIONAL = SubscriptionType('professional', 'api', True)
+    ENTERPRISE = SubscriptionType('enterprise', 'api', True)
 
     @classmethod
     def lookup_by_name(cls, name):

pyowm/constants.py

@@ -1,10 +1,61 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-PYOWM_VERSION = (3, 0, 0)
+PYOWM_VERSION = (3, 1, 0)
 AGRO_API_VERSION = (1, 0, 0)
 AIRPOLLUTION_API_VERSION = (3, 0, 0)
 ALERT_API_VERSION = (3, 0, 0)
 STATIONS_API_VERSION = (3, 0, 0)
 UVINDEX_API_VERSION = (3, 0, 0)
 WEATHER_API_VERSION = (2, 5, 0)
+LANGUAGES = [
+    "af",
+    "al",
+    "ar",
+    "az",
+    "bg",
+    "ca",
+    "cz",
+    "da",
+    "de",
+    "el",
+    "en",
+    "es",
+    "eu",
+    "fa",
+    "fi",
+    "fr",
+    "gl",
+    "he",
+    "hi",
+    "hr",
+    "hu",
+    "id",
+    "it",
+    "ja",
+    "kr",
+    "la",
+    "lt",
+    "mk",
+    "nl",
+    "no",
+    "pl",
+    "pt",
+    "pt_br",
+    "ro",
+    "ru",
+    "se",
+    "sk",
+    "sl",
+    "sp",
+    "sr",
+    "sv",
+    "th",
+    "tr",
+    "ua",
+    "uk",
+    "vi",
+    "zh_cn",
+    "zh_tw",
+    "zu",
+]

pyowm/owm.py

@@ -53,6 +53,16 @@ def version(self):
         """
         return constants.PYOWM_VERSION
 
+    @property
+    def supported_languages(self):
+        """
+        Returns the languages that the OWM API supports
+
+        :return: `list` of `str`
+
+        """
+        return constants.LANGUAGES
+
     def agro_manager(self):
         """
         Gives a `pyowm.agro10.agro_manager.AgroManager` instance that can be used to read/write data from the