Cursor rule

1---
2description: Python App
3globs: **/*.py
4alwaysApply: false
5---
6## Python App
7 
8 
9- `app/lib/` is for code that is not specified to this application and with some effort could extracted into a external package.
10- `app/helpers` is for larger reusable modules that if they weren't specific to this application, could be extracted into their own package.
11- `app/utils` are small helper functions that are specific to a particular page or area of the application.
12- `app/__init__.py` is the entrypoint for the application which is run when _anything_ is executed (fastapi, celery, etc).
13  - It primarily runs `configure_*` commands for any `app.configuration.*` modules. These modules primary setup API clients, database connections, python language configuration, etc.
14  - Also makes sure anything that mutates global state loads early.
15- FastAPI server and routes are specified in `app/routes/`
16- SQLModels are specified in `app/models/`
17- Files within `app/commands/` should have:
18  - Are not designed for CLI execution, but instead are interactor-style internal commands.
19  - Should not be used on the queuing system
20  - A `perform` function that is the main entry point for the command.
21  - Look at existing commands for examples of how to structure the command.
22  - Use `TypeID` for any parameters that are IDs of models.
23- Files within `app/jobs/` should have:
24  - Are designed for use on the queuing system.
25  - A `perform` function that is the main entry point for the job.
26  - Look at existing jobs for examples of how to structure the job.
27  - Use `TypeID | str` for any parameters that are IDs of models.
28- When referencing a command, use the full-qualified name, e.g. `app.commands.transcript_deletion.perform`.
29- When queuing a job or `perform`ing it in a test, use the full-qualified name, e.g. `app.jobs.transcript_deletion.perform`.
30- `app/cli/` is for scripts or CLI tools that are specific to the application.
31 
32### Factories
33 
34globs: app/factories/**/.py
35 
36* Each model should get it's own file under app/factories/model_name.py
37* `ActiveModelFactory` (which is a polyfactory subclass) should be used.
38* Use `BaseFactory.__faker__` to generate more specific fake data for important fields (used in routes, etc)
39* Prefer `slug = BaseFactory.__faker__.unique.slug` to `slug = Use(lambda: BaseFactory.__faker__.unique.slug())`
40 
41#### Factory Example
42 
43```python
44class ScreeningFactory(ActiveModelFactory[Screening]):
45    funding_goal = lambda: BaseFactory.__faker__.random_int(
46        min=0, max=2000_00
47    )
48 
49    ticket_price = DEFAULT_TICKET_PRICE
50    status = ScreeningStatus.active
51 
52    # always None
53    funding_ending_at = None
54 
55    # pick entry from a fixed list
56    zip_code = lambda: BaseFactory.__faker__.random_element(elements=REAL_ZIP_CODES)
57 
58    host_name = BaseFactory.__faker__.name
59    host_description = lambda: BaseFactory.__faker__.paragraph(nb_sentences=2)
60 
61    # this method runs before the model is persisted to the database
62    @classmethod
63    def post_build(cls, model):
64      # if the user does not pass in a important relationship during creation, you can generate a factory fallback
65        if not model.distribution_id:
66            model.distribution_id = DistributionFactory.save().id
67 
68        return model.save()
69 
70    # runs after the model is persisted to the database
71    @classmethod
72    def post_save(cls, model):
73        return model.save()
74```
75 
76### Database & ORM
77 
78When accessing database records:
79 
80* SQLModel (wrapping SQLAlchemy) is used
81* `Model.one(primary_key)` or `Model.get(primary_key)` should be used to retrieve a single record
82* Do not manage database sessions, these are managed by a custom tool
83  * Use `TheModel(...).save()` to persist a record
84  * Use `TheModel.where(...).order_by(...)` to query records. `.where()` returns a SQLAlchemy select object that you can further customize the query.
85  * To iterate over the records, you'll need to end your query chain with `.all()` which returns an interator: `TheModel.where(...)...all()`
86* Instead of repulling a record `order = HostScreeningOrder.one(order.id)` refresh it using `order.refresh()`
87 
88When writing database models:
89 
90* Don't use `Field(...)` unless required (i.e. when specifying a JSON type for a `dict` or pydantic model using `Field(sa_type=JSONB)`). For instance, use `= None` instead of `= Field(default=None)`.
91* Add enum classes close to where they are used, unless they are used across multiple classes (then put them at the top of the file)
92* Use `ModelName.foreign_key()` when generating a foreign key field
93* Store currency as an integer, e.g. $1 = 100.
94* `before_save`, `after_save(self):`, `after_updated(self):` are lifecycle methods (modelled after ActiveRecord) you can use.
95 
96Example:
97 
98```python
99class Distribution(
100    BaseModel, TimestampsMixin, SoftDeletionMixin, table=True
101):
102    """Triple-quoted strings for multi-line class docstring"""
103 
104    id: TypeID[Literal["dst"]] = TypeIDPrimaryKey("dst")
105 
106    date_field_with_comment: datetime | None = None
107    "use a string under the field to add a comment about the field"
108 
109    # no need to add a comment about an obvious field; no need for line breaks if there are no field-level docstrings
110    title: str = Field(unique=True)
111    state: str
112 
113    optional_field: str | None = None
114 
115    # here's how relationships are constructed
116    doctor_id: TypeID = Doctor.foreign_key()
117    doctor: Doctor = Relationship()
118 
119    @computed_field
120    @property
121    def order_count(self) -> int:
122        return self.where(Order.distribution_id == self.id).count()
123```
124