from typing import Callable, NoReturn, Any


def todo_str(what: str) -> NoReturn:
  """
  A placeholder for code that needs to be implemented.
  Raises a NotImplementedError with a descriptive message about the call site.
  Can be inserted anywhere in the code where functionality is yet to be implemented, without basedpyright screaming warnings.
  """
  import inspect
  import sys

  # Temporarily suppress the traceback to show a cleaner error message.
  sys.tracebacklimit = 0
  caller_frame = inspect.stack()[1]
  message = (
    f"\n\nTODO: {'Implementation needed' if not what else f'{f"Implement {what}" if not what.startswith("Implement") else what}'}\n"
    f"      in function '{caller_frame.function}'\n"
    f"      at {caller_frame.filename}:{caller_frame.lineno}\n"
  )
  raise NotImplementedError(message)


def todo_wrap(what: Callable[..., Any]) -> Callable[..., NoReturn]:  # pyright: ignore[reportExplicitAny]
  """
  A decorator that can be used to mark entire functions as TODOs.
  When the decorated function is called, it raises a NotImplementedError with a descriptive message about the call site.
  """

  def wrapper(*args: Any, **kwargs: Any) -> NoReturn:  # pyright: ignore[reportExplicitAny, reportAny, reportUnusedParameter]
    _ = todo_str(f"Implement {what.__name__}")

  return wrapper


def todo(what: str | Callable[..., Any] = "") -> NoReturn | Callable[..., NoReturn]:  # pyright: ignore[reportExplicitAny]
  match what:
    case str():
      return todo_str(what)
    case Callable():
      return todo_wrap(what)
