Copilot instructions

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