প্রজেক্ট, পর্ব ২: টেস্ট, ডকুমেন্টেশন ও প্রকাশ

mkdir -p ~/projects/data-explorer/app
cd ~/projects/data-explorer

# file: .gitignore
# Python
__pycache__/
*.pyc

# Virtual environment (rebuilt from uv.lock with `uv sync`)
.venv/

# Secrets and local settings
.env

# Logs from local runs
*.log

# file: app/schemas.py
"""The shapes of the data this API sends out and accepts from upstream."""
from typing import Literal

from pydantic import BaseModel, Field

Level = Literal["beginner", "intermediate", "advanced"]


class Course(BaseModel):
    id: int = Field(ge=1)
    title: str = Field(min_length=1)
    level: Level
    hours: int = Field(ge=0)
    rating: float = Field(ge=0, le=5)


class CourseList(BaseModel):
    count: int
    items: list[Course]


class LevelSummary(BaseModel):
    level: Level
    courses: int
    total_hours: int
    average_rating: float


class UpstreamWeather(BaseModel):
    """What the Practice API sends for /v1/weather (its names, not ours)."""
    city: str
    temp_c: float
    humidity: int
    condition: str


class Weather(BaseModel):
    city: str
    temperature_c: float
    humidity_pct: int = Field(ge=0, le=100)
    condition: str
    advice: str

# file: app/upstream.py
"""Everything that talks to the BitByte Practice API lives in this one file."""
import os

import requests
from pydantic import BaseModel, ValidationError

from app.schemas import Course, UpstreamWeather

BASE_URL = os.environ.get("PRACTICE_API_URL", "http://localhost:8800")
TIMEOUT_SECONDS = float(os.environ.get("UPSTREAM_TIMEOUT", "5"))
MAX_PAGES = 50

session = requests.Session()
session.headers["User-Agent"] = "bitbyte-data-explorer/0.1"


class UpstreamError(Exception):
    """The Practice API was unreachable, too slow, or sent something we cannot use."""

    def __init__(self, message: str, status_code: int = 502):
        super().__init__(message)
        self.message = message
        self.status_code = status_code


def get_json(path: str, params: dict | None = None) -> dict | None:
    """GET a Practice API path and return the JSON body, or None for a 404."""
    try:
        response = session.get(f"{BASE_URL}{path}", params=params, timeout=TIMEOUT_SECONDS)
    except requests.Timeout:
        raise UpstreamError(f"Practice API did not answer within {TIMEOUT_SECONDS:g} s", 504)
    except requests.ConnectionError:
        raise UpstreamError("Practice API is unreachable")
    if response.status_code == 404:
        return None
    if not response.ok:
        raise UpstreamError(f"Practice API failed with status {response.status_code}")
    try:
        return response.json()
    except ValueError:
        raise UpstreamError("Practice API sent a body that is not JSON")


def parse(model: type[BaseModel], data: dict):
    """Validate upstream data before we trust it."""
    try:
        return model.model_validate(data)
    except ValidationError:
        raise UpstreamError(f"Practice API sent {model.__name__} data in an unexpected shape")


def fetch_courses(level: str | None = None) -> list[Course]:
    """All courses (optionally of one level), following next_page to the end."""
    courses, page = [], 1
    while page is not None:
        if page > MAX_PAGES:
            raise UpstreamError("Practice API returned too many pages")
        data = get_json("/v1/courses", {"level": level, "page": page, "per_page": 20})
        if data is None:
            raise UpstreamError("Practice API has no /v1/courses endpoint")
        courses += [parse(Course, item) for item in data["items"]]
        page = data["next_page"]
    return courses


def fetch_course(course_id: int) -> Course | None:
    data = get_json(f"/v1/courses/{course_id}")
    return None if data is None else parse(Course, data)


def fetch_weather(city: str) -> UpstreamWeather | None:
    data = get_json("/v1/weather", {"city": city})
    return None if data is None else parse(UpstreamWeather, data)

