inmet-forecast 1.0.0__tar.gz

inmet_forecast-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 inmet-forecast contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

inmet_forecast-1.0.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: inmet-forecast
+Version: 1.0.0
+Summary: A dependency-free Python client for INMET municipality forecasts
+License-Expression: MIT
+Keywords: inmet,weather,forecast,brazil
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# inmet-forecast
+
+<p align="center">
+  <img src="docs/inmet-forecast-icon.png" width="128" alt="inmet-forecast weather icon: sun, cloud, and rain">
+</p>
+
+<p align="center">
+  A dependency-free Python client for INMET's Brazilian municipality forecasts,
+  with raw API data, normalized records, and a JSON command line.
+</p>
+
+<p align="center">
+  <a href="https://github.com/rteoo/inmet-forecast/actions/workflows/publish.yml"><img src="https://github.com/rteoo/inmet-forecast/actions/workflows/publish.yml/badge.svg" alt="Publishing workflow status"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10 or later">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+Fetch forecasts by IBGE municipality code from Python or the command line.
+Keep INMET's original JSON or turn its period-based and daily entries into
+chronological records without losing Portuguese descriptions or unknown fields.
+
+## Highlights
+
+- Municipality forecasts from INMET's forecast API, including temperature,
+  humidity, wind, weather descriptions, sunrise, and sunset when supplied.
+- Raw responses and normalized morning, afternoon, night, and daily records.
+- UTF-8 JSON output through `inmet-forecast` or `python -m forecast`.
+- Configurable socket timeouts, bounded responses, and specific error classes.
+- Python 3.10 or later, using only the standard library at runtime.
+
+## Quick start
+
+Install from a repository checkout:
+
+```powershell
+git clone https://github.com/rteoo/inmet-forecast.git
+cd inmet-forecast
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install .
+python -m forecast 5218508
+```
+
+Use `python -m pip install -e .` for an editable development install. The
+distribution and console command are named `inmet-forecast`; the Python import
+is `forecast`. The example uses Quirinópolis, Goiás, municipality code `5218508`.
+
+## Python
+
+```python
+from forecast import InmetClient, fetch_forecast, normalize_forecast
+
+# Quirinópolis, Goiás (IBGE municipality code).
+raw = fetch_forecast(5218508, timeout=20)
+records = normalize_forecast(raw)
+
+for record in records:
+    print(record["date"], record["period"], record["resumo"])
+
+# Reuse a configured client across requests.
+client = InmetClient(timeout=30)
+raw = client.get_forecast("5218508")
+```
+
+`fetch_forecast()` and `get_forecast()` return the original validated dictionary,
+including base64 icons. `normalize_forecast()` returns chronological rows with
+`municipality_code`, ISO `date`, and `period` (`morning`, `afternoon`, `night`, or
+`daily`). Original INMET fields and Portuguese descriptions are retained. Embedded
+images are excluded from normalized rows unless `include_icons=True`.
+
+The first two dates currently contain `manha`, `tarde`, and `noite` objects; later
+dates contain one daily object. Normalization detects the shape of each date
+instead of assuming a fixed five-day horizon. Temperatures are Celsius and
+humidity values are percentages; numeric values may be `None` when missing.
+Dates arrive from INMET as `DD/MM/YYYY`.
+
+## Command line
+
+```powershell
+inmet-forecast 5218508
+python -m forecast 5218508 --timeout 30
+python -m forecast 5218508 --raw
+```
+
+Default output is normalized UTF-8 JSON. `--raw` includes all original fields
+and embedded images; `--include-icons` keeps images in normalized output.
+Failures print an error to stderr and return exit status 1.
+
+## Errors and service limits
+
+Catch `InmetError` for service failures, or its specific subclasses:
+`InmetHTTPError` (with `.status`), `InmetNetworkError`, and `InmetResponseError`.
+Invalid codes and timeouts raise `ValueError` before making a request.
+Responses are limited to 8 MiB, and must be nonempty UTF-8 JSON with valid forecast
+entries. The timeout bounds individual socket operations, not total elapsed time.
+There are no automatic retries or caches. Caller applications should cache
+appropriately and label retrieval times.
+
+Only forecasts are supported. They are not current station measurements.
+The API has no moon-phase field in the response inspected on 2026-10-07.
+Do not keep today's temperature header when showing tomorrow's forecast: use
+the fields from the selected date/period.
+
+## Source and verification
+
+- [Forecast API example](https://apiprevmet3.inmet.gov.br/previsao/5218508)
+- [Official forecast page](https://previsao.inmet.gov.br/5218508)
+- [IBGE municipality](https://www.ibge.gov.br/cidades-e-estados/go/quirinopolis.html)
+- [INMET forecast service](https://portal.inmet.gov.br/servicos/previs%C3%A3o-do-tempo)
+- [API access contact](https://portal.inmet.gov.br/fale-conosco): api@inmet.gov.br
+
+The official forecast frontend uses this API. An unauthenticated request returned
+HTTP 200 on 2026-10-07; this is a point-in-time observation, not an authentication,
+rate-limit, uptime, or schema guarantee. This project is an independent client
+and is not affiliated with INMET. Data remains attributed to INMET; the MIT
+license covers this client code, not a grant of rights over third-party data.
+
+## Development
+
+Tests use the standard library and a local HTTP server; they never call INMET.
+
+```powershell
+$env:PYTHONPATH = 'src'
+python -W error::ResourceWarning -m unittest discover -s tests -v
+python -m ruff check src tests
+python -m build --no-isolation
+python -m twine check dist/*
+```
+
+The build and lint commands use tooling already installed on the host. Tests
+shut down their server and close their files even on failure.
+
+Verified on Windows/Python 3.14.6 on 2026-10-07: 18 tests passed from source and
+from an installed wheel, Ruff passed, wheel/sdist builds and Twine checks passed.
+The installed CLI fetched nine forecast rows for Quirinópolis. October 7's
+afternoon forecast matched 19–36°C, 30–90% humidity, light NE-E winds, and the
+portal's showers/thunderstorms description. Other Python versions and operating
+systems have not been exercised locally.
+
+## Publishing to PyPI
+
+`.github/workflows/publish.yml` publishes when a GitHub release is published. It tests
+the installed package on Python 3.10 through 3.14, checks lint and formatting,
+builds and validates a wheel and source distribution, then uploads those same
+artifacts using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+No PyPI API token is needed. A manual workflow run performs validation only.
+
+Before the first release:
+
+1. Create the GitHub repository environment `pypi`. Configure required reviewers
+   and restrict its deployment tags to `v*` where the repository plan permits.
+2. Register a [pending PyPI publisher](https://pypi.org/manage/account/publishing/)
+   with project name `inmet-forecast`, owner `rteoo`, repository `inmet-forecast`,
+   workflow filename `publish.yml`, and environment `pypi`.
+3. Publish a GitHub release whose tag exactly matches `v` plus the version in
+   `pyproject.toml`, currently `v1.0.0`. The tagged commit must contain the workflow.
+
+For later releases, update the package version before tagging. PyPI versions
+cannot be overwritten. The workflow deliberately fails on an existing version
+instead of silently skipping its upload. GitHub Actions execution and PyPI
+publication have not been verified from this local checkout.
+
+## License
+
+This client is released under the [MIT License](LICENSE). Weather data remains
+attributed to INMET. The [project icon](docs/inmet-forecast-icon.png) is an
+independent weather mark; its design reference and generation prompt are recorded
+in [docs/README.md](docs/README.md).

inmet_forecast-1.0.0/README.md

@@ -0,0 +1,168 @@
+# inmet-forecast
+
+<p align="center">
+  <img src="docs/inmet-forecast-icon.png" width="128" alt="inmet-forecast weather icon: sun, cloud, and rain">
+</p>
+
+<p align="center">
+  A dependency-free Python client for INMET's Brazilian municipality forecasts,
+  with raw API data, normalized records, and a JSON command line.
+</p>
+
+<p align="center">
+  <a href="https://github.com/rteoo/inmet-forecast/actions/workflows/publish.yml"><img src="https://github.com/rteoo/inmet-forecast/actions/workflows/publish.yml/badge.svg" alt="Publishing workflow status"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10 or later">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+Fetch forecasts by IBGE municipality code from Python or the command line.
+Keep INMET's original JSON or turn its period-based and daily entries into
+chronological records without losing Portuguese descriptions or unknown fields.
+
+## Highlights
+
+- Municipality forecasts from INMET's forecast API, including temperature,
+  humidity, wind, weather descriptions, sunrise, and sunset when supplied.
+- Raw responses and normalized morning, afternoon, night, and daily records.
+- UTF-8 JSON output through `inmet-forecast` or `python -m forecast`.
+- Configurable socket timeouts, bounded responses, and specific error classes.
+- Python 3.10 or later, using only the standard library at runtime.
+
+## Quick start
+
+Install from a repository checkout:
+
+```powershell
+git clone https://github.com/rteoo/inmet-forecast.git
+cd inmet-forecast
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install .
+python -m forecast 5218508
+```
+
+Use `python -m pip install -e .` for an editable development install. The
+distribution and console command are named `inmet-forecast`; the Python import
+is `forecast`. The example uses Quirinópolis, Goiás, municipality code `5218508`.
+
+## Python
+
+```python
+from forecast import InmetClient, fetch_forecast, normalize_forecast
+
+# Quirinópolis, Goiás (IBGE municipality code).
+raw = fetch_forecast(5218508, timeout=20)
+records = normalize_forecast(raw)
+
+for record in records:
+    print(record["date"], record["period"], record["resumo"])
+
+# Reuse a configured client across requests.
+client = InmetClient(timeout=30)
+raw = client.get_forecast("5218508")
+```
+
+`fetch_forecast()` and `get_forecast()` return the original validated dictionary,
+including base64 icons. `normalize_forecast()` returns chronological rows with
+`municipality_code`, ISO `date`, and `period` (`morning`, `afternoon`, `night`, or
+`daily`). Original INMET fields and Portuguese descriptions are retained. Embedded
+images are excluded from normalized rows unless `include_icons=True`.
+
+The first two dates currently contain `manha`, `tarde`, and `noite` objects; later
+dates contain one daily object. Normalization detects the shape of each date
+instead of assuming a fixed five-day horizon. Temperatures are Celsius and
+humidity values are percentages; numeric values may be `None` when missing.
+Dates arrive from INMET as `DD/MM/YYYY`.
+
+## Command line
+
+```powershell
+inmet-forecast 5218508
+python -m forecast 5218508 --timeout 30
+python -m forecast 5218508 --raw
+```
+
+Default output is normalized UTF-8 JSON. `--raw` includes all original fields
+and embedded images; `--include-icons` keeps images in normalized output.
+Failures print an error to stderr and return exit status 1.
+
+## Errors and service limits
+
+Catch `InmetError` for service failures, or its specific subclasses:
+`InmetHTTPError` (with `.status`), `InmetNetworkError`, and `InmetResponseError`.
+Invalid codes and timeouts raise `ValueError` before making a request.
+Responses are limited to 8 MiB, and must be nonempty UTF-8 JSON with valid forecast
+entries. The timeout bounds individual socket operations, not total elapsed time.
+There are no automatic retries or caches. Caller applications should cache
+appropriately and label retrieval times.
+
+Only forecasts are supported. They are not current station measurements.
+The API has no moon-phase field in the response inspected on 2026-10-07.
+Do not keep today's temperature header when showing tomorrow's forecast: use
+the fields from the selected date/period.
+
+## Source and verification
+
+- [Forecast API example](https://apiprevmet3.inmet.gov.br/previsao/5218508)
+- [Official forecast page](https://previsao.inmet.gov.br/5218508)
+- [IBGE municipality](https://www.ibge.gov.br/cidades-e-estados/go/quirinopolis.html)
+- [INMET forecast service](https://portal.inmet.gov.br/servicos/previs%C3%A3o-do-tempo)
+- [API access contact](https://portal.inmet.gov.br/fale-conosco): api@inmet.gov.br
+
+The official forecast frontend uses this API. An unauthenticated request returned
+HTTP 200 on 2026-10-07; this is a point-in-time observation, not an authentication,
+rate-limit, uptime, or schema guarantee. This project is an independent client
+and is not affiliated with INMET. Data remains attributed to INMET; the MIT
+license covers this client code, not a grant of rights over third-party data.
+
+## Development
+
+Tests use the standard library and a local HTTP server; they never call INMET.
+
+```powershell
+$env:PYTHONPATH = 'src'
+python -W error::ResourceWarning -m unittest discover -s tests -v
+python -m ruff check src tests
+python -m build --no-isolation
+python -m twine check dist/*
+```
+
+The build and lint commands use tooling already installed on the host. Tests
+shut down their server and close their files even on failure.
+
+Verified on Windows/Python 3.14.6 on 2026-10-07: 18 tests passed from source and
+from an installed wheel, Ruff passed, wheel/sdist builds and Twine checks passed.
+The installed CLI fetched nine forecast rows for Quirinópolis. October 7's
+afternoon forecast matched 19–36°C, 30–90% humidity, light NE-E winds, and the
+portal's showers/thunderstorms description. Other Python versions and operating
+systems have not been exercised locally.
+
+## Publishing to PyPI
+
+`.github/workflows/publish.yml` publishes when a GitHub release is published. It tests
+the installed package on Python 3.10 through 3.14, checks lint and formatting,
+builds and validates a wheel and source distribution, then uploads those same
+artifacts using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+No PyPI API token is needed. A manual workflow run performs validation only.
+
+Before the first release:
+
+1. Create the GitHub repository environment `pypi`. Configure required reviewers
+   and restrict its deployment tags to `v*` where the repository plan permits.
+2. Register a [pending PyPI publisher](https://pypi.org/manage/account/publishing/)
+   with project name `inmet-forecast`, owner `rteoo`, repository `inmet-forecast`,
+   workflow filename `publish.yml`, and environment `pypi`.
+3. Publish a GitHub release whose tag exactly matches `v` plus the version in
+   `pyproject.toml`, currently `v1.0.0`. The tagged commit must contain the workflow.
+
+For later releases, update the package version before tagging. PyPI versions
+cannot be overwritten. The workflow deliberately fails on an existing version
+instead of silently skipping its upload. GitHub Actions execution and PyPI
+publication have not been verified from this local checkout.
+
+## License
+
+This client is released under the [MIT License](LICENSE). Weather data remains
+attributed to INMET. The [project icon](docs/inmet-forecast-icon.png) is an
+independent weather mark; its design reference and generation prompt are recorded
+in [docs/README.md](docs/README.md).

inmet_forecast-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "inmet-forecast"
+version = "1.0.0"
+description = "A dependency-free Python client for INMET municipality forecasts"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["inmet", "weather", "forecast", "brazil"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+inmet-forecast = "forecast.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+forecast = ["py.typed"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

inmet_forecast-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

inmet_forecast-1.0.0/src/forecast/__init__.py

@@ -0,0 +1,16 @@
+"""Fetch and normalize official INMET municipality forecasts."""
+
+from .client import InmetClient, fetch_forecast
+from .errors import InmetError, InmetHTTPError, InmetNetworkError, InmetResponseError
+from .forecast import normalize_forecast
+
+__version__ = "1.0.0"
+__all__ = [
+    "InmetClient",
+    "InmetError",
+    "InmetHTTPError",
+    "InmetNetworkError",
+    "InmetResponseError",
+    "fetch_forecast",
+    "normalize_forecast",
+]

inmet_forecast-1.0.0/src/forecast/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

inmet_forecast-1.0.0/src/forecast/cli.py

@@ -0,0 +1,40 @@
+"""Command-line forecast output as UTF-8 JSON."""
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from .client import fetch_forecast
+from .errors import InmetError
+from .forecast import normalize_forecast
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Fetch an INMET municipality forecast as JSON.")
+    parser.add_argument("municipality_code", help="Seven-digit IBGE code, e.g. 5218508")
+    parser.add_argument("--timeout", type=float, default=20.0, help="Socket timeout in seconds")
+    parser.add_argument(
+        "--raw", action="store_true", help="Original JSON, including embedded icons"
+    )
+    parser.add_argument(
+        "--include-icons", action="store_true", help="Keep icons in normalized rows"
+    )
+    args = parser.parse_args(argv)
+    try:
+        payload = fetch_forecast(args.municipality_code, timeout=args.timeout)
+        output = (
+            payload
+            if args.raw
+            else normalize_forecast(
+                payload, args.municipality_code, include_icons=args.include_icons
+            )
+        )
+    except (InmetError, ValueError) as error:
+        print(f"inmet-forecast: {error}", file=sys.stderr)
+        return 1
+    # Emit UTF-8 on Windows too, including when stdout is redirected.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    print(json.dumps(output, ensure_ascii=False, indent=2))
+    return 0

inmet_forecast-1.0.0/src/forecast/client.py

@@ -0,0 +1,80 @@
+"""Small HTTPS client built entirely on the Python standard library."""
+
+import json
+import math
+from http.client import HTTPException
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .errors import InmetHTTPError, InmetNetworkError, InmetResponseError
+from .forecast import municipality_code, validate_forecast
+
+FORECAST_BASE_URL = "https://apiprevmet3.inmet.gov.br"
+# ceiling: 8 MiB per response, including icons; review if INMET expands its forecast horizon.
+MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+
+class InmetClient:
+    """Fetch municipality forecasts with a finite per-socket timeout.
+
+    No credentials, persistent session, automatic retries, or caching are used.
+    ``timeout`` is a socket-operation limit, not a total request deadline.
+    """
+
+    def __init__(self, *, timeout: float = 20.0) -> None:
+        if (
+            isinstance(timeout, bool)
+            or not isinstance(timeout, (int, float))
+            or not math.isfinite(timeout)
+            or timeout <= 0
+        ):
+            raise ValueError("Timeout must be a positive, finite number of seconds.")
+        self.timeout = timeout
+
+    def get_forecast(self, code: str | int) -> dict[str, Any]:
+        """GET /previsao/{IBGE_CODE} and return validated, unmodified JSON."""
+        selected = municipality_code(code)
+        request = Request(
+            f"{FORECAST_BASE_URL}/previsao/{selected}",
+            headers={"Accept": "application/json", "User-Agent": "inmet-forecast/1.0.0"},
+            method="GET",
+        )
+        try:
+            with urlopen(request, timeout=self.timeout) as response:
+                if response.status != 200:
+                    raise InmetHTTPError(response.status)
+                content_type = response.headers.get_content_type()
+                if content_type != "application/json" and not content_type.endswith("+json"):
+                    raise InmetResponseError("INMET returned non-JSON content.")
+                declared_length = response.length
+                if declared_length is not None and declared_length > MAX_RESPONSE_BYTES:
+                    raise InmetResponseError("INMET response exceeded the 8 MiB limit.")
+                body = response.read(MAX_RESPONSE_BYTES + 1)
+                if declared_length is not None and len(body) < declared_length:
+                    raise InmetNetworkError(
+                        "INMET connection ended before the response was complete."
+                    )
+        except HTTPError as error:
+            status = error.code
+            error.close()
+            raise InmetHTTPError(status) from None
+        except (URLError, TimeoutError, OSError, HTTPException):
+            raise InmetNetworkError(
+                "Could not reach INMET. Check connectivity and retry; "
+                "increase timeout if the service is slow."
+            ) from None
+        if not body.strip():
+            raise InmetResponseError("INMET returned an empty response.")
+        if len(body) > MAX_RESPONSE_BYTES:
+            raise InmetResponseError("INMET response exceeded the 8 MiB limit.")
+        try:
+            payload = json.loads(body.decode("utf-8-sig"))
+        except (UnicodeDecodeError, json.JSONDecodeError, RecursionError):
+            raise InmetResponseError("INMET returned invalid UTF-8 JSON.") from None
+        return validate_forecast(payload, selected)
+
+
+def fetch_forecast(code: str | int, *, timeout: float = 20.0) -> dict[str, Any]:
+    """Fetch raw forecast JSON using a temporary client."""
+    return InmetClient(timeout=timeout).get_forecast(code)

inmet_forecast-1.0.0/src/forecast/errors.py

@@ -0,0 +1,21 @@
+"""Public exceptions; response bodies are deliberately excluded from messages."""
+
+
+class InmetError(Exception):
+    """Base class for INMET transport and response failures."""
+
+
+class InmetHTTPError(InmetError):
+    """The API returned an unsuccessful HTTP status."""
+
+    def __init__(self, status: int) -> None:
+        self.status = status
+        super().__init__(f"INMET returned HTTP {status}.")
+
+
+class InmetNetworkError(InmetError):
+    """The API could not be reached or the connection timed out."""
+
+
+class InmetResponseError(InmetError):
+    """The API response was empty, malformed, or incompatible."""

inmet_forecast-1.0.0/src/forecast/forecast.py

@@ -0,0 +1,108 @@
+"""Validate INMET's date-keyed JSON and flatten its two forecast shapes."""
+
+import math
+from datetime import datetime
+from typing import Any
+
+from .errors import InmetResponseError
+
+PERIODS = {"manha": "morning", "tarde": "afternoon", "noite": "night"}
+
+
+def municipality_code(value: str | int) -> str:
+    """Return a seven-digit IBGE code, without accepting URL fragments."""
+    if isinstance(value, bool) or not isinstance(value, (str, int)):
+        raise ValueError("Municipality code must be a seven-digit IBGE code.")
+    code = str(value)
+    if len(code) != 7 or not code.isascii() or not code.isdigit():
+        raise ValueError("Municipality code must be a seven-digit IBGE code.")
+    return code
+
+
+def _date(value: str) -> str:
+    try:
+        parsed = datetime.strptime(value, "%d/%m/%Y")
+    except (ValueError, TypeError):
+        raise InmetResponseError("INMET returned an invalid forecast date.") from None
+    if parsed.strftime("%d/%m/%Y") != value:
+        raise InmetResponseError("INMET returned an invalid forecast date.")
+    return parsed.date().isoformat()
+
+
+def _entry(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        raise InmetResponseError("INMET returned an invalid forecast entry.")
+    for key in ("uf", "entidade", "resumo"):
+        if not isinstance(value.get(key), str) or not value[key].strip():
+            raise InmetResponseError(f"INMET forecast is missing a valid {key} field.")
+    for key in ("temp_min", "temp_max", "umidade_min", "umidade_max"):
+        if key not in value:
+            raise InmetResponseError(f"INMET forecast is missing {key}.")
+        number = value[key]
+        if number is not None and (
+            isinstance(number, bool)
+            or not isinstance(number, (int, float))
+            or not math.isfinite(number)
+        ):
+            raise InmetResponseError(f"INMET forecast has an invalid {key} value.")
+    return value
+
+
+def validate_forecast(payload: Any, code: str) -> dict[str, Any]:
+    """Validate the requested municipality while retaining all original fields."""
+    if not isinstance(payload, dict) or not isinstance(payload.get(code), dict):
+        raise InmetResponseError("INMET response does not contain the requested municipality.")
+    days = payload[code]
+    if not days:
+        raise InmetResponseError("INMET returned no forecasts for the requested municipality.")
+    for day, value in days.items():
+        _date(day)
+        if not isinstance(value, dict) or not value:
+            raise InmetResponseError("INMET returned an invalid forecast day.")
+        period_keys = set(value).intersection(PERIODS)
+        if period_keys:
+            if set(value) != period_keys:
+                raise InmetResponseError("INMET returned a mixed or unknown forecast period.")
+            for period in period_keys:
+                _entry(value[period])
+        else:
+            _entry(value)
+    return payload
+
+
+def normalize_forecast(
+    payload: dict[str, Any],
+    code: str | int | None = None,
+    *,
+    include_icons: bool = False,
+) -> list[dict[str, Any]]:
+    """Return chronological rows with ISO dates and English period identifiers.
+
+    Original INMET field names and Portuguese descriptions are preserved. Embedded
+    images are omitted by default. The input payload is never modified.
+    """
+    if code is None:
+        if not isinstance(payload, dict) or len(payload) != 1:
+            raise ValueError(
+                "Supply a municipality code for a response with multiple municipalities."
+            )
+        code = next(iter(payload))
+    selected = municipality_code(code)
+    days = validate_forecast(payload, selected)[selected]
+    records = []
+    for day in sorted(days, key=_date):
+        value = days[day]
+        entries = (
+            [(PERIODS[period], value[period]) for period in PERIODS if period in value]
+            if set(value).intersection(PERIODS)
+            else [("daily", value)]
+        )
+        for period, entry in entries:
+            record = {
+                key: item
+                for key, item in entry.items()
+                if include_icons or not (isinstance(item, str) and item.startswith("data:image/"))
+            }
+            record.update(municipality_code=selected, date=_date(day), period=period)
+            records.append(record)
+    return records

inmet_forecast-1.0.0/src/inmet_forecast.egg-info/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: inmet-forecast
+Version: 1.0.0
+Summary: A dependency-free Python client for INMET municipality forecasts
+License-Expression: MIT
+Keywords: inmet,weather,forecast,brazil
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# inmet-forecast
+
+<p align="center">
+  <img src="docs/inmet-forecast-icon.png" width="128" alt="inmet-forecast weather icon: sun, cloud, and rain">
+</p>
+
+<p align="center">
+  A dependency-free Python client for INMET's Brazilian municipality forecasts,
+  with raw API data, normalized records, and a JSON command line.
+</p>
+
+<p align="center">
+  <a href="https://github.com/rteoo/inmet-forecast/actions/workflows/publish.yml"><img src="https://github.com/rteoo/inmet-forecast/actions/workflows/publish.yml/badge.svg" alt="Publishing workflow status"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10 or later">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+Fetch forecasts by IBGE municipality code from Python or the command line.
+Keep INMET's original JSON or turn its period-based and daily entries into
+chronological records without losing Portuguese descriptions or unknown fields.
+
+## Highlights
+
+- Municipality forecasts from INMET's forecast API, including temperature,
+  humidity, wind, weather descriptions, sunrise, and sunset when supplied.
+- Raw responses and normalized morning, afternoon, night, and daily records.
+- UTF-8 JSON output through `inmet-forecast` or `python -m forecast`.
+- Configurable socket timeouts, bounded responses, and specific error classes.
+- Python 3.10 or later, using only the standard library at runtime.
+
+## Quick start
+
+Install from a repository checkout:
+
+```powershell
+git clone https://github.com/rteoo/inmet-forecast.git
+cd inmet-forecast
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install .
+python -m forecast 5218508
+```
+
+Use `python -m pip install -e .` for an editable development install. The
+distribution and console command are named `inmet-forecast`; the Python import
+is `forecast`. The example uses Quirinópolis, Goiás, municipality code `5218508`.
+
+## Python
+
+```python
+from forecast import InmetClient, fetch_forecast, normalize_forecast
+
+# Quirinópolis, Goiás (IBGE municipality code).
+raw = fetch_forecast(5218508, timeout=20)
+records = normalize_forecast(raw)
+
+for record in records:
+    print(record["date"], record["period"], record["resumo"])
+
+# Reuse a configured client across requests.
+client = InmetClient(timeout=30)
+raw = client.get_forecast("5218508")
+```
+
+`fetch_forecast()` and `get_forecast()` return the original validated dictionary,
+including base64 icons. `normalize_forecast()` returns chronological rows with
+`municipality_code`, ISO `date`, and `period` (`morning`, `afternoon`, `night`, or
+`daily`). Original INMET fields and Portuguese descriptions are retained. Embedded
+images are excluded from normalized rows unless `include_icons=True`.
+
+The first two dates currently contain `manha`, `tarde`, and `noite` objects; later
+dates contain one daily object. Normalization detects the shape of each date
+instead of assuming a fixed five-day horizon. Temperatures are Celsius and
+humidity values are percentages; numeric values may be `None` when missing.
+Dates arrive from INMET as `DD/MM/YYYY`.
+
+## Command line
+
+```powershell
+inmet-forecast 5218508
+python -m forecast 5218508 --timeout 30
+python -m forecast 5218508 --raw
+```
+
+Default output is normalized UTF-8 JSON. `--raw` includes all original fields
+and embedded images; `--include-icons` keeps images in normalized output.
+Failures print an error to stderr and return exit status 1.
+
+## Errors and service limits
+
+Catch `InmetError` for service failures, or its specific subclasses:
+`InmetHTTPError` (with `.status`), `InmetNetworkError`, and `InmetResponseError`.
+Invalid codes and timeouts raise `ValueError` before making a request.
+Responses are limited to 8 MiB, and must be nonempty UTF-8 JSON with valid forecast
+entries. The timeout bounds individual socket operations, not total elapsed time.
+There are no automatic retries or caches. Caller applications should cache
+appropriately and label retrieval times.
+
+Only forecasts are supported. They are not current station measurements.
+The API has no moon-phase field in the response inspected on 2026-10-07.
+Do not keep today's temperature header when showing tomorrow's forecast: use
+the fields from the selected date/period.
+
+## Source and verification
+
+- [Forecast API example](https://apiprevmet3.inmet.gov.br/previsao/5218508)
+- [Official forecast page](https://previsao.inmet.gov.br/5218508)
+- [IBGE municipality](https://www.ibge.gov.br/cidades-e-estados/go/quirinopolis.html)
+- [INMET forecast service](https://portal.inmet.gov.br/servicos/previs%C3%A3o-do-tempo)
+- [API access contact](https://portal.inmet.gov.br/fale-conosco): api@inmet.gov.br
+
+The official forecast frontend uses this API. An unauthenticated request returned
+HTTP 200 on 2026-10-07; this is a point-in-time observation, not an authentication,
+rate-limit, uptime, or schema guarantee. This project is an independent client
+and is not affiliated with INMET. Data remains attributed to INMET; the MIT
+license covers this client code, not a grant of rights over third-party data.
+
+## Development
+
+Tests use the standard library and a local HTTP server; they never call INMET.
+
+```powershell
+$env:PYTHONPATH = 'src'
+python -W error::ResourceWarning -m unittest discover -s tests -v
+python -m ruff check src tests
+python -m build --no-isolation
+python -m twine check dist/*
+```
+
+The build and lint commands use tooling already installed on the host. Tests
+shut down their server and close their files even on failure.
+
+Verified on Windows/Python 3.14.6 on 2026-10-07: 18 tests passed from source and
+from an installed wheel, Ruff passed, wheel/sdist builds and Twine checks passed.
+The installed CLI fetched nine forecast rows for Quirinópolis. October 7's
+afternoon forecast matched 19–36°C, 30–90% humidity, light NE-E winds, and the
+portal's showers/thunderstorms description. Other Python versions and operating
+systems have not been exercised locally.
+
+## Publishing to PyPI
+
+`.github/workflows/publish.yml` publishes when a GitHub release is published. It tests
+the installed package on Python 3.10 through 3.14, checks lint and formatting,
+builds and validates a wheel and source distribution, then uploads those same
+artifacts using [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/).
+No PyPI API token is needed. A manual workflow run performs validation only.
+
+Before the first release:
+
+1. Create the GitHub repository environment `pypi`. Configure required reviewers
+   and restrict its deployment tags to `v*` where the repository plan permits.
+2. Register a [pending PyPI publisher](https://pypi.org/manage/account/publishing/)
+   with project name `inmet-forecast`, owner `rteoo`, repository `inmet-forecast`,
+   workflow filename `publish.yml`, and environment `pypi`.
+3. Publish a GitHub release whose tag exactly matches `v` plus the version in
+   `pyproject.toml`, currently `v1.0.0`. The tagged commit must contain the workflow.
+
+For later releases, update the package version before tagging. PyPI versions
+cannot be overwritten. The workflow deliberately fails on an existing version
+instead of silently skipping its upload. GitHub Actions execution and PyPI
+publication have not been verified from this local checkout.
+
+## License
+
+This client is released under the [MIT License](LICENSE). Weather data remains
+attributed to INMET. The [project icon](docs/inmet-forecast-icon.png) is an
+independent weather mark; its design reference and generation prompt are recorded
+in [docs/README.md](docs/README.md).

inmet_forecast-1.0.0/src/inmet_forecast.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/forecast/__init__.py
+src/forecast/__main__.py
+src/forecast/cli.py
+src/forecast/client.py
+src/forecast/errors.py
+src/forecast/forecast.py
+src/forecast/py.typed
+src/inmet_forecast.egg-info/PKG-INFO
+src/inmet_forecast.egg-info/SOURCES.txt
+src/inmet_forecast.egg-info/dependency_links.txt
+src/inmet_forecast.egg-info/entry_points.txt
+src/inmet_forecast.egg-info/top_level.txt
+tests/test_forecast.py

inmet_forecast-1.0.0/src/inmet_forecast.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

inmet_forecast-1.0.0/src/inmet_forecast.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+inmet-forecast = forecast.cli:main

inmet_forecast-1.0.0/src/inmet_forecast.egg-info/top_level.txt

@@ -0,0 +1 @@
+forecast

inmet_forecast-1.0.0/tests/test_forecast.py

@@ -0,0 +1,231 @@
+import copy
+import io
+import json
+import threading
+import time
+import unittest
+from contextlib import contextmanager, redirect_stderr, redirect_stdout
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest.mock import patch
+
+from forecast import (
+    InmetClient,
+    InmetHTTPError,
+    InmetNetworkError,
+    InmetResponseError,
+    fetch_forecast,
+    normalize_forecast,
+)
+from forecast.cli import main
+
+CODE = "5218508"
+
+
+def entry(**updates):
+    data = {
+        "uf": "GO",
+        "entidade": "Quirinópolis",
+        "resumo": "Muitas nuvens com chuva isolada",
+        "temp_min": 19,
+        "temp_max": 36,
+        "umidade_min": 30,
+        "umidade_max": 90,
+        "dir_vento": "SE-S",
+        "int_vento": "Fracos",
+        "icone": "data:image/png;base64,fixture",
+    }
+    return dict(data, **updates)
+
+
+def forecast():
+    # Date ordering intentionally crosses months and differs from insertion order.
+    return {
+        CODE: {
+            "01/11/2026": entry(temp_min=23, temp_max=39),
+            "31/10/2026": {
+                "noite": entry(),
+                "manha": entry(resumo="Poucas nuvens", temp_min=21, temp_max=39),
+                "tarde": entry(resumo="Muitas nuvens com pancadas de chuva e trovoadas"),
+            },
+        }
+    }
+
+
+@contextmanager
+def serve(body, *, status=200, content_type="application/json", delay=0, truncated=False):
+    requests = []
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            requests.append((self.command, self.path, self.headers.get("Accept")))
+            self.send_response(status)
+            self.send_header("Content-Type", content_type)
+            self.send_header("Content-Length", str(len(body) + (100 if truncated else 0)))
+            self.end_headers()
+            if delay:
+                time.sleep(delay)
+            try:
+                self.wfile.write(body)
+            except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
+                pass  # The timeout test deliberately closes the client's socket.
+
+        def log_message(self, *args):
+            pass
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+    thread = threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.01})
+    thread.start()
+    try:
+        with patch("forecast.client.FORECAST_BASE_URL", f"http://127.0.0.1:{server.server_port}"):
+            yield requests
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
+        if thread.is_alive():
+            raise RuntimeError("Test HTTP server did not stop.")
+
+
+class ClientTests(unittest.TestCase):
+    def test_real_http_get_preserves_unicode_payload_and_headers(self):
+        payload = forecast()
+        with serve(json.dumps(payload, ensure_ascii=False).encode("utf-8")) as requests:
+            self.assertEqual(fetch_forecast(5218508), payload)
+        self.assertEqual(requests, [("GET", "/previsao/5218508", "application/json")])
+
+    def test_http_errors_expose_status_without_response_body(self):
+        for status in (403, 404, 429, 500):
+            with self.subTest(status=status), serve(b"private upstream detail", status=status):
+                with self.assertRaises(InmetHTTPError) as caught:
+                    fetch_forecast(CODE)
+                self.assertEqual(caught.exception.status, status)
+                self.assertNotIn("private", str(caught.exception))
+
+    def test_non_json_empty_malformed_and_wrong_city_responses(self):
+        scenarios = [
+            (b"<html>upstream error</html>", "text/html"),
+            (b"", "application/json"),
+            (b"not json", "application/json"),
+            (b"\xff", "application/json"),
+            (b"[]", "application/json"),
+            (b'{"5218508":{}}', "application/json"),
+            (b'{"5300108":{}}', "application/json"),
+        ]
+        for body, content_type in scenarios:
+            with self.subTest(body=body), serve(body, content_type=content_type):
+                with self.assertRaises(InmetResponseError):
+                    fetch_forecast(CODE)
+
+    def test_utf8_bom_and_json_suffix_content_type(self):
+        body = b"\xef\xbb\xbf" + json.dumps(forecast()).encode()
+        with serve(body, content_type="application/vnd.inmet+json"):
+            self.assertEqual(fetch_forecast(CODE), forecast())
+
+    def test_no_content_is_not_a_successful_forecast(self):
+        with serve(b"", status=204):
+            with self.assertRaises(InmetHTTPError) as caught:
+                fetch_forecast(CODE)
+            self.assertEqual(caught.exception.status, 204)
+
+    def test_read_timeout_becomes_network_error_and_does_not_retry(self):
+        with serve(json.dumps(forecast()).encode(), delay=0.1) as requests:
+            with self.assertRaises(InmetNetworkError):
+                fetch_forecast(CODE, timeout=0.02)
+        self.assertEqual(len(requests), 1)
+
+    def test_truncated_http_body_becomes_network_error(self):
+        with serve(b"{", truncated=True):
+            with self.assertRaises(InmetNetworkError):
+                fetch_forecast(CODE)
+
+    def test_response_size_limit(self):
+        with patch("forecast.client.MAX_RESPONSE_BYTES", 8), serve(b"123456789"):
+            with self.assertRaisesRegex(InmetResponseError, "limit"):
+                fetch_forecast(CODE)
+
+    def test_invalid_inputs_make_no_request(self):
+        with patch("forecast.client.urlopen") as opener:
+            for code in (True, None, 1.0, "5218508/x", "１２３４５６７", "", "123456"):
+                with self.subTest(code=code), self.assertRaises(ValueError):
+                    fetch_forecast(code)
+            for timeout in (True, None, 0, -1, "20", float("nan"), float("inf")):
+                with self.subTest(timeout=timeout), self.assertRaises(ValueError):
+                    InmetClient(timeout=timeout)
+            opener.assert_not_called()
+
+
+class NormalizationTests(unittest.TestCase):
+    def test_mixed_shapes_sort_by_calendar_date_and_preserve_period_data(self):
+        rows = normalize_forecast(forecast())
+        self.assertEqual(
+            [(row["date"], row["period"]) for row in rows],
+            [
+                ("2026-10-31", "morning"),
+                ("2026-10-31", "afternoon"),
+                ("2026-10-31", "night"),
+                ("2026-11-01", "daily"),
+            ],
+        )
+        self.assertEqual(rows[0]["temp_min"], 21)
+        self.assertEqual(rows[0]["resumo"], "Poucas nuvens")
+        self.assertEqual(rows[2]["dir_vento"], "SE-S")
+        self.assertEqual(rows[3]["municipality_code"], CODE)
+
+    def test_icons_are_optional_and_raw_payload_is_not_mutated(self):
+        payload = forecast()
+        before = copy.deepcopy(payload)
+        self.assertNotIn("icone", normalize_forecast(payload)[0])
+        self.assertIn("icone", normalize_forecast(payload, include_icons=True)[0])
+        self.assertEqual(payload, before)
+
+    def test_null_numeric_values_are_preserved(self):
+        rows = normalize_forecast({CODE: {"07/10/2026": entry(temp_min=None)}})
+        self.assertIsNone(rows[0]["temp_min"])
+
+    def test_unknown_fields_are_retained(self):
+        rows = normalize_forecast({CODE: {"07/10/2026": entry(new_field="future")}})
+        self.assertEqual(rows[0]["new_field"], "future")
+
+    def test_partial_period_day_is_supported(self):
+        rows = normalize_forecast({CODE: {"07/10/2026": {"noite": entry()}}})
+        self.assertEqual(rows[0]["period"], "night")
+
+    def test_malformed_dates_and_entries_are_rejected(self):
+        for day, value in [
+            ("31/02/2026", entry()),
+            ("7/10/2026", entry()),
+            ("07/10/2026", {}),
+            ("07/10/2026", {"manha": entry(), "other": {}}),
+            ("07/10/2026", entry(resumo="")),
+            ("07/10/2026", entry(temp_min="19")),
+            ("07/10/2026", entry(temp_max=float("nan"))),
+            ("07/10/2026", entry(umidade_min=True)),
+        ]:
+            with self.subTest(day=day, value=value), self.assertRaises(InmetResponseError):
+                normalize_forecast({CODE: {day: value}})
+
+    def test_multiple_cities_require_explicit_selection(self):
+        payload = dict(forecast(), **{"5300108": {"07/10/2026": entry(entidade="Brasília")}})
+        with self.assertRaises(ValueError):
+            normalize_forecast(payload)
+        self.assertEqual(normalize_forecast(payload, CODE)[0]["entidade"], "Quirinópolis")
+
+
+class CLITests(unittest.TestCase):
+    def test_normalized_and_raw_cli_json(self):
+        with patch("forecast.cli.fetch_forecast", return_value=forecast()):
+            for extra, expected in [([], normalize_forecast(forecast())), (["--raw"], forecast())]:
+                with self.subTest(extra=extra), redirect_stdout(io.StringIO()) as output:
+                    self.assertEqual(main([CODE, *extra]), 0)
+                    self.assertEqual(json.loads(output.getvalue()), expected)
+
+    def test_cli_failure_returns_nonzero_without_traceback(self):
+        with patch("forecast.cli.fetch_forecast", side_effect=InmetHTTPError(429)):
+            with redirect_stderr(io.StringIO()) as error, redirect_stdout(io.StringIO()) as output:
+                self.assertEqual(main([CODE]), 1)
+                self.assertIn("HTTP 429", error.getvalue())
+                self.assertEqual(output.getvalue(), "")
+
+
+if __name__ == "__main__":
+    unittest.main()