command
/command
Definiuje komendę Protean, niezmienny DTO opisujący zamiar zmiany stanu agregatu, nazywany czasownikiem w trybie rozkazującym (PlaceOrder, RegisterUser, CancelReservation).
- Autor
- proteanhq ↗
- Repozytorium
- protean ↗
- Licencja
- Apache-2.0
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 11
- Skrypty
- 5
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 5 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: assets/command_inheritance.py, assets/command_simple.py, assets/command_validation.py, assets/command_with_value_object.py, assets/submitting_commands.py
Co robi i kiedy
Definiuje komendę Protean, niezmienny DTO opisujący zamiar zmiany stanu agregatu, nazywany czasownikiem w trybie rozkazującym (PlaceOrder, RegisterUser, CancelReservation).
Wyzwalacze z opisu
Oryginalny opis (EN)
Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "r
Jak działa
- Basic structure
- Key rules
- Fields and options
- Quick example
- Submitting commands
- Common mistakes
- Detailed references
- Verify your work
Podgląd SKILL.md
---
name: command
description: Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "register a user", "cancel a reservation"). Commands can be processed synchronously or asynchronously.
license: Apache-2.0
compatibility: Requires Python 3.11+, protean framework
metadata:
author: proteanhq
version: "0.1"
category: element
diagnostic_codes:
- COMMAND_NOT_IMPERATIVE
- UNUSED_COMMAND
---
# Command
A command carries one request to change one aggregate, and exactly one command handler processes it. This skill defines commands: fields, naming, and how to submit them.
## Basic structure
A command is defined using the `@domain.command(part_of="...")` decorator:
```python
from protean import Domain
from protean.fields import String, Identifier
domain = Domain()
@domain.aggregate
class Order:
customer_id: String(required=True)
@domain.command(part_of="Order")
class PlaceOrder:
order_id: Identifier(required=True)
customer_id: String(required=True)
product_id: String(required=True)
```
## Key rules
1. **Commands must be associated with aggregates**: Always specify `part_of` parameter with the aggregate name
2. **Commands are named with imperative verbs**: Use imperative mood: `PlaceOrder`, not `OrderPlaced`
3. **Commands are immutable**: Once created, commands cannot be modified
4. **Commands are DTOs**: Can contain simple fields and value objects, but NOT entities or aggregates (no HasOne, HasMany)
5. **Commands are unique**: Each command is unique throughout the domain
6. **One handler per command**: A command can only be processed by one command handler
7. **Commands carry intent**: They describe what should happen, not what happened (that is events)
8. **Commands have metadata**: Protean automatically adds timestamps, unique IDs, and versioning
9. **Commands are submitted via `domain.process()`**: The domain dispatches to the appropriate handler
10. **Commands support sync and async processing**: Controlled per-instance or via domain configuration
## Fields and options
| Field/Option | Purpose | Required |
|--------------|---------|----------|
| `part_of` | Associate command with an aggregate | Yes (unless abstract) |
| `abstract` | Mark as abstract base command | No |
| `__version__` | Schema version as positive integer (defaults to `1`) | No |
### Supported field types
```python
from protean.fields import (
String, Integer, Float, Boolean,
DateTime, Date, Identifier,
List, Dict, ValueObject,
)
```
Commands cannot use `HasOne`, `HasMany`, or `Reference` fields.
## Quick example
```python
from protean import Domain, handle
from protean.fields import DateTime, Decimal, Identifier, String
domain = Domain()
@domain.aggregate
class Order:
order_id: Identifier(identifier=True)
customer_id: String(required=True)
total_amount: Decimal(precision=19, scale=4)
@domain.command(part_of="Order")
class PlaceOrder:
order_id: Identifier(required=True)
customer_id: String(required=True)
total_amount: Decimal(precision=19, scale=4, required=True)
# Register the handler before init(); one registered after is not wired
@domain.command_handler(part_of="Order")
class OrderCommandHandler:
@handle(PlaceOrder)
def place_order(self, command: PlaceOrder):
order = Order(
order_id=command.order_id,
customer_id=command.customer_id,
total_amount=command.total_amount,
)
domain.repository_for(Order).add(order)
domain.init(traverse=False)
# Create and submit command
with domain.domain_context():
command = PlaceOrder(
order_id="ORD-001",
customer_id="CUST-123",
total_amount=99.99
)
domain.process(command)
```
## Submitting commands
Commands are submitted to the domain for processing:
```python
with domain.domain_context():
# Default processing (based on domain config, default is async)
domain.process(command)
# Explicit synchronous processing
domain.process(command, asynchronous=False)
# Explicit asynchronous processing
domain.process(command, asynchronous=True)
```
Domain-wide configuration:
```python
# In domain.toml
# command_processing = "sync" # or "async"
# In code
domain.config["command_processing"] = "sync"
```
## Common mistakes
### Including entities in commands
```python
# fragment
@domain.command(part_of="Order")
class PlaceOrder:
items = HasMany(OrderItem) # Wrong! Commands can't contain entities
```
Instead: Only fields and value objects
```python
@domain.value_object
class Money:
amount: Decimal(precision=19, scale=4, required=True)
currency: String(max_length=3, default="USD")
@domain.command(part_of="Order")
class PlaceOrder:
order_id: Identifier(required=True)
customer_id: String(required=True)
items: List() # Serialize as list of dicts
total = ValueObject(Money) # Value objects are allowed
```
### Trying to modify a command after creation
```python
# fragment
command = PlaceOrder(order_id="ORD-001", customer_id="CUST-123")
command.customer_id = "CUST-456" # Raises IncorrectUsageError!
```
Instead: Create a new command instance with the values you need.
### What `check` reports
`check` inspects your commands and reports these diagnostics:
- `COMMAND_NOT_IMPERATIVE`: the command is named in a mood that is not imperative (`OrderPlacement`), so it reads like data or an event. Rename it to a verb-first imperative phrase (`PlaceOrder`).
- `UNUSED_COMMAND`: the command has no registered handler, so nothing processes it. Add a command handler method for it, or remove the command if it is unused.
## Detailed references
### Core Concepts
- [Commands with Value Objects](references/with-value-objects.md): Using value objects in commands
- [Command Validation](references/command-validation.md): Field validation and error handling
- [Command Processing](references/command-processing.md): Synchronous and asynchronous processing
- [Command Inheritance](references/command-inheritance.md): Abstract commands and inheritance
- [Anti-patterns](references/anti-patterns.md): Common mistakes and how to avoid them
### Complete Examples
- [Simple Command](assets/command_simple.py): Basic commands with simple fields
- [Command with Value Objects](assets/command_with_value_object.py): Commands containing value objects
- [Command Validation](assets/command_validation.py): Field validation examples
- [Command Inheritance](assets/command_inheritance.py): Abstract base commands and inheritance
- [Submitting Commands](assets/submitting_commands.py): Command submission and processing
### Related Skills
- `aggregate`: Commands are always part of aggregates
- `command-handler`: How commands are processed
- `event`: Commands and events are complementary (commands = intent, events = result)
- `value-object`: Commands can contain value objects
- [CQRS](https://docs.proteanhq.com/concepts/architecture/cqrs/): Commands are the "C" in CQRS
## Verify your work
- [Verify with check](../../references/verify-with-check.md): run `check` and resolve what it reports
Pliki w paczce (11)
- SKILL.md 7 KB
- assets/command_inheritance.py 4 KB
- assets/command_simple.py 4 KB
- assets/command_validation.py 4 KB
- assets/command_with_value_object.py 5 KB
- assets/submitting_commands.py 4 KB
- references/anti-patterns.md 6 KB
- references/command-inheritance.md 3 KB
- references/command-processing.md 4 KB
- references/command-validation.md 4 KB
- references/with-value-objects.md 2 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · proteanhq/protean | 100 | Apache-2.0 |
| proteanhq/protean | 100 | Apache-2.0 |
Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.
Migawka bazy z 13.11.2026 · wersja paczki c74b2717db31 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.