---
name: create-pubsub-python
description: Creates a Dapr pub/sub app in Python with FastAPI (publisher, subscriber or both) and declarative, programmatic or streaming subscriptions. Use for "create a pub/sub app in Python" or "build a FastAPI publisher and subscriber with Dapr". For an existing app use add-pubsub-python.
allowed-tools:
  - Write
  - Edit
  - Bash(diagrid-dev-dashboard --version)
---

# Create Dapr Pub/Sub Python Application

## Overview

This skill creates a Dapr pub/sub application in Python: a FastAPI publisher, a subscriber or both, sharing the message contract the user described and one `dapr.yaml`. The subscriber uses a declarative (default), programmatic or streaming subscription.

The application is built from the user's own domain. There is no built-in sample scenario: the event, its fields, its topic and what the subscriber does with it all come from the **Check specification** interview, and every template is filled in from the placeholder vocabulary in [`../dapr-shared/pubsub-placeholders.md`](../dapr-shared/pubsub-placeholders.md).

## Execution Order

You MUST follow these phases in strict order:
1. **Check specification** - Check if the user specified what needs to be built; infer first, then ask.
2. **Check optional tools** — Check whether the Diagrid Dapr Dev Dashboard is installed and remember the result. Never stop, ask or install for this.
3. **Project Setup** — Create all files and folders.
4. **Verify** — Verify that the project installs and compiles.
5. **Create README.md** — Create a readme that summarizes what is built and how to run & test the application. Do not provide instructions at the end of this phase.
6. **Show final message** - Your LAST output MUST be EXACTLY the message defined in the `## Show final message` section: the closing sentence followed by the Dev Dashboard recommendation. Do NOT add any other text, summary, or commentary.

## Prerequisites

The following must be installed by the user before this skill can run. Do not run the check-prereq skills; assume the prerequisites are installed.

