Appendix 4: Web APIs, Pydantic, Dash, and Python Decorators

@app.get("/profiles/{profile_id}")
def get_profile(profile_id: int):  # FastAPI validates that profile_id is an int
    ...

# api/main.py
from fastapi import FastAPI

app = FastAPI()

# In-memory storage for now (you'll replace with database)
profiles = [
    {"id": 1, "name": "default", "x_coordinates": [0, 10, 20], "y_coordinates": [0, 5, 2]}
]

@app.get("/profiles")
def list_profiles():
    """Return all road profiles."""
    return profiles

@app.get("/profiles/{profile_id}")
def get_profile(profile_id: int):
    """Return a specific road profile by ID."""
    for profile in profiles:
        if profile["id"] == profile_id:
            return profile
    return {"error": "Profile not found"}

@app.post("/profiles")
def create_profile(profile: dict):
    """Create a new road profile."""
    profile["id"] = len(profiles) + 1
    profiles.append(profile)
    return profile

# In your Dash app
import requests

# Get all profiles for the dropdown
response = requests.get("http://localhost:8000/profiles")
profiles = response.json()  # [{"id": 1, "name": "default", ...}, ...]

# Create a new profile from uploaded JSON
new_profile = {
    "name": "mountain_road",
    "x_coordinates": [0, 10, 20],
    "y_coordinates": [0, 5, 8]
}
response = requests.post("http://localhost:8000/profiles", json=new_profile)
created = response.json()

from pydantic import BaseModel

class RoadProfile(BaseModel):
    name: str
    x_coordinates: list[float]
    y_coordinates: list[float]

# This works
profile = RoadProfile(
    name="mountain",
    x_coordinates=[0.0, 10.0, 20.0],
    y_coordinates=[0.0, 5.0, 8.0]
)

# This fails with a clear error
profile = RoadProfile(
    name=123,  # Should be string!
    x_coordinates=[0.0, 10.0],
    y_coordinates=[0.0, 5.0]
)
# ValidationError: name - Input should be a valid string

from pydantic import BaseModel, Field
from typing import List

