Project Creation And Default Structure
This document describes the default project structure of Seaplane applications. It assumes you have the Seaplane SDK and CLI tool installed. You can learn more about installation and setup here.
Creating A New Project​
To create a new Seaplane application run the following command inside your terminal. We recommend you set up a virtual environment to avoid dependency conflicts.
Create a virtual environment
Run the following commands to create a virtual environment. You can learn more about virtual environments here.
python3 -m venv my-seaplane-project source my-seaplane-project/bin/activate
seaplane init my-project-name
Seaplane automatically generates the default project structure and populates the
main.py
file with a "hello world" application.
Default Project structure And Files​
A default seaplane project consists of the following elements.
my-project-name/
├── my-project-name/
│ └── main.py
├── .env
└── pyproject.toml
The main my-project-name
directory contains all the files associated with this
project. Including a directory for the project's Python scripts, a
pyproject.toml
file for build configuration and a .env
file for declaring
project secrets.
Python File Directory​
Each Seaplane project requires another directory by the same name containing at
least one Python script indicated as the main Python script by the
pyproject.toml
file. You can learn more about the Pyproject file in the
section below.
The only requirement for the main Python script is that it includes the
start()
command. The init function generates a sample project with one file
main.py
containing the application, two tasks and the start command.
For larger projects, we recommend you define your @app
inside main.py
and
create a new file for each @task
. This enables easier collaboration and keeps the
project structured and easy to understand.
A sample project structure might look something like this.
my-project-name/
├── my-project-name/
├── database.py
│ ├── task1.py
│ ├── task2.py
│ ├── task3.py
│ └── main.py
├── .env
└── pyproject.toml
Pyproject​
The pyproject.toml
file is the main configuration file. It contains basic
information about your app and its dependencies, and it indicates which Python script
in your project contains the start command. More information on each section
below.
[tool.poetry]
- Includes the name, version and optionally a description and authors of the project.[tool.seaplane]
- Indicates which Python script includes thestart()
command. By default, it is set tomain.py
but you can use any Python script you like as long as it contains the start command.[tool.poetry.dependencies]
- This section should include all dependencies of your project. Add each dependency as a new line. To avoid dependency conflicts we recommend using loosely defined depedencies i.e'package>=1.0.0'
instead of'package==1.0.0'
[build-system]
- This section defines the build backend and relevant configuration options for building your project.
Environment Variables​
Use the .env
file to define application secrets. During deployment, Seaplane
automatically creates environment variables for all secrets defined in .env
.
Make sure you include the following line inside your .gitignore
file to avoid
pushing application secrets to your GitHub repository.
.env
You can load environment secrets inside your application using
os.getenv('SECRET_NAME')
. For example, assume you have the following .env
file.
DB_USERNAME=<YOUR-DB-USERNAME>
DB_PASSWORD=<YOUR-DB-PASSWORD>
DB_NAME=<YOUR-DB-NAME>
During deployment, Seaplane automatically creates the required secrets as
environment variables. You can load them inside a sql_access
object as
follows.
from seaplane import task
import os
# create a SQL access object
sql_access = {
"username": os.getenv('DB_USERNAME'),
"password": os.getenv('DB_PASSWORD'),
"database": os.getenv('DB_NAME')
}
@task(id='my-sql-task', sql=sql_access)
def my_sql_task(data, sql):
# run SQL queries
sql.execute("INSERT INTO my_table ....")