- [Python 3.12+](https://www.python.org/downloads/)
- [uv](https://docs.astral.sh/uv/getting-started/installation/) (Astral)
- [Docker](https://www.docker.com/products/docker-desktop/) or [Podman](https://podman.io/docs/installation)
- [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) 1.18+

Python packages (handled during project setup): `dapr` 1.18.3, `dapr-ext-fastapi` 1.18.3 (programmatic subscriber only), `fastapi` 0.118.2, `pydantic` 2.12.0, `uvicorn` 0.37.0. Optional: the [Diagrid Dapr Dev Dashboard](https://github.com/diagridio/dev-dashboard).

Background on delivery guarantees, CloudEvents and the subscription types: [`../dapr-shared/pubsub-concepts.md`](../dapr-shared/pubsub-concepts.md).
Placeholder vocabulary used by every template: [`../dapr-shared/pubsub-placeholders.md`](../dapr-shared/pubsub-placeholders.md).

## Check specification

**Never build a default scenario.** The application is about the user's domain, and the templates are
placeholders waiting for it. Infer everything the prompt already says, then ask only what is missing, one
question at a time, waiting for each answer. If the prompt gives no domain at all, ask for it — do not
invent one and do not fall back to an order-processing example.

Domain, first:

1. "What is the purpose of this pub/sub application?"
2. "Which event does it publish, and on which topic?" Accept several if the user describes several; one is
   the normal case. The topic name is lowercase and hyphenated; the event type is PascalCase.
3. For each event: "Which fields does the message carry, and which one uniquely identifies it?" The
   identifying field becomes `<id_field>`: the handler deduplicates on it, so there must be exactly one per
   event. Ask for the type of each field when the name does not make it obvious, and note any constraint
   the domain implies — it becomes a Pydantic `Field(...)` rule.
4. "What should the subscriber do when it receives this event?" If the user wants nothing beyond receiving
   it, say that the handler will log it and move on; never invent a side effect.

Then the wiring:

5. "Should this app publish, subscribe, or both? (default: both)"
6. Only if the role includes a subscriber: "Which subscription type? **declarative** (default — a Subscription YAML file, no Dapr code in the subscriber), **programmatic** (`DaprApp(app).subscribe(...)` in code) or **streaming** (the app pulls messages; no inbound port)". Inference: "streaming", "no inbound port" or "pull" → streaming; "programmatic", `DaprApp` or "dapr-ext-fastapi" → programmatic; "declarative" or "subscription YAML" → declarative.
7. The name of the project (no spaces). It becomes `<ProjectRoot>` (the folder) and `<root-kebab>` (lowercase, hyphen-separated, used for app ids and package names).

There is no hosting or style question: Python uses `dapr run` and FastAPI.

Feature rules:

- The dead-letter topic (`<TopicName>-deadletter`) is on unless the user declines, and always comes with the inbound retry policy.
- Content-based routing, message TTL and raw payload are added only when the user mentions them (see `REFERENCE.md` → **Routing, TTL and raw payload**).
- The broker is always Redis locally. If the user names another broker (for example Kafka), still scaffold Redis and explain in the README how to switch (see **Create README.md**).
- Routing with a streaming subscriber → ask: "Streaming subscriptions cannot route by content. Use a declarative subscription for this topic instead? (default: yes)".
- Routing with a programmatic subscriber → ask: "dapr-ext-fastapi cannot route by content. Use a declarative subscription for this topic instead? (default: yes)".

### Resolving the placeholders

Before creating any file, write out the resolved values and restate them to the user in two or three
lines, so a wrong reading is caught before it is scaffolded. Resolve them exactly as
[`../dapr-shared/pubsub-placeholders.md`](../dapr-shared/pubsub-placeholders.md) defines them:

| Placeholder | Resolved from |
|---|---|
| `<EventName>`, `<event_fields>`, `<id_field>` | questions 2 and 3 |
| `<event_name>`, `<EventDescription>` | `<EventName>`, in snake_case and as a lowercase noun phrase |
| `<TopicName>`, `<DeadLetterTopicName>` | question 2; the dead-letter topic is `<TopicName>-deadletter` |
| `<TOPIC_CONST>`, `<DEAD_LETTER_TOPIC_CONST>` | UPPER_SNAKE_CASE of `<TopicName>` |
| `<publish_route>`, `<subscribe_route>`, `<dead_letter_route>` | `<TopicName>`; the subscribe route is `/events/pubsub/<TopicName>` |
| `<validation_condition>`, `<handler_body>` | questions 3 and 4 |

Fixed, never derived from the domain: the component name `pubsub`, the constant `PUBSUB_NAME`, and the
`_processed_event_ids` idempotency set.

## Check optional tools

Check once whether the optional Diagrid Dapr Dev Dashboard is installed by following the **Check** section of [`../dapr-shared/dev-dashboard.md`](../dapr-shared/dev-dashboard.md) (`diagrid-dev-dashboard --version`). Remember the result (`DevDashboardInstalled`) for the final message. This check never stops the skill: do not ask the user about it, do not install anything, and continue whether or not the dashboard is installed.

## Project Setup

Create the project root folder inside the current location where the terminal is open:

```shell
mkdir <ProjectRoot>
cd <ProjectRoot>
```

### Folder structure

Role both (a uv workspace; `subscription.yaml` only for declarative). A single role is one service folder with `models.py` and no workspace; replace `from contracts import` with `from models import` in the handler, publisher and streaming blocks (they import `contracts` in the workspace layout). See `REFERENCE.md` → **Folder structures**.

```
<ProjectRoot>/
├── .gitignore
├── pyproject.toml
├── dapr.yaml
├── pubsub.http
├── README.md
├── resources/
│   ├── pubsub.yaml
│   ├── resiliency.yaml
│   └── subscription.yaml
├── contracts/
│   ├── pyproject.toml
│   └── contracts/__init__.py
├── publisher/
│   ├── pyproject.toml
│   └── main.py
└── subscriber/
    ├── pyproject.toml
    ├── main.py
    └── handler.py
```

A streaming subscriber has `main.py` and `streaming.py` instead of `handler.py`, and no `resources/subscription.yaml`.

### Files

Copy each file from its shared file and replace every placeholder with the value resolved in **Resolving
the placeholders**. A file is never written with a placeholder left in it: after writing each one, check it
for a stray `<` ... `>`. Ports: publisher `appPort` 8001 / `daprHTTPPort` 3501, subscriber `appPort` 8002 /
`daprHTTPPort` 3502.

- **`.gitignore`**: Python style, from https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Python.gitignore.
- **`pyproject.toml` files** (workspace root, `contracts`, services): [`../dapr-shared/python-pubsub-project.md`](../dapr-shared/python-pubsub-project.md). Take the subscriber dependencies from its table for the chosen type (declarative has no `dapr`; programmatic adds `dapr-ext-fastapi`; streaming has no FastAPI).
- **`dapr.yaml`**: [`../dapr-shared/pubsub-dapr-yaml.md`](../dapr-shared/pubsub-dapr-yaml.md) (Python block). The `appID` values are `<root-kebab>-publisher` and `<root-kebab>-subscriber`. Omit `appPort` for a streaming-only subscriber; keep it for declarative and programmatic subscribers.
- **`resources/pubsub.yaml`**: [`../dapr-shared/dapr-pubsub-redis.md`](../dapr-shared/dapr-pubsub-redis.md).
- **`resources/resiliency.yaml`**: [`../dapr-shared/dapr-pubsub-resiliency.md`](../dapr-shared/dapr-pubsub-resiliency.md) (dead-letter on).
- **`resources/subscription.yaml`** (declarative only): [`../dapr-shared/dapr-pubsub-subscription.md`](../dapr-shared/dapr-pubsub-subscription.md). `scopes` must be exactly the subscriber `appID`, `<root-kebab>-subscriber`.
- **Contracts**: [`../dapr-shared/python-pubsub-publisher.md`](../dapr-shared/python-pubsub-publisher.md) → **Contracts**.
- **Publisher `main.py`**: [`../dapr-shared/python-pubsub-publisher.md`](../dapr-shared/python-pubsub-publisher.md) → **Publish endpoint**.
- **Subscriber**, by type:
  - declarative: [`../dapr-shared/python-pubsub-subscriber-declarative.md`](../dapr-shared/python-pubsub-subscriber-declarative.md) plus `handler.py` from [`../dapr-shared/python-pubsub-handler.md`](../dapr-shared/python-pubsub-handler.md);
  - programmatic: [`../dapr-shared/python-pubsub-subscriber-programmatic.md`](../dapr-shared/python-pubsub-subscriber-programmatic.md) plus the same `handler.py`;
  - streaming: [`../dapr-shared/python-pubsub-subscriber-streaming.md`](../dapr-shared/python-pubsub-subscriber-streaming.md) → **Standalone subscriber (create)** (`streaming.py` and `main.py`, no handler file).
- **Optional features**: routing (declarative only), TTL and raw payload per `REFERENCE.md` → **Routing, TTL and raw payload**.
- **`pubsub.http`**: [`../dapr-shared/pubsub-local-http.md`](../dapr-shared/pubsub-local-http.md), Python variant (snake_case keys, ports 8001, 8002, 3501).

Rules that matter:

- One subscription type per topic per app. Never combine `subscription.yaml` with `DaprApp` or `subscribe_with_handler` for the same topic.
- The subscriber answers `{"status": ...}` and never returns 404 (Dapr drops the message).
- Raw payload metadata key is `rawPayload`.

## Verify

**IMPORTANT: After Project Setup you MUST run these exact verification instructions:**

1. Role both: run `uv sync --all-packages` in `<ProjectRoot>`. Single role: run `uv sync` in the service folder.
2. Run `uv run python -m compileall -q <service folders>` (for example `contracts publisher subscriber`). It must exit with code 0.
3. Fix any error and re-run.
4. Remove any `__pycache__` folders created by the compile step.

## Create README.md

**IMPORTANT: After Verify you MUST run these instructions:**

Create a README.md file inside the <ProjectRoot> folder. See `REFERENCE.md` → **README key points**. It contains:

1. Summary of what this folder contains.
2. Architecture: what the application does in the user's own domain terms, the roles, the subscription type and why, and a mermaid sequence diagram showing who opens the connection (sidecar push for declarative and programmatic, app pull for streaming). **DO NOT suggest to run Redis separately; `dapr init` provides it and it is already running in a container.**
3. How to run: `dapr run -f .` from the project root, and how to try it with curl plus a link to `pubsub.http`.
4. How to see subscriptions: `GET http://localhost:3502/v1.0/metadata` and the Dev Dashboard's subscriptions view.
5. Declarative only: the subscription hot-reloads.
6. The local-only items: Redis without a password, no component scopes, no stream trimming. Add a "Switching the message broker" paragraph. It MUST contain the link https://docs.dapr.io/reference/components-reference/supported-pubsub/ and MUST say that `resources/pubsub.yaml` is replaced while `metadata.name: pubsub` stays the same, so no code changes. A heading with no paragraph, or a paragraph without that link, is incomplete. See `REFERENCE.md` → **README key points** for the full wording.
7. The **Diagrid Dapr Dev Dashboard** section from the **README section** of [`../dapr-shared/dev-dashboard.md`](../dapr-shared/dev-dashboard.md).
8. Running with Diagrid Catalyst, from [`../dapr-shared/running-with-catalyst.md`](../dapr-shared/running-with-catalyst.md) (`<ProjectName>` is `<root-kebab>`).
9. Next steps: the review skills `review-pubsub-publishing`, `review-pubsub-subscriptions` and `review-pubsub-components`.

## Show final message

**IMPORTANT: This is the LAST step. After Create README.md, your final output MUST be ONLY the message below followed by the Dev Dashboard recommendation — no preamble, no summary, no additional commentary, only replace the <ProjectRoot> with the actual value:**

The <ProjectRoot> pub/sub application is created. Open the README.md file in the <ProjectRoot> folder for a summary and instructions for running locally.

Then add, as a separate paragraph, the block from the **Final recommendation** section of [`../dapr-shared/dev-dashboard.md`](../dapr-shared/dev-dashboard.md) that matches `DevDashboardInstalled`. Use it as written. Nothing may follow it.