python-weather 1.1.1__tar.gz → 2.0.0__tar.gz

{python-weather-1.1.1 → python-weather-2.0.0}/MANIFEST.in

@@ -1,6 +1,9 @@
 prune .github
+prune docs
 exclude .gitattributes
-exclude .style.yapf
 exclude .gitignore
+exclude .readthedocs.yml
+exclude .style.yapf
 exclude LICENSE
+exclude changelog.yml
 exclude test.py

{python-weather-1.1.1/python_weather.egg-info → python-weather-2.0.0}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.1
 Name: python-weather
-Version: 1.1.1
+Version: 2.0.0
 Summary: A free and asynchronous weather API wrapper made in Python, for Python.
 Author: null8626
 License: MIT
-Project-URL: repository, https://github.com/null8626/python-weather
-Project-URL: download_url, https://github.com/null8626/python-weather/archive/1.1.1.tar.gz
+Project-URL: Changelog, https://python-weather.readthedocs.io/en/latest/changelog.html
+Project-URL: Homepage, https://python-weather.readthedocs.io/en/latest/
+Project-URL: Documentation, https://python-weather.readthedocs.io/en/latest/
+Project-URL: Repository, https://github.com/null8626/python-weather
 Keywords: weather,forecast,weather-api,weather-forecast
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Framework :: aiohttp
@@ -23,7 +25,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.7
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -34,17 +35,11 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp==3.9.3
 
-# [python-weather][pypi-url] [![pypi][pypi-image]][pypi-url] [![downloads][downloads-image]][pypi-url] [![Build Status][ci-image]][ci-url] [![license][github-license-image]][github-license-url] [![BLAZINGLY FAST!!!][blazingly-fast-image]][blazingly-fast-url]
+# [python-weather][pypi-url] [![pypi][pypi-image]][pypi-url] [![downloads][downloads-image]][pypi-url]
 
 [pypi-image]: https://img.shields.io/pypi/v/python-weather.svg?style=flat-square
 [pypi-url]: https://pypi.org/project/python-weather/
 [downloads-image]: https://img.shields.io/pypi/dm/python-weather?style=flat-square
-[ci-image]: https://github.com/null8626/python-weather/workflows/CI/badge.svg
-[ci-url]: https://github.com/null8626/python-weather/actions/workflows/CI.yml
-[github-license-image]: https://img.shields.io/github/license/null8626/python-weather?style=flat-square
-[github-license-url]: https://github.com/null8626/python-weather/blob/main/LICENSE
-[blazingly-fast-image]: https://img.shields.io/badge/speed-BLAZINGLY%20FAST!!!%20%F0%9F%94%A5%F0%9F%9A%80%F0%9F%92%AA%F0%9F%98%8E-brightgreen.svg?style=flat-square
-[blazingly-fast-url]: https://twitter.com/acdlite/status/974390255393505280
 
 A free and asynchronous weather Python API wrapper made in Python, for Python.
 
@@ -56,6 +51,8 @@ $ pip install python-weather
 
 ## Example
 
