DO NOT MERGE: chore(tooling): add pre-commit and black quality gates

.github/workflows/cd.yml

@@ -8,12 +8,34 @@ permissions:
   contents: read
 
 jobs:
+  quality-gates:
+    name: Formatting and Linting
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Install pip dependencies
+      run: |
+        python -m pip install --upgrade pip
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Black check
+      run: |
+        black --check webapi/schemas webapi/tests/functional/test_auth_routes.py
+    - name: Pylint check
+      run: |
+        pylint webapi/schemas
+
   cd-tests:
     name: Python Tests
     runs-on: ubuntu-latest
+    needs: quality-gates
 
     steps:
-    - uses: actions/checkout@v4 
+    - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v5
       with:

.github/workflows/ci.yaml

@@ -8,9 +8,31 @@ on:
   workflow_dispatch:
 
 jobs:
+  quality-gates:
+    name: Formatting and Linting
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+    - name: Install pip dependencies
+      run: |
+        python -m pip install --upgrade pip
+        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+    - name: Black check
+      run: |
+        black --check webapi/schemas webapi/tests/functional/test_auth_routes.py
+    - name: Pylint check
+      run: |
+        pylint webapi/schemas
+
   ci-tests:
     name: Python Tests
     runs-on: ubuntu-latest
+    needs: quality-gates
 
     steps:
     - uses: actions/checkout@v4

.gitignore

@@ -15,3 +15,9 @@ __pycache__/
 .coverage
 coverage.xml
 htmlcov/
+
+# VSCode
+.vscode/
+
+# Environment variables
+.env

.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+        language_version: python3.12
+
+  - repo: local
+    hooks:
+      - id: pylint
+        name: pylint
+        entry: pylint
+        language: system
+        types: [python]
+        pass_filenames: true

.pylintrc

@@ -0,0 +1,19 @@
+[MASTER]
+ignore=.git,.venv,build,dist
+jobs=0
+
+[MESSAGES CONTROL]
+disable=
+    missing-module-docstring,
+    missing-function-docstring,
+    missing-class-docstring,
+    too-few-public-methods
+
+[FORMAT]
+max-line-length=100
+
+[DESIGN]
+max-args=10
+
+[TYPECHECK]
+ignored-modules=sqlmodel

README.md