# file: app/main.py
"""BitByte Data Explorer API: clean, validated endpoints over the BitByte Practice API."""
from typing import Annotated, Literal

from fastapi import FastAPI, HTTPException, Path, Query, Request
from fastapi.responses import JSONResponse

from app import upstream
from app.schemas import Course, CourseList, Level, LevelSummary, Weather

app = FastAPI(title="BitByte Data Explorer API", version="0.1.0")


@app.exception_handler(upstream.UpstreamError)
def upstream_failed(request: Request, exc: upstream.UpstreamError) -> JSONResponse:
    return JSONResponse({"detail": exc.message}, status_code=exc.status_code)


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/courses")
def list_courses(
    level: Level | None = None,
    min_rating: Annotated[float, Query(ge=0, le=5)] = 0,
    sort: Literal["id", "rating", "hours"] = "id",
) -> CourseList:
    courses = [c for c in upstream.fetch_courses(level) if c.rating >= min_rating]
    courses.sort(key=lambda c: getattr(c, sort), reverse=sort != "id")
    return CourseList(count=len(courses), items=courses)


@app.get("/courses/{course_id}")
def get_course(course_id: Annotated[int, Path(ge=1)]) -> Course:
    course = upstream.fetch_course(course_id)
    if course is None:
        raise HTTPException(404, f"Course {course_id} not found")
    return course


@app.get("/summary")
def summary() -> list[LevelSummary]:
    by_level: dict[str, list[Course]] = {}
    for course in upstream.fetch_courses():
        by_level.setdefault(course.level, []).append(course)
    return [
        LevelSummary(
            level=level,
            courses=len(group),
            total_hours=sum(c.hours for c in group),
            average_rating=round(sum(c.rating for c in group) / len(group), 2),
        )
        for level, group in by_level.items()
    ]


def advice_for(temp_c: float, condition: str) -> str:
    if condition == "Rain":
        return "Carry an umbrella."
    if temp_c >= 30:
        return "Hot day: drink water and avoid the midday sun."
    return "Good weather to go out."


@app.get("/weather/{city}")
def weather(city: Annotated[str, Path(min_length=2, max_length=40)]) -> Weather:
    data = upstream.fetch_weather(city)
    if data is None:
        raise HTTPException(404, f"No weather data for {city}")
    return Weather(
        city=data.city,
        temperature_c=data.temp_c,
        humidity_pct=data.humidity,
        condition=data.condition,
        advice=advice_for(data.temp_c, data.condition),
    )

git init -q
uv init -q --bare --name data-explorer
uv add -q "fastapi[standard]" requests
cat >> pyproject.toml <<'EOF'

[tool.fastapi]
entrypoint = "app.main:app"
EOF
touch app/__init__.py
git add .gitignore pyproject.toml uv.lock app/__init__.py
git commit -q -m "Set up the Data Explorer project with uv"
git switch -q -c feature/data-explorer
git add app/schemas.py
git commit -q -m "Add response and upstream schemas"
git add app/upstream.py
git commit -q -m "Add Practice API client with timeouts, pagination and validation"
git add app/main.py
git commit -q -m "Add courses, summary and weather endpoints"

git log --oneline --graph --decorate --all

* 3a8f75a (HEAD -> feature/data-explorer) Add courses, summary and weather endpoints
* 089f152 Add Practice API client with timeouts, pagination and validation
* 6bba991 Add response and upstream schemas
* 04b26f9 (main) Set up the Data Explorer project with uv

uv add -q --dev pytest httpx2
cat >> pyproject.toml <<'EOF'

[tool.pytest.ini_options]
pythonpath = ["."]
testpaths = ["tests"]
EOF
mkdir -p tests
cat pyproject.toml

[project]
name = "data-explorer"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]>=0.143.0",
    "requests>=2.34.2",
]

[tool.fastapi]
entrypoint = "app.main:app"

[dependency-groups]
dev = [
    "httpx2>=2.13.1",
    "pytest>=9.1.1",
]

