modgud 0.2.1__tar.gz

modgud-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Steven Miers]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modgud-0.2.1/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: modgud
+Version: 0.2.1
+Summary: Guard clauses are validation checks at the beginning of functions that exit early when preconditions aren't met. They prevent deeply nested conditional logic and make the "happy path" of your code more readable.
+License: MIT
+License-File: LICENSE
+Keywords: guards,validation,decorators,defensive-programming,single-return-point,implicit-return
+Author: steven.miers@gmail.com
+Requires-Python: >=3.13
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities

modgud-0.2.1/modgud/__init__.py

@@ -0,0 +1,28 @@
+"""Modgud - Modern Guard Clauses for Python.
+
+A library for implementing guard clause decorators with single return point architecture.
+
+Primary API:
+  - guarded_expression: Unified decorator combining guards + implicit return
+  - CommonGuards: Pre-built guard validators
+"""
+
+from .guarded_expression import CommonGuards, guarded_expression
+from .shared.errors import (
+  ExplicitReturnDisallowedError,
+  GuardClauseError,
+  ImplicitReturnError,
+  MissingImplicitReturnError,
+  UnsupportedConstructError,
+)
+
+__version__ = '0.2.0'
+__all__ = [
+  'guarded_expression',
+  'CommonGuards',
+  'GuardClauseError',
+  'ImplicitReturnError',
+  'ExplicitReturnDisallowedError',
+  'MissingImplicitReturnError',
+  'UnsupportedConstructError',
+]

modgud-0.2.1/modgud/guarded_expression/__init__.py

@@ -0,0 +1,13 @@
+"""Guarded Expression - Unified decorator combining guard clauses with implicit return.
+
+This package provides the primary interface for the modgud library, unifying
+guard clause validation and implicit return transformation into a single decorator.
+"""
+
+from .common_guards import CommonGuards
+from .decorator import guarded_expression
+
+__all__ = [
+  'guarded_expression',
+  'CommonGuards',
+]

modgud-0.2.1/modgud/guarded_expression/ast_transform.py