@@ -6,6 +6,56 @@ Build and run the app:
 docker build -t webapi:dev .; docker run --rm -p 8000:8000 webapi:dev
 ```
 
+## Development tooling and quality gates
+
+This project now includes recruiter-relevant backend tooling practices:
+
+- **Formatter:** Black (configured in [`pyproject.toml`](pyproject.toml))
+- **Linter:** Pylint (configured in [`.pylintrc`](.pylintrc))
+- **Git hooks:** pre-commit (configured in [`.pre-commit-config.yaml`](.pre-commit-config.yaml))
+- **Validation:** Pydantic constraints in schemas under [`webapi/schemas`](webapi/schemas)
+- **CI quality gates:** formatting and lint checks in [`.github/workflows/ci.yaml`](.github/workflows/ci.yaml) and [`.github/workflows/cd.yml`](.github/workflows/cd.yml)
+
+### Local setup
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Install git hooks:
+
+```bash
+pre-commit install
+```
+
+### Run tooling locally
+
+Run Black formatting:
+
+```bash
+black webapi
+```
+
+Run Pylint checks:
+
+```bash
+pylint webapi/schemas
+```
+
+Run pre-commit on all files:
+
+```bash
+pre-commit run --all-files
+```
+
+Run validation-focused tests:
+
+```bash
+pytest webapi/tests/functional/test_auth_routes.py -k validation
+```
+
 ## Database diagram documentation
 
 The ORM model and relational mapping documentation for dbdiagram.io is available at [`plans/dbdiagram.md`](plans/dbdiagram.md).

pyproject.toml

@@ -0,0 +1,17 @@
+[tool.black]
+line-length = 100
+target-version = ["py312"]
+include = '\\.pyi?$'
+extend-exclude = '''
+/(\
+  \.git
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.pytest.ini_options]
+testpaths = ["webapi/tests"]
+python_files = ["test_*.py"]
+addopts = "-q"

requirements.txt

@@ -12,4 +12,7 @@ python-dotenv
 fastapi-mail>=1.4.1
 redis~=5.3.1
 pytest~=8.4.2
-httpx~=0.28.1
+httpx~=0.28.1
+black~=24.10.0
+pylint~=3.3.1
+pre-commit~=4.0.1

webapi/api/endpoints/v1/auths.py

@@ -31,27 +31,27 @@ def signup(user: User, session: Session = Depends(get_session)):
     session.refresh(user)
     return {"message": "User created successfully"}
 
+
 @router.post("/login")
 def login(request: LoginRequest, session: Session = Depends(get_session)):
     user = authenticate_user(request.username, request.password, session)
     if not user:
         raise HTTPException(status_code=401, detail="Incorrect username or password")
-    access_token = crear_jwt(
-        data={"sub": user.username}
-    )
+    access_token = crear_jwt(data={"sub": user.username})
     return {"access_token": access_token, "token_type": "bearer"}
 
 
 @router.get("/profile")
 def profile(current_user: dict = Depends(get_current_user)):
     return {"profile data": current_user}
 
+
 @router.post("/generate")
 async def generate_password(
     username: str,
     ttl: int = 300,
     redis: Redis = Depends(get_redis),
-    session: Session = Depends(get_session)
+    session: Session = Depends(get_session),
 ):
     statement = select(User).where(User.username == username)
     result = session.exec(statement)
@@ -60,7 +60,7 @@ async def generate_password(
         raise HTTPException(status_code=404, detail="User not found")
 
     """Generate random key"""
-    encoded = base64.b64encode(username.encode('utf-8')).decode('utf-8')
+    encoded = base64.b64encode(username.encode("utf-8")).decode("utf-8")
     key = f"{secrets.token_hex(16)}.{encoded}"
     if redis.exists(key):
         raise HTTPException(status_code=400, detail="Key already exists")
@@ -70,17 +70,18 @@ async def generate_password(
     session.add(user)
     session.commit()
     session.refresh(user)
-    email_body = f"Hey {user.username} this is your recovery key:\n--> {key} <--\nit expires in {ttl/60}"
+    email_body = (
+        f"Hey {user.username} this is your recovery key:\n--> {key} <--\nit expires in {ttl/60}"
+    )
     await send_email(user.email, user.username, email_body)
     redis.setex(key, ttl, password)
 
     return {f"Message sent successfully, it expires in {ttl/60} minutes"}
 
+
 @router.post("/recover")
 def recover_password(
-    key: str,
-    redis: Redis = Depends(get_redis),
-    session: Session = Depends(get_session)
+    key: str, redis: Redis = Depends(get_redis), session: Session = Depends(get_session)
 ):
 
     match = re.search(r"\.(.+)$", key)
@@ -94,7 +95,7 @@ def recover_password(
     if missing_padding:
         username += "=" * (4 - missing_padding)
     try:
-        username = base64.b64decode(username).decode('utf-8')
+        username = base64.b64decode(username).decode("utf-8")
     except (binascii.Error, UnicodeDecodeError) as e:
         raise HTTPException(status_code=401, detail=f"Decode error: {e}")
     statement = select(User).where(User.username == username)

webapi/api/endpoints/v1/prompts.py

@@ -9,12 +9,13 @@
 
 router = APIRouter()
 
+
 @router.post("", response_model=Prompts)
 async def create_prompt(
     prompt: Prompts,
     session: Session = Depends(get_session),
     current_user: dict = Depends(get_current_user),
-    send_email_header: Optional[str] = Header("false", alias="send_email")
+    send_email_header: Optional[str] = Header("false", alias="send_email"),
 ):
     # Ensure the user exists before creating a prompt
     user = session.get(User, prompt.user_id)
@@ -34,10 +35,14 @@ async def create_prompt(
 
     return prompt
 
+
 @router.get("", response_model=list[Prompts])
-def read_prompts(skip: int = 0, limit: int = 10,
-               session: Session = Depends(get_session),
-               current_user: dict = Depends(get_current_user)):
+def read_prompts(
+    skip: int = 0,
+    limit: int = 10,
+    session: Session = Depends(get_session),
+    current_user: dict = Depends(get_current_user),
+):
     statement = select(Prompts).offset(skip).limit(limit)
     prompts = session.exec(statement).all()
     if not prompts:
@@ -46,17 +51,24 @@ def read_prompts(skip: int = 0, limit: int = 10,
 
 
 @router.get("/{prompt_id}", response_model=Prompts)
-def get_prompt(prompt_id: int, session: Session = Depends(get_session),
-               current_user: dict = Depends(get_current_user)):
+def get_prompt(
+    prompt_id: int,
+    session: Session = Depends(get_session),
+    current_user: dict = Depends(get_current_user),
+):
     prompt = session.get(Prompts, prompt_id)
     if not prompt:
         raise HTTPException(status_code=404, detail="Prompt not found")
     return prompt
 
+
 @router.put("/{prompt_id}", response_model=Prompts)
-def update_prompt(prompt_id: int, prompt: Prompts,
-                session: Session = Depends(get_session),
-                current_user: dict = Depends(get_current_user)):
+def update_prompt(
+    prompt_id: int,
+    prompt: Prompts,
+    session: Session = Depends(get_session),
+    current_user: dict = Depends(get_current_user),
+):
     existing_prompt = session.get(Prompts, prompt_id)
     if not existing_prompt:
         raise HTTPException(status_code=404, detail="Prompt not found")
@@ -75,8 +87,11 @@ def update_prompt(prompt_id: int, prompt: Prompts,
 
 
 @router.delete("/{prompt_id}")
-def delete_prompt(prompt_id: int, session: Session = Depends(get_session),
-                current_user: dict = Depends(get_current_user)):
+def delete_prompt(
+    prompt_id: int,
+    session: Session = Depends(get_session),
+    current_user: dict = Depends(get_current_user),
+):
     prompt = session.get(Prompts, prompt_id)
     if not prompt:
         raise HTTPException(status_code=404, detail="Prompt not found to delete")