feat(requirements): add Requirement.__replace__

[henryiii]

Let's start by providing a nice way to do this, then we can (maybe) deprecate in the future. Quite a few projects are mutating this.

---

Previous (available on a branch requirement-replace-and-deprecate in my fork for the future):

This was proposed in #1252. This assumes we want a deprecation period.

This enables caching __hash__, and __hash__ was always broken if you mutated this class
while it was in a set or similar.

Added support for __replace__ as an alternative if anyone was trying to mutate these.

Mutating the extras set inside doesn't warn. We should swap it for a frozenset when making this immutable.

Assisted-by: ClaudeCode:claude-fable-5

[henryiii]

Re: deprecation period: Yes, projects are mutating. :)

[shinzoxD]

copy.replace requires the replacement to have the same dynamic type as the input, but this implementation always constructs Requirement directly. On Python 3.13 at head f5bdf9e:

class CustomRequirement(Requirement):
    pass

result = copy.replace(CustomRequirement(demo>=1), name=renamed)
print(type(result).__name__, isinstance(result, CustomRequirement))
# Requirement False

This contradicts both the copy.replace / object.__replace__ contract and the neighboring Version.__replace__, which preserves self.__class__. Please preserve the subclass type and add coverage for direct __replace__ plus copy.replace on a subclass.

Also, this is a new public API, while the project contribution guide says new features should be documented in the changelog; please add a 26.4 entry.

The existing focused suite is otherwise clean locally: 5,334 passed and 1 Python-version skip; git diff --check is clean and all 62 upstream checks are green.

[notatallshaw]

Found a couple of issues.

[notatallshaw]

I think this needs a follow up PR, or the scope of this PR needs to grow, because it's a problem with pickling as well, but specifiers can carry policy that a requirement string cannot represent:

spec = SpecifierSet([Specifier(">=1", prereleases=True)])
result = Requirement("demo").__replace__(specifier=spec)

spec.filter(["1.1rc1", "1.1"]) keeps both; result.specifier.filter(...) drops 1.1rc1.

I think replacement needs to preserve a copy of spec after parsing the other fields, and Requirement.__getstate__ would also need to retain its inner policy for pickle round trips.

[henryiii]

Fixed with a copy.deepcopy (pickle, copy.copy and copy.deepcopy still need a followup).