class RoadProfile(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    x_coordinates: List[float] = Field(..., min_length=2)
    y_coordinates: List[float] = Field(..., min_length=2)

# Empty name - fails!
RoadProfile(name="", x_coordinates=[0, 10], y_coordinates=[0, 5])
# ValidationError: name - String should have at least 1 character

# Only one point - fails!
RoadProfile(name="road", x_coordinates=[0], y_coordinates=[0])
# ValidationError: x_coordinates - List should have at least 2 items

from pydantic import BaseModel, Field, model_validator
from typing import List

class RoadProfile(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    x_coordinates: List[float] = Field(..., min_length=2)
    y_coordinates: List[float] = Field(..., min_length=2)

    @model_validator(mode='after')
    def check_coordinate_lengths(self):
        if len(self.x_coordinates) != len(self.y_coordinates):
            raise ValueError(
                f"x_coordinates ({len(self.x_coordinates)} points) and "
                f"y_coordinates ({len(self.y_coordinates)} points) must have the same length"
            )
        return self

RoadProfile(
    name="bad_road",
    x_coordinates=[0, 10, 20],
    y_coordinates=[0, 5]  # Only 2 points!
)
# ValidationError: x_coordinates (3 points) and y_coordinates (2 points) must have the same length

from fastapi import FastAPI
from pydantic import BaseModel, Field, model_validator
from typing import List

app = FastAPI()

class RoadProfileCreate(BaseModel):
    """Schema for creating a new road profile."""
    name: str = Field(..., min_length=1, max_length=100)
    x_coordinates: List[float] = Field(..., min_length=2)
    y_coordinates: List[float] = Field(..., min_length=2)

    @model_validator(mode='after')
    def check_coordinate_lengths(self):
        if len(self.x_coordinates) != len(self.y_coordinates):
            raise ValueError("x and y coordinates must have the same length")
        return self

class RoadProfileResponse(BaseModel):
    """Schema for road profile responses (includes ID)."""
    id: int
    name: str
    x_coordinates: List[float]
    y_coordinates: List[float]

@app.post("/profiles", response_model=RoadProfileResponse)
def create_profile(profile: RoadProfileCreate):
    # FastAPI automatically validates 'profile' using Pydantic!
    # If validation fails, FastAPI returns a 422 error with details

    # Your database logic here...
    new_id = save_to_database(profile)

    return RoadProfileResponse(
        id=new_id,
        name=profile.name,
        x_coordinates=profile.x_coordinates,
        y_coordinates=profile.y_coordinates
    )

from typing import Optional

class RoadProfile(BaseModel):
    name: str
    description: Optional[str] = None  # Optional, defaults to None
    created_at: str = Field(default_factory=lambda: datetime.now().isoformat())

class Coordinates(BaseModel):
    x: List[float]
    y: List[float]

class RoadProfile(BaseModel):
    name: str
    coordinates: Coordinates  # Nested model

class RoadProfile(BaseModel):
    name: str
    x_coords: List[float] = Field(..., alias="x_coordinates")

    class Config:
        populate_by_name = True  # Accept both 'x_coords' and 'x_coordinates'

profile = RoadProfile(name="test", x_coordinates=[0, 10], y_coordinates=[0, 5])

# Convert to dictionary
profile.model_dump()
# {'name': 'test', 'x_coordinates': [0.0, 10.0], 'y_coordinates': [0.0, 5.0]}

# Convert to JSON string
profile.model_dump_json()
# '{"name":"test","x_coordinates":[0.0,10.0],"y_coordinates":[0.0,5.0]}'

from dash import Dash, html, dcc

app = Dash(__name__)

app.layout = html.Div([
    html.H1("Road Profile Viewer"),           # <h1>Road Profile Viewer</h1>

    dcc.Dropdown(                              # <select>...</select>
        id="profile-dropdown",
        options=[
            {"label": "Default", "value": 1},
            {"label": "Mountain", "value": 2}
        ],
        value=1
    ),

    dcc.Graph(id="profile-graph")              # <div> with Plotly chart
])

import plotly.graph_objects as go
from dash import Dash, dcc, html, callback, Output, Input

app = Dash(__name__)

app.layout = html.Div([
    dcc.Dropdown(
        id="profile-dropdown",
        options=[{"label": "Default", "value": 1}],
        value=1
    ),
    dcc.Graph(id="profile-graph")
])

@callback(
    Output("profile-graph", "figure"),
    Input("profile-dropdown", "value")
)
def update_graph(profile_id):
    # Fetch profile data (from API in your project)
    x = [0, 10, 20, 30]
    y = [0, 5, 8, 3]

    # Create Plotly figure
    fig = go.Figure()
    fig.add_trace(go.Scatter(x=x, y=y, mode='lines', name='Road Profile'))
    fig.update_layout(title="Road Profile", xaxis_title="Distance", yaxis_title="Elevation")

    return fig

if __name__ == "__main__":
    app.run(debug=True)

# pages/home.py
from dash import html, dcc, register_page

register_page(__name__, path="/")

layout = html.Div([
    html.H1("Road Profile Viewer"),
    dcc.Dropdown(id="profile-dropdown"),
    dcc.Graph(id="profile-graph"),
    dcc.Link("Go to Upload", href="/upload")
])

# pages/upload.py
from dash import html, dcc, register_page

register_page(__name__, path="/upload")

layout = html.Div([
    html.H1("Upload Road Profile"),
    dcc.Upload(
        id="upload-data",
        children=html.Div(["Drag and Drop or ", html.A("Select Files")]),
    ),
    html.Div(id="preview-container"),
    html.Button("Save Profile", id="save-button"),
    dcc.Link("Back to Viewer", href="/")
])

# app.py
from dash import Dash, page_container

app = Dash(__name__, use_pages=True)
app.layout = page_container

if __name__ == "__main__":
    app.run(debug=True)

@callback(
    Output("profile-graph", "figure"),
    Input("profile-dropdown", "value")
)
def update_graph(selected_profile):
    ...

@app.get("/profiles")
def list_profiles():
    return profiles

@callback(Output("graph", "figure"), Input("dropdown", "value"))
def update_graph(value):
    ...

def greet(name):
    return f"Hello, {name}!"

say_hello = greet  # No parentheses = reference to function, not calling it
print(say_hello("Alice"))  # "Hello, Alice!"

def apply_twice(func, value):
    return func(func(value))

def add_one(x):
    return x + 1

result = apply_twice(add_one, 5)  # add_one(add_one(5)) = 7

def create_multiplier(factor):
    def multiply(x):
        return x * factor
    return multiply  # Return the inner function

double = create_multiplier(2)
triple = create_multiplier(3)

print(double(5))  # 10
print(triple(5))  # 15

def greet(name):
    print(f"greet was called with: {name}")  # Manual logging
    return f"Hello, {name}!"

def farewell(name):
    print(f"farewell was called with: {name}")  # Duplicate!
    return f"Goodbye, {name}!"

def log_calls(func):
    def wrapper(*args, **kwargs):
        print(f"{func.__name__} was called with args={args}, kwargs={kwargs}")
        result = func(*args, **kwargs)
        print(f"{func.__name__} returned: {result}")
        return result
    return wrapper

def greet(name):
    return f"Hello, {name}!"

greet = log_calls(greet)  # Replace greet with wrapped version

greet("Alice")
# Output:
# greet was called with args=('Alice',), kwargs={}
# greet returned: Hello, Alice!

@log_calls
def greet(name):
    return f"Hello, {name}!"

# This is EXACTLY equivalent to:
# def greet(name):
#     return f"Hello, {name}!"
# greet = log_calls(greet)

def repeat(times):
    def decorator(func):
        def wrapper(*args, **kwargs):
            for _ in range(times):
                result = func(*args, **kwargs)
            return result
        return wrapper
    return decorator

@repeat(3)
def say_hello():
    print("Hello!")

say_hello()
# Output:
# Hello!
# Hello!
# Hello!

from fastapi import FastAPI

app = FastAPI()

@app.get("/profiles")
def list_profiles():
    return [{"id": 1, "name": "default"}]

class SimpleFastAPI:
    def __init__(self):
        self.routes = {}

    def get(self, path):
        def decorator(func):
            self.routes[("GET", path)] = func
            return func
        return decorator

    def post(self, path):
        def decorator(func):
            self.routes[("POST", path)] = func
            return func
        return decorator

app = SimpleFastAPI()

@app.get("/profiles")
def list_profiles():
    return [{"id": 1}]

@app.post("/profiles")
def create_profile(data):
    return {"id": 2, **data}

# Now app.routes contains:
# {
#   ("GET", "/profiles"): list_profiles,
#   ("POST", "/profiles"): create_profile
# }

@callback(
    Output("graph", "figure"),
    Input("dropdown", "value")
)
def update_graph(value):
    ...

class SimpleDash:
    def __init__(self):
        self.callbacks = []

    def callback(self, output, *inputs):
        def decorator(func):
            self.callbacks.append({
                "function": func,
                "output": output,
                "inputs": inputs
            })
            return func
        return decorator

app = SimpleDash()

@app.callback(Output("graph", "figure"), Input("dropdown", "value"))
def update_graph(value):
    return create_figure(value)

# Now app.callbacks contains information about when to call update_graph

class RoadProfile:
    def __init__(self, x_coords, y_coords):
        self._x = x_coords
        self._y = y_coords

    @property
    def num_points(self):
        return len(self._x)

profile = RoadProfile([0, 10, 20], [0, 5, 8])
print(profile.num_points)  # 3 (no parentheses needed!)

class MathUtils:
    @staticmethod
    def add(a, b):
        return a + b

MathUtils.add(2, 3)  # 5 (no instance needed)

class RoadProfile:
    def __init__(self, name, x, y):
        self.name = name
        self.x = x
        self.y = y

    @classmethod
    def from_json(cls, json_data):
        return cls(
            json_data["name"],
            json_data["x_coordinates"],
            json_data["y_coordinates"]
        )

data = {"name": "test", "x_coordinates": [0, 10], "y_coordinates": [0, 5]}
profile = RoadProfile.from_json(data)

import time
from functools import wraps

def log_endpoint(func):
    @wraps(func)  # Preserves function name and docstring
    def wrapper(*args, **kwargs):
        start = time.time()
        print(f"→ {func.__name__} called")

        try:
            result = func(*args, **kwargs)
            elapsed = time.time() - start
            print(f"← {func.__name__} returned in {elapsed:.3f}s")
            return result
        except Exception as e:
            print(f"✗ {func.__name__} raised {type(e).__name__}: {e}")
            raise

    return wrapper

# Usage in FastAPI
@app.get("/profiles")
@log_endpoint
def list_profiles():
    return profiles

# When called:
# → list_profiles called
# ← list_profiles returned in 0.001s

@app.get("/profiles")  # Applied second
@log_endpoint          # Applied first
def list_profiles():
    ...

# Equivalent to:
# list_profiles = app.get("/profiles")(log_endpoint(list_profiles))

# Dash callback triggered by file upload
@callback(Output("preview-graph", "figure"), Input("upload-data", "contents"))
def preview_upload(contents):
    if contents is None:
        return {}

    # Decode base64 content from upload
    content_string = contents.split(",")[1]
    decoded = base64.b64decode(content_string)
    data = json.loads(decoded)

    # Show preview graph
    return create_figure(data["x_coordinates"], data["y_coordinates"])

@callback(Output("save-message", "children"), Input("save-button", "n_clicks"), State("upload-data", "contents"))
def save_profile(n_clicks, contents):
    if n_clicks is None:
        return ""

    # Parse uploaded data
    data = parse_upload(contents)

    # Send to FastAPI
    response = requests.post(f"{API_URL}/profiles", json=data)

    if response.status_code == 200:
        return "Profile saved successfully!"
    else:
        return f"Error: {response.json()['detail']}"

@app.post("/profiles", response_model=RoadProfileResponse)
def create_profile(profile: RoadProfileCreate):
    # Pydantic already validated:
    # - name is 1-100 chars
    # - x and y have at least 2 points
    # - x and y have same length

    # Save to database
    db_profile = db.create_profile(profile)
    return db_profile

@callback(Output("profile-dropdown", "options"), Input("save-button", "n_clicks"))
def refresh_dropdown(_):
    # Fetch updated list from API
    response = requests.get(f"{API_URL}/profiles")
    profiles = response.json()

    return [{"label": p["name"], "value": p["id"]} for p in profiles]

from pydantic import BaseModel, Field, field_validator, model_validator

class Example(BaseModel):
    # Basic constraints
    name: str = Field(..., min_length=1, max_length=100)
    count: int = Field(..., ge=0, le=1000)  # >= 0, <= 1000
    items: List[str] = Field(..., min_length=1)

    # Field-level validation
    @field_validator('name')
    @classmethod
    def name_must_not_contain_spaces(cls, v):
        if ' ' in v:
            raise ValueError('must not contain spaces')
        return v

    # Model-level validation (after all fields)
    @model_validator(mode='after')
    def check_something(self):
        # Access self.name, self.count, etc.
        return self

# Simple decorator (no arguments)
def my_decorator(func):
    def wrapper(*args, **kwargs):
        # Before
        result = func(*args, **kwargs)
        # After
        return result
    return wrapper

@my_decorator
def my_function():
    pass

# Decorator with arguments
def my_decorator(arg1, arg2):
    def decorator(func):
        def wrapper(*args, **kwargs):
            # Use arg1, arg2 here
            return func(*args, **kwargs)
        return wrapper
    return decorator

@my_decorator("value1", "value2")
def my_function():
    pass