До этого момента мы работали с заранее подготовленными файлами. CSV находился внутри проекта, мы точно знали его структуру и могли спокойно строить графики, таблицы и фильтры. Но в реальной жизни dashboards редко работают только с заранее известными данными.

Представьте, что вы сделали красивое приложение и хотите показать его коллегам. Скорее всего, они захотят загрузить собственный файл. Один пользователь принесёт отчёт по продажам, другой — выгрузку клиентов, третий — данные из Excel. Если приложение умеет работать только с одним конкретным CSV-файлом, его практическая ценность будет довольно ограниченной. Поэтому одна из самых важных возможностей Streamlit — загрузка пользовательских файлов.

Именно в этот момент dashboard превращается из демонстрационного примера в универсальный инструмент. Пользователь может самостоятельно загрузить данные, посмотреть их содержимое, проверить структуру и начать анализировать информацию без изменения кода приложения.

Однако вместе с этим появляются новые задачи. Пользователь может загрузить неправильный файл, случайно выбрать не тот формат или передать таблицу с неожиданной структурой. Поэтому хороший dashboard должен не только принимать файлы, но и уметь корректно обрабатывать ошибки.

В этом уроке мы научимся работать с загрузкой CSV и Excel-файлов, познакомимся с компонентом file_uploader, разберём загрузку нескольких файлов, научимся показывать preview данных и реализуем базовую проверку структуры загружаемых таблиц.

К концу урока наше приложение сможет работать уже не только с заранее подготовленным набором данных, но и с файлами, которые загружает сам пользователь.

Что вы узнаете в рамках статьи

В этом уроке мы научимся принимать пользовательские файлы через интерфейс Streamlit и работать с ними через Pandas.

Мы разберём:

• компонент file_uploader;
• загрузку CSV-файлов;
• загрузку Excel-файлов;
• работу с несколькими файлами;
• отображение предварительного просмотра данных;
• обработку ошибок;
• проверку структуры таблиц.

В результате приложение станет значительно более универсальным и сможет работать с данными из разных источников.

Ключевые термины

• file_uploader — компонент Streamlit для загрузки файлов через интерфейс приложения.
• Preview данных — предварительный просмотр содержимого файла.
• CSV — текстовый формат хранения табличных данных.
• Excel — формат электронных таблиц Microsoft Excel.
• Валидация данных — проверка структуры и содержимого загружаемого файла.
• Обработка ошибок — механизм корректной реакции приложения на некорректные действия пользователя.

Почему загрузка файлов так важна

Представьте, что вы сделали dashboard для анализа продаж. Пока данные лежат внутри проекта, всё работает отлично. Но как только приложение попадает к другим людям, возникает очевидный вопрос: А как загрузить собственный файл?

Именно поэтому большинство аналитических приложений начинается с кнопки загрузки данных. Пользователь выбирает файл, приложение читает его содержимое, а затем строит таблицы, графики и показатели уже на основе загруженной информации.

Первый file_uploader

Для загрузки файлов используется компонент file_uploader.

Простейший пример выглядит так:

uploaded_file = st.file_uploader(
    "Выберите CSV файл"
)

После запуска приложения на странице появится область для выбора файла. Важно понимать, что до тех пор, пока пользователь ничего не загрузил, переменная uploaded_file будет содержать значение None.

Поэтому обычно добавляют проверку:

if uploaded_file is not None:
    st.write("Файл загружен")

Ограничиваем допустимые форматы

Часто приложение должно принимать только определённые типы файлов.

Например:

uploaded_file = st.file_uploader(
    "Выберите CSV файл",
    type=["csv"]
)

Теперь пользователь сможет выбирать только CSV-файлы. Такой подход помогает избежать многих ошибок ещё до загрузки данных.

Загрузка CSV через Pandas

После получения файла его можно сразу передать в Pandas.

if uploaded_file is not None:

    df = pd.read_csv(
        uploaded_file
    )

    st.dataframe(df)

Обратите внимание, что file_uploader возвращает объект файла, который Pandas умеет читать напрямую. Сохранять его на диск при этом не требуется.

Однако на практике часто возникает другая задача — использовать загруженные данные на нескольких страницах приложения. Если просто сохранить DataFrame в локальную переменную, он будет доступен только в рамках текущего запуска скрипта.

Для таких случаев удобно использовать session_state.

if uploaded_file is not None:

    st.session_state["df"] = pd.read_csv(
        uploaded_file
    )

    st.dataframe(
        st.session_state["df"]
    )

Теперь загруженная таблица сохраняется в состоянии приложения и может использоваться на других страницах dashboard.

Например, в файле из папки pages можно получить доступ к этим данным следующим образом:

if "df" in st.session_state:

    df = st.session_state["df"]

    st.dataframe(df)

Такой подход особенно полезен в многостраничных приложениях, где загрузка файла выполняется один раз, а дальнейшая работа с данными происходит в разных разделах dashboard.

