Python Functions — Language Specification¶

function.__name__         # str: unqualified name
function.__qualname__     # str: qualified name (e.g. "Class.method")
function.__doc__          # str | None: docstring
function.__module__       # str: defining module name
function.__defaults__     # tuple | None: positional default values
function.__kwdefaults__   # dict | None: keyword-only default values
function.__code__         # code object
function.__globals__      # module's global namespace dict
function.__annotations__  # dict of annotations
function.__closure__      # tuple of cells | None (for closures)
function.__dict__         # namespace for arbitrary attributes
function.__wrapped__      # original function if decorated with functools.wraps

object.__call__(self, *args, **kwargs)
# An object is callable if it defines __call__.
# callable(obj) checks for __call__ without invoking it.

# When a function is accessed as a class attribute, __get__ converts it to a method:
function.__get__(obj, objtype=None) -> bound_method | function

generator.__next__()              # advance; raises StopIteration when done
generator.send(value)             # send value to yield; returns next yielded value
generator.throw(type[, value[, tb]])  # raise exception at yield point
generator.close()                 # raises GeneratorExit at yield point
generator.__iter__() -> self      # generators are iterators

def append_item(item, lst=[]):   # lst shared across all calls
    lst.append(item)
    return lst

print(append_item(1))   # [1]
print(append_item(2))   # [1, 2]  — same list!
print(append_item(3))   # [1, 2, 3]

# Fix:
def append_item_safe(item, lst=None):
    if lst is None:
        lst = []
    lst.append(item)
    return lst

# TRAP: all closures reference the same 'i' cell
funcs = [lambda: i for i in range(5)]
print([f() for f in funcs])   # [4, 4, 4, 4, 4]  — all see i=4

# Fix: default argument captures the value at definition time
funcs = [lambda i=i: i for i in range(5)]
print([f() for f in funcs])   # [0, 1, 2, 3, 4]

x = 10

def f():
    print(x)   # UnboundLocalError! x is local because assigned below
    x = 20

# Fix:
def g():
    global x
    print(x)   # 10
    x = 20

def counter():
    count = 0
    def increment():
        nonlocal count
        count += 1
        return count
    return increment

c = counter()
print(c())   # 1
print(c())   # 2
print(c())   # 3

def sub():
    yield 1
    yield 2
    return "sub_done"   # becomes the value of 'yield from'

def main():
    result = yield from sub()   # result = "sub_done"
    print(f"Sub returned: {result}")
    yield 3

for v in main():
    print(v)   # 1, 2, 3

def add(a, b, /, c=0):
    return a + b + c

add(1, 2)         # OK
add(1, 2, c=3)    # OK
# add(a=1, b=2)   # TypeError: a is positional-only

import functools
from typing import Callable, TypeVar

T = TypeVar("T")

# ----------------------------------------------------------------
# 1. All parameter types in one function
# ----------------------------------------------------------------
def full_params(pos_only, /, normal, *args, kw_only, **kwargs):
    print(f"pos_only={pos_only!r}")
    print(f"normal={normal!r}")
    print(f"args={args!r}")
    print(f"kw_only={kw_only!r}")
    print(f"kwargs={kwargs!r}")

full_params(1, 2, 3, 4, kw_only="k", extra="x")
# pos_only=1, normal=2, args=(3, 4), kw_only='k', kwargs={'extra': 'x'}


# ----------------------------------------------------------------
# 2. Default arguments (evaluated once)
# ----------------------------------------------------------------
import time

def cached_now(ts=None):
    if ts is None:
        ts = time.time()
    return ts

# Calling multiple times returns different values (ts=None each time)
print(cached_now())
print(cached_now())


# ----------------------------------------------------------------
# 3. *args and **kwargs unpacking in calls
# ----------------------------------------------------------------
def add(a, b, c):
    return a + b + c

args_tuple = (1, 2, 3)
kwargs_dict = {"a": 1, "b": 2, "c": 3}

print(add(*args_tuple))    # 6
print(add(**kwargs_dict))  # 6
print(add(1, *[2, 3]))     # 6


# ----------------------------------------------------------------
# 4. Generator function
# ----------------------------------------------------------------
def countdown(n: int):
    while n > 0:
        yield n
        n -= 1

for val in countdown(5):
    print(val, end=" ")   # 5 4 3 2 1
print()

# Generator as iterator
gen = countdown(3)
print(next(gen))   # 3
print(next(gen))   # 2
print(list(gen))   # [1]  — exhausts the generator


# ----------------------------------------------------------------
# 5. yield from
# ----------------------------------------------------------------
def chain(*iterables):
    for it in iterables:
        yield from it

print(list(chain([1, 2], [3, 4], [5])))  # [1, 2, 3, 4, 5]


# ----------------------------------------------------------------
# 6. Closure and nonlocal
# ----------------------------------------------------------------
def make_accumulator(start=0):
    total = start
    def add(n):
        nonlocal total
        total += n
        return total
    return add

acc = make_accumulator()
print(acc(10))  # 10
print(acc(5))   # 15
print(acc(3))   # 18


# ----------------------------------------------------------------
# 7. Decorator
# ----------------------------------------------------------------
def timing(func):
    import time
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.6f}s")
        return result
    return wrapper

@timing
def slow_sum(n: int) -> int:
    return sum(range(n))

result = slow_sum(100_000)
print(result)   # 4999950000


# ----------------------------------------------------------------
# 8. Class decorator
# ----------------------------------------------------------------
def singleton(cls):
    instances = {}
    @functools.wraps(cls)
    def get_instance(*args, **kwargs):
        if cls not in instances:
            instances[cls] = cls(*args, **kwargs)
        return instances[cls]
    return get_instance

@singleton
class Config:
    def __init__(self, val=42):
        self.val = val

c1 = Config()
c2 = Config()
print(c1 is c2)   # True


# ----------------------------------------------------------------
# 9. Positional-only parameters (PEP 570)
# ----------------------------------------------------------------
def normalize(x, y, z, /, scale=1.0):
    import math
    length = math.sqrt(x**2 + y**2 + z**2)
    return (x/length * scale, y/length * scale, z/length * scale)

print(normalize(1, 0, 0))        # (1.0, 0.0, 0.0)
print(normalize(1, 0, 0, scale=2.0))  # (2.0, 0.0, 0.0)
# normalize(x=1, y=0, z=0)  # TypeError


# ----------------------------------------------------------------
# 10. Lambda
# ----------------------------------------------------------------
square = lambda x: x ** 2
print(square(5))   # 25

pairs = [(1, 3), (2, 1), (3, 2)]
pairs.sort(key=lambda p: p[1])
print(pairs)   # [(2, 1), (3, 2), (1, 3)]


# ----------------------------------------------------------------
# 11. Type parameters in function def (Python 3.12, PEP 695)
# ----------------------------------------------------------------
def first[T](lst: list[T]) -> T:
    return lst[0]

print(first([1, 2, 3]))        # 1
print(first(["a", "b", "c"]))  # a


# ----------------------------------------------------------------
# 12. Introspecting function metadata
# ----------------------------------------------------------------
import inspect

def greet(name: str, greeting: str = "Hello") -> str:
    """Return a greeting string."""
    return f"{greeting}, {name}!"

sig = inspect.signature(greet)
print(sig)                          # (name: str, greeting: str = 'Hello') -> str
print(greet.__annotations__)        # {'name': <class 'str'>, ...}
print(greet.__defaults__)           # ('Hello',)
print(greet.__doc__)                # Return a greeting string.