refactor: normalize spacing

Author: Eoic

AGENTS.md

@@ -19,7 +19,14 @@
 - Reuse or extend existing schema modules before creating new top-level packages.
 - Follow existing async patterns with `AsyncSession`, explicit return types, and Pydantic schemas.
 - Use vertical spacing to separate logical steps inside functions. Keep related statements together, but add a blank line when moving between setup, validation, branching, and side effects.
-- Prefer readable spacing over dense blocks. Short guard clauses, temporary assignments, and context-manager branches should usually be visually separated the way `papyrus/services/email.py` is structured.
+- Prefer readable spacing over dense blocks. Short guard clauses, temporary assignments, and context-manager branches should usually be visually separated the way `papyrus/services/email.py` and `papyrus/services/auth/` are structured.
+- Treat any multiline statement or block as a visual boundary inside a function. If one adjacent statement is multiline and both sides are real code, separate the two statements with a blank line.
+- Apply that rule to multiline conditionals, loops, `with` blocks, `try` blocks, multiline calls, multiline literals, and multiline return values. Treat `if` / `elif` / `else` as one block.
+- Do not add a blank line just because a docstring appears above the first statement in a function. The multiline-block rule applies between code statements, not between a docstring and the first line of code.
+- Add a blank line between query execution and result extraction, especially around `session.execute(...)` and subsequent `scalar*()` reads.
+- Add a blank line before persistence and side-effect boundaries such as `session.add(...)`, `send_email(...)`, `commit()`, redirects, and returned result objects when they start a new phase of the function.
+- Keep tightly coupled short sequences together when they are clearly one step. Do not add spacing mechanically when it makes a two-line operation harder to read.
+- Prefer extra spacing around state transitions and persistence boundaries rather than packing setup, branching, and writes into a single block.
 - When adding a new router module, register it in `papyrus/api/routes/__init__.py`.
 - Avoid adding dependencies unless the user explicitly asks for them.
 - Keep changes scoped. Do not refactor unrelated areas as part of a focused fix.

README.md

@@ -25,7 +25,7 @@ uv run alembic upgrade head
 Run the server:
 
 ```bash
-uv run uvicorn papyrus.main:app --reload
+uv run uvicorn papyrus.main:app --reload --port 8080
 ```
 
 Generate local PowerSync keys for auth testing:

papyrus/api/deps.py

