# Python Style

> Python code style guidelines for HestAI MCP including type hints, imports, error handling, and docstrings Use when this capability is needed.

- Skill: `tomevault-io/python-style` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/python-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/python-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/python-style

---


===PYTHON_STYLE===
META:
  TYPE::SKILL
  VERSION::"1.0"
  STATUS::ACTIVE
  PURPOSE::"Python code style guidelines for HestAI MCP development"
  DOMAIN::HEPHAESTUS[craftsmanship]⊕ATHENA[precision]

§1::TYPE_HINTS
  REQUIREMENT::all_functions_require_type_hints[enforced_by_mypy]
  FORWARD_REFS::"from __future__ import annotations"
  PREFER::[list,dict,set]
  AVOID::[List,Dict,Set][typing_module_deprecated]
  EXAMPLE::"def process(items: list[str]) -> dict[str, int]:"

§2::IMPORTS
  STYLE::absolute_imports_from_hestai_mcp
  ORDERING::ruff_handles_isort_style
  GROUPS::[
    stdlib::first,
    third_party::second,
    local::third
  ]
  EXAMPLE::[
    "from pathlib import Path",
    "from pydantic import BaseModel",
    "from hestai_mcp.schemas import SessionConfig"
  ]

§3::ERROR_HANDLING
  EXCEPTIONS::raise_specific[not_generic_Exception]
  DOCUMENTATION::document_exceptions_in_docstrings
  PATTERN::[
    "try:",
    "    result = risky_operation()",
    "except SpecificError as e:",
    "    logger.error(f'Operation failed: {e}')",
    "    raise"
  ]

§4::DOCSTRINGS
  STYLE::Google_style
  REQUIRED::public_functions_and_classes
  SECTIONS::[Args,Returns,Raises]
  EXAMPLE::[
    "\"\"\"Process items and return counts.",
    "",
    "Args:",
    "    items: List of items to process.",
    "    strict: If True, raise on invalid items.",
    "",
    "Returns:",
    "    Dictionary mapping item names to counts.",
    "",
    "Raises:",
    "    ValueError: If items is empty and strict is True.",
    "\"\"\""
  ]

§5::LINE_LENGTH
  MAX::100_characters
  ENFORCEMENT::[black,ruff]

§6::QUALITY_GATES
  COMMANDS::[
    "python -m ruff check src tests scripts",
    "python -m black --check src tests scripts",
    "python -m mypy src"
  ]
  FIX_COMMANDS::[
    "python -m black src tests scripts",
    "python -m ruff check --fix src tests scripts"
  ]

===END===

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/elevanaltd) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->