Plane Python SDK Examples
This directory contains practical examples demonstrating how to use the Plane Python SDK.
Before running these examples, ensure you have:
- Installed the Plane Python SDK:
pip install plane-sdk
- Set up your environment variables:
export PLANE_BASE_URL="https://api.plane.so"
export PLANE_API_KEY="your-api-key"
export WORKSPACE_SLUG="your-workspace-slug"
See SETUP.md for detailed setup instructions.
1. Project Setup (setup_project.py)
Sets up a complete project with all necessary configurations:
- Creates a new project
- Creates work item types (Bug, Feature, Task, Story)
- Creates workflow states (Backlog, To Do, In Progress, In Review, Done, Cancelled)
- Creates labels for categorization
Run:
python examples/setup_project.py
Use this when:
- Starting a new project
- You need to configure work item types, states, and labels
- Setting up a standardized project structure
2. Create Work Items (create_work_items.py)
Creates a basic project and populates it with work items:
- Creates a simple project
- Sets up basic states (To Do, In Progress, Done)
- Creates a few labels
- Creates multiple work items with different priorities
- Lists all work items in the project
Run:
python examples/create_work_items.py
Use this when:
- You want a quick project setup
- You need to create and track work items
- Getting started with the SDK
3. OAuth Authentication (oauth_example.py)
Demonstrates OAuth 2.0 authentication flows:
- Authorization code flow (for web applications)
- Client credentials flow (for server-to-server)
- Bot token generation (for workspace app installations)
- Token refresh and revocation
- Error handling with OAuth
Run:
# Set OAuth environment variables
export OAUTH_CLIENT_ID="your_client_id"
export OAUTH_CLIENT_SECRET="your_client_secret"
export APP_INSTALLATION_ID="optional_installation_id" # For bot token
python examples/oauth_example.py
Use this when:
- Building web applications that need user authorization
- Implementing server-to-server authentication
- Creating workspace app integrations with bot tokens
- Managing OAuth token lifecycle
- Set up environment variables (see SETUP.md):
export PLANE_BASE_URL="https://api.plane.so"
export PLANE_API_KEY="your-api-key"
export WORKSPACE_SLUG="your-workspace-slug"
- Run an example:
# Full project setup with types, states, and labels
python examples/setup_project.py
# Or create a simple project with work items
python examples/create_work_items.py
import os
from plane.client import PlaneClient
client = PlaneClient(
base_url=os.environ["PLANE_BASE_URL"],
api_key=os.environ["PLANE_API_KEY"]
)
from plane.models.projects import CreateProject
project = client.projects.create(
workspace_slug="my-workspace",
data=CreateProject(
name="My Project",
identifier="MP",
description="Project description"
)
)
from plane.models.states import CreateState
state = client.states.create(
workspace_slug="my-workspace",
project_id=project.id,
data=CreateState(
name="In Progress",
group="started",
color="#f59e0b"
)
)
from plane.models.work_items import CreateWorkItem
work_item = client.work_items.create(
workspace_slug="my-workspace",
project_id=project.id,
data=CreateWorkItem(
name="Fix bug",
description_html="<p>Description here</p>",
state_id=state.id,
priority="high"
)
)
Always handle potential errors when using the SDK:
from plane.errors import HttpError, ConfigurationError
try:
project = client.projects.create(workspace_slug, data=project_data)
except HttpError as e:
print(f"HTTP error {e.status_code}: {e}")
except ConfigurationError as e:
print(f"Configuration error: {e}")
After running the examples:
- Explore the SDK documentation for more features
- Check the Plane API documentation for details
- Build your own integrations using these examples as templates