Organizar os arquivos do seu app Streamlit

Quando você implanta um app no Streamlit in Snowflake, o arquivo de ponto de entrada do app pode ter qualquer nome que siga as convenções padrão de nomenclatura de arquivos e pode estar localizado em qualquer lugar no diretório de origem do app. O diretório de origem do app pode conter arquivos adicionais, como scripts de página, módulos Python, arquivos de mídia e arquivos de configuração.

A raiz do diretório de origem do seu app é o diretório de trabalho do Streamlit. Se você desenvolver e executar seu app localmente, isso significa que você deve executar o comando streamlit run a partir da raiz do seu diretório de origem para garantir que todos os caminhos estejam corretos.

Quando você inicializa um app Streamlit a partir do Snowsight ou usa CREATE STREAMLIT sem especificar uma localização de origem, a área de preparação incorporada do objeto Streamlit contém um arquivo de ponto de entrada na raiz. Você pode usar o explorador de arquivos para adicionar arquivos extras. Se precisar renomear ou mover seu arquivo de ponto de entrada, use os comandos SQL para atualizar o valor MAIN_FILE do seu objeto Streamlit.

Nota

Se você usar o comando CREATE STREAMLIT com o parâmetro ROOT_LOCATION, seu app só poderá usar um tempo de execução de warehouse e estará sujeito a limitações adicionais. Esta página aborda os apps criados com o parâmetro FROM. Para obter mais informações, consulte Explicação dos diferentes tipos de objetos Streamlit.

Estrutura de arquivos do tempo de execução de contêiner

Quando você usa um tempo de execução de contêiner, seu arquivo de ponto de entrada pode ter qualquer nome que siga as convenções padrão de nomenclatura de arquivos e pode estar localizado em qualquer lugar no seu diretório de origem. No entanto, com a introdução de st.navigation no Streamlit v1.36, a prática mais comum é usar streamlit_app.py como arquivo de ponto de entrada, pois os nomes das páginas não precisam ser inferidos a partir dos nomes dos arquivos.

O Snowflake executa o comando streamlit run a partir da raiz do diretório de origem; portanto, você deve lidar com os caminhos de acordo.

  • Seu arquivo de ponto de entrada pode ter qualquer nome e estar localizado em qualquer lugar no seu diretório de origem.

  • Seus arquivos de dependência podem estar em qualquer diretório entre a raiz do seu diretório de origem e o diretório que contém seu arquivo de ponto de entrada. Para obter mais informações, consulte Gerenciamento de dependências para o app Streamlit.

  • Você pode ter um ou mais diretórios .streamlit/ entre a raiz do seu diretório de origem e o diretório que contém seu arquivo de ponto de entrada.

  • A raiz do seu diretório de origem é o diretório de trabalho do Streamlit.

A estrutura de diretórios a seguir é válida para um app Streamlit de tempo de execução de contêiner:

source_directory/
├── .streamlit/           # Optional configuration
│   ├── config.toml
│   └── secrets.toml
├── page_1.py             # Page 1
├── page_2.py             # Page 2
├── pyproject.toml        # Python dependencies
├── streamlit_app.py      # Entrypoint file
└── uv.lock               # Auto-generated lockfile
Copy

A estrutura de diretórios a seguir mostra dois apps em um diretório de origem, cada um com o próprio arquivo de ponto de entrada e dependências. Neste exemplo, existem dois objetos Streamlit diferentes. Ambos os objetos Streamlit definem FROM para o local representado por source_directory, mas cada objeto define MAIN_FILE para um arquivo streamlit_app.py diferente. O primeiro app usa um arquivo pyproject.toml para dependências, enquanto o segundo usa um arquivo requirements.txt.

source_directory/
├── .streamlit/           # Shared configuration
│   ├── config.toml
│   └── secrets.toml
├── app_one/              # First app source directory
│   ├── .streamlit/       # Overriding first-app configuration
│   │   ├── config.toml
│   │   └── secrets.toml
│   ├── page_1.py
│   ├── page_2.py
│   ├── pyproject.toml     # Python dependencies for first app
│   ├── streamlit_app.py   # Entrypoint file for first app
│   └── uv.lock
├──  app_two/              # Second app source directory
│   ├── requirements.txt   # Python dependencies for second app
│   ├── page_1.py
│   ├── page_2.py
│   ├── streamlit_app.py   # Entrypoint file for second app
│   └── uv.lock
└── utils/                 # Shared modules
    └── helper.py
Copy

Importante

Alguns recursos do Streamlit exigem caminhos relativos ao diretório de trabalho, enquanto outros exigem caminhos relativos ao arquivo de ponto de entrada.

