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

[MadLittleMods]

Feature

As proposed in wemake-services/wemake-python-styleguide#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.

-- python/peps#990 (comment)

---

In mypy, I could find that Final was added in #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.

-- #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.

eslint/archive-website#686 (comment)
Related discussion, eslint/eslint#5306

---

• shadowing
• masking
• overriding
• overwriting

[erictraut]

Do you want to mark select function parameters as Final, or are you looking for a mode where mypy treats all typed function parameters as though they were implicitly marked Final? The latter seems more akin to the ESlint approach, and it wouldn't require any change to the PEP.

[MadLittleMods]

or are you looking for a mode where mypy treats all typed function parameters as though they were implicitly marked Final?

🤔 I think that would be good.

I am trying to think what would most likely get included in Synapse (where I want to end up using it). And around the mutable default argument pattern which was brought up in the proposal in the other project, https://florimond.dev/en/posts/2018/08/python-mutable-defaults-are-the-source-of-all-evil/

(via wemake-services/wemake-python-styleguide#2128 (comment))

class NotOurClass(object):
    def method(self, a: Union[List[str], None] = None):
        """default impl"""

class OurClass(NotOurClass):
    def method(self, a: Union[List[str], None] = None):
        if a is None:
            a = []
        # our own impl

The following could work if mypy enforced at an entire codebase level by default. Then remaining problem is just the a vs sanitizedA usage mistake 🤷 but seems better than the wrong re-assigned value.

class OurClass(NotOurClass):
    def method(self, a: Union[List[str], None] = None):
        sanitizedA = a
        if a is None:
            sanitizedA = []
        # our own impl

Or explicitly allow when we want to use it with ignore comments. Although this one had a detractor: "noqa is also not an option here 😞 Because this pattern is really common and it is something you can hardly replace."

class OurClass(NotOurClass):
    def method(self, a: Union[List[str], None] = None):
        if a is None:
            # type: ignore[no-param-reassign] # noqa
            a = []
        # our own impl

[fabioz]

I'm a bit confused... the description seems to be for marking selected parameters as Final (which is what I'd expect to be implemented), but there's a comment asking whether everything should be implicitly marked as Final (which seems to be a different request).

I think that this request (from title and description) should cover the mark selected parameters as Final and a different request should be open for marking everything as final (and thus would need users to selectively mark things as Mutable I guess?)