@@ -0,0 +1,230 @@
+"""Pure AST transformation logic for implicit return functionality.
+
+Extracts the AST rewriting logic from implicit_return into a composable,
+testable pure function that transforms function nodes to enforce implicit
+return semantics.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import List, Optional, Tuple
+
+from ..shared.errors import (
+  ExplicitReturnDisallowedError,
+  MissingImplicitReturnError,
+  UnsupportedConstructError,
+)
+
+
+class _NoExplicitReturnChecker(ast.NodeVisitor):
+
+  """Check for explicit return statements in top-level function body.
+
+  Ensures no explicit `return` appears in the *top-level* body of the decorated
+  function. We deliberately do NOT descend into nested function/async def/lambda
+  bodies so those can use normal Python semantics independently.
+  """
+
+  def __init__(self) -> None:
+    self.found: Optional[Tuple[int, int]] = None  # (lineno, col)
+
+  def visit_Return(self, node: ast.Return) -> None:  # type: ignore[override]
+    # If we are called, it means we're at top-level (we never recurse into nested defs)
+    self.found = (getattr(node, 'lineno', 0), getattr(node, 'col_offset', 0))
+
+  # Block traversal into nested defs/lambdas
+  def visit_FunctionDef(self, node: ast.FunctionDef) -> None:  # type: ignore[override]
+    return
+
+  def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:  # type: ignore[override]
+    return
+
+  def visit_Lambda(self, node: ast.Lambda) -> None:  # type: ignore[override]
+    return
+
+
+class _TailRewriter:
+
+  """Rewrite tail positions to assign to implicit result variable.
+
+  Rewrites *tail positions* (the final statement of a block that determines the
+  branch's return value) by replacing a final expression with an assignment to a
+  hidden result variable. After transforming the top-level body, we append a single
+  `return __implicit_result` to the function.
+
+  Supported tail forms:
+    - Expr        -> assign to result
+    - If          -> both body and orelse must set result via their own tails
+    - Try         -> body and each except must set result; else (if present) also sets it
+    - Match       -> each case body must set result via its tail
+  """
+
+  def __init__(self, result_name: str) -> None:
+    self.result_name = result_name
+
+  def _assign(self, value: ast.expr) -> ast.Assign:
+    return ast.Assign(targets=[ast.Name(id=self.result_name, ctx=ast.Store())], value=value)
+
+  def rewrite_tail_stmt(self, stmt: ast.stmt) -> List[ast.stmt]:
+    """Rewrite tail statement to assign to result variable.
+
+    Return a list of statements that replace the given tail statement,
+    ensuring the result variable is set on all runtime paths.
+    """
+    if isinstance(stmt, ast.Expr):
+      return [self._assign(stmt.value)]
+
+    if isinstance(stmt, ast.If):
+      if not stmt.orelse:
+        raise MissingImplicitReturnError(
+          'If without else at tail position must have an else clause.',
+          getattr(stmt, 'lineno', None),
+          getattr(stmt, 'col_offset', None),
+        )
+      stmt.body = self.rewrite_block(stmt.body)
+      stmt.orelse = self.rewrite_block(stmt.orelse)
+      return [stmt]
+
+    if isinstance(stmt, ast.Try):
+      # Body must produce a value
+      stmt.body = self.rewrite_block(stmt.body)
+      # Each except must produce a value
+      for h in stmt.handlers:
+        h.body = self.rewrite_block(h.body)
+      # Else (if present) also produces a value (it runs on success)
+      if stmt.orelse:
+        stmt.orelse = self.rewrite_block(stmt.orelse)
+      # finally is allowed, but it shouldn't need to assign result; it runs after
+      # the above assignments. We leave it unchanged.
+      return [stmt]
+
+    if isinstance(stmt, ast.Match):
+      # All cases must set the result
+      for case in stmt.cases:
+        if not case.body:
+          raise MissingImplicitReturnError(
+            'Empty match case body cannot yield a value.',
+            getattr(stmt, 'lineno', None),
+            getattr(stmt, 'col_offset', None),
+          )
+        case.body = self.rewrite_block(case.body)
+      return [stmt]
+
+    if isinstance(stmt, ast.Pass):
+      raise MissingImplicitReturnError(
+        'Pass statement cannot yield a value.',
+        getattr(stmt, 'lineno', None),
+        getattr(stmt, 'col_offset', None),
+      )
+
+    raise UnsupportedConstructError(
+      f'Unsupported tail construct: {type(stmt).__name__}',
+      getattr(stmt, 'lineno', None),
+      getattr(stmt, 'col_offset', None),
+    )
+
+  def rewrite_block(self, body: List[ast.stmt]) -> List[ast.stmt]:
+    if not body:
+      raise MissingImplicitReturnError('Empty block where a value is required.')
+    *init, last = body
+    new_last = self.rewrite_tail_stmt(last)
+    return [*init, *new_last]
+
+
+def transform_function_ast(fn_node: ast.AST, func_name: str) -> ast.AST:
+  """Transform function AST to enforce implicit return semantics.
+
+  Pure function that transforms a FunctionDef/AsyncFunctionDef AST node to enforce
+  implicit return semantics.
+
+  Steps:
+    1. Verify no explicit `return` at top-level
+    2. Rewrite tail of the function body to assign to a hidden result var
+    3. Append a single `return __implicit_result`
+
+  Args:
+      fn_node: The function AST node to transform
+      func_name: Name of the function (for error messages)
+
+  Returns:
+      The transformed AST node with implicit return semantics
+
+  Raises:
+      ExplicitReturnDisallowedError: If explicit return found at top level
+      MissingImplicitReturnError: If a block cannot yield a value
+      UnsupportedConstructError: If an unsupported construct is found
+
+  """
+  assert isinstance(fn_node, (ast.FunctionDef, ast.AsyncFunctionDef))
+  body = fn_node.body
+
+  # Check for explicit return at top-level
+  checker = _NoExplicitReturnChecker()
+  # Visit only top-level statements
+  for stmt in body:
+    checker.visit(stmt)
+  if checker.found is not None:
+    line, col = checker.found
+    raise ExplicitReturnDisallowedError(
+      f"Explicit `return` is disallowed in '@guarded_expression' function '{func_name}' with implicit_return=True.",
+      line,
+      col,
+    )
+
+  result_name = '__implicit_result'
+  rewriter = _TailRewriter(result_name)
+  new_body = rewriter.rewrite_block(body)
+  # Append the single return
+  new_body.append(ast.Return(value=ast.Name(id=result_name, ctx=ast.Load())))
+  fn_node.body = new_body
+  return fn_node
+
+
+class _TopLevelTransformer(ast.NodeTransformer):
+
+  """Transform only the target function definition.
+
+  Applies transformation only to the *decorated* function definition that we parsed.
+  We rely on inspect.getsource(func) returning just that function (common in modules).
+  Strips all decorators to prevent re-application during exec.
+  """
+
+  def __init__(self, target_name: str) -> None:
+    self.target_name = target_name
+    super().__init__()
+
+  def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.AST:  # type: ignore[override]
+    if node.name == self.target_name:
+      node.decorator_list = []
+      return transform_function_ast(node, node.name)
+    return node
+
+  def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> ast.AST:  # type: ignore[override]
+    if node.name == self.target_name:
+      node.decorator_list = []
+      return transform_function_ast(node, node.name)
+    return node
+
+
+def apply_implicit_return_transform(func_source: str, func_name: str) -> Tuple[ast.Module, str]:
+  """Pure function that applies implicit return transformation to function source code.
+
+  Args:
+      func_source: The source code of the function (dedented)
+      func_name: The name of the function to transform
+
+  Returns:
+      Tuple of (transformed_ast, compiled_code_object)
+
+  Raises:
+      ExplicitReturnDisallowedError: If explicit return found
+      MissingImplicitReturnError: If a block cannot yield a value
+      UnsupportedConstructError: If an unsupported construct is found
+
+  """
+  tree = ast.parse(func_source)
+  transformer = _TopLevelTransformer(func_name)
+  new_tree = transformer.visit(tree)
+  ast.fix_missing_locations(new_tree)
+  return new_tree, f'<{func_name}-implicit>'

modgud-0.2.1/modgud/guarded_expression/common_guards.py

@@ -0,0 +1,164 @@
+"""Common guard validators for typical validation scenarios.
+
+Provides pre-built guard functions through the CommonGuards class for
+common validation patterns like not_none, positive, in_range, etc.
+"""
+
+import re
+from typing import Any, Optional, Union
+
+from ..shared.types import GuardFunction
+
+
+class CommonGuards:
+
+  """Pre-defined common guard clauses.
+
+  Usage:
+      @guarded_expression(
+          CommonGuards.not_empty("username"),
+          log=True
+      )
+      def create_user(username):
+          return {"username": username}
+  """
+
+  @staticmethod
+  def _extract_param(
+    param_name: str, position: Optional[int], args: tuple, kwargs: dict, default: Any = None
+  ) -> Any:
+    """Extract parameter value from args or kwargs.
+
+    Args:
+        param_name: Name of the parameter in kwargs
+        position: Position in args (None means first arg)
+        args: Positional arguments tuple
+        kwargs: Keyword arguments dict
+        default: Default value if not found
+
+    Returns:
+        Parameter value or default
+
+    """
+    if param_name in kwargs:
+      return kwargs[param_name]
+
+    # Use explicit position if provided, else default to first arg
+    pos = position if position is not None else 0
+    if 0 <= pos < len(args):
+      return args[pos]
+
+    return default
+
+  @staticmethod
+  def not_empty(param_name: str = 'parameter', position: Optional[int] = None) -> GuardFunction:
+    """Guard ensuring collection parameter is not empty.
+
+    Args:
+        param_name: Name of the parameter to check
+        position: Optional explicit position for positional args (0-based)
+
+    """
+
+    def check_not_empty(*args: Any, **kwargs: Any) -> Union[bool, str]:
+      value = CommonGuards._extract_param(param_name, position, args, kwargs, default='')
+
+      # Check if value is empty (works for strings and collections)
+      if hasattr(value, '__len__'):
+        return len(value) > 0 or f'{param_name} cannot be empty'
+
+      return bool(value) or f'{param_name} cannot be empty'
+
+    return check_not_empty
+
+  @staticmethod
+  def not_none(param_name: str = 'parameter', position: int = 0) -> GuardFunction:
+    """Guard ensuring parameter is not None.
+
+    Args:
+        param_name: Name of the parameter to check
+        position: Position for positional args (default: 0)
+
+    """
+
+    def check_not_none(*args: Any, **kwargs: Any) -> Union[bool, str]:
+      value = CommonGuards._extract_param(param_name, position, args, kwargs, default=None)
+      return value is not None or f'{param_name} cannot be None'
+
+    return check_not_none
+
+  @staticmethod
+  def positive(param_name: str = 'parameter', position: int = 0) -> GuardFunction:
+    """Guard ensuring parameter is positive.
+
+    Args:
+        param_name: Name of the parameter to check
+        position: Position for positional args (default: 0)
+
+    """
+
+    def check_positive(*args: Any, **kwargs: Any) -> Union[bool, str]:
+      value = CommonGuards._extract_param(param_name, position, args, kwargs, default=0)
+      return value > 0 or f'{param_name} must be positive'
+
+    return check_positive
+
+  @staticmethod
+  def in_range(
+    min_val: float, max_val: float, param_name: str = 'parameter', position: int = 0
+  ) -> GuardFunction:
+    """Guard ensuring parameter is within range [min_val, max_val].
+
+    Args:
+        min_val: Minimum value (inclusive)
+        max_val: Maximum value (inclusive)
+        param_name: Name of the parameter to check
+        position: Position for positional args (default: 0)
+
+    """
+
+    def check_in_range(*args: Any, **kwargs: Any) -> Union[bool, str]:
+      value = CommonGuards._extract_param(param_name, position, args, kwargs, default=min_val - 1)
+      return min_val <= value <= max_val or f'{param_name} must be between {min_val} and {max_val}'
+
+    return check_in_range
+
+  @staticmethod
+  def type_check(
+    expected_type: type, param_name: str = 'parameter', position: int = 0
+  ) -> GuardFunction:
+    """Guard ensuring parameter matches expected type.
+
+    Args:
+        expected_type: Expected type for the parameter
+        param_name: Name of the parameter to check
+        position: Position for positional args (default: 0)
+
+    """
+
+    def check_type(*args: Any, **kwargs: Any) -> Union[bool, str]:
+      value = CommonGuards._extract_param(param_name, position, args, kwargs, default=None)
+      return (
+        isinstance(value, expected_type) or f'{param_name} must be of type {expected_type.__name__}'
+      )
+
+    return check_type
+
+  @staticmethod
+  def matches_pattern(
+    pattern: str, param_name: str = 'parameter', position: int = 0
+  ) -> GuardFunction:
+    """Guard ensuring string parameter matches regex pattern.
+
+    Args:
+        pattern: Regular expression pattern to match
+        param_name: Name of the parameter to check
+        position: Position for positional args (default: 0)
+
+    """
+
+    def check_pattern(*args: Any, **kwargs: Any) -> Union[bool, str]:
+      value = str(CommonGuards._extract_param(param_name, position, args, kwargs, default=''))
+      return re.match(pattern, value) is not None or f'{param_name} must match pattern {pattern}'
+
+    return check_pattern

modgud-0.2.1/modgud/guarded_expression/decorator.py

@@ -0,0 +1,130 @@
+"""Unified guarded_expression decorator combining guards and implicit returns.
+
+Unified guarded_expression decorator that combines guard clause validation
+with optional implicit return transformation.
+
+This is the primary decorator for the modgud library, unifying the functionality
+of guard_clause and implicit_return into a single, composable decorator.
+"""
+
+import functools
+import inspect
+from textwrap import dedent
+from typing import Any, Callable, Optional
+
+from ..shared.errors import GuardClauseError, UnsupportedConstructError
+from ..shared.types import FailureBehavior, GuardFunction
+from .ast_transform import apply_implicit_return_transform
+from .guard_runtime import check_guards, handle_failure
+
+
+class guarded_expression:
+
+  """Unified decorator combining guard clauses with optional implicit return.
+
+  Guards are callables that return True (pass) or a string error message (fail).
+  On failure, behavior is determined by the `on_error` parameter.
+
+  Default behavior: Raises GuardClauseError on guard failure.
+
+  Args:
+      *guards: Guard functions returning True or error message string
+      implicit_return: Enable implicit return transformation (default: True)
+      on_error: Failure behavior (default: GuardClauseError) - can be:
+          - Value (str, int, None, etc.): Returned on guard failure
+          - Callable: Invoked with (error_msg, *args, **kwargs), return value used
+          - Exception class: Instantiated with error message and raised
+      log: If True, log guard failures at INFO level (default: False)
+
+  Usage:
+      @guarded_expression(
+          lambda x: x > 0 or "Must be positive",
+          implicit_return=True,
+          on_error=GuardClauseError
+      )
+      def safe_divide(x):
+          result = 100 / x
+          # No explicit return needed when implicit_return=True
+
+  """
+
+  def __init__(
+    self,
+    *guards: GuardFunction,
+    implicit_return: bool = True,
+    on_error: FailureBehavior = GuardClauseError,
+    log: bool = False,
+  ):
+    """Initialize the guarded_expression decorator.
+
+    Args:
+        *guards: Variable number of guard functions
+        implicit_return: Enable implicit return transformation
+        on_error: Behavior on guard failure
+        log: Enable logging of guard failures
+
+    """
+    self.guards = guards
+    self.implicit_return_enabled = implicit_return
+    self.on_error = on_error
+    self.log = log
+
+  def __call__(self, func: Callable[..., Any]) -> Callable[..., Any]:
+    """Apply guard wrapping and optional implicit return transformation."""
+    return (
+      self._apply_implicit_return(func)
+      if self.implicit_return_enabled
+      else self._wrap_with_guards(func)
+    )
+
+  def _apply_implicit_return(self, func: Callable[..., Any]) -> Callable[..., Any]:
+    """Apply implicit return transformation to the function."""
+    # Extract and parse source
+    try:
+      source = dedent(inspect.getsource(func))
+    except OSError as e:
+      raise UnsupportedConstructError(
+        'Source unavailable — guarded_expression with implicit_return=True requires importable source code.'
+      ) from e
+
+    # Transform the AST
+    new_tree, filename = apply_implicit_return_transform(source, func.__name__)
+
+    # Compile the transformed code in the original global scope
+    env = func.__globals__.copy()
+    code = compile(new_tree, filename=filename, mode='exec')
+    exec(code, env)
+
+    transformed = env[func.__name__]
+
+    # Wrap with guards and return
+    return self._wrap_with_guards(transformed, preserve_metadata_from=func)
+
+  def _wrap_with_guards(
+    self, func: Callable[..., Any], preserve_metadata_from: Optional[Callable[..., Any]] = None
+  ) -> Callable[..., Any]:
+    """Wrap the function with guard checking logic."""
+    metadata_source = preserve_metadata_from if preserve_metadata_from is not None else func
+
+    @functools.wraps(metadata_source)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+      # Check guards if any are defined
+      if self.guards:
+        error_msg = check_guards(self.guards, args, kwargs)
+        if error_msg is not None:
+          # Handle failure
+          result, exception_to_raise = handle_failure(
+            error_msg, self.on_error, func.__name__, args, kwargs, self.log
+          )
+          # Raise exception if configured
+          if exception_to_raise:
+            raise exception_to_raise
+          return result
+
+      # All guards passed - execute the function
+      return func(*args, **kwargs)
+
+    # Preserve explicit annotations for typing/IDE help
+    wrapper.__signature__ = inspect.signature(metadata_source)  # type: ignore[attr-defined]
+    wrapper.__annotations__ = getattr(metadata_source, '__annotations__', {})
+    return wrapper

modgud-0.2.1/modgud/guarded_expression/guard_runtime.py

@@ -0,0 +1,73 @@
+"""Pure guard checking logic extracted from guard_clause.
+
+Provides composable functions for evaluating guards and handling failures
+without decorator-specific concerns.
+"""
+
+import logging
+from typing import Any, Optional, Tuple
+
+from ..shared.types import FailureBehavior, GuardFunction
+
+# Module-level logger for guard failures
+_logger = logging.getLogger(__name__)
+
+
+def check_guards(
+  guards: Tuple[GuardFunction, ...], args: Tuple[Any, ...], kwargs: dict
+) -> Optional[str]:
+  """Pure function that evaluates all guards sequentially.
+
+  Args:
+      guards: Tuple of guard functions to evaluate
+      args: Positional arguments passed to the decorated function
+      kwargs: Keyword arguments passed to the decorated function
+
+  Returns:
+      None if all guards pass, or error message string if any guard fails
+
+  """
+  for guard in guards:
+    guard_result = guard(*args, **kwargs)
+    # Handle guard failure
+    if guard_result is not True:
+      return guard_result if isinstance(guard_result, str) else 'Guard clause failed'
+  return None
+
+
+def handle_failure(
+  error_msg: str,
+  on_error: FailureBehavior,
+  func_name: str,
+  args: Tuple[Any, ...],
+  kwargs: dict,
+  log_enabled: bool,
+) -> Tuple[Any, Optional[BaseException]]:
+  """Pure function that handles guard failure based on on_error configuration.
+
+  Args:
+      error_msg: The error message from the failed guard
+      on_error: The failure behavior configuration
+      func_name: Name of the decorated function (for logging)
+      args: Positional arguments passed to the decorated function
+      kwargs: Keyword arguments passed to the decorated function
+      log_enabled: Whether to log the failure
+
+  Returns:
+      Tuple of (return_value, exception_to_raise)
+      - If exception should be raised: (None, exception_instance)
+      - If value should be returned: (value, None)
+
+  """
+  # Log if enabled
+  if log_enabled:
+    _logger.info(f'Guard clause failed in {func_name}: {error_msg}')
+
+  # Handle failure based on on_error type
+  if isinstance(on_error, type) and issubclass(on_error, BaseException):
+    return None, on_error(error_msg)
+
+  if callable(on_error):
+    return on_error(error_msg, *args, **kwargs), None  # type: ignore[call-arg]
+
+  return on_error, None

modgud-0.2.1/modgud/shared/__init__.py

@@ -0,0 +1,21 @@
+"""Shared types and errors for the modgud library."""
+
+from .errors import (
+  ExplicitReturnDisallowedError,
+  GuardClauseError,
+  ImplicitReturnError,
+  MissingImplicitReturnError,
+  UnsupportedConstructError,
+)
+from .types import FailureBehavior, FailureTypes, GuardFunction
+
+__all__ = [
+  'GuardFunction',
+  'FailureBehavior',
+  'FailureTypes',
+  'GuardClauseError',
+  'ImplicitReturnError',
+  'ExplicitReturnDisallowedError',
+  'MissingImplicitReturnError',
+  'UnsupportedConstructError',
+]

modgud-0.2.1/modgud/shared/errors.py

@@ -0,0 +1,51 @@
+"""Shared error classes for the modgud library."""
+
+from typing import Optional
+
+
+class GuardClauseError(Exception):
+
+  """Exception raised when a guard clause fails."""
+
+  pass
+
+
+class ImplicitReturnError(SyntaxError):
+
+  """Base class for implicit-return related transformation errors."""
+
+  def __init__(
+    self, message: str, lineno: Optional[int] = None, col_offset: Optional[int] = None
+  ) -> None:
+    """Initialize the ImplicitReturnError with location information.
+
+    Args:
+        message: Error message describing the issue
+        lineno: Line number where the error occurred
+        col_offset: Column offset where the error occurred
+
+    """
+    super().__init__(message)
+    if lineno is not None:
+      self.lineno = lineno  # type: ignore[attr-defined]
+    if col_offset is not None:
+      self.offset = col_offset  # type: ignore[attr-defined]
+
+
+class ExplicitReturnDisallowedError(ImplicitReturnError):
+
+  """Raised when an explicit `return` statement is found in a decorated function."""
+
+
+class MissingImplicitReturnError(ImplicitReturnError):
+
+  """Raised when block cannot yield a value.
+
+  Raised when a block is required to yield a value but does not end with
+  a (convertible) final expression or a supported branching structure.
+  """
+
+
+class UnsupportedConstructError(ImplicitReturnError):
+
+  """Raised when an unsupported AST construct appears at a required return boundary."""

modgud-0.2.1/modgud/shared/types.py

@@ -0,0 +1,10 @@
+"""Shared type definitions for the modgud library."""
+
+from typing import Callable, Union
+
+# Guard function signature: (*args, **kwargs) -> True | str
+GuardFunction = Callable[..., Union[bool, str]]
+
+# Failure behavior types
+FailureTypes = Union[bool, str, int, float, None, dict, list, tuple]
+FailureBehavior = Union[FailureTypes, Callable, type]

modgud-0.2.1/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "modgud"
+version = "0.2.1"
+description = "Guard clauses are validation checks at the beginning of functions that exit early when preconditions aren't met. They prevent deeply nested conditional logic and make the \"happy path\" of your code more readable."
+authors = [
+    {name = "steven.miers@gmail.com"}
+]
+license = {text = "MIT"}
+requires-python = ">=3.13"
+
+repository = "https://github.com/terracoil/modgud"
+homepage = "https://pypi.org/project/modgud/"
+documentation = "https://github.com/terracoil/modgud/tree/main/docs"
+keywords = ["guards", "validation", "decorators", "defensive-programming", "single-return-point", "implicit-return"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
+]
+packages = [{include = "modgud"}]
+include = [
+    "LICENSE",
+    "README.md",
+    "modgud/py.typed",
+]
+
+
+[tool.poetry.dependencies]
+python = "^3.13"
+# No runtime dependencies - modgud only stdlib
+
+[dependency-groups]
+test = [
+    "pytest (>=8.4.2,<9.0.0)",
+    "pytest-cov (>=7.0.0,<8.0.0)",
+    "pytest-timeout (>=2.3.1,<3.0.0)",
+    "pytest-xdist (>=3.8.0,<4.0.0)",
+    "ruff (>=0.14.2,<0.15.0)"
+]
+dev = [
+    { include-group = "test" },
+    "freyja (>=1.0.22,<2.0.0)",
+    "mypy[reports] (>=1.18.2,<2.0.0)",
+    "pre-commit (>=4.3.0,<5.0.0)",
+    "poetry-dynamic-versioning (>=1.9.1,<2.0.0)"
+]
+
+[tool.mypy]
+cache_dir = "tmp/.mypy_cache"
+disallow_untyped_defs = true
+exclude = [
+    "build/",
+    "dist/",
+]
+
+# Output
+linecount_report = "reports/mypy/"
+linecoverage_report = "reports/mypy/"
+lineprecision_report = "reports/mypy/"
+python_version = "3.13"
+show_error_codes = true
+verbosity=1
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+cache_dir = "tmp/.pytest_cache"
+minversion = "8.0"
+addopts = "-ra -q --strict-markers --cov=modgud --cov-report=term-missing --cov-report=html:reports/coverage --cov-report=xml:reports/coverage/converage.xml"
+log_file = "tmp/pytest.log" # Path to the log file
+log_file_level = "DEBUG" # Minimum level for logging to file
+log_file_format = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)"
+log_file_date_format = "%Y-%m-%d %H:%M:%S"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+style = "semver"
+
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"