nph-client 0.1.2__tar.gz

nph_client-0.1.2/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: nph-client
+Version: 0.1.2
+Summary: Biblioteca de visualização de dados oceanográficos e meteorológicos do NPH-UNISANTA.
+Author: NPH UNISANTA
+Keywords: nph,nph-client,oceanografia,meteorologia,plotly,graficos,nivel-do-mar,chuva,unisanta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: nbformat>=4.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: kaleido>=0.2.1; extra == "dev"
+
+# nph-client 🌊
+
+Biblioteca em Python para geração padronizada e simplificada de gráficos oceanográficos e meteorológicos do **NPH-UNISANTA** (Núcleo de Pesquisas Hidrodinâmicas da Unisanta).
+
+## Instalação
+
+```bash
+pip install nph-client
+```
+
+## Principais Funções
+
+### 1. Nível do Mar (`plot_nivel_mar`)
+Plota o gráfico de linha de nível do mar com picos destacados e limiares do **PPDC Ressacas**:
+- **OBSERVAÇÃO**: `< 1.8m`
+- **ATENÇÃO**: `1.8m a 2.0m`
+- **ALERTA**: `≥ 2.0m`
+
+```python
+from nph_client import NPHClient, plot_nivel_mar
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_nivel = client.get_measurements(stations=349, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_nivel_mar(df=df_nivel, title="Nível do Mar - Santos")
+fig.show()
+```
+
+> **Dica**: Para ocultar as linhas e faixas dos limiares PPDC, passe `show_thresholds=False`.
+
+---
+
+### 2. Precipitação Pluviométrica / Chuva (`plot_chuva`)
+Plota o gráfico de barras para chuva (mm):
+
+```python
+from nph_client import NPHClient, plot_chuva
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_chuva = client.get_measurements(stations=26, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_chuva(df=df_chuva, title="Precipitação Pluviométrica - Portão 40")
+fig.show()
+```
+
+---
+
+### 3. Hidrograma Combinado (`plot_nivel_e_chuva`)
+Reúne Nível do Mar e Chuva no mesmo gráfico com eixo secundário:
+
+```python
+from nph_client import NPHClient, plot_nivel_e_chuva
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_nivel = client.get_measurements(stations=349, start_date="2026-08-05", end_date="2026-08-07")
+df_chuva = client.get_measurements(stations=26, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_nivel_e_chuva(df_nivel=df_nivel, df_chuva=df_chuva, title="Hidrograma")
+fig.show()
+```
+
+## Requisitos
+- `pandas`
+- `plotly`
+- `requests`
+- `python-dateutil`
+- `numpy`
+- `nbformat`
+
+## Licença
+Licenciado sob a licença MIT.

nph_client-0.1.2/README.md

@@ -0,0 +1,71 @@
+# nph-client 🌊
+
+Biblioteca em Python para geração padronizada e simplificada de gráficos oceanográficos e meteorológicos do **NPH-UNISANTA** (Núcleo de Pesquisas Hidrodinâmicas da Unisanta).
+
+## Instalação
+
+```bash
+pip install nph-client
+```
+
+## Principais Funções
+
+### 1. Nível do Mar (`plot_nivel_mar`)
+Plota o gráfico de linha de nível do mar com picos destacados e limiares do **PPDC Ressacas**:
+- **OBSERVAÇÃO**: `< 1.8m`
+- **ATENÇÃO**: `1.8m a 2.0m`
+- **ALERTA**: `≥ 2.0m`
+
+```python
+from nph_client import NPHClient, plot_nivel_mar
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_nivel = client.get_measurements(stations=349, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_nivel_mar(df=df_nivel, title="Nível do Mar - Santos")
+fig.show()
+```
+
+> **Dica**: Para ocultar as linhas e faixas dos limiares PPDC, passe `show_thresholds=False`.
+
+---
+
+### 2. Precipitação Pluviométrica / Chuva (`plot_chuva`)
+Plota o gráfico de barras para chuva (mm):
+
+```python
+from nph_client import NPHClient, plot_chuva
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_chuva = client.get_measurements(stations=26, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_chuva(df=df_chuva, title="Precipitação Pluviométrica - Portão 40")
+fig.show()
+```
+
+---
+
+### 3. Hidrograma Combinado (`plot_nivel_e_chuva`)
+Reúne Nível do Mar e Chuva no mesmo gráfico com eixo secundário:
+
+```python
+from nph_client import NPHClient, plot_nivel_e_chuva
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_nivel = client.get_measurements(stations=349, start_date="2026-08-05", end_date="2026-08-07")
+df_chuva = client.get_measurements(stations=26, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_nivel_e_chuva(df_nivel=df_nivel, df_chuva=df_chuva, title="Hidrograma")
+fig.show()
+```
+
+## Requisitos
+- `pandas`
+- `plotly`
+- `requests`
+- `python-dateutil`
+- `numpy`
+- `nbformat`
+
+## Licença
+Licenciado sob a licença MIT.

