You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
CI will validate that the lockfile and environment are consistent. If you forgot to update the lockfile, the PR will fail with a clear error.
180
180
181
+
---
182
+
183
+
## Type Safety Practices
184
+
185
+
Python is a dynamically typed language. This flexibility makes Python productive and expressive, but it also increases the risk of subtle bugs caused by incorrect function calls, unexpected None values, or inconsistent data structures.To balance flexibility with long-term maintainability we use [Pyright](https://microsoft.github.io/pyright) for CI level type-checking.
186
+
187
+
We run Pyright in `standard` mode. This mode provides strong type correctness guarantees without requiring the full strictness and annotation overhead of `strict` mode.
188
+
189
+
You can check the exact type checking constraints enforced in `standard` mode here in the `Diagnostic Defaults` section of the [Pyright documentation](https://microsoft.github.io/pyright/#/configuration?id=diagnostic-settings-defaults).
190
+
191
+
`standard` mode in Pyright is chosen because it enforces the following principles:
192
+
193
+
-**Catch real bugs early** - It prevents incorrect function calls, invalid attribute access, misuse of Optional values, inconsistent overloads, and a wide range of type errors that would otherwise only appear at runtime.
194
+
195
+
-**Maintain clarity without excessive annotation burden** - Developers are not expected to annotate every variable or build fully typed signatures for every function. Pyright uses inference aggressively, and `standard` mode focuses on correctness where types are known or inferred.
196
+
197
+
-**Work seamlessly with third-party libraries** - Many Python libraries ship without type stubs. In `standard` mode, these imports are treated as Any, allowing us to use them without blocking type checks while still preserving type safety inside our own code.
198
+
199
+
### Runtime Type Safety at System Boundaries
200
+
201
+
While Pyright provides excellent static type checking during development, **system boundaries** require additional runtime validation. These are points where our Python code interfaces with external systems, user input, or network requests where data types cannot be guaranteed at compile time.
202
+
203
+
In this project, we use **Pydantic** for rigorous runtime type checking at these critical handover points:
204
+
205
+
#### FastAPI Endpoints
206
+
All FastAPI route handlers use Pydantic models for request/response validation:
207
+
- Request bodies are validated against Pydantic schemas
208
+
- Query parameters and path parameters are type-checked at runtime
209
+
- Response models ensure consistent API contract enforcement
210
+
```python
211
+
# Example: API endpoint with Pydantic validation
212
+
from pydantic import BaseModel
213
+
from fastapi import FastAPI
214
+
215
+
classUserRequest(BaseModel):
216
+
name: str
217
+
age: int
218
+
219
+
@app.post("/users")
220
+
asyncdefcreate_user(user: UserRequest):
221
+
# Pydantic validates name is string, age is int
222
+
# Invalid data raises 422 before reaching this code
223
+
return {"id": 1, "name": user.name}
224
+
```
225
+
226
+
This dual approach of **static type checking with Pyright** + **runtime validation with Pydantic** ensures both development-time correctness and production-time reliability at system boundaries where type safety cannot be statically guaranteed.
227
+
228
+
**Note: Type checks are only run on core source code and not on test-cases**
229
+
230
+
## Linter Rules
231
+
232
+
Consistent linting is essential for maintaining a reliable and scalable code-base. By adhering to a well-defined linter configuration, we ensure the code remains readable, secure, and predictable even as the project evolves.
233
+
234
+
The following set of rules are enabled in this repository. Linter rules are enforced automatically through the CI pipeline and must pass before merging changes into the `wip`, `dev`, or `main` branches.
235
+
.
236
+
237
+
Each category is summarized with a description and a link to the Ruff documentation explaining these rules.
238
+
239
+
### Selected Linter Rule Categories
240
+
241
+
#### E4, E7, E9 — Pycodestyle Error Rules
242
+
243
+
These check for fundamental correctness issues such as import formatting, indentation, and syntax problems that would otherwise cause runtime failures.
Static analysis rules that detect real bug patterns such as unused variables, unused imports, undefined names, duplicate definitions, and logical mistakes that can cause bugs.
257
+
258
+
(https://docs.astral.sh/ruff/rules/#pyflakes-f)
259
+
260
+
#### B — Flake8-Bugbear
261
+
262
+
A set of high-value checks for common Python pitfalls: mutable default arguments, improper exception handling, unsafe patterns, redundant checks, and subtle bugs that impact correctness and security.
Flags any usage of `print()` or `pprint()` in production code to prevent leaking sensitive information, mixing debug output into logs, or introducing uncontrolled console output.
Ensures consistent and conventional naming across classes, functions, variables, and modules. This helps maintain readability across the engineering team and reinforces clarity in code reviews.
Enforces type annotation discipline across functions, methods, and class structures. With Pyright used for type checking, these rules ensure that type information remains explicit and complete.
Removes or flags commented-out code fragments. Commented code tends to accumulate over time and reduces clarity. The goal is to keep the repository clean and avoid keeping dead code in version control.
Performance-oriented rules that highlight inefficient constructs, slow loops, unnecessary list or dict operations, and patterns that degrade runtime efficiency.
Linting issues should always be resolved manually.
299
+
We **strongly discourage** relying on autofixes using `ruff check --fix` for this repository.
300
+
301
+
Unlike `ruff format`, which performs safe and predictable code formatting, the linter's autofix mode can alter control flow, refactor logic, or rewrite expressions in ways that introduce unintended bugs.
302
+
303
+
All linter errors will have **rule-code** like `ANN204` for example.
304
+
You can use the command line command
305
+
```bash
306
+
ruff rule <rule-code>#for example: ANN204
307
+
```
308
+
309
+
to get an explanation on the rule code, why it's a problem and how you can fix it.
310
+
311
+
Human oversight is essential to ensure that any corrective changes maintain the intended behavior of the application. Contributors should review each reported linting issue, understand why it is flagged, and apply the appropriate fix by hand.
312
+
313
+
---
314
+
315
+
## Formatting Rules
316
+
317
+
This repository uses the **Ruff Formatter** for code formatting. Its behavior is deterministic, safe, and aligned with the [Black Code Style](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html).
318
+
319
+
Formatting is enforced automatically through the CI pipeline and must pass before merging changes into the `wip`, `dev`, or `main` branches.
320
+
321
+
### Selected Formatting Behaviors
322
+
323
+
#### String Quote Style
324
+
325
+
All string literals are formatted using **double quotes**.
326
+
This preserves consistency across the codebase and avoids unnecessary formatting churn.
The formatter **does not reformat** code blocks inside docstrings.
358
+
This ensures that examples, snippets, API usage patterns, and documentation content remain exactly as written, preventing unintended modifications to teaching material or markdown-style fenced blocks.
0 commit comments