garua 0.30.0__tar.gz

garua-0.30.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+dist/
+build/
+site/
+output/
+*.egg-info/
+.eggs/
+.venv
+
+
+# PyPI publishing
+.pypirc
+*.whl
+*.tar.gz
+
+# IDEs
+.vscode/
+
+# Project specific
+downloads/
+temp/
+test/
+reports/
+exports/
+
+
+# Logs
+*.log
+logs/

garua-0.30.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dany Daniel Neyra
+
+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.

garua-0.30.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: garua
+Version: 0.30.0
+Summary: CLI interactiva y servidor MCP para consultar estaciones SENAMHI y descargar datos hidrometeorológicos históricos del Perú.
+Project-URL: Homepage, https://garua.danyneyra.dev
+Project-URL: Documentation, https://garua.danyneyra.dev
+Project-URL: Repository, https://github.com/danyneyra/garua
+Project-URL: Issues, https://github.com/danyneyra/garua/issues
+Project-URL: Changelog, https://github.com/danyneyra/garua/releases
+Project-URL: Website, https://garua.danyneyra.dev
+Author-email: Dany Daniel <hi@danyneyra.dev>
+Maintainer-email: Dany Daniel <hi@danyneyra.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,climate,data-download,garua,garua-app,hydrology,mcp,meteorologia,model-context-protocol,peru,scraper,senamhi,weather
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: Hydrology
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12.3
+Requires-Dist: fastmcp>=3.3.1
+Requires-Dist: mcp>=1.27.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: requests>=2.34.2
+Requires-Dist: rich>=15.0.0
+Requires-Dist: zendriver>=0.15.3
+Provides-Extra: dev
+Requires-Dist: black>=24.0.0; extra == 'dev'
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: zensical>=0.0.45; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <a href="https://garua.danyneyra.dev/">
+    <img alt="Logo de Garúa" src="https://garua.danyneyra.dev/images/garua-logo.svg">
+  </a>
+
+  <p><strong>Garúa</strong> descarga, explora y analiza datos hidrometeorológicos oficiales del SENAMHI Perú.</p>
+</div>
+
+> Garúa es la llovizna fina característica de la costa peruana.
+
+[![PyPI](https://img.shields.io/badge/PyPI-1c83ff?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/garua/)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-89e240?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+---
+
+**Documentación:** [garua.danyneyra.dev](https://garua.danyneyra.dev)
+
+**Código fuente:** [github.com/danyneyra/garua](https://github.com/danyneyra/garua)
+
+---
+
+Garúa es una herramienta de código abierto para trabajar con estaciones meteorológicas e hidrológicas del [SENAMHI]. Permite buscar estaciones, descargar datos históricos en CSV, revisar archivos locales, resumir periodos, comparar meses o años, validar calidad de datos y recomendar estaciones cercanas a un punto geográfico.
+
+## Qué puedes hacer
+
+| Tarea | Descripción |
+| --- | --- |
+| Buscar estaciones | Filtra estaciones por nombre, código, ubicación, tipo, altitud o cercanía a un punto geográfico. |
+| Descargar históricos | Obtén datos mensuales, anuales o multianuales en archivos CSV listos para revisar o procesar. |
+| Analizar periodos | Resume precipitación, temperatura, humedad, viento o nivel de río según el tipo de estación. |
+| Validar calidad | Detecta duplicados, fechas faltantes, valores `S/D`, trazas `T` y otros problemas frecuentes. |
+
+## Formas de uso
+
+Garúa puede usarse de tres maneras:
+
+- **App interactiva:** ejecuta `garua` y navega por un menú en terminal. Es ideal para explorar estaciones y descargar datos paso a paso.
+- **Comandos directos:** usa parámetros cuando ya conoces la estación y el periodo, o cuando quieres automatizar búsquedas y descargas.
+- **Servidor MCP:** conecta Garúa con VS Code, Claude Desktop, Codex u otros clientes de IA compatibles con [Model Context Protocol].
+
+## Instalación rápida
+
+Requisitos principales:
+
+- Python 3.11+.
+- Windows, macOS o Linux.
+- Google Chrome, Brave o Microsoft Edge para las descargas desde SENAMHI.
+
+Instala Garúa desde PyPI:
+
+```bash
+pip install garua
+```
+
+También puedes instalarlo con `pipx` si quieres usarlo como herramienta global de terminal:
+
+```bash
+pipx install garua
+```
+
+Verifica la instalación:
+
+```bash
+garua --help
+garua --doctor
+```
+
+La guía completa está en [Instalación](https://garua.danyneyra.dev/installation/).
+
+## Uso rápido
+
+Abre la app interactiva:
+
+```bash
+garua
+```
+
+<p align="center">
+  <img src="https://garua.danyneyra.dev/images/garua-cli-ui.jpg" alt="Interfaz interactiva de Garúa en la terminal" width="820">
+</p>
+
+Busca estaciones desde la línea de comandos:
+
+```bash
+garua --search Cabana
+```
+
+Descarga un mes específico:
+
+```bash
+garua --station 108047 --mode month --year 2025 --month 7
+```
+
+Ejecuta el servidor MCP:
+
+```bash
+garua-mcp
+```
+
+> Nota: cuando pidas descargar datos, Garúa abrirá un navegador local para consultar el sitio de SENAMHI y superar la verificación Cloudflare Turnstile cuando aparezca. Esto es esperado en la herramienta de descarga.
+
+## Vista MCP
+
+Garúa también funciona como servidor MCP. Puedes pedir tareas en lenguaje natural y el cliente usa las herramientas de Garúa para buscar estaciones, descargar datos o analizar CSV.
+
+### Codex
+
+<p align="center">
+  <img src="https://garua.danyneyra.dev/images/garua-codex.gif" alt="Vista de Garúa MCP en Codex" width="820">
+</p>
+
+### Claude Desktop
+
+<p align="center">
+  <img src="https://garua.danyneyra.dev/images/garua-claude.gif" alt="Vista de Garúa MCP en Claude Desktop" width="820">
+</p>
+
+Ver configuración completa en [Configurar MCP](https://garua.danyneyra.dev/installation/#configurar-mcp) y más ejemplos en [Uso MCP](https://garua.danyneyra.dev/usage/mcp/).
+
+Ejemplos en un cliente MCP:
+
+```text
+Busca estaciones meteorológicas en Arequipa sobre 3000 msnm
+Recomienda una estación para lat -7.61, lon -77.82 con altitud 3000 msnm
+Descarga datos de febrero 2025 de la estación Cabana
+Resume diciembre 2025 para la estación 107008
+Compara marzo 2025 vs marzo 2026 para Cabana
+```
+
+## Documentación
+
+- [Primeros pasos](https://garua.danyneyra.dev/quickstart/)
+- [Instalación](https://garua.danyneyra.dev/installation/)
+- [Uso CLI](https://garua.danyneyra.dev/usage/cli/)
+- [Uso MCP](https://garua.danyneyra.dev/usage/mcp/)
+- [Ejemplos completos](https://garua.danyneyra.dev/usage/examples/)
+- [Referencia de herramientas MCP](https://garua.danyneyra.dev/reference/tools/)
+- [Variables de entorno](https://garua.danyneyra.dev/reference/environment/)
+- [Changelog](https://garua.danyneyra.dev/changelog/)
+
+## Guías principales
+
+- [Buscar estaciones](https://garua.danyneyra.dev/guides/buscar-estaciones/)
+- [Descargar datos](https://garua.danyneyra.dev/guides/descargar-datos/)
+- [Explorar CSV](https://garua.danyneyra.dev/guides/explorar-csv/)
+- [Resumir un periodo](https://garua.danyneyra.dev/guides/resumir-periodo/)
+- [Comparar periodos](https://garua.danyneyra.dev/guides/comparar-periodos/)
+- [Validar calidad de datos](https://garua.danyneyra.dev/guides/validar-datos/)
+- [Recomendar estaciones](https://garua.danyneyra.dev/guides/recomendar-estacion/)
+
+## Desarrollo
+
+```bash
+git clone https://github.com/danyneyra/garua.git
+cd garua
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+En Linux o macOS:
+
+```bash
+source .venv/bin/activate
+```
+
+Más detalles en [Arquitectura](https://garua.danyneyra.dev/development/architecture/) y [Contribuir](https://garua.danyneyra.dev/development/contributing/).
+
+## Licencia
+
+Este proyecto se publica bajo los términos de la licencia MIT. Ver [LICENSE](https://github.com/danyneyra/garua/blob/main/LICENSE).
+
+[Model Context Protocol]: https://modelcontextprotocol.io/docs/getting-started/intro
+[SENAMHI]: https://www.senamhi.gob.pe/?p=estaciones

garua-0.30.0/README.md

@@ -0,0 +1,175 @@
+<div align="center">
+  <a href="https://garua.danyneyra.dev/">
+    <img alt="Logo de Garúa" src="https://garua.danyneyra.dev/images/garua-logo.svg">
+  </a>
+
+  <p><strong>Garúa</strong> descarga, explora y analiza datos hidrometeorológicos oficiales del SENAMHI Perú.</p>
+</div>
+
+> Garúa es la llovizna fina característica de la costa peruana.
+
+[![PyPI](https://img.shields.io/badge/PyPI-1c83ff?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/garua/)
+[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-89e240?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+---
+
+**Documentación:** [garua.danyneyra.dev](https://garua.danyneyra.dev)
+
+**Código fuente:** [github.com/danyneyra/garua](https://github.com/danyneyra/garua)
+
+---
+
+Garúa es una herramienta de código abierto para trabajar con estaciones meteorológicas e hidrológicas del [SENAMHI]. Permite buscar estaciones, descargar datos históricos en CSV, revisar archivos locales, resumir periodos, comparar meses o años, validar calidad de datos y recomendar estaciones cercanas a un punto geográfico.
+
+## Qué puedes hacer
+
+| Tarea | Descripción |
+| --- | --- |
+| Buscar estaciones | Filtra estaciones por nombre, código, ubicación, tipo, altitud o cercanía a un punto geográfico. |
+| Descargar históricos | Obtén datos mensuales, anuales o multianuales en archivos CSV listos para revisar o procesar. |
+| Analizar periodos | Resume precipitación, temperatura, humedad, viento o nivel de río según el tipo de estación. |
+| Validar calidad | Detecta duplicados, fechas faltantes, valores `S/D`, trazas `T` y otros problemas frecuentes. |
+
+## Formas de uso
+
+Garúa puede usarse de tres maneras:
+
+- **App interactiva:** ejecuta `garua` y navega por un menú en terminal. Es ideal para explorar estaciones y descargar datos paso a paso.
+- **Comandos directos:** usa parámetros cuando ya conoces la estación y el periodo, o cuando quieres automatizar búsquedas y descargas.
+- **Servidor MCP:** conecta Garúa con VS Code, Claude Desktop, Codex u otros clientes de IA compatibles con [Model Context Protocol].
+
+## Instalación rápida
+
+Requisitos principales:
+
+- Python 3.11+.
+- Windows, macOS o Linux.
+- Google Chrome, Brave o Microsoft Edge para las descargas desde SENAMHI.
+
+Instala Garúa desde PyPI:
+
+```bash
+pip install garua
+```
+
+También puedes instalarlo con `pipx` si quieres usarlo como herramienta global de terminal:
+
+```bash
+pipx install garua
+```
+
+Verifica la instalación:
+
+```bash
+garua --help
+garua --doctor
+```
+
+La guía completa está en [Instalación](https://garua.danyneyra.dev/installation/).
+
+## Uso rápido
+
+Abre la app interactiva:
+
+```bash
+garua
+```
+
+<p align="center">
+  <img src="https://garua.danyneyra.dev/images/garua-cli-ui.jpg" alt="Interfaz interactiva de Garúa en la terminal" width="820">
+</p>
+
+Busca estaciones desde la línea de comandos:
+
+```bash
+garua --search Cabana
+```
+
+Descarga un mes específico:
+
+```bash
+garua --station 108047 --mode month --year 2025 --month 7
+```
+
+Ejecuta el servidor MCP:
+
+```bash
+garua-mcp
+```
+
+> Nota: cuando pidas descargar datos, Garúa abrirá un navegador local para consultar el sitio de SENAMHI y superar la verificación Cloudflare Turnstile cuando aparezca. Esto es esperado en la herramienta de descarga.
+
+## Vista MCP
+
+Garúa también funciona como servidor MCP. Puedes pedir tareas en lenguaje natural y el cliente usa las herramientas de Garúa para buscar estaciones, descargar datos o analizar CSV.
+
+### Codex
+
+<p align="center">
+  <img src="https://garua.danyneyra.dev/images/garua-codex.gif" alt="Vista de Garúa MCP en Codex" width="820">
+</p>
+
+### Claude Desktop
+
+<p align="center">
+  <img src="https://garua.danyneyra.dev/images/garua-claude.gif" alt="Vista de Garúa MCP en Claude Desktop" width="820">
+</p>
+
+Ver configuración completa en [Configurar MCP](https://garua.danyneyra.dev/installation/#configurar-mcp) y más ejemplos en [Uso MCP](https://garua.danyneyra.dev/usage/mcp/).
+
+Ejemplos en un cliente MCP:
+
+```text
+Busca estaciones meteorológicas en Arequipa sobre 3000 msnm
+Recomienda una estación para lat -7.61, lon -77.82 con altitud 3000 msnm
+Descarga datos de febrero 2025 de la estación Cabana
+Resume diciembre 2025 para la estación 107008
+Compara marzo 2025 vs marzo 2026 para Cabana
+```
+
+## Documentación
+
+- [Primeros pasos](https://garua.danyneyra.dev/quickstart/)
+- [Instalación](https://garua.danyneyra.dev/installation/)
+- [Uso CLI](https://garua.danyneyra.dev/usage/cli/)
+- [Uso MCP](https://garua.danyneyra.dev/usage/mcp/)
+- [Ejemplos completos](https://garua.danyneyra.dev/usage/examples/)
+- [Referencia de herramientas MCP](https://garua.danyneyra.dev/reference/tools/)
+- [Variables de entorno](https://garua.danyneyra.dev/reference/environment/)
+- [Changelog](https://garua.danyneyra.dev/changelog/)
+
+## Guías principales
+
+- [Buscar estaciones](https://garua.danyneyra.dev/guides/buscar-estaciones/)
+- [Descargar datos](https://garua.danyneyra.dev/guides/descargar-datos/)
+- [Explorar CSV](https://garua.danyneyra.dev/guides/explorar-csv/)
+- [Resumir un periodo](https://garua.danyneyra.dev/guides/resumir-periodo/)
+- [Comparar periodos](https://garua.danyneyra.dev/guides/comparar-periodos/)
+- [Validar calidad de datos](https://garua.danyneyra.dev/guides/validar-datos/)
+- [Recomendar estaciones](https://garua.danyneyra.dev/guides/recomendar-estacion/)
+
+## Desarrollo
+
+```bash
+git clone https://github.com/danyneyra/garua.git
+cd garua
+python -m venv .venv
+.venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+En Linux o macOS:
+
+```bash
+source .venv/bin/activate
+```
+
+Más detalles en [Arquitectura](https://garua.danyneyra.dev/development/architecture/) y [Contribuir](https://garua.danyneyra.dev/development/contributing/).
+
+## Licencia
+
+Este proyecto se publica bajo los términos de la licencia MIT. Ver [LICENSE](https://github.com/danyneyra/garua/blob/main/LICENSE).
+
+[Model Context Protocol]: https://modelcontextprotocol.io/docs/getting-started/intro
+[SENAMHI]: https://www.senamhi.gob.pe/?p=estaciones

garua-0.30.0/pyproject.toml

@@ -0,0 +1,109 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "garua"
+version = "0.30.0"
+description = "CLI interactiva y servidor MCP para consultar estaciones SENAMHI y descargar datos hidrometeorológicos históricos del Perú."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Dany Daniel", email = "hi@danyneyra.dev" }
+]
+maintainers = [
+    { name = "Dany Daniel", email = "hi@danyneyra.dev" }
+]
+keywords = [
+    "garua",
+    "senamhi",
+    "meteorologia",
+    "peru",
+    "weather",
+    "climate",
+    "hydrology",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "scraper",
+    "data-download",
+    "garua-app"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Hydrology",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "beautifulsoup4>=4.12.3",
+    "fastmcp>=3.3.1",
+    "mcp>=1.27.1",
+    "pydantic>=2.13.4",
+    "requests>=2.34.2",
+    "rich>=15.0.0",
+    "zendriver>=0.15.3",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black>=24.0.0",
+    "isort>=5.13.0",
+    "mypy>=1.13.0",
+    "pytest>=8.0.0",
+]
+docs = [
+    "zensical>=0.0.45",
+]
+
+[project.urls]
+Homepage = "https://garua.danyneyra.dev"
+Documentation = "https://garua.danyneyra.dev"
+Repository = "https://github.com/danyneyra/garua"
+Issues = "https://github.com/danyneyra/garua/issues"
+Changelog = "https://github.com/danyneyra/garua/releases"
+Website = "https://garua.danyneyra.dev"
+
+[project.scripts]
+garua = "garua.main:cli"
+garua-mcp = "garua.mcp_server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/garua", "src/garua_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/garua",
+    "/src/garua_mcp",
+    "/README.md",
+    "/CHANGELOG.md",
+    "/CONTRIBUTING.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+
+[tool.black]
+line-length = 88
+target-version = ["py311", "py312", "py313"]
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false

garua-0.30.0/src/garua/__init__.py

@@ -0,0 +1 @@
+"""Garua: SENAMHI data tools and MCP server."""

garua-0.30.0/src/garua/__main__.py

@@ -0,0 +1,9 @@
+"""Ejecutar la CLI de Garua con ``python -m garua``."""
+
+import sys
+
+from garua.main import cli
+
+
+if __name__ == "__main__":
+    sys.exit(cli())