nph_client-0.1.2/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nph-client"
+version = "0.1.2"
+description = "Biblioteca de visualização de dados oceanográficos e meteorológicos do NPH-UNISANTA."
+readme = "README.md"
+authors = [
+    { name = "NPH UNISANTA" }
+]
+keywords = ["nph", "nph-client", "oceanografia", "meteorologia", "plotly", "graficos", "nivel-do-mar", "chuva", "unisanta"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas>=1.5.0",
+    "plotly>=5.0.0",
+    "requests>=2.25.0",
+    "python-dateutil>=2.8.0",
+    "numpy>=1.20.0",
+    "nbformat>=4.2.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "kaleido>=0.2.1"
+]

nph_client-0.1.2/setup.cfg

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

nph_client-0.1.2/src/nph_client/__init__.py

@@ -0,0 +1,26 @@
+from .charts import plot_nivel_mar, plot_chuva, plot_nivel_e_chuva
+from .client import NPHClient, MODELS_GLOSSARY, PARAMS_GLOSSARY
+from .thresholds import (
+    Threshold,
+    get_ppdc_sea_level_thresholds,
+    PPDC_THRESHOLD_ATENCAO,
+    PPDC_THRESHOLD_ALERTA
+)
+from .plotting import AxisConfig, plot_base_series
+
+__all__ = [
+    "plot_nivel_mar",
+    "plot_chuva",
+    "plot_nivel_e_chuva",
+    "NPHClient",
+    "Threshold",
+    "get_ppdc_sea_level_thresholds",
+    "PPDC_THRESHOLD_ATENCAO",
+    "PPDC_THRESHOLD_ALERTA",
+    "AxisConfig",
+    "plot_base_series",
+    "MODELS_GLOSSARY",
+    "PARAMS_GLOSSARY"
+]
+
+__version__ = "0.1.2"

nph_client-0.1.2/src/nph_client/charts.py

@@ -0,0 +1,150 @@
+import logging
+import pandas as pd
+from typing import Optional, List, Union, Tuple
+import plotly.graph_objects as go
+
+from .thresholds import Threshold, get_ppdc_sea_level_thresholds
+from .plotting import AxisConfig, plot_base_series
+from .client import NPHClient
+
+logger = logging.getLogger(__name__)
+
+
+def plot_nivel_mar(
+    df: Optional[pd.DataFrame] = None,
+    stations: Optional[Union[List[Union[str, int]], str, int]] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    api_key: Optional[str] = None,
+    client: Optional[NPHClient] = None,
+    columns: Optional[List[str]] = None,
+    title: str = "Nível do Mar - PPDC Ressacas (NPH-UNISANTA)",
+    thresholds: Optional[List[Threshold]] = None,
+    show_thresholds: bool = True,
+    show_peaks: bool = True,
+    figsize: Tuple[int, int] = (12, 6),
+    save_path: Optional[str] = None
+) -> go.Figure:
+    if df is None:
+        cli = client or NPHClient(api_key=api_key)
+        df = cli.get_measurements(stations=stations, start_date=start_date, end_date=end_date)
+        if df.empty:
+            df = cli.get_forecasts(stations=stations, start_date=start_date, end_date=end_date, param_id="Nível do Mar")
+
+    if df.empty:
+        raise ValueError("Nenhum dado encontrado para gerar o gráfico de Nível do Mar.")
+
+    if not show_thresholds:
+        thresholds_to_use = []
+    elif thresholds is not None:
+        thresholds_to_use = thresholds
+    else:
+        thresholds_to_use = get_ppdc_sea_level_thresholds()
+
+    primary_conf = AxisConfig(
+        label="Nível do Mar (m)",
+        columns=columns,
+        plot_type='line',
+        show_peaks=show_peaks,
+        thresholds=thresholds_to_use,
+        color_palette='Ocean'
+    )
+
+    return plot_base_series(
+        df=df,
+        primary_conf=primary_conf,
+        title=title,
+        figsize=figsize,
+        save_path=save_path
+    )
+
+
+def plot_chuva(
+    df: Optional[pd.DataFrame] = None,
+    stations: Optional[Union[List[Union[str, int]], str, int]] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    api_key: Optional[str] = None,
+    client: Optional[NPHClient] = None,
+    columns: Optional[List[str]] = None,
+    title: str = "Precipitação Pluviométrica (NPH-UNISANTA)",
+    figsize: Tuple[int, int] = (12, 6),
+    save_path: Optional[str] = None
+) -> go.Figure:
+    if df is None:
+        cli = client or NPHClient(api_key=api_key)
+        df = cli.get_measurements(stations=stations, start_date=start_date, end_date=end_date)
+        if df.empty:
+            df = cli.get_forecasts(stations=stations, start_date=start_date, end_date=end_date, param_id="Precipitação")
+
+    if df.empty:
+        raise ValueError("Nenhum dado encontrado para gerar o gráfico de Chuva.")
+
+    primary_conf = AxisConfig(
+        label="Precipitação (mm)",
+        columns=columns,
+        plot_type='bar',
+        custom_colors=['#1f77b4', '#0096c7', '#03045e'],
+        plot_kwargs={'alpha': 0.8, 'width': 0.04}
+    )
+
+    return plot_base_series(
+        df=df,
+        primary_conf=primary_conf,
+        title=title,
+        figsize=figsize,
+        save_path=save_path
+    )
+
+
+def plot_nivel_e_chuva(
+    df_nivel: pd.DataFrame,
+    df_chuva: pd.DataFrame,
+    title: str = "Hidrograma: Nível do Mar e Precipitação (NPH-UNISANTA)",
+    level_columns: Optional[List[str]] = None,
+    precip_columns: Optional[List[str]] = None,
+    thresholds: Optional[List[Threshold]] = None,
+    show_thresholds: bool = True,
+    show_peaks: bool = True,
+    invert_rain_axis: bool = True,
+    figsize: Tuple[int, int] = (12, 6),
+    save_path: Optional[str] = None
+) -> go.Figure:
+    if df_nivel.empty:
+        raise ValueError("O DataFrame de nível do mar está vazio.")
+    if df_chuva.empty:
+        raise ValueError("O DataFrame de chuva está vazio.")
+
+    if not show_thresholds:
+        thresholds_to_use = []
+    elif thresholds is not None:
+        thresholds_to_use = thresholds
+    else:
+        thresholds_to_use = get_ppdc_sea_level_thresholds()
+
+    primary_conf = AxisConfig(
+        label="Nível do Mar (m)",
+        columns=level_columns,
+        plot_type='line',
+        show_peaks=show_peaks,
+        thresholds=thresholds_to_use,
+        color_palette='Ocean'
+    )
+
+    secondary_conf = AxisConfig(
+        label="Precipitação (mm)",
+        columns=precip_columns,
+        plot_type='bar',
+        invert_yaxis=invert_rain_axis,
+        custom_colors=['#2b5c8f', '#4682b4'],
+        plot_kwargs={'alpha': 0.65, 'width': 0.04}
+    )
+
+    return plot_base_series(
+        df=[df_nivel, df_chuva],
+        primary_conf=primary_conf,
+        secondary_conf=secondary_conf,
+        title=title,
+        figsize=figsize,
+        save_path=save_path
+    )

