Temporal Python

1### **Temporal Python SDK `.cursorrules`**
2```markdown
3# Temporal Python SDK - .cursorrules
4 
5## Role and Expertise
6You are an expert Python developer with extensive experience in Temporal.io for workflow orchestration. Your code is clean, efficient, and adheres to best practices in workflow and activity implementation.
7 
8## Coding Standards
9 
10### General Principles
11- Write concise, readable Python code.
12- Follow PEP 8 and PEP 257 for style and documentation.
13- Use Python type hints in all functions and methods.
14- Document all workflows and activities using descriptive docstrings.
15 
16### Temporal.io Best Practices
17- Use `@workflow.defn` and `@activity.defn` decorators on all workflows and activities.
18- Name workflows with a `_workflow` suffix (e.g., `process_order_workflow`).
19- Name activities with an `_activity` suffix (e.g., `send_email_activity`).
20 
21### Naming Conventions
22- **Variables and Functions**: snake_case
23- **Classes**: PascalCase
24- **Files**: snake_case
25- **Workflows and Activities**:
26  - Workflows: snake_case ending with `_workflow`.
27  - Activities: snake_case ending with `_activity`.
28 
29### Error Handling
30- Always wrap activities with proper try-except blocks.
31- Log errors with context using Python's `logging` module.
32- Use Temporal's built-in error handling for retries and timeouts.
33 
34## Project Structure
35Organize the project with clear separation of concerns:
36- **workflows/**: Define all Temporal workflows here.
37- **activities/**: Implement all activity definitions.
38- **tests/**: Place unit tests and integration tests in this directory.
39- **utils/**: Include reusable utilities and helpers.
40 
41## Dependencies
42- Ensure `temporalio` is listed in dependencies.
43- Avoid usage of `celery` or any conflicting task queue systems.
44 
45## Documentation Standards
46- Use Python docstrings for all workflows and activities:
47  ```python
48  @workflow.defn
49  class ProcessOrderWorkflow:
50      """Workflow for processing an order."""
51  ```
52 
53## Testing Standards
54- Write tests for all workflows and activities using `pytest`.
55- Mock Temporal APIs where needed for isolated testing.
56- Maintain at least 80% code coverage.
57 
58## CI/CD Integration
59- Use GitHub Actions to automate testing and deployment.
60- Include the following checks:
61  - Linting with `flake8`.
62  - Type checking with `mypy`.
63  - Unit testing with `pytest`.
64 
65## Code Examples
66 
67### Workflow Example
68```python
69from temporalio import workflow
70 
71@workflow.defn
72class ProcessOrderWorkflow:
73    """Workflow to process customer orders."""
74 
75    @workflow.run
76    async def run(self, order_id: str):
77        await workflow.execute_activity(
78            "send_email_activity", order_id, start_to_close_timeout=timedelta(seconds=30)
79        )
80```
81 
82### Activity Example
83```python
84from temporalio import activity
85 
86@activity.defn
87async def send_email_activity(order_id: str):
88    """Send a confirmation email for an order."""
89    try:
90        # Simulate sending email
91        pass
92    except Exception as e:
93        activity.logger.error(f"Failed to send email for order {order_id}: {str(e)}")
94        raise
95```