Streamlit 상태 관리 완벽 가이드: Session State 활용법과 실습 예제

Streamlit은 웹 애플리케이션을 쉽게 구축할 수 있는 도구이지만, 기본적으로 Stateless 구조이다.
즉, 사용자가 값을 입력하거나 특정 동작(예: 버튼 클릭, 드롭다운 선택 등)을 수행하더라도, 상태를 명시적으로 관리하지 않으면, 모든 값이 기본값으로 초기화된다.

하지만 많은 경우 상태(State)를 유지해야 하는 요구가 발생한다. 예를 들어 보면, 사용자의 입력 값을 저장하거나 이전 작업 결과를 계속 유지하려는 등의 상황에서 필요한 것이 바로 상태 관리이다.

Streamlit에서는 이러한 상태를 관리하기 위해 Session State라는 기능을 제공한다.

Table of Contents　

Session State란?

Session State는 Streamlit 애플리케이션의 실행 중에 값을 저장하고 상태를 유지할 수 있는 저장 공간이다.
이를 통해 다음과 같은 기능을 구현할 수 있다.

사용자 입력 값 유지
버튼 클릭 여부 확인
상태에 따라 화면 동적으로 업데이트

Session State의 주요 기능

초기화 및 값 설정

상태를 정의하고 초기값을 설정한다.

st.session_state["key"] = value

상태 값 읽기

저장된 값을 읽어서 동적으로 활용한다.

value = st.session_state["key"]

값 변경 및 리셋

상태값을 변경하거나 초기화할 수 있다.

st.session_state["key"] = new_value
del st.session_state["key"] #상태 값 삭제

콜백과 연동

상태 값이 변경될 때 특정 동작을 수행하는 콜백 함수를 설정할 수 있다.

import streamlit as st

# 상태 초기화
if "result" not in st.session_state:
    st.session_state.result = 0  # 초기 계산 결과

# 콜백 함수 정의
def update_result():
    """슬라이더 값을 가져와 계산 결과를 업데이트합니다."""
    input_value = st.session_state.slider_value
    st.session_state.result = input_value ** 2 #값의 제곱을 계산

st.title("콜백 함수 연동 실습")
st.write("슬라이더를 움직이면 자동으로 계산 결과가 업데이트됩니다.")

#슬라이더
st.slider(
    "값을 선택하세요",
    min_value=0,
    max_value=100,
    value=0,
    key="slider_value", #상태 키
    on_change=update_result, #값 변경 시 콜백 호출
)

# 계산 결과 표시
st.subheader("결과")
st.write(f"선택한 값의 제곱은 {st.session_state.result}입니다.")

예제 코드 – 간단한 To-Do 리스트 관리 애플리케이션

Streamlit의 상태 관리(Session State)를 활용해 할 일(To-Do) 목록을 관리하는 애플리케이션을 만들어보자.
사용자는 할 일을 추가하거나 완료 표시를 할 수 있으며, 새로운 입력을 하더라도 데이터가 리셋되지 않고 유지하게 된다.
모든 목록 초기화를 선택하면, 목록을 초기화 하는 기능을 포함한다.

코드

import streamlit as st

# Session State 초기화
if "todo_list" not in st.session_state:
    st.session_state.todo_list = []  # 할 일 목록 초기화

if "completed_tasks" not in st.session_state:
    st.session_state.completed_tasks = []  # 완료된 할 일 목록 초기화

# 타이틀 및 설명
st.title("✅ 할 일 관리 애플리케이션")
st.write("할 일을 추가하고 완료를 체크하세요!")

# 새로운 할 일 추가
new_task = st.text_input("할 일을 입력하세요:")

if st.button("추가"):
    if new_task:
        st.session_state.todo_list.append(new_task)
        st.success(f"'{new_task}'이(가) 목록에 추가되었습니다.")
    else:
        st.warning("할 일을 입력해주세요!")

# 할 일 목록 출력
st.subheader("📋 할 일 목록")
if st.session_state.todo_list:
    for i, task in enumerate(st.session_state.todo_list):
        # 체크박스를 사용해 완료 처리
        if st.checkbox(task, key=f"todo-{i}"):
            st.session_state.completed_tasks.append(task)  # 완료 목록에 추가
            st.session_state.todo_list.remove(task)  # 할 일 목록에서 제거
            st.rerun()  # 화면 갱신
else:
    st.info("현재 할 일이 없습니다.")

# 완료된 할 일 목록 출력
st.subheader("🎉 완료된 할 일")
if st.session_state.completed_tasks:
    for task in st.session_state.completed_tasks:
        st.write(f"✔️ {task}")
else:
    st.info("아직 완료된 할 일이 없습니다.")

# 할 일 및 완료 목록 초기화 버튼
if st.button("모든 목록 초기화"):
    st.session_state.todo_list.clear()
    st.session_state.completed_tasks.clear()
    st.info("모든 목록이 초기화되었습니다.")
    st.rerun()

코드 설명

st.session_state 초기화
- todo_list와 completed_tasks 키를 사용해 상태를 관리한다.
- todo_list는 현재 진행 중인 할 일 목록, completed_tasks는 완료된 할 일 목록을 저장한다.
할 일 추가
- st.text_input으로 사용자가 새 할 일을 입력할 수 있다.
- 입력값이 비어 있지 않으면 “추가” 버튼 클릭 시 todo_list에 저장한다.
할 일 완료
- 할 일 목록에 체크박스를 추가하고, 체크 시 해당 항목을 completed_tasks로 이동한다.
- 변경 사항을 즉시 반영하기 위해 st.experimental_rerun()을 호출해 화면을 갱신한다.
목록 출력
- todo_list와 completed_tasks를 각각 출력한다.
- 상태에 따라 “현재 할 일이 없습니다.” 또는 “아직 완료된 할 일이 없습니다.” 메시지를 표시한다.
목록 초기화
- “모든 목록 초기화” 버튼으로 todo_list와 completed_tasks를 비운다.

Streamlit의Session State는 사용자 입력 상태를 유지하고, 동적인 웹 애플리케이션을 만드는 데 매우 유용하다.
이번 예제를 통해 상태 관리의 기본 개념과 활용 방법을 익힐 수 있었으며, 이를 바탕으로 더욱 복잡한 애플리케이션에도 적용할 수 있다.