nph_client-0.1.2/src/nph_client/client.py

@@ -0,0 +1,257 @@
+import logging
+import requests
+import pandas as pd
+import time
+from datetime import date, datetime, timedelta
+from dateutil.relativedelta import relativedelta
+from typing import List, Dict, Union, Optional, Any
+
+logger = logging.getLogger(__name__)
+
+_STATION_COLUMNS = [
+    "id", "station_prefix_id", "station_prefix", "station_name",
+    "latitude", "longitude", "station_type", "city_name",
+    "station_owner", "station_operator", "ugrhi_name",
+    "subugrhi_name", "station_status"
+]
+
+_STATION_RENAME_MAP = {
+    "station_prefix_id": "id_sibh",
+    "station_prefix": "prefixo",
+    "station_name": "nome_da_estacao",
+    "latitude": "latitude",
+    "longitude": "longitude",
+    "station_type": "tipo_da_estacao",
+    "city_name": "cidade",
+    "station_owner": "proprietario",
+    "station_operator": "operador",
+    "ugrhi_name": "ugrhi",
+    "sub_ugrhi_name": "sub_ugrhi",
+    "station_status": "status"
+}
+
+MODELS_GLOSSARY = {
+    "WRF 3km": 1,
+    "WRF 1km": 2,
+    "ECMWF 9km": 3,
+    "WRF 7km": 13,
+    "GFS 25km": 15,
+    "MOHID": 4,
+    "Delft - FLOW (BAIXADA)": 5,
+    "Delft - WAVE (BAIXADA)": 6,
+    "Delft - FLOW (SESSV)": 7,
+    "Delft - WAVE (SESSV)": 8,
+    "SWAN v1": 9,
+    "SWAN v2": 10,
+    "CMS - Hydro Hourly": 11,
+    "CMS - Wave": 12,
+    "NALA 10min": 17,
+    "NALA 1h": 18,
+    "NALA 3h": 19,
+    "NALA Best": 20
+}
+
+PARAMS_GLOSSARY = {
+    "Temperatura": 1,
+    "Precipitação": 2,
+    "Pressão": 3,
+    "Rajada de Vento": 4,
+    "Velocidade do Vento": 5,
+    "Direção do Vento": 6,
+    "CAPE": 7,
+    "LIFT": 8,
+    "Umidade Relativa": 9,
+    "Cobertura Total de Nuvens": 10,
+    "Ponto de Orvalho": 11,
+    "Precipitação Convectiva": 12,
+    "Nível do Mar": 13,
+    "Direção da Corrente": 14,
+    "Velocidade da Corrente": 15,
+    "Altura Significativa das Ondas (Hs)": 16,
+    "Direção média das ondas": 17,
+    "Período de Pico (Tp)": 18,
+    "Direção de Pico das Ondas": 19
+}
+
+
+class NPHClient:
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key
+        self.base_url = 'https://nph.unisanta.br/ssbs/api'
+
+    def _get_headers(self) -> Dict[str, str]:
+        return {
+            'apiKey': self.api_key or '',
+            'Content-Type': 'application/json'
+        }
+
+    @staticmethod
+    def _resolve_value_col(status: int) -> str:
+        if status == 0:
+            return 'primary_value'
+        elif status == 1:
+            return 'secondary_value'
+        elif status == 2:
+            return 'extra_values'
+        else:
+            return 'primary_value'
+
+    def _fetch_paginated_data(
+        self,
+        url: str,
+        start_dt: Optional[Union[datetime, bool]] = None,
+        end_dt: Optional[Union[datetime, bool]] = None,
+        base_params: Optional[Dict[str, Any]] = None
+    ) -> pd.DataFrame:
+        base_params = base_params or {}
+
+        if not start_dt or not end_dt:
+            try:
+                response = requests.get(url=url, headers=self._get_headers(), params=base_params)
+                response.raise_for_status()
+                data = response.json()
+                return pd.DataFrame(data) if data else pd.DataFrame()
+            except Exception as e:
+                logger.error(f"Erro ao buscar dados: {e}")
+                return pd.DataFrame()
+
+        all_dataframes = []
+        current_start = start_dt
+
+        while current_start < end_dt:
+            chunk_end = min(current_start + relativedelta(years=1), end_dt)
+            params = base_params.copy()
+            params['startDate'] = current_start.strftime('%Y-%m-%d %H:%M:%S')
+            params['endDate'] = chunk_end.strftime('%Y-%m-%d %H:%M:%S')
+
+            try:
+                response = requests.get(url=url, headers=self._get_headers(), params=params)
+                response.raise_for_status()
+                data = response.json()
+                if data:
+                    all_dataframes.append(pd.DataFrame(data))
+            except Exception as e:
+                logger.error(f"Erro ao buscar intervalo {params['startDate']}: {e}")
+                break
+
+            current_start = chunk_end
+            if current_start < end_dt:
+                time.sleep(0.05)
+
+        if not all_dataframes:
+            return pd.DataFrame()
+
+        return pd.concat(all_dataframes, ignore_index=True)
+
+    def get_stations(self) -> pd.DataFrame:
+        url = f"{self.base_url}/stations"
+        try:
+            response = requests.get(url=url, headers=self._get_headers())
+            response.raise_for_status()
+            data = response.json()
+            if not data:
+                return pd.DataFrame()
+
+            df = pd.DataFrame(data)
+            cols_to_keep = [c for c in _STATION_COLUMNS if c in df.columns]
+            return df[cols_to_keep].set_index('id').rename(columns=_STATION_RENAME_MAP)
+        except Exception as e:
+            logger.error(f"Erro ao buscar estações: {e}")
+            return pd.DataFrame()
+
+    def get_measurements(
+        self,
+        stations: Optional[Union[List[Union[str, int]], str, int]] = None,
+        start_date: Optional[Union[str, date]] = None,
+        end_date: Optional[Union[str, datetime]] = None,
+        return_value: int = 0,
+        time_offset: Optional[timedelta] = timedelta(hours=-3)
+    ) -> pd.DataFrame:
+        start_dt = pd.to_datetime(start_date or (date.today() - timedelta(days=7)))
+        end_dt = pd.to_datetime(end_date or datetime.now())
+
+        base_params = {}
+        if stations:
+            if isinstance(stations, (str, int)):
+                base_params['stationId'] = str(stations)
+            elif isinstance(stations, list):
+                base_params['stationId'] = ','.join(map(str, stations))
+
+        df = self._fetch_paginated_data(
+            url=f"{self.base_url}/measurements",
+            start_dt=start_dt,
+            end_dt=end_dt,
+            base_params=base_params
+        )
+
+        if df.empty:
+            return df
+
+        try:
+            df['datetime'] = pd.to_datetime(df['datetime'])
+            value_col = self._resolve_value_col(return_value)
+
+            if time_offset:
+                df['datetime'] = df['datetime'] + time_offset
+
+            col_name = 'station_name' if 'station_name' in df.columns else 'station_id'
+            df_pivot = df.pivot_table(index='datetime', columns=col_name, values=value_col, aggfunc='mean')
+            df_pivot = df_pivot.sort_index()
+            return df_pivot
+        except Exception as e:
+            logger.error(f"Erro ao processar medições: {e}")
+            return pd.DataFrame()
+
+    def get_forecasts(
+        self,
+        stations: Optional[Union[List[Union[str, int]], str, int]] = None,
+        start_date: Optional[Union[str, date]] = None,
+        end_date: Optional[Union[str, datetime]] = None,
+        model_id: Union[int, str] = 1,
+        param_id: Union[int, str] = "Nível do Mar",
+        time_offset: Optional[timedelta] = timedelta(hours=-3)
+    ) -> pd.DataFrame:
+        start_dt = pd.to_datetime(start_date or (date.today() - timedelta(days=7)))
+        end_dt = pd.to_datetime(end_date or (datetime.now() + timedelta(days=3)))
+
+        if isinstance(model_id, str):
+            model_id = MODELS_GLOSSARY.get(model_id, 1)
+
+        if isinstance(param_id, str):
+            param_id = PARAMS_GLOSSARY.get(param_id, 13)
+
+        base_params = {
+            'modelId': str(model_id),
+            'parameterId': str(param_id)
+        }
+
+        if stations:
+            if isinstance(stations, (str, int)):
+                base_params['stationId'] = str(stations)
+            elif isinstance(stations, list):
+                base_params['stationId'] = ','.join(map(str, stations))
+
+        df = self._fetch_paginated_data(
+            url=f"{self.base_url}/forecasts",
+            start_dt=start_dt,
+            end_dt=end_dt,
+            base_params=base_params
+        )
+
+        if df.empty:
+            return df
+
+        try:
+            df['datetime'] = pd.to_datetime(df['datetime'])
+            if time_offset:
+                df['datetime'] = df['datetime'] + time_offset
+
+            col_name = 'station_name' if 'station_name' in df.columns else 'station_id'
+            value_col = 'value' if 'value' in df.columns else df.columns[-1]
+            df_pivot = df.pivot_table(index='datetime', columns=col_name, values=value_col, aggfunc='mean')
+            df_pivot = df_pivot.sort_index()
+            return df_pivot
+        except Exception as e:
+            logger.error(f"Erro ao processar previsões: {e}")
+            return pd.DataFrame()

