fix(http): replace http by web for better naming and include a preview of the web service on home page (#299)

Author: luabida

README.md

@@ -23,7 +23,7 @@ pip install pysus
 
 For the local Streamlit web interface:
 ```bash
-pip install pysus[http]
+pip install pysus[web]
 ```
 
 ### Docker
@@ -129,19 +129,19 @@ async def main():
 Launch the local web interface:
 
 ```bash
-pysus http
+pysus web
 ```
 
 Or with a custom port:
 
 ```bash
-pysus http -p 8080
+pysus web -p 8080
 ```
 
 Or run directly with Streamlit:
 
 ```bash
-streamlit run pysus/http/app.py
+streamlit run pysus/web/app.py
 ```
 
 The web interface provides three data sources:

docs/source/index.rst

@@ -20,6 +20,9 @@ PySUS is a Python package for accessing and analyzing Brazil's public health dat
 and work with health datasets including SINAN (disease notifications), SIM (mortality),
 SINASC (births), SIH (hospitalizations), SIA (ambulatory), CIHA, CNES, PNI, and more.
 
+A local web server (`pysus web`) is included for interactive browsing and downloading
+of datasets through a graphical Streamlit interface.
+
 This documentation covers PySUS 2.0+.
 
 .. toctree::

docs/source/installation.rst

@@ -60,6 +60,25 @@ Using Poetry:
 
    poetry install
 
+Web Interface
+-------------
+
+PySUS includes a local Streamlit-based web server for browsing and downloading
+datasets interactively. Start it with:
+
+.. code-block:: bash
+
+   pysus web
+
+Or directly:
+
+.. code-block:: bash
+
+   streamlit run pysus/web/app.py
+
+This opens a browser at ``http://localhost:8501`` with a graphical interface for
+querying PySUS s3, DATASUS FTP, and dados.gov.br sources.
+
 Configuration
 -------------
 

poetry.lock

@@ -12,7 +12,6 @@ exclude = [
   "pysus/tests/**",
   "pysus/management",
   "pysus/management/**",
-  "pysus/http/**",
 ]
 
 [tool.poetry.dependencies]
@@ -47,7 +46,7 @@ typer = "^0.24.1"
 humanize = "^4.8.0"
 
 [tool.poetry.extras]
-http = ["streamlit"]
+web = ["streamlit"]
 
 [tool.poetry.group.dev.dependencies]
 pytest = ">=6.1.0"
@@ -106,7 +105,7 @@ exclude = ["*.git", "docs/"]
 omit = [
     "pysus/management/client.py",
     "pysus/tui/*",
-    "pysus/http/*",
+    "pysus/web/*",
     "pysus/cli/*",
 ]
 

pyproject.toml

@@ -10,7 +10,7 @@ def version():
 
 
 @app.command()
-def http(
+def web(
     port: int = typer.Option(  # noqa: B008
         8501,
         "-p",
@@ -25,13 +25,13 @@ def http(
     except ImportError:
         raise ImportError(
             "The HTTP UI requires extra dependencies. "
-            "Install them with: pip install pysus[http]"
+            "Install them with: pip install pysus[web]"
         )
     import os
     import sys
     import webbrowser
 
-    app_path = os.path.join(os.path.dirname(__file__), "..", "http", "app.py")
+    app_path = os.path.join(os.path.dirname(__file__), "..", "web", "app.py")
     app_path = os.path.abspath(app_path)
 
     from streamlit.web import cli as stcli

pysus/cli/__init__.py

@@ -2,10 +2,8 @@
 from datetime import date
 from pathlib import Path
 
-import numpy as np
 import pandas as pd
 import pytest
-
 from pysus.data.dbf_reader import (
     _parse_header,
     read_dbf_fast,
@@ -14,7 +12,6 @@
     stream_dbf_fast,
 )
 
-
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
@@ -85,9 +82,7 @@ def simple_dbf(tmp_dir):
 def wide_dbf(tmp_dir):
     dbf_path = tmp_dir / "wide.dbf"
     fields = [(f"COL{i}", "C", 8, 0) for i in range(20)]
-    records = [
-        tuple(f"val{i}_{j}" for j in range(20)) for i in range(100)
-    ]
+    records = [tuple(f"val{i}_{j}" for j in range(20)) for i in range(100)]
     _create_dbf(dbf_path, fields, records)
     return dbf_path
 
@@ -200,7 +195,6 @@ def test_read_fast_wide(wide_dbf):
 def test_read_fast_strips_nul_bytes(tmp_dir):
     dbf_path = tmp_dir / "nuls.dbf"
     today = date.today()
-    fields = [("VAL", "C", 8, 0)]
     buf = bytearray()
     buf.append(0x03)
     buf.append(today.year - 1900)
@@ -289,15 +283,11 @@ def test_read_filtered_column_subset(disease_dbf):
 
 def test_read_filtered_missing_column(disease_dbf):
     with pytest.raises(KeyError, match="not found"):
-        read_dbf_filtered(
-            disease_dbf, column="NONEXISTENT", values=["X"]
-        )
+        read_dbf_filtered(disease_dbf, column="NONEXISTENT", values=["X"])
 
 
 def test_read_filtered_empty_file(empty_dbf):
-    df = read_dbf_filtered(
-        empty_dbf, column="NAME", values=["X"]
-    )
+    df = read_dbf_filtered(empty_dbf, column="NAME", values=["X"])
     assert len(df) == 0
 
 
@@ -378,9 +368,7 @@ def test_large_record_count(tmp_dir):
 
 
 def test_field_name_lowercase_match():
-    from pysus.data.dbf_reader import _find_field
-
-    from pysus.data.dbf_reader import DBFSchema, DBFField
+    from pysus.data.dbf_reader import DBFField, DBFSchema, _find_field
 
     schema = DBFSchema(
         num_records=1,

pysus/http/app.py

@@ -1,3 +1,3 @@
 """PySUS HTTP — Streamlit-based visual interface for localhost use."""
 
-from pysus.http.app import home  # noqa
+from pysus.web.app import home  # noqa