From 21b648e18f6d9d095206d2b4dd1a7eef760758ef Mon Sep 17 00:00:00 2001 From: LordBaryhobal Date: Thu, 9 Jul 2026 15:56:56 +0200 Subject: [PATCH] docs: fix some docstrings --- midas/checker/builtins.py | 6 +++++- midas/checker/dispatcher.py | 23 +++++++++++++--------- midas/checker/evaluator.py | 2 ++ midas/checker/frames/column_manager.py | 2 +- midas/checker/frames/column_methods.py | 10 ++++++---- midas/checker/python.py | 27 ++++++++++++++++++++++---- midas/checker/reporter.py | 5 +++++ 7 files changed, 56 insertions(+), 19 deletions(-) diff --git a/midas/checker/builtins.py b/midas/checker/builtins.py index 427d414..bfae66b 100644 --- a/midas/checker/builtins.py +++ b/midas/checker/builtins.py @@ -26,7 +26,11 @@ Circular dependencies and diamond inheritance MUST be avoided def define_builtins(reg: TypesRegistry): - """Define builtin types and operations""" + """Define builtin types and operations + + Args: + reg (TypesRegistry): the types registry + """ any = reg.define_type("Any", TopType()) unit = reg.define_type("None", UnitType()) object = reg.define_type("object", BaseType(name="object")) diff --git a/midas/checker/dispatcher.py b/midas/checker/dispatcher.py index 77e1f45..8320e8d 100644 --- a/midas/checker/dispatcher.py +++ b/midas/checker/dispatcher.py @@ -102,6 +102,11 @@ class CallDispatcher(Generic[E]): self.logger: logging.Logger = logging.getLogger("CallDispatcher") def set_reporter(self, reporter: FileReporter): + """Set the current reporter + + Args: + reporter (FileReporter): the new file reporter + """ self.reporter = reporter def get_result( @@ -123,8 +128,8 @@ class CallDispatcher(Generic[E]): Args: location (Location): the call location callee (Type): the called function - positional (list[TypedExpr]): the list of positional arguments - keywords (dict[str, TypedExpr]): the map of keyword arguments + positional (list[TypedExpr[E]]): the list of positional arguments + keywords (dict[str, TypedExpr[E]]): the map of keyword arguments report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True. Returns: @@ -250,7 +255,7 @@ class CallDispatcher(Generic[E]): """Check whether the passed argument types correspond to their matched parameter definitions Args: - arguments (list[MappedArgument]): the list of argument/parameter pairs + arguments (list[MappedArgument[E]]): the list of argument/parameter pairs report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True. Returns: @@ -286,8 +291,8 @@ class CallDispatcher(Generic[E]): Args: overloads (list[Type]): the list of possible overloads location (Location): the call location - positional (list[TypedExpr]): the list of positional arguments - keywords (dict[str, TypedExpr]): the map of keywords arguments + positional (list[TypedExpr[E]]): the list of positional arguments + keywords (dict[str, TypedExpr[E]]): the map of keywords arguments report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True. Returns: @@ -385,8 +390,8 @@ class CallDispatcher(Generic[E]): Args: function (Function): the function definition location (Location): the call location - positional (list[TypedExpr]): the list of positional arguments - keywords (dict[str, TypedExpr]): the map of keyword arguments + positional (list[TypedExpr[E]]): the list of positional arguments + keywords (dict[str, TypedExpr[E]]): the map of keyword arguments report_errors (bool, optional): whether type errors should be reported as diagnostics. Defaults to True. Returns: @@ -514,8 +519,8 @@ class CallDispatcher(Generic[E]): function / a subtype of another. Args: - mapped1 (list[MappedArgument]): the first argument mappings (subtype) - mapped2 (list[MappedArgument]): the second argument mappings (supertype) + mapped1 (list[MappedArgument[E]]): the first argument mappings (subtype) + mapped2 (list[MappedArgument[E]]): the second argument mappings (supertype) Returns: bool: `True` if `mapped1` is a subtype of `mapped2`, `False` otherwise diff --git a/midas/checker/evaluator.py b/midas/checker/evaluator.py index baefc0d..79dc9c1 100644 --- a/midas/checker/evaluator.py +++ b/midas/checker/evaluator.py @@ -190,6 +190,7 @@ class Evaluator(m.Expr.Visitor[Any]): """Evaluate a predicate function call Args: + location (Location): the location of the call expression predicate (Predicate): the predicate to evaluate args (list[Any]): a list of positional arguments kwargs (dict[str, Any]): a map of keyword arguments @@ -234,6 +235,7 @@ class Evaluator(m.Expr.Visitor[Any]): is set in the context using :func:`set_value` with the parameter's name Args: + location (Location): the location of the call expression function (Function): the called function args (list[Any]): a list of positional arguments kwargs (dict[str, Any]): a map of keyword arguments diff --git a/midas/checker/frames/column_manager.py b/midas/checker/frames/column_manager.py index 4fa9e81..16c8187 100644 --- a/midas/checker/frames/column_manager.py +++ b/midas/checker/frames/column_manager.py @@ -45,7 +45,7 @@ class ColumnManager: Args: reporter (FileReporter): the file reporter to use for diagnostics location (Location): the subscript's location - column (DataFrameType): the column type + column (ColumnType): the column type index (TypedExpr): the index Returns: diff --git a/midas/checker/frames/column_methods.py b/midas/checker/frames/column_methods.py index a7dae13..e957a55 100644 --- a/midas/checker/frames/column_methods.py +++ b/midas/checker/frames/column_methods.py @@ -353,10 +353,12 @@ class ColumnMethodRegistry(MethodRegistry[Call]): call (Call): the call object kwargs (list[Function.Parameter], optional): a list of extra keyword-only parameters. Defaults to []. - formula (Callable[[Type], Formula], optional): optional formula - builder function to compute the return type. If set, the function - should accept the inner column type and return a formula. - If `None`, the result is typed as `Column[Any]`. Defaults to None. + formula (Optional[Callable[[Type], Formula]], optional): + optional formula builder function to compute the return type.
+ If set, the function should accept the inner column type and + return a formula.
+ If `None`, the result is typed as `Column[Any]`. + Defaults to None. Returns: Type: the result type diff --git a/midas/checker/python.py b/midas/checker/python.py index 0eb751f..0192dfc 100644 --- a/midas/checker/python.py +++ b/midas/checker/python.py @@ -518,11 +518,12 @@ class PythonTyper( def _assign_attr( self, location: Location, object: p.Expr, name: str, value_type: Type ): - """Type check assignment to the given target + """Type check assignment to the given attribute target Args: location (Location): the location of the assignment - target (p.VariableExpr): the assignment's target + object (p.Expr): the target attribute's owner object + name (str): the target attribute's name value_type (Type): the value to be assigned """ object_type: Type = self.type_of(object) @@ -544,11 +545,15 @@ class PythonTyper( index: p.Expr, value_type: Type, ): - """Type check assignment to the given target + """Type check assignment to the given subscript target Args: location (Location): the location of the assignment - target (p.VariableExpr): the assignment's target + var (p.VariableExpr): the target subscript's owner. We only allow + a variable expression here because we might modify its type (for + example when assigning a column to a dataframe) and reference + types are not implemented + index (p.Expr): the target subscript's index expression value_type (Type): the value to be assigned """ var_type: Type = self.type_of(var) @@ -690,6 +695,20 @@ class PythonTyper( right: TypedExpr, method: str, ) -> Type: + """Compute the result type of a binary operation method call + + This method is called for dunder methods called by binary operators + + Args: + location (Location): the location of the operation + expr (p.Expr): the expression which triggered this resolution + left (TypedExpr): the left operand + right (TypedExpr): the right operand + method (str): the method name + + Returns: + Type: the result type + """ try: return self.call_method( location=location, diff --git a/midas/checker/reporter.py b/midas/checker/reporter.py index 8604dcd..ba97c07 100644 --- a/midas/checker/reporter.py +++ b/midas/checker/reporter.py @@ -70,6 +70,11 @@ class FileReporter: @contextmanager def with_context(self, ctx: str): + """Push given context for reports inside this manager and pop it on exit + + Args: + ctx (str): the context to temporarily push on the stack + """ self._context.append(ctx) try: yield