bom-weather-api 0.1.0__tar.gz

bom_weather_api-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+.DS_Store

bom_weather_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
+project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-28
+
+### Added
+
+- `BomClient` with forecast locations, observation stations, observations,
+  daily town forecasts (FTP), hourly forecasts and warnings (BoM app API).
+- Typed, null-safe models and parsers for the BoM FTP products and app API.
+- Support for Python 3.12 to 3.15.
+- Anonymous FTP transport built on `aioftp`, with injectable transports for
+  testing.

bom_weather_api-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

bom_weather_api-0.1.0/PKG-INFO

@@ -0,0 +1,247 @@
+Metadata-Version: 2.5
+Name: bom-weather-api
+Version: 0.1.0
+Summary: Async Python client for the Australian Bureau of Meteorology weather API
+Project-URL: Homepage, https://github.com/tinkerologie/bom-weather-api
+Project-URL: Issues, https://github.com/tinkerologie/bom-weather-api/issues
+Project-URL: Changelog, https://github.com/tinkerologie/bom-weather-api/blob/main/CHANGELOG.md
+Author-email: Ruaan Deysel <ruaan.deysel@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: asyncio,australia,bom,bureau of meteorology,home-assistant,weather
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aioftp>=0.21.3
+Requires-Dist: aiohttp>=3.10.0
+Requires-Dist: defusedxml>=0.7.1
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# BoM Weather API
+
+**Async Python client for Australian Bureau of Meteorology weather data**
+
+[![PyPI](https://img.shields.io/pypi/v/bom-weather-api?style=flat-square)](https://pypi.org/project/bom-weather-api/)
+[![Python](https://img.shields.io/pypi/pyversions/bom-weather-api?style=flat-square)](https://pypi.org/project/bom-weather-api/)
+[![CI](https://img.shields.io/github/actions/workflow/status/tinkerologie/bom-weather-api/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/tinkerologie/bom-weather-api/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/tinkerologie/bom-weather-api?style=flat-square)](https://codecov.io/gh/tinkerologie/bom-weather-api)
+[![License](https://img.shields.io/github/license/tinkerologie/bom-weather-api?style=flat-square)](LICENSE)
+
+</div>
+
+BoM Weather API gives Python code typed, async access to Australian
+[Bureau of Meteorology](https://www.bom.gov.au/) (BoM) data: station
+observations, 7-day town forecasts, hourly forecasts and weather warnings.
+It was built for the [Bureau of Meteorology integration for Home Assistant](https://github.com/tinkerologie/ha-bom-australia),
+and works in any asyncio application.
+
+## Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Data sources](#data-sources)
+- [API reference](#api-reference)
+- [Error handling](#error-handling)
+- [Responsible use](#responsible-use)
+- [Development](#development)
+- [Licence and attribution](#licence-and-attribution)
+
+## Features
+
+- **Async throughout**: built on `aiohttp` and `aioftp`, and accepts your own `aiohttp.ClientSession`.
+- **Fully typed**: frozen dataclass models, ships `py.typed`, and passes `mypy --strict`.
+- **Tolerates missing data**: BoM regularly omits values, such as today's minimum temperature after the morning or today's icon late in the evening. Every field is optional, and a missing value is `None` rather than an exception.
+- **Built on official feeds**: forecasts and observations come from BoM's sanctioned anonymous FTP products.
+- **Location helpers**: find the nearest forecast towns and observation stations to any coordinate.
+- **Predictable errors**: a single exception hierarchy; transport exceptions never leak.
+- **Tested**: 100% line and branch coverage against real BoM responses, on Python 3.12, 3.13, 3.14 and 3.15.
+
+## Installation
+
+```bash
+pip install bom-weather-api
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add bom-weather-api
+```
+
+Requires Python 3.12 or later, and outbound FTP access (port 21) to `ftp.bom.gov.au`.
+
+## Quick start
+
+```python
+import asyncio
+
+from bom_weather_api import BomClient, Coordinate
+
+
+async def main() -> None:
+    home = Coordinate(latitude=-27.47, longitude=153.02)
+
+    async with BomClient() as client:
+        # Find the nearest forecast town and observation station.
+        towns = await client.get_forecast_locations()
+        town, distance = BomClient.nearest(home, towns, limit=1)[0]
+
+        stations = await client.get_stations(town.product_state)
+        station, _ = BomClient.nearest(town.coordinate, stations, limit=1)[0]
+
+        # Fetch current conditions, forecasts and warnings.
+        observation = await client.get_observation(town.product_state, station.id)
+        daily = await client.get_daily_forecast(town)
+        hourly = await client.get_hourly_forecast(town.coordinate)
+        warnings = await client.get_warnings(town.coordinate, details=True)
+
+    today = daily.days[0]
+    print(f"{town.name} ({distance} km away), station {station.name}")
+    print(
+        f"Now: {observation.temperature} °C, feels like {observation.apparent_temperature} °C"
+    )
+    print(
+        f"Today: {today.short_text} Max {today.temp_max} °C, {today.rain_chance}% chance of rain"
+    )
+    print(f"{len(hourly.hours)} hourly forecasts, {len(warnings)} active warnings")
+
+
+asyncio.run(main())
+```
+
+### Sharing a session
+
+Pass an existing `aiohttp.ClientSession` to reuse its connections. The client
+never closes a session it did not create.
+
+```python
+import aiohttp
+
+async with aiohttp.ClientSession() as session:
+    client = BomClient(session)
+    forecast = await client.get_daily_forecast(town)
+```
+
+## Data sources
+
+| Data | Source |
+|---|---|
+| Forecast towns, daily town (précis) forecasts, station observations | BoM's official [anonymous FTP data feeds](https://www.bom.gov.au/catalogue/data-feeds.shtml) on `ftp.bom.gov.au` |
+| Hourly forecasts, warnings, and the extended text, UV, fire danger and sun times in the daily forecast | The undocumented JSON API behind the BoM app (`api.weather.bom.gov.au`) |
+
+The FTP products are free to access for non-commercial use. The app API is not
+a public BoM service and may change without notice. If its daily extras are
+unavailable, `get_daily_forecast` still returns the FTP forecast without them.
+
+## API reference
+
+### `BomClient`
+
+```python
+BomClient(
+    session: aiohttp.ClientSession | None = None,
+    *,
+    transport: FileTransport | None = None,  # defaults to FtpTransport()
+    timeout: float = 30.0,
+    user_agent: str = DEFAULT_USER_AGENT,
+)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `get_forecast_locations()` | `list[ForecastLocation]` | Every town BoM issues a forecast for (about 680) |
+| `get_stations(state)` | `list[Station]` | Observation stations in a state: `NSW`, `VIC`, `QLD`, `SA`, `WA`, `TAS` or `NT` (ACT stations are in `NSW`) |
+| `get_observation(state, station_id)` | `Observation` | Latest observation from a station |
+| `get_daily_forecast(location, *, extras=True)` | `DailyForecast` | 7-day town forecast; `extras` adds extended text, UV, fire danger and sun times |
+| `get_hourly_forecast(coordinate)` | `HourlyForecast` | Hourly forecast for about the next 72 hours |
+| `get_warnings(coordinate, *, details=False)` | `list[WeatherWarning]` | Current warnings, excluding cancellations; `details` adds each warning's full message |
+| `get_warning(warning_id)` | `WarningDetails` | The full plain-text message of a warning |
+| `BomClient.nearest(coordinate, items, *, limit=None)` | `list[tuple[item, float]]` | Towns or stations sorted by distance in km |
+
+`BomClient` is an async context manager; `close()` releases a session the client created itself.
+
+### Models
+
+All models are frozen dataclasses exported from `bom_weather_api`.
+
+| Model | Key fields |
+|---|---|
+| `Coordinate` | `latitude`, `longitude`, `geohash`, `distance_to()` |
+| `ForecastLocation` | `aac`, `name`, `state`, `coordinate`, `timezone`, `product_state` |
+| `Station` | `id`, `name`, `state`, `coordinate`, `wmo_id` |
+| `Observation` | `temperature`, `apparent_temperature`, `dew_point`, `humidity`, `pressure`, `wind_speed`, `wind_direction`, `wind_gust`, `rain_since_9am`, `observed_at`, … |
+| `DailyForecast` | `issued_at`, `next_issue_at`, `days`, `now` |
+| `DailyForecastDay` | `date`, `temp_max`, `temp_min`, `short_text`, `extended_text`, `rain_chance`, `rain_amount_range`, `uv_index`, `fire_danger`, `sunrise`, `sunset`, … |
+| `HourlyForecast` / `HourlyForecastPoint` | `time`, `temperature`, `humidity`, `wind_speed`, `wind_direction`, `rain_chance`, `uv_index`, `is_night`, … |
+| `WeatherWarning` / `WarningDetails` | `id`, `type`, `title`, `phase`, `issued_at`, `expires_at`, `message` |
+
+Units are metric: °C, km/h, hPa, mm and km. Times are timezone-aware `datetime` objects.
+
+## Error handling
+
+Every error raised by the client derives from `BomError`:
+
+```text
+BomError
+├── BomConnectionError        the service could not be reached
+│   └── BomTimeoutError       the request timed out
+├── BomResponseError          unexpected HTTP or FTP status (.status)
+│   ├── BomNotFoundError      unknown station, warning or file
+│   └── BomRateLimitError     slow down (.retry_after, in seconds)
+└── BomParseError             the response had an unexpected format
+```
+
+```python
+from bom_weather_api import BomError, BomNotFoundError, BomRateLimitError
+
+try:
+    observation = await client.get_observation("QLD", "040913")
+except BomNotFoundError:
+    ...  # the station is not reporting; choose another one
+except BomRateLimitError as err:
+    ...  # retry after err.retry_after seconds
+except BomError:
+    ...  # any other failure
+```
+
+## Responsible use
+
+- The client identifies itself with an honest User-Agent. Please keep one that identifies your application.
+- Poll no more often than the data changes: observations update every 10 minutes, and town forecasts a few times a day.
+- This library does not use the bom.gov.au website API (`api.bom.gov.au`), which blocks automated clients.
+- The BoM FTP products are free for non-commercial use. For commercial use, see BoM's [data services](https://www.bom.gov.au/resources/data-services).
+
+## Development
+
+```bash
+git clone https://github.com/tinkerologie/bom-weather-api.git
+cd bom-weather-api
+uv sync
+
+uv run pytest --cov                                         # tests, 100% coverage required
+uv run ruff format . && uv run ruff check . && uv run mypy  # format, lint, type-check
+uvx bandit --recursive src                                  # security scan
+```
+
+Test fixtures in `tests/fixtures/` are real BoM responses captured on
+2026-10-28. Releases are published to PyPI from GitHub releases using trusted
+publishing; see [CHANGELOG.md](CHANGELOG.md) for the release history.
+
+## Licence and attribution
+
+Released under the [Apache License 2.0](LICENSE).
+
+Weather data © Commonwealth of Australia, Bureau of Meteorology. This project
+is not affiliated with or endorsed by the Bureau of Meteorology.