A function signature gives callers the function’s name and parameters: the shape of a call. Arguments are the values supplied by a caller; parameters are the names in the definition that receive them. In a Python API, parameter order, keyword names, and defaults all affect how easy that call is to understand and use. section 3.1.2 section 3.2.2
print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)
The signature of `print` shows a flexible call: `*objects` accepts multiple values, while `sep`, `end`, `file`, and `flush` have defaults that callers can change by name. section 3.1.2
Choose a signature for the calls people will actually make. `full_name(fname, mname, lname)` permits positional calls, where order matters, and keyword calls, where names make the inputs explicit. Making `mname` optional with `full_name(fname, mname=None, lname=None)` also permits a call such as `full_name("John", lname="Smith")`. A `**kwargs` parameter offers more flexibility, but can hide which keywords the function expects unless they are documented. section 3.2.2 section 3.2.2
Across related functions, keep a shared input in the same position and give it the same name when possible. Functions that work on `user_data`, for example, are easier to read together when each takes that dictionary first. The same principle applies to shared file handles or database resources. section 3.2.2
Extend behavior without changing every call
Suppose existing code calls `get_name(person)` to format email greetings. Adding a `tone` parameter would require updating those calls. Separate modules can instead provide formal, informal, and casual implementations with the same `get_name(person)` signature; the application selects the appropriate function while its later call stays unchanged. section 2.3.5
A useful signature makes expected inputs visible, keeps related calls predictable, and avoids unnecessary changes to callers. Here, “signature” concerns the callable name and parameters, not a formal statement of input and return types. section 3.1.2 section 2.3.5
