"""
Functions are reusable blocks of code that perform a specific task.

In Python, functions are first-class citizens, meaning they can be passed as
arguments to other functions, returned from other functions, and assigned to
variables. This module covers parameter definition, argument passing, function scope
following the LEGB (Local, Enclosing, Global, Built-in) lookup rule, and the
consequences of mutable vs immutable default parameter values.
"""

from collections.abc import Callable
from functools import partial
from typing import Any


def add(x: Any, y: Any) -> Any:
    """Add two objects together to produce a new object.

    Two differences between `add` and `main` are that:

    - It accepts input parameters
    - It returns a value
    """
    return x + y


def sum_until(fn: Callable[[int], int], n: int) -> int:
    """Sum function results from 0 until n - 1.

    This expects a function to be provided as its first input and an integer
    as its second input. Like `add`, `sum_until` returns a value.

    The fact that a function can be passed into `sum_until` highlights a core
    concept that was mentioned before: everything in Python is an object, and
    that includes this docstring!
    """
    total = 0
    for i in range(n):
        total += fn(i)
    return total


def without_parameters() -> object:
    """A function that does not accept parameters and does not return a value.

    The return type is annotated as `object` to allow callers that assert
    on the returned value (e.g. `assert without_parameters() is None`) without
    triggering static checker complaints about a function annotated as
    returning None being used as a value.
    """
    return None


def main() -> None:
    # The `add` function can be used for numbers as expected
    add_result_int = add(1, 2)
    assert add_result_int == 3

    # We can use `functools.partial` to create a new function with some
    # arguments pre-filled, which is a cleaner alternative to lambdas in many cases.
    add_five = partial(add, 5)
    assert add_five(10) == 15

    # The `add` function can be used for strings as well
    add_result_string = add("hello", " world")
    assert add_result_string == "hello world"

    # Run the input function multiple times. Notice that we make use of
    # `lambda` to create an anonymous function (i.e. a function without
    # a name) that accepts one input and does something with it. Anonymous
    # functions are powerful because they allow us to write functions
    # inline, unlike `add` and `sum_until`
    run_results = sum_until(lambda i: i * 100, 5)
    assert run_results == 1000, run_results

    # We can see the `sum_until` docstring by accessing the `__doc__` magic
    # attribute! Remember this - everything in Python is an object
    # `__doc__` may be None in some environments, coalesce to an empty string
    assert "includes this docstring!" in (sum_until.__doc__ or "")

    # Call a function without parameters
    assert without_parameters() is None


if __name__ == "__main__":
    main()