Preview данных

Очень часто после загрузки файла пользователю хочется быстро убедиться, что всё считалось правильно. Полностью выводить огромную таблицу не всегда удобно.

Поэтому часто показывают только первые строки:

st.dataframe(
    df.head()
)

Такой подход называют preview данных. Он позволяет быстро убедиться, что файл загрузился корректно, проверить названия столбцов, посмотреть типы данных и вовремя заметить возможные ошибки в содержимом таблицы.

Работа с Excel

Во многих компаниях данные хранятся именно в Excel. К счастью, Pandas умеет работать и с этим форматом.

Для начала понадобится установить дополнительную библиотеку:

pip install openpyxl

После этого Excel-файл можно прочитать так:

df = pd.read_excel(
    uploaded_file
)

С точки зрения дальнейшей работы разницы практически нет. После загрузки мы всё так же получаем обычный DataFrame.

Поддержка нескольких форматов

Иногда удобно принимать сразу несколько типов файлов.

Например:

uploaded_file = st.file_uploader(
    "Выберите файл",
    type=["csv", "xlsx"]
)

После этого можно определить тип файла и выбрать подходящий способ чтения.

if uploaded_file.name.endswith(".csv"):
    df = pd.read_csv(uploaded_file)
else:
    df = pd.read_excel(uploaded_file)

Загрузка нескольких файлов

Иногда одного файла недостаточно. Например, продажи могут находиться в одной таблице, клиенты — в другой, а товары — в третьей. В таких случаях можно разрешить множественную загрузку.

files = st.file_uploader(
    "Выберите файлы",
    accept_multiple_files=True
)

Теперь пользователь сможет выбрать сразу несколько файлов.

Далее их можно обрабатывать в цикле:

for file in files:
    st.write(file.name)

Проверяем структуру файла

Одна из самых частых ошибок возникает тогда, когда пользователь загружает таблицу с неожиданными столбцами. Например, приложение ожидает: product, price, category, а пользователь загружает совершенно другой файл.

Поэтому перед анализом данных полезно проверять структуру.

Например:

required_columns = [
    "product",
    "price",
    "category"
]

Теперь можно проверить наличие всех столбцов:

if not all(column in df.columns for column in required_columns):
    st.error("Некорректная структура файла")

Обработка ошибок

Даже если пользователь выбрал правильный файл, ошибки всё равно возможны. Например, пользователь может загрузить повреждённый CSV-файл, пустую Excel-таблицу или файл с неподходящей кодировкой. Поэтому чтение файлов часто помещают в блок try/except.

try:
    df = pd.read_csv(
        uploaded_file
    )

except Exception:
    st.error(
        "Не удалось прочитать файл"
    )

Так приложение будет вести себя намного стабильнее.

Создаём универсальный загрузчик

Теперь объединим всё вместе.

uploaded_file = st.file_uploader(
    "Выберите файл",
    type=["csv", "xlsx"]
)

if uploaded_file is not None:

    try:
        if uploaded_file.name.endswith(".csv"):
            df = pd.read_csv(uploaded_file)
        else:
            df = pd.read_excel(uploaded_file)

        st.dataframe(df.head())

    except Exception:
        st.error("Ошибка чтения файла")

Получается универсальный механизм загрузки данных, который уже можно использовать во многих реальных проектах.

Наиболее частые ошибки

• Пользователь загружает файл неподдерживаемого формата
  Стоит заранее ограничивать допустимые расширения через параметр type.
• Приложение ожидает одни столбцы, а получает другие
  Перед обработкой данных полезно выполнять проверку структуры таблицы.
• Ошибки при чтении Excel-файлов
  Обычно связаны с отсутствием библиотеки openpyxl.
• Попытка работать с файлом до загрузки
  Перед чтением всегда стоит проверять, что uploaded_file не содержит значение None.

Наиболее частые вопросы

• Можно ли загружать несколько файлов одновременно? 
  Да, для этого используется параметр accept_multiple_files=True.
• Обязательно ли поддерживать Excel?
  Нет, но на практике пользователи очень часто работают именно с этим форматом.
• Можно ли загружать файлы других типов?
  Да, file_uploader поддерживает множество различных расширений.
• Нужно ли сохранять файл на диск перед чтением?
  Нет, Pandas может работать с объектом файла напрямую.

Итоги

Сегодня мы сделали приложение значительно более универсальным. Теперь dashboard умеет принимать пользовательские файлы, работать с CSV и Excel, отображать предварительный просмотр данных и проверять структуру загружаемых таблиц.

Кроме того, мы познакомились с обработкой ошибок и увидели, насколько важно предусматривать ситуации, когда пользователь загружает неправильные или повреждённые файлы.

Благодаря этим возможностям приложение перестаёт зависеть от заранее подготовленного набора данных и превращается в универсальный инструмент для анализа информации из различных источников.