ماژول‌ها و پکیج‌ها

Streamlit: ساخت رابط کاربری وب با چند خط پایتون

۵ دقیقه مطالعه · به‌روزرسانی ۲۸ مهر ۱۴۰۵

حالا که بلدیم کتابخانه نصب کنیم، بیایید با یکی از آن‌ها کار جذابی بکنیم. تا اینجا برنامه‌هایمان با input() و print() در ترمینال کار می‌کردند. Streamlit کتابخانه‌ای است که با چند خط پایتون — بدون یک خط HTML یا جاوااسکریپت — یک صفحهٔ وب با کادر متن و دکمه می‌سازد.

به چنین کتابخانه‌ای سطح بالا می‌گویند: درگیر جزئیاتتان نمی‌کند. در عوض انعطاف کمتری از ابزارهای سطح‌پایین‌تر دارد؛ این یک معاملهٔ همیشگی در مهندسی نرم‌افزار است.

نصب

pip install streamlit

اگر ترمینال دستور pip را نشناخت، همان ترفند درس قبل:

python -m pip install streamlit

برای اطمینان از نصب:

pip freeze

باید خطی مثل streamlit==1.66.0 در خروجی ببینید (شمارهٔ نسخه ممکن است فرق کند).

اولین برنامه

Streamlit داخل نوت‌بوک اجرا نمی‌شود؛ باید یک فایل .py بسازید. اسمش را مثلاً 02_intro_streamlit.py بگذارید:

# in CMD: streamlit run 02_intro_streamlit.py
import streamlit as st

st.title("Test UI")

text = st.text_input("input:")

b = st.button("OK")

if b:
    if text:
        st.markdown(text)

خط به خط:

• st.title(...) یک عنوان بزرگ بالای صفحه می‌گذارد.
• st.text_input(...) یک کادر متن می‌سازد. متنی که داخل پرانتز می‌دهید برچسب بالای کادر است، و هرچه کاربر تایپ کند در متغیر text می‌نشیند.
• st.button("OK") یک دکمه می‌سازد و True/False برمی‌گرداند: لحظه‌ای که روی دکمه کلیک شود True است.
• if b: یعنی «اگر دکمه کلیک شد». if text: هم یعنی «اگر کادر خالی نیست» — همان ارزش بولی که رشتهٔ خالی را False و هر رشتهٔ دیگری را True حساب می‌کند.
• st.markdown(...) متن را در صفحه نمایش می‌دهد و قالب‌بندی Markdown را هم می‌فهمد: دو ستاره دور یک کلمه آن را پررنگ و یک ستاره ایتالیک می‌کند.

⚠️ print() در Streamlit به‌درد نمی‌خورد. چیزی که print می‌کنید در ترمینال چاپ می‌شود، نه در صفحهٔ وب. برای نمایش در صفحه از st.markdown (یا st.write) استفاده کنید.

اجرا

Streamlit با python file.py اجرا نمی‌شود. در ترمینال، در همان پوشه‌ای که فایل هست:

streamlit run 02_intro_streamlit.py

مرورگر خودش باز می‌شود و برنامه بالا می‌آید. نکتهٔ مهم: این صفحه روی کامپیوتر خودتان اجرا می‌شود و به اینترنت نیازی ندارد؛ فقط ظاهرش وب است.

برای متوقف‌کردنش در ترمینال Ctrl+C بزنید.

