Imports:
  - Types:
      - EntityContract
      - RoutineContract
    Usages:
      - contract_data
    From: goga/contract/data

Usages:
  conventions: .goga/usages/conventions.md
  tree-sitter-python: .goga/usages/cooks/tree-sitter-python.md

Annotations: |
  During development and testing, use practice `conventions`.
  For parsing Python files, use practice `tree-sitter-python`.

---

"python_contract(cell_path: str) -> contracts:list[EntityContract | RoutineContract]":
  location: python.py
  annotations: |
    Collect all public definitions from .py files of the cell via AST parsing.
    Use practice `contract_data` to form results.

    `cell_path`: path to the cell in the format path/to/cell

    Algorithm:
    - find all .py files in the cell_path directory
    - for each file — parse AST via practice `tree-sitter-python`
    - collect all class_definition and function_definition
    - filter public definitions (name without _-prefix)
    - for EntityContract:
      - __init__ parameters → signature (self is excluded)
      - @property decorated methods → properties (type from return annotation)
      - type-annotated fields (PEP 526) → properties (type from annotation)
      - public methods → methods (self is excluded, types from annotations)
    - for RoutineContract: parameters and return annotation → signature
    - sort result via sort_contracts from treesitter_utils

    Requirements:
    - public definitions (no _-prefix) are included in the contract
    - type annotations are included in the contract (string representation)
    - argument order in signature is important
    - default argument values are important
    - argument type (positional, named, *args, **kwargs) is important
    - self is excluded from the signature
    - for properties, signature is the return data type, if absent — empty string
    - when parameter/return type annotation is missing — empty string
    - only methods/properties declared directly in the class (no inherited ones)

---

Author: Goga
CreatedAt: 19/05/26

Description: |
  Extract contract from the facade of a Python package via tree-sitter
