Allow `Final` in type arguments to avoid shadowing arguments - disallow reassignment of function parameters

Feature

As proposed in https://github.com/wemake-services/wemake-python-styleguide/issues/2128, I am looking to find a way to disallow reassignment of function parameters. During the discussion, I discovered that Final was introduced in PEP 591 and seemed like a great solution but I ran into the limitation around function arguments:

Final can’t be used in annotations for function arguments:

https://mypy.readthedocs.io/en/stable/final_attrs.html#details-of-using-final

---

I was curious on why the limitation was there in the first place but all I could really find was from the PEP 591 PR on GitHub. And was unable to find the pre-discussion on the mailing list or that GitHub project.

Two more things worth mentioning in rejected ideas: [...]

2. allow Final in function argument annotations

For the second point, it would cause too much confusion with function not mutating the argument.

-- https://github.com/python/peps/pull/990#commitcomment-33164572

---

In mypy, I could find that Final was added in https://github.com/python/mypy/pull/5522 which mentions:

I don't allow Final in function argument types. One argument is simplicity, another is I didn't see many bugs related to shadowing an argument in function bodies, finally people might have quite different expectations for this. If people will ask, this would be easy to implement.

-- https://github.com/python/mypy/pull/5522

In a previous revision of the documentation, it mentioned this example:

• Final can be only used as an outermost type in assignments, using it in
  any other position is an error. In particular, Final can't be used in
  annotations for function arguments because this may cause confusions about
  what are the guarantees in this case:

: List[Final[int]] = []  # Error!
def fun(x: Final[List[int]]) ->  None:  # Error!

-- https://github.com/python/mypy/pull/5522/files/c9abd9db835240962467a9ee164f4bbb50d56545#diff-3b595f6f83800d78a304cf528ed39aff352c8cd8282edda26bafced79646baad

Pitch

Allow Final in type arguments.

Recently ran into a real-life bug because of accidentally re-assigning a function parameter, https://github.com/matrix-org/synapse/pull/10439/files/a94217ee34840237867d037cf1133f3a9bf6b95a

Simplified reproduction case (original code):

def ensure_correct_context(event: EventBase, context: EventContext):
  remote_auth_chain = get_event_auth(event)
  for auth_event in remote_auth_chain:
    # XXX: Problem is here!
    # We are introducing a bug because `context` which corresponds to `event`
    # is being re-assigned to the `context` for the `auth_event`
    context = compute_event_context(auth_event)
    persist_event(auth_event, context)

  # logic for context_needs_updating

  if context_needs_updating:
    return compute_event_context(event)

  return context

Fixed code:

def ensure_correct_context(event: EventBase, context: EventContext):
  remote_auth_chain = get_event_auth(event)
  for auth_event in remote_auth_chain:
    auth_event_context = compute_event_context(auth_event)
    persist_event(auth_event, auth_event_context)

  # logic for context_needs_updating

  if context_needs_updating:
    return compute_event_context(event)

  return context

Proposed mypy code that would trigger a violation for the bug to catch it in the first place when writing the original code:

def ensure_correct_context(event: EventBase, context: Final[EventContext]):
  remote_auth_chain = get_event_auth(event)
  for auth_event in remote_auth_chain:
    # XXX: Violation shold trigger here!
    # We are introducing a bug because `context` which corresponds to `event`
    # is being re-assigned to the `context` for the `auth_event`
    context = compute_event_context(auth_event)
    persist_event(auth_event, context)

  # logic for context_needs_updating

  if context_needs_updating:
    return compute_event_context(event)

  return context

---

I am coming at this from a JavaScript background where ESlint has a no-param-reassign rule for JavaScript which disallows reassignment of function parameters.

Assignment to variables declared as function parameters can be misleading and lead to confusing behavior, as modifying function parameters will also mutate the arguments object. Often, assignment to function parameters is unintended and indicative of a mistake or programmer error.

https://eslint.org/docs/rules/no-param-reassign

Why? Manipulating objects passed in as parameters can cause unwanted variable side effects in the original caller.

https://airbnb.io/javascript/#functions--mutate-params

It's also about the clarity of mutating and reassigning - it's easier to understand functions when the arguments are static and constant throughout the life of the function.

https://github.com/eslint/website/issues/686#issuecomment-577419721
Related discussion, https://github.com/eslint/eslint/issues/5306

---

• shadowing
• masking
• overriding
• overwriting

Start by reading the PEP 591 restriction and mypy's existing Final implementation described in PR #5522. Review the linked examples and discussion about function argument annotations and reassignment semantics. Done means a decided behavior for Final in function parameters, with reassignment violations reported consistently.