Coding Python

Python Coding Standards

Mandatory Metadata

Every function or class you create or modify must include this header comment:

# Created by [Model_Name] | YYYY-MM-DD
# Example: # Created by GPT-5.5 | 2026-07-04

For modifications to existing functions/classes:

# Modified by [Model_Name] | YYYY-MM-DD
# Example: # Modified by Claude-Sonnet-4.8 | 2026-07-04

Use the current model name from context and today's date.

Syntax & Style

Quotes

• Use double quotes (") in all cases.
  • Good: x += "."
  • Bad: x += '.'

String Formatting

• Use f-strings for interpolation (not % or .format()).
  • Good: f"Hello, {name}!"
  • Bad: "Hello, {}!".format(name) or "Hello, %s" % name

SQL

• Always use multi-line triple-quoted strings for SQL queries.

Readability

• Prioritize readable code over clever/compact one-liners.
• Keep vertical spacing compact — no excessive blank lines.

Type Hints

• Add type hints to new functions you write (not required when modifying existing code without type hints).

  def user_get(user_id: int) -> dict:
  

Error Handling

• Use specific exception types — avoid bare except:.
• Log errors with context before re-raising or returning.

  try:
      result = file_read(path)
  except FileNotFoundError as e:
      logger.error(f"File not found: {path} — {e}")
      raise
  

Docstrings

• Add a one-line docstring to every new public function or class.
• Use triple double-quotes.

  def user_sync(folders: list) -> bool:
      """Sync skill directories across all provided folder paths."""
  

Flask-Specific Patterns

Route Organization

• Keep route handlers thin — delegate logic to utility functions.
• Group related routes into blueprints (blueprints/ folder).
• Route naming: use domain-first (e.g., /user/edit or /user_edit, not /edit_user).

Error Handlers

• Register global error handlers in the app factory, not inline.

  @app.errorhandler(404)
  def error_not_found(e):
      return jsonify({"error": "Not found"}), 404
  

Response Pattern

• Use jsonify() for API responses; set explicit status codes.

Jinja2-Specific Patterns

Template Inheritance

• All page templates should extend a base layout:

  {% extends "layout.jinja" %}
  {% block content %}
    {# page content here #}
  {% endblock %}
  

Variable Safety

• Use the | default() filter when a variable might be undefined:

  {{ user.name | default("Guest") }}
  

Logic in Templates

• Keep logic minimal in templates — complex logic belongs in Python, not Jinja.
• Use {% set %} for local variables rather than inline expressions when readability suffers.

Testing (pytest)

• Read skill-local guidance only when .kilocode/skills/coding-python/AGENTS.md is confirmed to exist; otherwise use root AGENTS.md for project-specific Python, Flask, Jinja, and test paths.
• Test files generally follow test_[module_name].py naming.
• Each test function name describes what it verifies: test_user_sync_creates_backup.
• Use tmp_path fixture for file system tests — never write to real project paths.
• Confirm a test doesn't already exist before writing a new one.