[tool.pytest.ini_options]
pythonpath = ["."]
testpaths = ["tests"]

# file: tests/conftest.py
"""Shared fixtures: a test client and a fake upstream with fixed data."""
import pytest
from fastapi.testclient import TestClient

from app import upstream
from app.main import app
from app.schemas import Course, UpstreamWeather

FAKE_COURSES = [
    Course(id=1, title="Intro to AI", level="beginner", hours=4, rating=4.0),
    Course(id=2, title="Agents", level="advanced", hours=10, rating=4.9),
    Course(id=3, title="Python", level="beginner", hours=12, rating=4.6),
    Course(id=4, title="Prompting", level="intermediate", hours=5, rating=4.4),
]

FAKE_WEATHER = {
    "dhaka": UpstreamWeather(city="Dhaka", temp_c=31.5, humidity=78, condition="Humid"),
    "sylhet": UpstreamWeather(city="Sylhet", temp_c=27.4, humidity=85, condition="Rain"),
}


@pytest.fixture
def client():
    return TestClient(app)


@pytest.fixture
def fake_courses():
    return FAKE_COURSES


@pytest.fixture
def fake_upstream(monkeypatch):
    """Replace the upstream functions with fakes that never touch the network."""
    calls = []

    def fake_fetch_courses(level=None):
        calls.append(("courses", level))
        return [c for c in FAKE_COURSES if level is None or c.level == level]

    def fake_fetch_course(course_id):
        calls.append(("course", course_id))
        return next((c for c in FAKE_COURSES if c.id == course_id), None)

    def fake_fetch_weather(city):
        calls.append(("weather", city))
        return FAKE_WEATHER.get(city.lower())

    monkeypatch.setattr(upstream, "fetch_courses", fake_fetch_courses)
    monkeypatch.setattr(upstream, "fetch_course", fake_fetch_course)
    monkeypatch.setattr(upstream, "fetch_weather", fake_fetch_weather)
    return calls

# file: tests/test_api.py
"""Endpoint tests. The upstream is replaced by fakes (see conftest.py)."""
from app import upstream


def test_health(client):
    response = client.get("/health")
    assert response.status_code == 200
    assert response.json() == {"status": "ok"}


def test_courses_sorted_by_rating(client, fake_upstream):
    response = client.get("/courses", params={"sort": "rating"})
    assert response.status_code == 200
    body = response.json()
    assert body["count"] == 4
    assert [c["id"] for c in body["items"]] == [2, 3, 4, 1]


def test_courses_filters(client, fake_upstream):
    body = client.get("/courses", params={"level": "beginner", "min_rating": 4.5}).json()
    assert [c["title"] for c in body["items"]] == ["Python"]
    assert fake_upstream == [("courses", "beginner")]


def test_bad_parameters_never_reach_upstream(client, fake_upstream):
    assert client.get("/courses", params={"min_rating": 6}).status_code == 422
    assert client.get("/courses", params={"sort": "price"}).status_code == 422
    assert client.get("/courses/0").status_code == 422
    assert fake_upstream == []


def test_course_found_and_missing(client, fake_upstream):
    assert client.get("/courses/2").json()["title"] == "Agents"
    missing = client.get("/courses/99")
    assert missing.status_code == 404
    assert missing.json() == {"detail": "Course 99 not found"}


def test_summary_numbers(client, fake_upstream):
    rows = {row["level"]: row for row in client.get("/summary").json()}
    assert rows["beginner"] == {
        "level": "beginner", "courses": 2, "total_hours": 16, "average_rating": 4.3,
    }


def test_weather_is_reshaped(client, fake_upstream):
    assert client.get("/weather/Sylhet").json() == {
        "city": "Sylhet", "temperature_c": 27.4, "humidity_pct": 85,
        "condition": "Rain", "advice": "Carry an umbrella.",
    }
    assert client.get("/weather/Comilla").status_code == 404


