From ab0359220fbe757d43e69d349a9a7c3f81ee3bc5 Mon Sep 17 00:00:00 2001 From: null8626 Date: Tue, 15 Oct 2024 13:53:02 +0700 Subject: [PATCH] doc: add more and simplify documentation hyperlinks --- changelog.yml | 52 ++++++++++++++++++++-------------------- docs/changelog.rst | 52 ++++++++++++++++++++-------------------- python_weather/base.py | 4 ++-- python_weather/client.py | 14 +++++------ python_weather/errors.py | 2 +- 5 files changed, 62 insertions(+), 62 deletions(-) diff --git a/changelog.yml b/changelog.yml index 6241bcf..0bb91c4 100644 --- a/changelog.yml +++ b/changelog.yml @@ -19,7 +19,7 @@ changelog: - add: Add ``example.py`` in the project root directory. - fix: Use python's walrus operator to clean up repetitive code. - fix: Implement Python's inheritance rather than keeping everything in one class. - - fix: Separate :class:`~.client.Client` from ``HTTPClient``. + - fix: Separate :class:`.Client` from ``HTTPClient``. - fix: Improve the example in README. - version: 0.3.3 release-date: 18 June 2021 @@ -70,7 +70,7 @@ changelog: - version: 0.4.2 release-date: 9 September 2022 changes: - - rem: Rename ``DailyForecast.average_temperature`` to ``DailyForecast.temperature``. + - rem: Rename ``DailyForecast.average_temperature`` to :attr:`.DailyForecast.temperature`. - fix: Printing the forecast result should no longer raise an :py:class:`AttributeError`. - fix: '``Weather.location`` should not return ``None`` now, and should return floats insead of ints. (making it consistent to the type-hint)' - add: Add ``Mist`` property to the ``WeatherType`` enum. @@ -96,11 +96,11 @@ changelog: release-date: 18 May 2023 changes: - fix: Fix ``tempC`` and ``tempF`` :py:class:`KeyError`. - - fix: Fix :class:`~.enums.UltraViolet` enum returning incorrect values. + - fix: Fix :class:`.UltraViolet` enum returning incorrect values. - version: 1.0.3 release-date: 20 June 2023 changes: - - add: Add missing ``index`` property in the :class:`~.enums.UltraViolet` enum. + - add: Add missing ``index`` property in the :class:`.UltraViolet` enum. - add: Add more helper methods. - fix: Improve docstrings of several properties. - version: 1.1.0 @@ -121,22 +121,22 @@ changelog: - version: 2.0.0 release-date: 18 March 2024 changes: - - rem: Rename the main forecast's class name from ``Weather`` to :class:`~.forecast.Forecast`. - - rem: Merge ``CurrentForecast`` class' properties with :class:`~.forecast.Forecast`'s. Therefore the ``current`` property is removed. - - rem: Merge ``Area`` class' properties with :class:`~.forecast.Forecast`. - - rem: Rename ``Weather.forecasts`` to ``Forecast.daily_forecasts``. - - rem: Rename ``Weather.location`` to ``Forecast.coordinates``. The former now returns the forecast location's name and the latter is no longer an optional type. + - rem: Rename the main forecast's class name from ``Weather`` to :class:`.Forecast`. + - rem: Merge ``CurrentForecast`` class' properties with :class:`.Forecast`'s. Therefore the ``current`` property is removed. + - rem: Merge ``Area`` class' properties with :class:`.Forecast`. + - rem: Rename ``Weather.forecasts`` to :attr:`.Forecast.daily_forecasts`. + - rem: Rename ``Weather.location`` to :attr:`.Forecast.coordinates`. The former now returns the forecast location's name and the latter is no longer an optional type. - rem: Rename ``CurrentForecast.chances_of_hightemp`` to ``Forecast.chances_of_high_temperature``. - rem: Rename ``CurrentForecast.chances_of_remdry`` to ``Forecast.chances_of_remaining_dry``. - - rem: Rename ``CurrentForecast.date`` to ``Forecast.datetime``. - - rem: Rename ``DailyForecast.hourly`` to ``DailyForecast.hourly_forecasts``. - - rem: Rename ``Ultraviolet`` to :class:`~.enums.UltraViolet`. - - add: '``HourlyForecast.heat_index`` now returns a convenience enum called :class:`~.enums.HeatIndex`.' - - rem: Merge ``Astronomy`` class' properties with :class:`~.forecast.DailyForecast`. - - rem: Rename ``Astronomy.sun_rise`` to ``DailyForecast.sunrise``. - - rem: Rename ``Astronomy.sun_set`` to ``DailyForecast.sunset``. - - rem: Rename ``Astronomy.moon_rise`` to ``DailyForecast.moonrise``. - - rem: Rename ``Astronomy.moon_set`` to ``DailyForecast.moonset``. + - rem: Rename ``CurrentForecast.date`` to :attr:`.Forecast.datetime`. + - rem: Rename ``DailyForecast.hourly`` to :attr:`.DailyForecast.hourly_forecasts`. + - rem: Rename ``Ultraviolet`` to :class:`.UltraViolet`. + - add: ':attr:`.HourlyForecast.heat_index` now returns a convenience enum called :class:`.HeatIndex`.' + - rem: Merge ``Astronomy`` class' properties with :class:`.DailyForecast`. + - rem: Rename ``Astronomy.sun_rise`` to :attr:`.DailyForecast.sunrise`. + - rem: Rename ``Astronomy.sun_set`` to :attr:`.DailyForecast.sunset`. + - rem: Rename ``Astronomy.moon_rise`` to :attr:`.DailyForecast.moonrise`. + - rem: Rename ``Astronomy.moon_set`` to :attr:`.DailyForecast.moonset`. - version: 2.0.1 release-date: 25 March 2024 changes: @@ -152,22 +152,22 @@ changelog: - version: 2.0.3 release-date: 5 May 2024 changes: - - fix: Fix potential :py:class:`NameError` while accessing the ``Phase.emoji`` property. + - fix: Fix potential :py:class:`NameError` while accessing the :attr:`.Phase.emoji` property. - fix: Refactors on the request delay calculation. - fix: Fix broken donations redirect in the documentation page. - version: 2.0.4 release-date: 2 October 2024 changes: - fix: The ``Client.close`` method now no longer closes the :class:`~aiohttp.ClientSession` if an existing :class:`~aiohttp.ClientSession` was provided in the constructor. - - add: HTTP exceptions are now wrapped under :class:`~.errors.RequestError`. + - add: HTTP exceptions are now wrapped under :class:`.RequestError`. - add: Add ``__iter__`` and ``__list__`` helper implementations for the forecast classes. - fix: Bump the ``aiohttp`` dependency to be at least version ``3.10.8``. - add: Add an additional ``raise_for_status`` argument to the default :class:`~aiohttp.ClientSession`. - - fix: Refactor the regex retrieval for the ``Forecast.local_population`` property. + - fix: Refactor the regex retrieval for the :attr:`.Forecast.local_population` property. - version: 2.0.5 release-date: 13 October 2024 changes: - - fix: Migrate from using Python properties to raw Python attributes, this should save 50 KB in the size of the :class:`~.forecast.Forecast` object. + - fix: Migrate from using Python properties to raw Python attributes, this should save 50 KB in the size of the :class:`.Forecast` object. - fix: Fix infinite loop while calling the ``__iter__`` or ``__list__`` helper implementations of the forecast objects. - fix: Fix no status code error checking on clients using pre-existing :class:`~aiohttp.ClientSession` objects. - fix: The test workflow now also tests the example code in the README. @@ -176,8 +176,8 @@ changelog: - version: 2.0.7 release-date: 14 October 2024 changes: - - fix: Fix :py:class:`AttributeError` upon calling :class:`~.enums.WindDirection` helper functions. - - add: Add ``__int__`` helper implementation for the :class:`~.enums.WindDirection` enum. - - add: Add optional ``max_retries`` keyword argument to the :class:`~.client.Client` constructor. - - fix: Refactor the :class:`~.enums.Kind` enum to make its code more readable. + - fix: Fix :py:class:`AttributeError` upon calling :class:`.WindDirection` helper functions. + - add: Add ``__int__`` helper implementation for the :class:`.WindDirection` enum. + - add: Add optional ``max_retries`` keyword argument to the :class:`.Client` constructor. + - fix: Refactor the :class:`.Kind` enum to make its code more readable. - fix: Documentation fixes. \ No newline at end of file diff --git a/docs/changelog.rst b/docs/changelog.rst index ce51670..5fec34f 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -17,7 +17,7 @@ Changelog | | | - 🟩 Add ``example.py`` in the project root directory. | | | | - 🟦 Use python's walrus operator to clean up repetitive code. | | | | - 🟦 Implement Python's inheritance rather than keeping everything in one class. | -| | | - 🟦 Separate :class:`~.client.Client` from ``HTTPClient``. | +| | | - 🟦 Separate :class:`.Client` from ``HTTPClient``. | | | | - 🟦 Improve the example in README. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 0.3.3 | 18 June 2021 | - 🟩 Add a bundled-in CLI. | @@ -50,7 +50,7 @@ Changelog +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 0.4.1 | 8 August 2022 | - 🟦 Fix bug when retrieving ``CurrentForecast.local_time``. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 0.4.2 | 9 September 2022 | - 🟥 Rename ``DailyForecast.average_temperature`` to ``DailyForecast.temperature``. | +| 0.4.2 | 9 September 2022 | - 🟥 Rename ``DailyForecast.average_temperature`` to :attr:`.DailyForecast.temperature`. | | | | - 🟦 Printing the forecast result should no longer raise an :py:class:`AttributeError`. | | | | - 🟦 ``Weather.location`` should not return ``None`` now, and should return floats insead of ints. (making it consistent to the type-hint) | | | | - 🟩 Add ``Mist`` property to the ``WeatherType`` enum. | @@ -68,9 +68,9 @@ Changelog | 1.0.1 | 29 April 2023 | - 🟦 Fix backwards-compatibility for Python 3.7 users by removing the ``Self`` typing. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 1.0.2 | 18 May 2023 | - 🟦 Fix ``tempC`` and ``tempF`` :py:class:`KeyError`. | -| | | - 🟦 Fix :class:`~.enums.UltraViolet` enum returning incorrect values. | +| | | - 🟦 Fix :class:`.UltraViolet` enum returning incorrect values. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 1.0.3 | 20 June 2023 | - 🟩 Add missing ``index`` property in the :class:`~.enums.UltraViolet` enum. | +| 1.0.3 | 20 June 2023 | - 🟩 Add missing ``index`` property in the :class:`.UltraViolet` enum. | | | | - 🟩 Add more helper methods. | | | | - 🟦 Improve docstrings of several properties. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -83,22 +83,22 @@ Changelog +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 1.1.2 | 25 February 2024 | - 🟩 Add official project documentation in https://python-weather.readthedocs.io/en/latest/. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 2.0.0 | 18 March 2024 | - 🟥 Rename the main forecast's class name from ``Weather`` to :class:`~.forecast.Forecast`. | -| | | - 🟥 Merge ``CurrentForecast`` class' properties with :class:`~.forecast.Forecast`'s. Therefore the ``current`` property is removed. | -| | | - 🟥 Merge ``Area`` class' properties with :class:`~.forecast.Forecast`. | -| | | - 🟥 Rename ``Weather.forecasts`` to ``Forecast.daily_forecasts``. | -| | | - 🟥 Rename ``Weather.location`` to ``Forecast.coordinates``. The former now returns the forecast location's name and the latter is no longer an optional type. | +| 2.0.0 | 18 March 2024 | - 🟥 Rename the main forecast's class name from ``Weather`` to :class:`.Forecast`. | +| | | - 🟥 Merge ``CurrentForecast`` class' properties with :class:`.Forecast`'s. Therefore the ``current`` property is removed. | +| | | - 🟥 Merge ``Area`` class' properties with :class:`.Forecast`. | +| | | - 🟥 Rename ``Weather.forecasts`` to :attr:`.Forecast.daily_forecasts`. | +| | | - 🟥 Rename ``Weather.location`` to :attr:`.Forecast.coordinates`. The former now returns the forecast location's name and the latter is no longer an optional type. | | | | - 🟥 Rename ``CurrentForecast.chances_of_hightemp`` to ``Forecast.chances_of_high_temperature``. | | | | - 🟥 Rename ``CurrentForecast.chances_of_remdry`` to ``Forecast.chances_of_remaining_dry``. | -| | | - 🟥 Rename ``CurrentForecast.date`` to ``Forecast.datetime``. | -| | | - 🟥 Rename ``DailyForecast.hourly`` to ``DailyForecast.hourly_forecasts``. | -| | | - 🟥 Rename ``Ultraviolet`` to :class:`~.enums.UltraViolet`. | -| | | - 🟩 ``HourlyForecast.heat_index`` now returns a convenience enum called :class:`~.enums.HeatIndex`. | -| | | - 🟥 Merge ``Astronomy`` class' properties with :class:`~.forecast.DailyForecast`. | -| | | - 🟥 Rename ``Astronomy.sun_rise`` to ``DailyForecast.sunrise``. | -| | | - 🟥 Rename ``Astronomy.sun_set`` to ``DailyForecast.sunset``. | -| | | - 🟥 Rename ``Astronomy.moon_rise`` to ``DailyForecast.moonrise``. | -| | | - 🟥 Rename ``Astronomy.moon_set`` to ``DailyForecast.moonset``. | +| | | - 🟥 Rename ``CurrentForecast.date`` to :attr:`.Forecast.datetime`. | +| | | - 🟥 Rename ``DailyForecast.hourly`` to :attr:`.DailyForecast.hourly_forecasts`. | +| | | - 🟥 Rename ``Ultraviolet`` to :class:`.UltraViolet`. | +| | | - 🟩 :attr:`.HourlyForecast.heat_index` now returns a convenience enum called :class:`.HeatIndex`. | +| | | - 🟥 Merge ``Astronomy`` class' properties with :class:`.DailyForecast`. | +| | | - 🟥 Rename ``Astronomy.sun_rise`` to :attr:`.DailyForecast.sunrise`. | +| | | - 🟥 Rename ``Astronomy.sun_set`` to :attr:`.DailyForecast.sunset`. | +| | | - 🟥 Rename ``Astronomy.moon_rise`` to :attr:`.DailyForecast.moonrise`. | +| | | - 🟥 Rename ``Astronomy.moon_set`` to :attr:`.DailyForecast.moonset`. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 2.0.1 | 25 March 2024 | - 🟦 Migrate from ``yapf`` to ``ruff``. | | | | - 🟦 Fix potential :py:class:`NameError` while modifying forecast unit or locale. | @@ -108,27 +108,27 @@ Changelog | 2.0.2 | 25 April 2024 | - 🟩 Add a donation link over at https://ko-fi.com/null8626. | | | | - 🟦 As of 19 April 2024, all GitHub commits sent to the repository (both manual and automated) will be GPG-signed. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 2.0.3 | 5 May 2024 | - 🟦 Fix potential :py:class:`NameError` while accessing the ``Phase.emoji`` property. | +| 2.0.3 | 5 May 2024 | - 🟦 Fix potential :py:class:`NameError` while accessing the :attr:`.Phase.emoji` property. | | | | - 🟦 Refactors on the request delay calculation. | | | | - 🟦 Fix broken donations redirect in the documentation page. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | 2.0.4 | 2 October 2024 | - 🟦 The ``Client.close`` method now no longer closes the :class:`~aiohttp.ClientSession` if an existing :class:`~aiohttp.ClientSession` was provided in the constructor.| -| | | - 🟩 HTTP exceptions are now wrapped under :class:`~.errors.RequestError`. | +| | | - 🟩 HTTP exceptions are now wrapped under :class:`.RequestError`. | | | | - 🟩 Add ``__iter__`` and ``__list__`` helper implementations for the forecast classes. | | | | - 🟦 Bump the ``aiohttp`` dependency to be at least version ``3.10.8``. | | | | - 🟩 Add an additional ``raise_for_status`` argument to the default :class:`~aiohttp.ClientSession`. | -| | | - 🟦 Refactor the regex retrieval for the ``Forecast.local_population`` property. | +| | | - 🟦 Refactor the regex retrieval for the :attr:`.Forecast.local_population` property. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 2.0.5 | 13 October 2024 | - 🟦 Migrate from using Python properties to raw Python attributes, this should save 50 KB in the size of the :class:`~.forecast.Forecast` object. | +| 2.0.5 | 13 October 2024 | - 🟦 Migrate from using Python properties to raw Python attributes, this should save 50 KB in the size of the :class:`.Forecast` object. | | | | - 🟦 Fix infinite loop while calling the ``__iter__`` or ``__list__`` helper implementations of the forecast objects. | | | | - 🟦 Fix no status code error checking on clients using pre-existing :class:`~aiohttp.ClientSession` objects. | | | | - 🟦 The test workflow now also tests the example code in the README. | | | | - 🟩 Add ``__len__`` helper implementations for the forecast classes. | | | | - 🟦 Bump the ``aiohttp`` dependency to be at least version ``3.10.10``. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 2.0.7 | 14 October 2024 | - 🟦 Fix :py:class:`AttributeError` upon calling :class:`~.enums.WindDirection` helper functions. | -| | | - 🟩 Add ``__int__`` helper implementation for the :class:`~.enums.WindDirection` enum. | -| | | - 🟩 Add optional ``max_retries`` keyword argument to the :class:`~.client.Client` constructor. | -| | | - 🟦 Refactor the :class:`~.enums.Kind` enum to make its code more readable. | +| 2.0.7 | 14 October 2024 | - 🟦 Fix :py:class:`AttributeError` upon calling :class:`.WindDirection` helper functions. | +| | | - 🟩 Add ``__int__`` helper implementation for the :class:`.WindDirection` enum. | +| | | - 🟩 Add optional ``max_retries`` keyword argument to the :class:`.Client` constructor. | +| | | - 🟦 Refactor the :class:`.Kind` enum to make its code more readable. | | | | - 🟦 Documentation fixes. | +---------+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ \ No newline at end of file diff --git a/python_weather/base.py b/python_weather/base.py index 94f1288..8e87c3c 100644 --- a/python_weather/base.py +++ b/python_weather/base.py @@ -67,9 +67,9 @@ def locale(self, to: Locale) -> None: """ Sets the default localization used to display information in this object. - :param to: The new :class:`~.enums.Locale` to be 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:`~.enums.Locale` enum. + :exception Error: If the ``to`` argument is not a part of the :class:`.Locale` enum. """ if not isinstance(to, Locale): diff --git a/python_weather/client.py b/python_weather/client.py index 913d02d..fb51d7e 100644 --- a/python_weather/client.py +++ b/python_weather/client.py @@ -40,14 +40,14 @@ class Client(CustomizableBase): :param unit: Whether to use the metric or imperial/customary system (``IMPERIAL``). Defaults to ``METRIC``. :type unit: _Unit - :param locale: Whether to use a different locale/language as the description for the returned forecast. Defaults to ``Locale.ENGLISH``. + :param locale: Whether to use a different locale/language as the description for the returned forecast. Defaults to :attr:`.Locale.ENGLISH`. :type locale: 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`] - :param max_retries: Maximum amount of retries upon receiving HTTP request failure before raising a :class:`~.errors.RequestError`. To have infinite retries, use ``-1`` (NOT recommended). Defaults to ``None`` (or 3 retries). + :param max_retries: Maximum amount of retries upon receiving HTTP request failure before raising a :class:`.RequestError`. To have infinite retries, use ``-1`` (NOT recommended). Defaults to ``None`` (or 3 retries). :type max_retries: Optional[:class:`int`] - :raises Error: If ``unit`` is not ``METRIC`` or ``IMPERIAL``, or if ``locale`` is not a part of the :class:`~.enums.Locale` enum. + :raises Error: If ``unit`` is not ``METRIC`` or ``IMPERIAL``, or if ``locale`` is not a part of the :class:`.Locale` enum. """ __slots__: Tuple[str, ...] = ('__own_session', '__session', '__max_retries') @@ -87,10 +87,10 @@ async def get( :param unit: Overrides the unit used by this object. Defaults to the one used by this object. :type unit: Optional[``_Unit``] :param locale: Overrides the locale used by this object. Defaults to the one used by this object. - :type locale: Optional[:class:`~.enums.Locale`] + :type locale: Optional[:class:`.Locale`] - :exception Error: If the aiohttp client session used by the :class:`~.client.Client` object is already closed. - :exception RequestError: If the :class:`~.client.Client` can't send a web request to the web server. + :exception Error: If the aiohttp client session used by the :class:`.Client` object is already closed. + :exception RequestError: If the :class:`.Client` can't send a web request to the web server. :returns: The requested weather forecast. :rtype: Forecast @@ -128,7 +128,7 @@ async def get( delay *= 2 async def close(self) -> None: - """Closes the :class:`~.client.Client` object. Nothing will happen if the client uses a pre-existing :class:`~aiohttp.ClientSession` or if the session is already closed.""" + """Closes the :class:`.Client` object. Nothing will happen if the client uses a pre-existing :class:`~aiohttp.ClientSession` or if the session is already closed.""" if self.__own_session and not self.__session.closed: await self.__session.close() diff --git a/python_weather/errors.py b/python_weather/errors.py index 8222165..e67f1f8 100644 --- a/python_weather/errors.py +++ b/python_weather/errors.py @@ -32,7 +32,7 @@ class Error(Exception): class RequestError(Error): - """Thrown upon HTTP request failure. Extends :class:`~.errors.Error`.""" + """Thrown upon HTTP request failure. Extends :class:`.Error`.""" __slots__: Tuple[str, ...] = ('source',)