nph_client-0.1.2/src/nph_client/plotting.py

@@ -0,0 +1,309 @@
+import logging
+import pandas as pd
+import numpy as np
+from typing import List, Optional, Tuple, Dict, Any, Literal, Union
+from dataclasses import dataclass, field
+import plotly.graph_objects as go
+from plotly.subplots import make_subplots
+import plotly.colors as pcolors
+
+from .thresholds import Threshold
+
+logger = logging.getLogger(__name__)
+
+LINESTYLE_MAP = {
+    '-': 'solid',
+    '--': 'dash',
+    ':': 'dot',
+    '-.': 'dashdot'
+}
+
+PALETTE_MAP = {
+    'tab10': pcolors.qualitative.T10,
+    'Set1': pcolors.qualitative.Set1,
+    'Dark2': pcolors.qualitative.Dark2,
+    'Plotly': pcolors.qualitative.Plotly,
+    'Ocean': ['#0077b6', '#00b4d8', '#90e0ef', '#03045e', '#0096c7']
+}
+
+
+@dataclass
+class AxisConfig:
+    label: str = "Valor"
+    columns: Optional[List[str]] = None
+    plot_type: Literal['line', 'scatter', 'bar', 'area'] = 'line'
+    min_val: Optional[float] = None
+    max_val: Optional[float] = None
+    step: Optional[float] = None
+    show_peaks: bool = False
+    color_palette: str = 'tab10'
+    invert_yaxis: bool = False
+    custom_colors: Optional[List[str]] = None
+    plot_kwargs: Dict[str, Any] = field(default_factory=dict)
+    thresholds: List[Threshold] = field(default_factory=list)
+
+
+def get_palette_colors(palette_name: str) -> List[str]:
+    return PALETTE_MAP.get(palette_name, pcolors.qualitative.T10)
+
+
+def hex_to_rgba(hex_str: str, alpha: float) -> str:
+    try:
+        hex_str = hex_str.lstrip('#')
+        if len(hex_str) == 3:
+            hex_str = ''.join([c * 2 for c in hex_str])
+        r, g, b = (int(hex_str[i:i+2], 16) for i in (0, 2, 4))
+        return f"rgba({r}, {g}, {b}, {alpha})"
+    except Exception:
+        return f"rgba(31, 119, 180, {alpha})"
+
+
+def annotate_peaks(fig: go.Figure, series: pd.Series, color: str, secondary_y: bool):
+    clean_series = series.dropna()
+    if clean_series.empty:
+        return
+
+    max_val = clean_series.max()
+    max_date = clean_series.idxmax()
+    max_date_str = max_date.isoformat() if hasattr(max_date, 'isoformat') else str(max_date)
+
+    min_val = clean_series.min()
+    min_date = clean_series.idxmin()
+    min_date_str = min_date.isoformat() if hasattr(min_date, 'isoformat') else str(min_date)
+
+    fig.add_trace(
+        go.Scatter(
+            x=[max_date_str],
+            y=[max_val],
+            mode='markers+text',
+            marker=dict(color=color, size=10, line=dict(color='black', width=1.5)),
+            text=[f"Máx: {max_val:.2f}"],
+            textposition="top center",
+            textfont=dict(color='black', size=11, family="Arial"),
+            showlegend=False,
+            hoverinfo='skip'
+        ),
+        secondary_y=secondary_y
+    )
+
+    if min_date != max_date:
+        fig.add_trace(
+            go.Scatter(
+                x=[min_date_str],
+                y=[min_val],
+                mode='markers+text',
+                marker=dict(color=color, size=9, line=dict(color='black', width=1)),
+                text=[f"Mín: {min_val:.2f}"],
+                textposition="bottom center",
+                textfont=dict(color='#555555', size=10, family="Arial"),
+                showlegend=False,
+                hoverinfo='skip'
+            ),
+            secondary_y=secondary_y
+        )
+
+
+def draw_thresholds(fig: go.Figure, config: AxisConfig, secondary_y: bool, y_range: Tuple[float, float]):
+    yref = 'y2' if secondary_y else 'y'
+    y_min, y_max = y_range
+
+    for t in config.thresholds:
+        dash_style = LINESTYLE_MAP.get(t.linestyle, 'dash')
+
+        fig.add_hline(
+            y=t.value,
+            line=dict(color=t.color, width=1.8, dash=dash_style),
+            annotation_text=f" <b>{t.label}</b> ({t.value:.2f}m)",
+            annotation_position="top left",
+            annotation_font=dict(color=t.color, size=11, family="Arial"),
+            yref=yref
+        )
+
+        y0 = t.value if t.fill_above else y_min
+        y1 = (t.max_fill_value if t.max_fill_value is not None else y_max) if t.fill_above else t.value
+
+        fig.add_hrect(
+            y0=y0,
+            y1=y1,
+            fillcolor=t.color,
+            opacity=t.alpha,
+            layer="below",
+            line_width=0,
+            yref=yref
+        )
+
+
+def add_traces(fig: go.Figure, df: pd.DataFrame, config: AxisConfig, secondary_y: bool):
+    cols_to_plot = config.columns if config.columns else df.columns
+    colors = config.custom_colors or get_palette_colors(config.color_palette)
+
+    for i, col in enumerate(cols_to_plot):
+        if col not in df.columns:
+            logger.warning(f"Coluna '{col}' não encontrada no DataFrame.")
+            continue
+
+        color = colors[i % len(colors)]
+        clean_kwargs = {k: v for k, v in config.plot_kwargs.items() if k not in ['alpha', 'width', 'dash', 'size']}
+
+        hovertemplate = (
+            f"<b>{col}</b><br>"
+            "<b>Data/Hora:</b> %{x|%d/%m/%Y %H:%M}<br>"
+            f"<b>{config.label}:</b> %{{y:.2f}}<extra></extra>"
+        )
+
+        if config.plot_type == 'bar':
+            opacity = config.plot_kwargs.get('alpha', 0.75)
+            bar_width = None
+            if 'width' in config.plot_kwargs:
+                w = config.plot_kwargs['width']
+                bar_width = w * 86400000 if isinstance(df.index, pd.DatetimeIndex) else w
+
+            trace = go.Bar(
+                x=df.index,
+                y=df[col],
+                name=f"{col} (Chuva)",
+                marker_color=color,
+                opacity=opacity,
+                width=bar_width,
+                hovertemplate=hovertemplate,
+                **clean_kwargs
+            )
+        elif config.plot_type == 'scatter':
+            marker_size = config.plot_kwargs.get('size', 8)
+            trace = go.Scatter(
+                x=df.index,
+                y=df[col],
+                name=col,
+                mode='markers',
+                marker=dict(color=color, size=marker_size),
+                hovertemplate=hovertemplate,
+                **clean_kwargs
+            )
+        else:
+            line_dict = dict(color=color, width=2.5)
+            if 'dash' in config.plot_kwargs:
+                line_dict['dash'] = config.plot_kwargs['dash']
+            trace = go.Scatter(
+                x=df.index,
+                y=df[col],
+                name=col,
+                mode='lines',
+                line=line_dict,
+                hovertemplate=hovertemplate,
+                **clean_kwargs
+            )
+
+        fig.add_trace(trace, secondary_y=secondary_y)
+
+        if config.show_peaks and config.plot_type != 'bar':
+            annotate_peaks(fig, df[col], color, secondary_y)
+
+
+def plot_base_series(
+    df: Union[pd.DataFrame, List[pd.DataFrame]],
+    primary_conf: AxisConfig,
+    secondary_conf: Optional[AxisConfig] = None,
+    title: str = "Série Temporal NPH",
+    figsize: Tuple[int, int] = (12, 6),
+    save_path: Optional[str] = None
+) -> go.Figure:
+    fig = make_subplots(specs=[[{"secondary_y": True}]])
+
+    if isinstance(df, list):
+        df_primary = df[0]
+        df_secondary = df[1] if len(df) > 1 else df[0]
+    else:
+        df_primary = df
+        df_secondary = df
+
+    add_traces(fig, df_primary, primary_conf, secondary_y=False)
+
+    if secondary_conf:
+        add_traces(fig, df_secondary, secondary_conf, secondary_y=True)
+
+    primary_cols = [c for c in (primary_conf.columns or df_primary.columns) if c in df_primary.columns]
+
+    if primary_cols and not df_primary[primary_cols].empty:
+        p_min = df_primary[primary_cols].min().min()
+        p_max = df_primary[primary_cols].max().max()
+        p_min, p_max = (0.0, 1.0) if pd.isna(p_min) or pd.isna(p_max) else (p_min, p_max)
+    else:
+        p_min, p_max = 0.0, 1.0
+
+    all_p_vals = [p_min, p_max] + [t.value for t in primary_conf.thresholds]
+    y1_min_val, y1_max_val = min(all_p_vals), max(all_p_vals)
+    pad1 = (y1_max_val - y1_min_val) * 0.15 if y1_max_val != y1_min_val else 1.0
+
+    y1_min = primary_conf.min_val if primary_conf.min_val is not None else y1_min_val - pad1
+    y1_max = primary_conf.max_val if primary_conf.max_val is not None else y1_max_val + pad1
+    y1_range = (y1_min, y1_max)
+
+    y1_layout = dict(
+        title=dict(text=primary_conf.label, font=dict(family="Arial", size=13, color="#111111")),
+        gridcolor="rgba(200, 200, 200, 0.25)",
+        showgrid=True,
+        range=[y1_max, y1_min] if primary_conf.invert_yaxis else [y1_min, y1_max]
+    )
+
+    y2_range = (0.0, 10.0)
+    y2_layout = dict(showgrid=False)
+
+    if secondary_conf:
+        scols = [c for c in (secondary_conf.columns or df_secondary.columns) if c in df_secondary.columns]
+        if scols and not df_secondary[scols].empty:
+            s_min = df_secondary[scols].min().min()
+            s_max = df_secondary[scols].max().max()
+            s_min, s_max = (0.0, 10.0) if pd.isna(s_min) or pd.isna(s_max) else (s_min, s_max)
+        else:
+            s_min, s_max = 0.0, 10.0
+
+        y2_min = secondary_conf.min_val if secondary_conf.min_val is not None else 0.0
+        y2_max = secondary_conf.max_val if secondary_conf.max_val is not None else max(s_max * 2.5, 10.0)
+        y2_range = (y2_min, y2_max)
+
+        y2_layout.update(dict(
+            title=dict(text=secondary_conf.label, font=dict(family="Arial", size=13, color="#111111")),
+            range=[y2_max, y2_min] if secondary_conf.invert_yaxis else [y2_min, y2_max]
+        ))
+
+    if primary_conf.thresholds:
+        draw_thresholds(fig, primary_conf, secondary_y=False, y_range=y1_range)
+    if secondary_conf and secondary_conf.thresholds:
+        draw_thresholds(fig, secondary_conf, secondary_y=True, y_range=y2_range)
+
+    fig.update_layout(
+        title=dict(text=f"<b>{title}</b>", x=0.5, xanchor='center', font=dict(family="Arial", size=16)),
+        xaxis=dict(
+            title=dict(text="Data / Hora", font=dict(family="Arial", size=12)),
+            gridcolor="rgba(200, 200, 200, 0.25)",
+            showgrid=True
+        ),
+        yaxis=y1_layout,
+        yaxis2=y2_layout,
+        width=figsize[0] * 80,
+        height=figsize[1] * 80,
+        plot_bgcolor='#ffffff',
+        paper_bgcolor='#ffffff',
+        showlegend=True,
+        legend=dict(
+            orientation="h",
+            yanchor="bottom",
+            y=1.02,
+            xanchor="center",
+            x=0.5
+        ),
+        hovermode="x unified",
+        margin=dict(l=60, r=60, t=90, b=60)
+    )
+
+    if save_path:
+        try:
+            if save_path.endswith('.html'):
+                fig.write_html(save_path)
+            else:
+                fig.write_image(save_path)
+            logger.info(f"Gráfico salvo em {save_path}")
+        except Exception as e:
+            logger.error(f"Erro ao salvar gráfico em {save_path}: {e}")
+
+    return fig

