Streamlit URL 狀態契約：Query Params、篩選還原與雙向同步

uv init --python 3.12
uv add 'streamlit==1.66.1'
uv add --dev 'pytest==9.1.1'

from dataclasses import dataclass
import re

REGIONS = ("all", "north", "south")
TAGS = ("coffee", "cookie", "notebook")

@dataclass(frozen=True)
class Filters:
    region: str = "all"
    tags: tuple[str, ...] = ()
    page: int = 1

def single(raw, key, default):
    values = raw.get(key, [])
    return values[0] if len(values) == 1 else default

def decode(raw: dict[str, list[str]]) -> Filters:
    region = single(raw, "region", "all")
    if region not in REGIONS:
        region = "all"
    text = single(raw, "page", "1")
    # 先限長度與 ASCII 格式，再轉 int；不接受 +2、2.0、全形數字。
    page = int(text) if re.fullmatch(r"[0-9]{1,2}", text) else 1
    if not 1 <= page <= 50:
        page = 1
    tags = tuple(sorted(set(raw.get("tag", [])) & set(TAGS)))
    return Filters(region, tags, page)

def encode(filters: Filters) -> dict[str, list[str]]:
    result = {}
    if filters.region != "all":
        result["region"] = [filters.region]
    if filters.tags:
        result["tag"] = list(filters.tags)
    if filters.page != 1:
        result["page"] = [str(filters.page)]
    return result

def signature(raw):
    return tuple(sorted((key, tuple(values)) for key, values in raw.items()))

輸入：?region=all&tag=cookie&tag=coffee&tag=coffee&page=02&x=old
輸出：?tag=coffee&tag=cookie&page=2

from dataclasses import asdict
import streamlit as st
from filters import Filters, REGIONS, TAGS, decode, encode, signature

st.set_page_config(page_title="拍拍君公開篩選")
ss = st.session_state

def read_query():
    return {key: st.query_params.get_all(key) for key in st.query_params}

def seed(filters):
    ss["ui_region"] = filters.region
    ss["ui_tags"] = list(filters.tags)
    ss["ui_page"] = filters.page

def write_query(filters):
    wanted = encode(filters)
    if signature(read_query()) != signature(wanted):
        st.query_params.from_dict(wanted)
    ss["_url_seen"] = signature(wanted)

def from_widgets():
    return Filters(
        ss["ui_region"], tuple(sorted(ss["ui_tags"])), int(ss["ui_page"])
    )

def commit_widgets():
    write_query(from_widgets())

def reset():
    seed(Filters())
    write_query(Filters())

raw = read_query()
if ss.get("_url_seen") != signature(raw):
    restored = decode(raw)
    seed(restored)
    write_query(restored)

st.title("拍拍君公開篩選")
st.selectbox("地區", REGIONS, key="ui_region", on_change=commit_widgets)
st.multiselect("標籤", TAGS, key="ui_tags", on_change=commit_widgets)
st.number_input("頁碼", 1, 50, step=1, key="ui_page", on_change=commit_widgets)
st.button("重設", key="reset", on_click=reset)
st.button("重新整理畫面", key="refresh")
current = from_widgets()
st.json(asdict(current))
ss["_runs"] = ss.get("_runs", 0) + 1
st.caption(f"執行輪數：{ss['_runs']}")

import pytest
from filters import Filters, decode, encode

@pytest.mark.parametrize("text", ["", "0", "51", "-1", "+2", "2.0", "２", "9" * 100])
def test_bad_page(text):
    assert decode({"page": [text]}).page == 1

def test_duplicates_and_allowlist():
    result = decode({"region": ["north", "south"],
                     "tag": ["cookie", "coffee", "cookie", "unknown"]})
    assert result == Filters("all", ("coffee", "cookie"), 1)
    assert decode({"page": ["2", "3"]}).page == 1

@pytest.mark.parametrize("raw", [
    {}, {"region": ["invalid"]}, {"page": ["02"]},
    {"region": ["all"], "tag": ["cookie", "coffee", "cookie"], "x": ["old"]},
])
def test_canonical_converges(raw):
    once = encode(decode(raw))
    assert encode(decode(once)) == once
    assert decode(once) == decode(raw)

from streamlit.testing.v1 import AppTest

def test_restore_edit_external_reset():
    at = AppTest.from_file("app.py")
    at.query_params.update({"region": ["north"], "tag": ["cookie", "coffee"]})
    at.run()
    assert not at.exception
    assert at.selectbox("ui_region").value == "north"
    assert at.multiselect("ui_tags").value == ["coffee", "cookie"]
    at.selectbox("ui_region").set_value("south").run()
    assert at.query_params["region"] == "south"
    at.button("refresh").click().run()
    assert at.selectbox("ui_region").value == "south"
    at.query_params.clear()
    at.query_params.update({"region": ["north"], "page": ["2"]})
    at.run()
    assert at.selectbox("ui_region").value == "north"
    assert at.number_input("ui_page").value == 2
    at.button("reset").click().run()
    assert not at.exception
    assert at.query_params == {}
    assert at.multiselect("ui_tags").value == []
    assert at.number_input("ui_page").value == 1
    for _ in range(3):
        at.run()
        assert at.query_params == {}
        assert not at.exception

uv run streamlit run app.py --server.address 127.0.0.1