@@ -65,6 +65,7 @@ async def get_current_auth_session(
     result = await db.execute(
         select(AuthSession).options(selectinload(AuthSession.user)).where(AuthSession.session_id == session_uuid)
     )
+
     auth_session = result.scalar_one_or_none()
 
     if auth_session is None or auth_session.user_id != user_uuid:

papyrus/api/routes/auth.py

@@ -55,6 +55,7 @@ def _public_callback_url(request: Request, route_name: str) -> str:
 
     route_parts = urlsplit(route_url)
     public_parts = urlsplit(public_base_url.rstrip("/"))
+
     return urlunsplit(
         (
             public_parts.scheme,
@@ -110,6 +111,7 @@ async def google_oauth_start(
         redirect_uri=redirect_uri,
         callback_uri=_public_callback_url(request, "google_oauth_callback"),
     )
+
     return RedirectResponse(url=authorization_url, status_code=status.HTTP_302_FOUND)
 
 
@@ -133,6 +135,7 @@ async def google_oauth_callback(
         state_token=state,
         error=error,
     )
+
     return RedirectResponse(url=redirect_url, status_code=status.HTTP_302_FOUND)
 
 
@@ -215,6 +218,7 @@ async def start_google_link(
         redirect_uri=request.redirect_uri,
         callback_uri=_public_callback_url(http_request, "google_oauth_callback"),
     )
+
     return AuthorizationUrlResponse(authorization_url=authorization_url)
 
 

papyrus/api/routes/books.py

@@ -193,6 +193,7 @@ async def batch_create_books(
                 updated_at=datetime.now(UTC),
             )
         )
+
     return BatchCreateResponse(created=created, errors=[])
 
 

papyrus/api/routes/goals.py

@@ -21,6 +21,7 @@
 def _example_goal(goal_id: UUID | None = None) -> Goal:
     """Create an example goal for responses."""
     today = date.today()
+
     return Goal(
         goal_id=goal_id or uuid4(),
         title="Read 12 books this year",

papyrus/api/routes/series.py

@@ -77,6 +77,7 @@ async def get_series(
 ) -> SeriesWithBooks:
     """Return detailed information about a series with its books."""
     base = _example_series(series_id)
+
     return SeriesWithBooks(
         series_id=base.series_id,
         name=base.name,

papyrus/config.py

@@ -65,6 +65,7 @@ def normalize_debug(cls, value: bool | str) -> bool:
 
         if normalized in truthy:
             return True
+
         if normalized in falsy:
             return False
 

papyrus/core/security.py

@@ -153,6 +153,7 @@ def create_powersync_token(user_id: str, expires_delta: timedelta | None = None)
 def get_powersync_jwks() -> dict[str, list[dict[str, Any]]]:
     settings = get_settings()
     jwk = RSAAlgorithm.to_jwk(_get_powersync_public_key(), as_dict=True)
+
     jwk.update(
         {
             "kid": settings.powersync_jwt_key_id,

papyrus/services/auth/_core.py

@@ -68,11 +68,12 @@ async def _create_session_for_user(
         expires_at=_now() + timedelta(days=get_settings().refresh_token_expire_days),
         last_seen_at=_now(),
     )
+
     session.add(auth_session)
     user.last_login_at = _now()
     await session.flush()
-
     access_token = create_access_token({"sub": str(user.user_id), "sid": str(auth_session.session_id)})
+
     return AuthResult(
         access_token=access_token,
         refresh_token=refresh_token,
@@ -102,6 +103,7 @@ async def _revoke_user_sessions(session: AsyncSession, user_id: UUID) -> None:
     result = await session.execute(
         select(AuthSession).where(AuthSession.user_id == user_id, AuthSession.revoked_at.is_(None))
     )
+
     for auth_session in result.scalars():
         auth_session.revoked_at = _now()
 
@@ -120,6 +122,7 @@ async def _create_exchange_code(
     avatar_url: str | None = None,
 ) -> str:
     plain_code = generate_opaque_token()
+
     session.add(
         AuthExchangeCode(
             code_hash=hash_opaque_token(plain_code),
@@ -135,6 +138,7 @@ async def _create_exchange_code(
             expires_at=_now() + timedelta(minutes=get_settings().auth_exchange_code_expire_minutes),
         )
     )
+
     await session.flush()
     return plain_code
 
@@ -164,6 +168,7 @@ async def _issue_email_action_token(
     expires_minutes: int,
 ) -> str:
     plain_token = generate_opaque_token()
+
     session.add(
         EmailActionToken(
             user_id=user_id,
@@ -172,6 +177,7 @@ async def _issue_email_action_token(
             expires_at=_now() + timedelta(minutes=expires_minutes),
         )
     )
+
     await session.flush()
     return plain_token
 
@@ -206,6 +212,7 @@ def _default_display_name(identity: GoogleIdentity | None = None, email: str | N
 
 def _build_api_url(path: str) -> str | None:
     public_base_url = get_settings().public_base_url
+
     if public_base_url is None:
         return None
 
@@ -223,10 +230,12 @@ def _verification_email_body(token: str) -> str:
     ]
 
     if verify_url is not None:
-        lines.extend([
-            "",
-            f"Submit this token to: {verify_url}",
-        ])
+        lines.extend(
+            [
+                "",
+                f"Submit this token to: {verify_url}",
+            ]
+        )
 
     return "\n".join(lines)
 
@@ -240,9 +249,11 @@ def _password_reset_email_body(token: str) -> str:
     ]
 
     if reset_url is not None:
-        lines.extend([
-            "",
-            f"Submit this token and your new password to: {reset_url}",
-        ])
+        lines.extend(
+            [
+                "",
+                f"Submit this token and your new password to: {reset_url}",
+            ]
+        )
 
     return "\n".join(lines)