+For more information, please read the [documentation](https://python-weather.readthedocs.io/en/latest/).
+
 ```py
 # import the module
 import python_weather
@@ -70,14 +67,14 @@ async def getweather():
     weather = await client.get('New York')
     
     # returns the current day's forecast temperature (int)
-    print(weather.current.temperature)
+    print(weather.temperature)
     
     # get the weather forecast for a few days
-    for forecast in weather.forecasts:
-      print(forecast)
+    for daily in weather.daily_forecasts:
+      print(daily)
       
       # hourly forecasts
-      for hourly in forecast.hourly:
+      for hourly in daily.hourly_forecasts:
         print(f' --> {hourly!r}')
 
 if __name__ == '__main__':

{python-weather-1.1.1 → python-weather-2.0.0}/README.md

@@ -1,14 +1,8 @@
-# [python-weather][pypi-url] [![pypi][pypi-image]][pypi-url] [![downloads][downloads-image]][pypi-url] [![Build Status][ci-image]][ci-url] [![license][github-license-image]][github-license-url] [![BLAZINGLY FAST!!!][blazingly-fast-image]][blazingly-fast-url]
+# [python-weather][pypi-url] [![pypi][pypi-image]][pypi-url] [![downloads][downloads-image]][pypi-url]
 
 [pypi-image]: https://img.shields.io/pypi/v/python-weather.svg?style=flat-square
 [pypi-url]: https://pypi.org/project/python-weather/
 [downloads-image]: https://img.shields.io/pypi/dm/python-weather?style=flat-square
-[ci-image]: https://github.com/null8626/python-weather/workflows/CI/badge.svg
-[ci-url]: https://github.com/null8626/python-weather/actions/workflows/CI.yml
-[github-license-image]: https://img.shields.io/github/license/null8626/python-weather?style=flat-square
-[github-license-url]: https://github.com/null8626/python-weather/blob/main/LICENSE
-[blazingly-fast-image]: https://img.shields.io/badge/speed-BLAZINGLY%20FAST!!!%20%F0%9F%94%A5%F0%9F%9A%80%F0%9F%92%AA%F0%9F%98%8E-brightgreen.svg?style=flat-square
-[blazingly-fast-url]: https://twitter.com/acdlite/status/974390255393505280
 
 A free and asynchronous weather Python API wrapper made in Python, for Python.
 
@@ -20,6 +14,8 @@ $ pip install python-weather
 
 ## Example
 
+For more information, please read the [documentation](https://python-weather.readthedocs.io/en/latest/).
+
 ```py
 # import the module
 import python_weather
@@ -34,14 +30,14 @@ async def getweather():
     weather = await client.get('New York')
     
     # returns the current day's forecast temperature (int)
-    print(weather.current.temperature)
+    print(weather.temperature)
     
     # get the weather forecast for a few days
-    for forecast in weather.forecasts:
-      print(forecast)
+    for daily in weather.daily_forecasts:
+      print(daily)
       
       # hourly forecasts
-      for hourly in forecast.hourly:
+      for hourly in daily.hourly_forecasts:
         print(f' --> {hourly!r}')
 
 if __name__ == '__main__':

{python-weather-1.1.1 → python-weather-2.0.0}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools"]
 
 [project]
 name = "python-weather"
-version = "1.1.1"
+version = "2.0.0"
 description = "A free and asynchronous weather API wrapper made in Python, for Python."
 readme = "README.md"
 license = { text = "MIT" }
@@ -27,7 +27,6 @@ classifiers = [
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.7",
   "Programming Language :: Python :: 3.8",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
@@ -37,5 +36,7 @@ classifiers = [
 requires-python = ">=3.8"
 
 [project.urls]
-repository = "https://github.com/null8626/python-weather"
-download_url = "https://github.com/null8626/python-weather/archive/1.1.1.tar.gz"
+Changelog = "https://python-weather.readthedocs.io/en/latest/changelog.html"
+Homepage = "https://python-weather.readthedocs.io/en/latest/"
+Documentation = "https://python-weather.readthedocs.io/en/latest/"
+Repository = "https://github.com/null8626/python-weather"

python-weather-2.0.0/python_weather/__init__.py

@@ -0,0 +1,14 @@
+"""
+python-weather
+"""
+
+from .enums import HeatIndex, Kind, Locale, Phase, UltraViolet, WindDirection
+from .constants import METRIC, IMPERIAL
+from .client import Client
+from .errors import Error
+
+__version__ = '2.0.0'
+__all__ = (
+  'METRIC', 'IMPERIAL', 'Client', 'Error', 'HeatIndex', 'Kind', 'Locale',
+  'Phase', 'UltraViolet', 'WindDirection'
+)

python-weather-2.0.0/python_weather/base.py

@@ -0,0 +1,140 @@
+from enum import auto, Enum
+
+from .enums import WindDirection, Kind, Locale, UltraViolet
+from .constants import _Unit
+
+class CustomizableBase:
+  __slots__ = ('__unit', '__locale')
+  
+  def __init__(self, unit: _Unit, locale: Locale):
+    self.unit = unit
+    self.locale = locale
+  
+  @property
+  def unit(self) -> auto:
+    """The measuring unit used to display information in this object."""
+    
+    return self.__unit
+  
+  @unit.setter
+  def unit(self, to: _Unit):
+    """
+    Sets the default measuring unit used to display information in this object.
+    
+    :param to: The new default measuring unit to be used to display information in this object. Must be either ``METRIC`` or ``IMPERIAL``.
+    :exception Error: If the ``to`` argument is not either ``METRIC`` or ``IMPERIAL``.
+    """
+    
+    if not isinstance(to, _Unit):
+      raise Error('Invalid measuring unit specified!')
+    
+    self.__unit = to
+  
+  @property
+  def locale(self) -> Locale:
+    """The localization used to display information in this object."""
+    
+    return self.__locale
+  
+  @locale.setter
+  def locale(self, to: Locale):
+    """
+    Sets the default localization used to display information in this object.
+    
+    :param to: The new :class:`Locale` to be used to display information in this object.
+    :type to: Locale
+    :exception Error: If the ``to`` argument is not a part of the :class:`Locale` enum.
+    """
+    
+    if not isinstance(to, Locale):
+      raise Error(f'Expected {to!r} to be a Locale enum')
+    
+    self.__locale = to
+
+class BaseForecast(CustomizableBase):
+  __slots__ = ('__inner',)
+  
+  def __init__(self, json: dict, unit: _Unit, locale: Locale):
+    self.__inner = json
+    
+    super().__init__(unit, locale)
+  
+  @property
+  def ultraviolet(self) -> UltraViolet:
+    """The ultra-violet (UV) index."""
+    
+    return UltraViolet._new(int(self.__inner['uvIndex']))
+  
+  @property
+  def feels_like(self) -> int:
+    """What it felt like, in Celcius or Fahrenheit."""
+    
+    return int(
+      self.__inner[f'FeelsLike{self._CustomizableBase__unit.temperature}']
+    )
+  
+  @property
+  def humidity(self) -> int:
+    """The humidity value in percent."""
+    
+    return int(self.__inner['humidity'])
+  
+  @property
+  def temperature(self) -> int:
+    """The temperature in either Celcius or Fahrenheit."""
+    
+    return int(self.__inner[f'temp_{self._CustomizableBase__unit.temperature}'])
+  
+  @property
+  def precipitation(self) -> float:
+    """The precipitation in either Millimeters or Inches."""
+    
+    return float(
+      self.__inner[f'precip{self._CustomizableBase__unit.precipitation}']
+    )
+  
+  @property
+  def pressure(self) -> float:
+    """The pressure in either Pascal or Inches."""
+    
+    return float(
+      self.__inner[f'pressure{self._CustomizableBase__unit.pressure}']
+    )
+  
+  @property
+  def visibility(self) -> int:
+    """The visibility distance in either Kilometers or Miles."""
+    
+    return int(
+      self.__inner[f'visibility{self._CustomizableBase__unit.visibility}']
+    )
+  
+  @property
+  def wind_speed(self) -> int:
+    """The wind speeds in either Kilometers per hour or Miles per hour."""
+    
+    return int(
+      self.__inner[f'windspeed{self._CustomizableBase__unit.velocity}']
+    )
+  
+  @property
+  def wind_direction(self) -> WindDirection:
+    """The wind direction."""
+    
+    return WindDirection._new(
+      self.__inner['winddir16Point'], int(self.__inner['winddirDegree'])
+    )
+  
+  @property
+  def description(self) -> str:
+    """The description regarding the forecast. This can be localized in different languages depending on the localization used."""
+    
+    description = self.__inner['weatherDesc'][0]['value'] if self._CustomizableBase__locale == Locale.ENGLISH else self.__inner[f'lang_{self._CustomizableBase__locale.value}'][0]['value'] # yapf: disable
+    
+    return description.strip()
+  
+  @property
+  def kind(self) -> Kind:
+    """The kind of the forecast."""
+    
+    return Kind(int(self.__inner['weatherCode']))

python-weather-2.0.0/python_weather/client.py

@@ -0,0 +1,109 @@
+from aiohttp import ClientSession, ClientTimeout, TCPConnector
+from urllib.parse import quote_plus
+from typing import Optional
+from asyncio import sleep
+from enum import auto
+
+from .constants import _Unit, METRIC
+from .base import CustomizableBase
+from .forecast import Forecast
+from .errors import Error
+from .enums import Locale
+
+class Client(CustomizableBase):
+  """
+  The class that lets you interact with the API.
+  
+  :param unit: Whether to use the metric or imperial/customary system (``IMPERIAL``). Defaults to ``METRIC``.
+  :type unit: Optional[:py:class:`enum.auto`]
+  :param locale: Whether to use a different locale/language as the description for the returned forecast. Defaults to ``Locale.ENGLISH``.
+  :type locale: Optional[Locale]
+  :param session: Whether to use an existing aiohttp client session for requesting or not. Defaults to ``None`` (creates a new one instead)
+  :type session: Optional[:class:`aiohttp.ClientSession`]
+  
+  :raises Error: If the ``unit`` argument is not ``None`` and it's also not ``METRIC`` or ``IMPERIAL``, or if the ``locale`` argument is not ``None`` and it's also not a part of the :class:`Locale` enum.
+  """
+  
+  __slots__ = ('__session',)
+  
+  def __init__(
+    self,
+    *,
+    unit: Optional[auto] = METRIC,
+    locale: Optional[Locale] = Locale.ENGLISH,
+    session: Optional[ClientSession] = None
+  ):
+    super().__init__(unit, locale)
+    
+    self.__session = session or ClientSession(
+      timeout=ClientTimeout(total=5000.0),
+      connector=TCPConnector(verify_ssl=False)
+    )
+  
+  def __repr__(self) -> str:
+    return f'<{self.__class__.__name__} {self.__session!r}>'
+  
+  async def get(
+    self,
+    location: str,
+    *,
+    unit: Optional[auto] = None,
+    locale: Optional[Locale] = None
+  ) -> Forecast:
+    """
+    Fetches a weather forecast for a specific location.
+    
+    :param location: The requested location name for said weather forecast.
+    :type location: str
+    :param unit: Overrides the metric or imperial/customary system (``IMPERIAL``) used by the :class:`Client` object. Defaults to ``None`` (uses the one from the :class:`Client`).
+    :type unit: Optional[:py:class:`enum.auto`]
+    :param locale: Overrides the locale/language used by the :class:`Client` object. Defaults to ``None`` (uses the one from the :class:`Client`).
+    :type locale: Optional[Locale]
+    
+    :exception Error: If the aiohttp client session used by the :class:`Client` object is already closed, if the ``unit`` argument is not ``None`` and it's also not ``METRIC`` or ``IMPERIAL``, if the ``locale`` argument is not ``None`` and it's also not a part of the :class:`Locale` enum, or if the :class:`Client` cannot send a web request to the web server.
+    
+    :returns: The requested weather forecast.
+    :rtype: Forecast
+    """
+    
+    if (not isinstance(location, str)) or (not location):
+      raise Error(f'Expected a proper location str, got {location!r}')
+    elif self.__session.closed:
+      raise Error('Client is already closed')
+    
+    if not isinstance(unit, _Unit):
+      unit = self._CustomizableBase__unit
+    
+    if not isinstance(locale, Locale):
+      locale = self._CustomizableBase__locale
+    
+    subdomain = f'{locale.value}.' if locale != Locale.ENGLISH else ''
+    delay = 0
+    
+    while True:
+      if delay != 0:
+        await sleep(delay)
+        delay *= 2
+      
+      async with self.__session.get(
+        f'https://{subdomain}wttr.in/{quote_plus(location)}?format=j1'
+      ) as resp:
+        try:
+          return Forecast(await resp.json(), unit, locale)
+        except Exception as e:
+          if delay == 4:
+            raise e  # okay, that's too much requests - just raise the error
+          elif delay == 0:
+            delay = 0.5
+  
+  async def close(self):
+    """Closes the :class:`Client` object. Nothing will happen if it's already closed."""
+    
+    if not self.__session.closed:
+      await self.__session.close()
+  
+  async def __aenter__(self):
+    return self
+  
+  async def __aexit__(self, *_, **__):
+    await self.close()

python-weather-2.0.0/python_weather/constants.py

@@ -0,0 +1,34 @@
+from typing import Union
+from re import compile
+from enum import auto
+
+class _Unit:
+  __slots__ = (
+    'temperature', 'velocity', 'pressure', 'precipitation', 'visibility',
+    'cm_divisor'
+  )
+  
+  def __init__(
+    self,
+    temperature: str,
+    velocity: str,
+    pressure: str,
+    precipitation: str,
+    visibility: str,
+    cm_divisor: Union[int, float],
+  ):
+    self.temperature = temperature
+    self.velocity = velocity
+    self.pressure = pressure
+    self.precipitation = precipitation
+    self.visibility = visibility
+    self.cm_divisor = cm_divisor
+  
+  def __repr__(self) -> str:
+    return f'<Unit [{self.temperature}, {self.velocity}]>'
+
+METRIC = _Unit('C', 'Kmph', '', 'MM', '', 1)
+IMPERIAL = _Unit('F', 'Miles', 'Inches', 'Inches', 'Miles', 2.54)
+
+WIND_DIRECTION_EMOJIS = ['↓', '↙', '←', '↖', '↑', '↗', '→', '↘']
+LATLON_REGEX = compile(r'^Lat (\-?[\d\.]+) and Lon (\-?[\d\.]+)$')