1002-python-type-hinting

description: WHEN writing Python code ALWAYS use type hints for functions, methods, and variables globs: src/the_aichemist_codex/**/*.py

  Args:
      {parameter_name} ({parameter_type}): {parameter_description}

  Returns:
      {return_type}: {return_description}

  Raises:
      {exception_type}: {exception_description}
  """
  </template>
</function>

<class>
  <template>
  """
  {class_description}

  Attributes:
      {attribute_name} ({attribute_type}): {attribute_description}
  """
  </template>
</class>

Args:
    document (Document): The document to process
    tags (Optional[List[str]]): Tags to apply to the document
    max_length (int): Maximum length to process

Returns:
    Dict[str, Any]: Processed document data with applied tags

Raises:
    ValueError: If document is empty or invalid
"""
if not document.content:
    raise ValueError("Document content cannot be empty")

result: Dict[str, Any] = {
    "id": document.id,
    "content": document.content[:max_length],
    "processed_at": datetime.now()
}

if tags:
    document.tags.update(tags)
    result["tags"] = list(document.tags)

return result
  </code>
</good-example>

<good-example>
  <description>Class with typed attributes and methods</description>
  <code>

class DocumentProcessor: """ Processes documents and applies transformations.

Attributes:
    max_length (int): Maximum content length to process
    supported_formats (Set[str]): Document formats supported by this processor
"""

def __init__(self, max_length: int = 1000) -> None:
    """
    Initialize the document processor.

    Args:
        max_length (int): Maximum content length to process
    """
    self.max_length: int = max_length
    self.supported_formats: Set[str] = {"txt", "md", "pdf"}

def process(self, document: Document) -> ProcessedDocument:
    """
    Process a document into a standardized format.