nph_client-0.1.2/src/nph_client/thresholds.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+@dataclass
+class Threshold:
+    value: float
+    color: str
+    label: str
+    fill_above: bool = True
+    max_fill_value: Optional[float] = None
+    alpha: float = 0.12
+    linestyle: str = '--'
+
+
+PPDC_THRESHOLD_ATENCAO = Threshold(
+    value=1.8,
+    color="#f39c12",
+    label="ATENÇÃO",
+    fill_above=True,
+    max_fill_value=2.0,
+    alpha=0.15,
+    linestyle="--"
+)
+
+PPDC_THRESHOLD_ALERTA = Threshold(
+    value=2.0,
+    color="#e74c3c",
+    label="ALERTA",
+    fill_above=True,
+    max_fill_value=None,
+    alpha=0.20,
+    linestyle="--"
+)
+
+def get_ppdc_sea_level_thresholds() -> List[Threshold]:
+    return [PPDC_THRESHOLD_ATENCAO, PPDC_THRESHOLD_ALERTA]

nph_client-0.1.2/src/nph_client.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: nph-client
+Version: 0.1.2
+Summary: Biblioteca de visualização de dados oceanográficos e meteorológicos do NPH-UNISANTA.
+Author: NPH UNISANTA
+Keywords: nph,nph-client,oceanografia,meteorologia,plotly,graficos,nivel-do-mar,chuva,unisanta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: plotly>=5.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: python-dateutil>=2.8.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: nbformat>=4.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: kaleido>=0.2.1; extra == "dev"
+
+# nph-client 🌊
+
+Biblioteca em Python para geração padronizada e simplificada de gráficos oceanográficos e meteorológicos do **NPH-UNISANTA** (Núcleo de Pesquisas Hidrodinâmicas da Unisanta).
+
+## Instalação
+
+```bash
+pip install nph-client
+```
+
+## Principais Funções
+
+### 1. Nível do Mar (`plot_nivel_mar`)
+Plota o gráfico de linha de nível do mar com picos destacados e limiares do **PPDC Ressacas**:
+- **OBSERVAÇÃO**: `< 1.8m`
+- **ATENÇÃO**: `1.8m a 2.0m`
+- **ALERTA**: `≥ 2.0m`
+
+```python
+from nph_client import NPHClient, plot_nivel_mar
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_nivel = client.get_measurements(stations=349, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_nivel_mar(df=df_nivel, title="Nível do Mar - Santos")
+fig.show()
+```
+
+> **Dica**: Para ocultar as linhas e faixas dos limiares PPDC, passe `show_thresholds=False`.
+
+---
+
+### 2. Precipitação Pluviométrica / Chuva (`plot_chuva`)
+Plota o gráfico de barras para chuva (mm):
+
+```python
+from nph_client import NPHClient, plot_chuva
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_chuva = client.get_measurements(stations=26, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_chuva(df=df_chuva, title="Precipitação Pluviométrica - Portão 40")
+fig.show()
+```
+
+---
+
+### 3. Hidrograma Combinado (`plot_nivel_e_chuva`)
+Reúne Nível do Mar e Chuva no mesmo gráfico com eixo secundário:
+
+```python
+from nph_client import NPHClient, plot_nivel_e_chuva
+
+client = NPHClient(api_key="SUA_API_KEY")
+df_nivel = client.get_measurements(stations=349, start_date="2026-08-05", end_date="2026-08-07")
+df_chuva = client.get_measurements(stations=26, start_date="2026-08-05", end_date="2026-08-07")
+
+fig = plot_nivel_e_chuva(df_nivel=df_nivel, df_chuva=df_chuva, title="Hidrograma")
+fig.show()
+```
+
+## Requisitos
+- `pandas`
+- `plotly`
+- `requests`
+- `python-dateutil`
+- `numpy`
+- `nbformat`
+
+## Licença
+Licenciado sob a licença MIT.