Normalmente, os caminhos para imagens e outras mídias dentro do seu app devem ser relativos ao diretório de trabalho (a raiz do seu diretório de origem). No entanto, os caminhos para outras páginas em um app com várias páginas são relativos ao local do arquivo de ponto de entrada.

Para evitar confusão, considere organizar os arquivos do seu app de forma que o arquivo de ponto de entrada esteja na raiz do seu diretório de origem. Você pode salvar vários apps em um repositório Git e passar um subdiretório para o parâmetro FROM ao criar o objeto Streamlit. Esse subdiretório será então o diretório de origem do seu app. No exemplo anterior, isso significa usar source_directory/app_one e source_directory/app_two no parâmetro FROM. Embora, nesse caso, os apps perderiam o acesso aos módulos compartilhados em source_directory/utils.

Estrutura de arquivos do tempo de execução de warehouse

Quando você usa um tempo de execução de warehouse, seu arquivo de ponto de entrada pode ter qualquer nome, mas deve estar localizado na raiz do seu diretório de origem. Sua versão do Python e as dependências são especificadas em um arquivo environment.yml na raiz do seu diretório de origem. Se você não incluir um arquivo environment.yml, seu app será executado na versão mais recente do Python e na versão mais recente do Streamlit compatíveis atualmente com o Streamlit in Snowflake. Se você usar o seletor de pacotes no Snowsight para adicionar pacotes, o arquivo environment.yml será atualizado ou criado automaticamente para você.

A estrutura de diretórios a seguir é válida para um app Streamlit de tempo de execução de warehouse:

source_directory/
├── .streamlit/           # Optional configuration
│   └── config.toml
├── environment.yml       # Conda dependencies
├── page_1.py
├── page_2.py
└── streamlit_app.py      # Entrypoint file
Copy

Importação de módulos e arquivos de outras áreas de preparação

Os comandos CREATE STREAMLIT e ALTER STREAMLIT são compatíveis com o parâmetro IMPORTS, que permite importar arquivos adicionais de outras áreas de preparação para o diretório de origem do seu app. Se você tiver um conjunto de módulos ou arquivos comuns que deseja compartilhar entre vários apps, poderá armazená-los em uma área de preparação e importá-los para cada app usando o parâmetro IMPORTS. No entanto, isso só é compatível com apps que usam um tempo de execução de warehouse.

Apps com várias páginas

O Streamlit tem dois métodos para criar apps com várias páginas:

  • Usando st.navigation: Você pode usar o comando st.navigation para criar uma estrutura de navegação personalizada em seu app. Isso permite definir páginas programaticamente e controlar o fluxo de navegação. O arquivo de ponto de entrada atua como um roteador de páginas, e as páginas do seu app podem ser definidas como funções ou scripts Python em qualquer lugar no diretório de origem. Esse é o método recomendado para criar apps com várias páginas, pois oferece a maior flexibilidade.

  • Uso de um diretório pages/: Você pode criar um diretório chamado pages/ adjacente ao arquivo de ponto de entrada do seu app. O arquivo de ponto de entrada é tratado como a página inicial do seu app. Cada arquivo Python no diretório pages/ é tratado como uma página adicional no app. Os nomes das páginas são derivados dos nomes dos arquivos.

Não é possível misturar os dois métodos para criar apps com várias páginas. Para obter mais informações sobre apps com várias páginas, consulte Visão geral de apps com várias páginas na documentação do Streamlit.

Nota

Quando você hospeda aplicativos de várias páginas no Streamlit in Snowflake, os nomes de caminho de URL são prefixados com /!. Por exemplo, se o caminho relativo para uma página for /page2 em um aplicativo de várias páginas, seu caminho relativo no Streamlit in Snowflake se tornará /!/page2, conforme mostrado no seguinte URL: https://app.snowflake.com/org/account_name/#/streamlit-apps/DB.SCHEMA.APP_NAME/!/page_2

Atualizar seu arquivo de ponto de entrada

Se você renomear ou mover seu arquivo de ponto de entrada, deverá usar os comandos SQL para atualizar seu objeto Streamlit para usar o arquivo novo. Você deverá usar um tempo de execução de contêiner se mover seu arquivo de ponto de entrada para um subdiretório.

  1. Use o comando ALTER STREAMLIT para alterar o parâmetro MAIN_FILE do seu objeto Streamlit, conforme mostrado no exemplo a seguir:

    ALTER STREAMLIT my_streamlit_app
SET MAIN_FILE = 'subdir/new_entrypoint.py';
    Copy

    Este exemplo altera o arquivo de ponto de entrada do objeto Streamlit my_streamlit_app para subdir/new_entrypoint.py.

Linguagem: Português