create-pubsub-python

Files (2)

• REFERENCE.md
• SKILL.md

SKILL.md (first lines)

# 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

From diagrid-labs/dapr-skills, MIT.

More from diagrid-labs/dapr-skills