def test_upstream_failure_becomes_502(client, monkeypatch):
    def broken(level=None):
        raise upstream.UpstreamError("Practice API is unreachable")

    monkeypatch.setattr(upstream, "fetch_courses", broken)
    response = client.get("/courses")
    assert response.status_code == 502
    assert response.json() == {"detail": "Practice API is unreachable"}

# file: tests/test_upstream.py
"""Client tests. session.get is replaced, so no request leaves the machine."""
import pytest
import requests

from app import upstream


class FakeResponse:
    """Just enough of requests.Response for app/upstream.py."""

    def __init__(self, status_code=200, data=None):
        self.status_code = status_code
        self.ok = status_code < 400
        self._data = data

    def json(self):
        if self._data is None:
            raise ValueError("not JSON")
        return self._data


def course(course_id):
    return {"id": course_id, "title": f"Course {course_id}", "level": "beginner",
            "hours": 2, "rating": 4.5}


def test_fetch_courses_follows_pages_with_a_timeout(monkeypatch):
    pages = {
        1: {"items": [course(1), course(2)], "next_page": 2},
        2: {"items": [course(3)], "next_page": None},
    }
    seen = []

    def fake_get(url, params=None, timeout=None):
        seen.append((params["page"], timeout))
        return FakeResponse(200, pages[params["page"]])

    monkeypatch.setattr(upstream.session, "get", fake_get)
    assert [c.id for c in upstream.fetch_courses()] == [1, 2, 3]
    assert seen == [(1, upstream.TIMEOUT_SECONDS), (2, upstream.TIMEOUT_SECONDS)]


@pytest.mark.parametrize(
    ("error", "status"),
    [(requests.Timeout(), 504), (requests.ConnectionError(), 502)],
)
def test_network_errors(monkeypatch, error, status):
    def fake_get(url, params=None, timeout=None):
        raise error

    monkeypatch.setattr(upstream.session, "get", fake_get)
    with pytest.raises(upstream.UpstreamError) as caught:
        upstream.fetch_course(1)
    assert caught.value.status_code == status


@pytest.mark.parametrize(
    "response",
    [FakeResponse(503, {"detail": "down"}), FakeResponse(200, None), FakeResponse(200, {"id": 1})],
    ids=["status-503", "not-json", "wrong-shape"],
)
def test_bad_answers_become_502(monkeypatch, response):
    monkeypatch.setattr(upstream.session, "get", lambda *args, **kwargs: response)
    with pytest.raises(upstream.UpstreamError) as caught:
        upstream.fetch_course(1)
    assert caught.value.status_code == 502


def test_404_means_none(monkeypatch):
    monkeypatch.setattr(upstream.session, "get", lambda *args, **kwargs: FakeResponse(404, {}))
    assert upstream.fetch_course(99) is None

PRACTICE_API_URL=http://127.0.0.1:9 uv run pytest -q

...............                                                                              [100%]
15 passed in 0.05s

git add pyproject.toml uv.lock tests/
git commit -q -m "Add endpoint and client tests with a faked upstream"

cat > README.md <<'EOF'
# BitByte Data Explorer API

A small FastAPI service that serves clean, validated course and weather data from the
BitByte Practice API. It is the project of *Git, APIs and Backend for AI: Beginner*.

## Endpoints

| Request | Returns |
|---|---|
| `GET /health` | `{"status": "ok"}` |
| `GET /courses?level=&min_rating=&sort=` | `{"count": n, "items": [...]}`; `sort` is `id`, `rating` or `hours` |
| `GET /courses/{course_id}` | one course |
| `GET /summary` | per level: number of courses, total hours, average rating |
| `GET /weather/{city}` | temperature, humidity, condition and a one-line advice |

Errors are JSON, `{"detail": "..."}`:

| Status | Meaning |
|---|---|
| 404 | no such course or city |
| 422 | a parameter is invalid (the body says which) |
| 502 | the Practice API failed, is unreachable or sent unexpected data |
| 504 | the Practice API did not answer in time |

## Run it