💡 بار اول: Streamlit در ترمینال یک پیام خوش‌آمد نشان می‌دهد و ایمیل می‌پرسد. اجباری نیست؛ فقط Enter بزنید تا رد شود. اگر مرورگر خودش باز نشد، آدرسی را که در ترمینال چاپ شده (معمولاً http://localhost:8501) در مرورگر باز کنید.

💡 اگر ترمینال streamlit را نشناخت، همان الگوی همیشگی: python -m streamlit run 02_intro_streamlit.py

هر بار که فایل را ذخیره کنید، Streamlit خودش متوجه تغییر می‌شود و گوشهٔ صفحه پیشنهاد می‌دهد دوباره اجرا کند.

مثال دوم: سلام با نام و نام خانوادگی

import streamlit as st

st.title("Test UI")

fname = st.text_input("input your firstname:")
lname = st.text_input("input your lastname:")

b = st.button("OK")

if b:
    if fname and lname:
        st.markdown(f"سلام آقا/خانم **{fname} {lname}**")

if fname and lname: یعنی هر دو کادر باید پر باشند. اگر می‌خواستید نام خانوادگی اختیاری باشد، if fname: کافی بود.

برای ساختن متن، f-string تمیزترین راه است. با + هم می‌شد، ولی خواندنش سخت‌تر است و باید حواستان به فاصله‌ها باشد:

st.markdown("سلام آقا/خانم " + "**" + fname + " " + lname + "**")

💡 یادتان باشد + فقط رشته را به رشته می‌چسباند. اگر یک طرف عدد باشد خطا می‌گیرید؛ در f-string این مشکل وجود ندارد.

مثال سوم: ضرب دو عدد

import streamlit as st

st.title("Test UI")

a = st.text_input("input 1st number:")
b = st.text_input("input 2nd number:")

button = st.button("OK")

if button:
    if a and b:
        a = float(a)
        b = float(b)
        st.markdown(f"result: {a * b}")

اینجا یک نکتهٔ مهم هست. چیزی که از st.text_input می‌گیرید همیشه رشته است، حتی اگر کاربر عدد تایپ کند — دقیقاً مثل input(). پس باید float() کنید.

ولی جای این تبدیل مهم است. اگر float(a) را بالاتر و بیرون از if بنویسید:

a = st.text_input("input 1st number:")
a = float(a)      # ← خطا

همان لحظهٔ اول که صفحه باز می‌شود و هنوز چیزی تایپ نشده، a رشتهٔ خالی است و می‌گیرید:

ValueError: could not convert string to float: ''

چون Streamlit کل فایل را از اول اجرا می‌کند، نه فقط وقتی دکمه زده شود. پس اول شرط، بعد تبدیل: تبدیل را داخل if بگذارید، جایی که مطمئن هستید کادرها پر است.

💡 برای عدد گرفتن، Streamlit خودش st.number_input را هم دارد که این دردسر را ندارد. ولی خوب است یک بار با همین text_input ساده کار کرده باشید.

اجرا با یک دابل‌کلیک

می‌خواهید برنامه را به کسی بدهید که بلد نیست ترمینال باز کند؟ در ویندوز یک فایل متنی بسازید، این خط را در آن بنویسید و اسمش را run.bat بگذارید:

streamlit run 03_streamlit_name_lastname.py

فایل .bat یعنی «این دستورها را در ترمینال اجرا کن». کاربر فقط دابل‌کلیک می‌کند و برنامه بالا می‌آید. (خیلی از فایل‌هایی که برایتان «اجراکننده» می‌فرستند دقیقاً همین‌اند: چند دستور پشت سر هم.)

چه چیزهای دیگری دارد؟

Streamlit المان‌های زیادی دارد که هرکدام یک خط کدند: st.slider، st.selectbox، st.radio، st.checkbox، st.file_uploader (برای آپلود فایل)، st.dataframe و نمودار. با همین چند تایی که دیدید می‌شود کلی چیز ساخت.

تمرین

یک برنامهٔ Streamlit بنویسید که دو عدد بگیرد و یک st.selectbox با گزینه‌های «جمع»، «تفریق» و «ضرب» داشته باشد؛ بعد از کلیک روی دکمه، نتیجهٔ عملیات انتخاب‌شده را نشان دهد.

import streamlit as st

st.title("ماشین‌حساب ساده")

a = st.text_input("عدد اول:")
b = st.text_input("عدد دوم:")

op = st.selectbox("عملیات:", ["جمع", "تفریق", "ضرب"])

if st.button("حساب کن"):
    if a and b:
        a = float(a)
        b = float(b)

        if op == "جمع":
            result = a + b
        elif op == "تفریق":
            result = a - b
        else:
            result = a * b

        st.markdown(f"**نتیجه:** {result}")
    else:
        st.markdown("هر دو عدد را وارد کنید.")