nph_client-0.1.2/src/nph_client.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/nph_client/__init__.py
+src/nph_client/charts.py
+src/nph_client/client.py
+src/nph_client/plotting.py
+src/nph_client/thresholds.py
+src/nph_client.egg-info/PKG-INFO
+src/nph_client.egg-info/SOURCES.txt
+src/nph_client.egg-info/dependency_links.txt
+src/nph_client.egg-info/requires.txt
+src/nph_client.egg-info/top_level.txt
+tests/test_graficos.py

nph_client-0.1.2/src/nph_client.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nph_client-0.1.2/src/nph_client.egg-info/requires.txt

@@ -0,0 +1,10 @@
+pandas>=1.5.0
+plotly>=5.0.0
+requests>=2.25.0
+python-dateutil>=2.8.0
+numpy>=1.20.0
+nbformat>=4.2.0
+
+[dev]
+pytest>=7.0.0
+kaleido>=0.2.1

nph_client-0.1.2/src/nph_client.egg-info/top_level.txt

@@ -0,0 +1 @@
+nph_client

nph_client-0.1.2/tests/test_graficos.py

@@ -0,0 +1,64 @@
+import unittest
+import pandas as pd
+import numpy as np
+import plotly.graph_objects as go
+
+from nph_client import (
+    plot_nivel_mar,
+    plot_chuva,
+    plot_nivel_e_chuva,
+    get_ppdc_sea_level_thresholds,
+    NPHClient
+)
+
+
+class TestNPHClient(unittest.TestCase):
+
+    def setUp(self):
+        dates = pd.date_range(start="2026-08-01", periods=48, freq="h")
+        np.random.seed(42)
+
+        nivel = 1.6 + 0.5 * np.sin(np.linspace(0, 4 * np.pi, 48)) + np.random.normal(0, 0.1, 48)
+        self.df_nivel = pd.DataFrame({"Praticagem de Santos": nivel}, index=dates)
+
+        chuva = np.random.exponential(scale=2.0, size=48)
+        self.df_chuva = pd.DataFrame({"Portão 40": chuva}, index=dates)
+
+    def test_plot_nivel_mar(self):
+        fig = plot_nivel_mar(self.df_nivel, title="Nível do Mar")
+        self.assertIsInstance(fig, go.Figure)
+        self.assertEqual(fig.layout.title.text, "<b>Nível do Mar</b>")
+
+    def test_plot_nivel_mar_opcoes(self):
+        fig = plot_nivel_mar(self.df_nivel, show_thresholds=False, show_peaks=False)
+        self.assertIsInstance(fig, go.Figure)
+
+    def test_plot_chuva(self):
+        fig = plot_chuva(self.df_chuva, title="Precipitação")
+        self.assertIsInstance(fig, go.Figure)
+        self.assertEqual(fig.layout.title.text, "<b>Precipitação</b>")
+
+    def test_plot_nivel_e_chuva(self):
+        fig = plot_nivel_e_chuva(self.df_nivel, self.df_chuva, title="Hidrograma")
+        self.assertIsInstance(fig, go.Figure)
+        self.assertEqual(fig.layout.title.text, "<b>Hidrograma</b>")
+
+    def test_plot_nivel_e_chuva_sem_limiares(self):
+        fig = plot_nivel_e_chuva(self.df_nivel, self.df_chuva, show_thresholds=False)
+        self.assertIsInstance(fig, go.Figure)
+
+    def test_client_init(self):
+        client = NPHClient(api_key="teste_key")
+        self.assertEqual(client.api_key, "teste_key")
+
+    def test_ppdc_thresholds(self):
+        thresholds = get_ppdc_sea_level_thresholds()
+        self.assertEqual(len(thresholds), 2)
+        self.assertEqual(thresholds[0].value, 1.8)
+        self.assertEqual(thresholds[0].label, "ATENÇÃO")
+        self.assertEqual(thresholds[1].value, 2.0)
+        self.assertEqual(thresholds[1].label, "ALERTA")
+
+
+if __name__ == "__main__":
+    unittest.main()