Needs Python 3.12+ and [uv](https://docs.astral.sh/uv/). Start the BitByte Practice API first.

```bash
uv sync                 # create .venv and install the locked versions
uv run fastapi dev      # development server with auto-reload; open /docs
```

Example: `GET /weather/sylhet` returns

```json
{"city": "Sylhet", "temperature_c": 27.4, "humidity_pct": 85, "condition": "Rain", "advice": "Carry an umbrella."}
```

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `PRACTICE_API_URL` | the Practice API on this computer (see `app/upstream.py`) | base URL of the upstream API |
| `UPSTREAM_TIMEOUT` | `5` | seconds to wait for the upstream before answering 504 |

## Tests

```bash
uv run pytest -q
```

The tests replace the Practice API with fakes, so they need no network and no running server.

## Project layout

```
app/main.py       routes, parameters and status codes
app/upstream.py   every call to the Practice API
app/schemas.py    Pydantic models
tests/            pytest tests (endpoints and client)
```
EOF
head -n 4 README.md

# BitByte Data Explorer API

A small FastAPI service that serves clean, validated course and weather data from the
BitByte Practice API. It is the project of *Git, APIs and Backend for AI: Beginner*.

# file: .gitignore
# Python
__pycache__/
*.pyc

# Virtual environment (rebuilt from uv.lock with `uv sync`)
.venv/

# Secrets and local settings: commit a .env.example with fake values instead
.env
.env.*
!.env.example

# Test and tool caches
.pytest_cache/
.coverage
htmlcov/
.ruff_cache/

# Logs from local runs
*.log

git check-ignore -v .env.local .pytest_cache/README.md server.log app/__pycache__/main.cpython-314.pyc
git check-ignore -v .env.example || echo ".env.example is not ignored"
git status --short

.gitignore:11:.env.*	.env.local
.gitignore:15:.pytest_cache/	.pytest_cache/README.md
.gitignore:21:*.log	server.log
.gitignore:3:__pycache__/	app/__pycache__/main.cpython-314.pyc
.gitignore:12:!.env.example	.env.example
 M .gitignore
?? README.md

git add README.md
git commit -q -m "Add README with endpoints, setup, configuration and tests"
git add .gitignore
git commit -q -m "Ignore test caches and local env files"
git log --oneline main..feature/data-explorer

26ccb95 Ignore test caches and local env files
a7d6e20 Add README with endpoints, setup, configuration and tests
b5fc148 Add endpoint and client tests with a faked upstream
3a8f75a Add courses, summary and weather endpoints
089f152 Add Practice API client with timeouts, pagination and validation
6bba991 Add response and upstream schemas

git init -q --bare ~/remotes/data-explorer.git
git remote add origin ~/remotes/data-explorer.git
git push -q origin main
git push -u origin feature/data-explorer

To /home/nadia/remotes/data-explorer.git
 * [new branch]      feature/data-explorer -> feature/data-explorer
branch 'feature/data-explorer' set up to track 'origin/feature/data-explorer'.

gh pr create --base main --head feature/data-explorer \
  --title "Data Explorer API: courses, summary and weather" \
  --body-file pr-description.md
gh pr view --web

## What
A FastAPI service over the BitByte Practice API: /courses (filter, sort),
/courses/{id}, /summary and /weather/{city}, with /health.

## Why
The study assistant needs short, validated answers from one place
instead of calling the Practice API directly.

## How
- app/upstream.py owns every upstream call: shared session, timeout on
  every request, pagination with a page limit, Pydantic validation.
- Upstream trouble becomes UpstreamError -> 502 (504 for timeouts)
  through one exception handler.

## How to test
uv sync && uv run pytest -q        (15 tests, no network needed)
Manual: start the Practice API, uv run fastapi dev, open /docs.

## Not in this PR
Caching and retries for upstream calls.

git diff --stat main...feature/data-explorer

 .gitignore             | 10 +++++++-
 README.md              | 62 +++++++++++++++++++++++++++++++++++++++++++++
 app/main.py            | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 app/schemas.py         | 43 +++++++++++++++++++++++++++++++
 app/upstream.py        | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 pyproject.toml         | 10 ++++++++
 tests/conftest.py      | 53 +++++++++++++++++++++++++++++++++++++++
 tests/test_api.py      | 62 +++++++++++++++++++++++++++++++++++++++++++++
 tests/test_upstream.py | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 uv.lock                | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 10 files changed, 559 insertions(+), 1 deletion(-)

# file: app/services.py
"""Business rules of the Data Explorer, kept free of HTTP so they are easy to test."""
from app.schemas import Course, LevelSummary


def advice_for(temp_c: float, condition: str) -> str:
    if condition == "Rain":
        return "Carry an umbrella."
    if temp_c >= 30:
        return "Hot day: drink water and avoid the midday sun."
    return "Good weather to go out."


def summarise(courses: list[Course]) -> list[LevelSummary]:
    by_level: dict[str, list[Course]] = {}
    for course in courses:
        by_level.setdefault(course.level, []).append(course)
    return [
        LevelSummary(
            level=level,
            courses=len(group),
            total_hours=sum(c.hours for c in group),
            average_rating=round(sum(c.rating for c in group) / len(group), 2),
        )
        for level, group in by_level.items()
    ]

# file: app/main.py
"""BitByte Data Explorer API: clean, validated endpoints over the BitByte Practice API."""
from typing import Annotated, Literal

from fastapi import FastAPI, HTTPException, Path, Query, Request
from fastapi.responses import JSONResponse

from app import services, upstream
from app.schemas import Course, CourseList, Level, LevelSummary, Weather

app = FastAPI(title="BitByte Data Explorer API", version="0.1.0")


@app.exception_handler(upstream.UpstreamError)
def upstream_failed(request: Request, exc: upstream.UpstreamError) -> JSONResponse:
    return JSONResponse({"detail": exc.message}, status_code=exc.status_code)


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/courses")
def list_courses(
    level: Level | None = None,
    min_rating: Annotated[float, Query(ge=0, le=5)] = 0,
    sort: Literal["id", "rating", "hours"] = "id",
) -> CourseList:
    courses = [c for c in upstream.fetch_courses(level) if c.rating >= min_rating]
    courses.sort(key=lambda c: getattr(c, sort), reverse=sort != "id")
    return CourseList(count=len(courses), items=courses)


@app.get("/courses/{course_id}")
def get_course(course_id: Annotated[int, Path(ge=1)]) -> Course:
    course = upstream.fetch_course(course_id)
    if course is None:
        raise HTTPException(404, f"Course {course_id} not found")
    return course


@app.get("/summary")
def summary() -> list[LevelSummary]:
    return services.summarise(upstream.fetch_courses())


@app.get("/weather/{city}")
def weather(city: Annotated[str, Path(min_length=2, max_length=40)]) -> Weather:
    data = upstream.fetch_weather(city)
    if data is None:
        raise HTTPException(404, f"No weather data for {city}")
    return Weather(
        city=data.city,
        temperature_c=data.temp_c,
        humidity_pct=data.humidity,
        condition=data.condition,
        advice=services.advice_for(data.temp_c, data.condition),
    )

uv run pytest -q

...............                                                                              [100%]
15 passed in 0.05s

# file: tests/test_services.py
"""Unit tests for the business rules: plain functions, no HTTP, no fakes."""
import pytest

from app import services


@pytest.mark.parametrize(
    ("temp_c", "condition", "advice"),
    [
        (25.0, "Rain", "Carry an umbrella."),
        (35.0, "Rain", "Carry an umbrella."),
        (30.0, "Sunny", "Hot day: drink water and avoid the midday sun."),
        (29.9, "Sunny", "Good weather to go out."),
    ],
)
def test_advice_for(temp_c, condition, advice):
    assert services.advice_for(temp_c, condition) == advice


def test_summarise_counts_every_course(fake_courses):
    rows = services.summarise(fake_courses)
    assert sum(row.courses for row in rows) == len(fake_courses)

uv run pytest -q
git add app/services.py app/main.py tests/test_services.py
git commit -q -m "Move business rules into app/services.py"

....................                                                                         [100%]
20 passed in 0.04s

cat >> tests/test_services.py <<'EOF'


def test_summarise_uses_a_fixed_level_order(fake_courses):
    levels = [row.level for row in services.summarise(fake_courses)]
    assert levels == ["beginner", "intermediate", "advanced"]
EOF
uv run pytest -q --tb=short

.............F.......                                                                        [100%]
============================================= FAILURES =============================================
_____________________________ test_summarise_uses_a_fixed_level_order ______________________________
tests/test_services.py:28: in test_summarise_uses_a_fixed_level_order
    assert levels == ["beginner", "intermediate", "advanced"]
E   AssertionError: assert ['beginner', ...intermediate'] == ['beginner', ...', 'advanced']
E     
E     At index 1 diff: 'advanced' != 'intermediate'
E     Use -v to get more diff
===================================== short test summary info ======================================
FAILED tests/test_services.py::test_summarise_uses_a_fixed_level_order - AssertionError: assert [...
1 failed, 20 passed in 0.06s

# file: app/services.py
"""Business rules of the Data Explorer, kept free of HTTP so they are easy to test."""
from typing import get_args

from app.schemas import Course, Level, LevelSummary

LEVELS = get_args(Level)  # ("beginner", "intermediate", "advanced")


def advice_for(temp_c: float, condition: str) -> str:
    if condition == "Rain":
        return "Carry an umbrella."
    if temp_c >= 30:
        return "Hot day: drink water and avoid the midday sun."
    return "Good weather to go out."


def summarise(courses: list[Course]) -> list[LevelSummary]:
    by_level: dict[str, list[Course]] = {}
    for course in courses:
        by_level.setdefault(course.level, []).append(course)
    summaries = []
    for level in LEVELS:  # our fixed order, not the upstream's
        group = by_level.get(level)
        if group:
            summaries.append(LevelSummary(
                level=level,
                courses=len(group),
                total_hours=sum(c.hours for c in group),
                average_rating=round(sum(c.rating for c in group) / len(group), 2),
            ))
    return summaries

uv run pytest -q
git add app/services.py tests/test_services.py
git commit -q -m "Return summary levels in a fixed order"
git push

.....................                                                                        [100%]
21 passed in 0.04s
To /home/nadia/remotes/data-explorer.git
   26ccb95..96a7ec5  feature/data-explorer -> feature/data-explorer

git switch main
git merge --no-ff feature/data-explorer -m "Merge pull request #1 from nadia/feature/data-explorer"
git push origin main

Switched to branch 'main'
Merge made by the 'ort' strategy.
 .gitignore             | 10 +++++++-
 README.md              | 62 +++++++++++++++++++++++++++++++++++++++++++++
 app/main.py            | 59 +++++++++++++++++++++++++++++++++++++++++++
 app/schemas.py         | 43 +++++++++++++++++++++++++++++++
 app/services.py        | 32 ++++++++++++++++++++++++
 app/upstream.py        | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 pyproject.toml         | 10 ++++++++
 tests/conftest.py      | 53 +++++++++++++++++++++++++++++++++++++++
 tests/test_api.py      | 62 +++++++++++++++++++++++++++++++++++++++++++++
 tests/test_services.py | 28 +++++++++++++++++++++
 tests/test_upstream.py | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 uv.lock                | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 12 files changed, 600 insertions(+), 1 deletion(-)
 create mode 100644 README.md
 create mode 100644 app/main.py
 create mode 100644 app/schemas.py
 create mode 100644 app/services.py
 create mode 100644 app/upstream.py
 create mode 100644 tests/conftest.py
 create mode 100644 tests/test_api.py
 create mode 100644 tests/test_services.py
 create mode 100644 tests/test_upstream.py
To /home/nadia/remotes/data-explorer.git
   04b26f9..b94b4cd  main -> main

git branch -d feature/data-explorer
git push origin --delete feature/data-explorer
git log --oneline --graph --decorate

Deleted branch feature/data-explorer (was 96a7ec5).
To /home/nadia/remotes/data-explorer.git
 - [deleted]         feature/data-explorer
*   b94b4cd (HEAD -> main, origin/main) Merge pull request #1 from nadia/feature/data-explorer
|\  
| * 96a7ec5 Return summary levels in a fixed order
| * 40763f0 Move business rules into app/services.py
| * 26ccb95 Ignore test caches and local env files
| * a7d6e20 Add README with endpoints, setup, configuration and tests
| * b5fc148 Add endpoint and client tests with a faked upstream
| * 3a8f75a Add courses, summary and weather endpoints
| * 089f152 Add Practice API client with timeouts, pagination and validation
| * 6bba991 Add response and upstream schemas
|/  
* 04b26f9 Set up the Data Explorer project with uv

cd ~
git clone -q ~/remotes/data-explorer.git data-explorer-check
cd data-explorer-check
uv sync -q
ls
uv run pytest -q

README.md
app
pyproject.toml
tests
uv.lock
.....................                                                                        [100%]
21 passed in 0.04s

export PRACTICE_API_URL=http://localhost:8800
uv run fastapi run --port 8000 > server.log 2>&1 &
curl -s --retry 20 --retry-connrefused --retry-delay 0 http://localhost:8000/health > /dev/null
curl -s http://localhost:8000/summary | python -m json.tool

[
    {
        "level": "beginner",
        "courses": 5,
        "total_hours": 42,
        "average_rating": 4.64
    },
    {
        "level": "intermediate",
        "courses": 2,
        "total_hours": 11,
        "average_rating": 4.55
    },
    {
        "level": "advanced",
        "courses": 3,
        "total_hours": 30,
        "average_rating": 4.67
    }
]

cd ~/projects/data-explorer
cat >> tests/test_api.py <<'EOF'


def test_one_letter_city_is_rejected(client, fake_upstream):
    assert client.get("/weather/x").status_code == 422
    assert fake_upstream == []
EOF
cat >> tests/test_upstream.py <<'EOF'


def test_endless_pages_are_stopped(monkeypatch):
    monkeypatch.setattr(upstream, "MAX_PAGES", 3)

    def fake_get(url, params=None, timeout=None):
        return FakeResponse(200, {"items": [course(params["page"])], "next_page": params["page"] + 1})

    monkeypatch.setattr(upstream.session, "get", fake_get)
    with pytest.raises(upstream.UpstreamError, match="too many pages"):
        upstream.fetch_courses()
EOF
uv run pytest -q

.......................                                                                      [100%]
23 passed in 0.04s

# ৩. GET /levels-এর পুরো চক্র
git add tests/
git commit -q -m "Test the city length limit and the page limit"
git switch -q -c feature/levels
cat >> app/main.py <<'EOF'


@app.get("/levels")
def levels() -> list[str]:
    return sorted({course.level for course in upstream.fetch_courses()})
EOF
cat >> tests/test_api.py <<'EOF'


def test_levels(client, fake_upstream):
    assert client.get("/levels").json() == ["advanced", "beginner", "intermediate"]
EOF
uv run pytest -q
git add app/main.py tests/test_api.py
git commit -q -m "Add GET /levels"
git push -q -u origin feature/levels
git switch -q main
git merge -q --no-ff feature/levels -m "Merge pull request #2 from nadia/feature/levels"
git push -q origin main
git branch -q -d feature/levels
git push -q origin --delete feature/levels
git log --oneline --graph -n 6

........................                                                                     [100%]
24 passed in 0.05s
*   0bc9e2a Merge pull request #2 from nadia/feature/levels
|\  
| * 3eac711 Add GET /levels
|/  
* 15de305 Test the city length limit and the page limit
*   b94b4cd Merge pull request #1 from nadia/feature/data-explorer
|\  
| * 96a7ec5 Return summary levels in a fixed order
| * 40763f0 Move business rules into app/services.py