Add Attribute.alias

[asford]

Summary

Spike implementation for #945.

Goals:

• [ ] This is silent no-op for "normal" users of attrs not using alias. Libraries building on attrs may use alias to detect both existing private-name init aliases and user-supplied aliases.
• [x] Add an alias : Optional[str] parameter to attr.ib et al and property to Attribute.
• [x] Lift current private-attribute-naming logic (name.lstrip("_")) into _ClassBuilder so that alias is always populated with the field's __init__ parameter name, regardless of whether an explicit alias is provided, during __init__ rendering and attr.fields introspection.
• [x] Leave Attribute.alias as None if not explicitly specified, so that field_transformer implementations can (a) create attributes without needing to be aware of alias and optionally provide alias overrides before attrs.
• [x] Update attr.evolve to use Attribute.alias rather than re-implemented name-mangling.
• [x] Update the attribute and private-attribute-handling documentation to note the new alias parameter.
• [ ] Expand dataclass_transform documentation to describe how alias can be used to inform type checkers of private-name renaming behavior.
• [ ] Politely file a bug against attrs noting the inconsistency between documentation and behavior.
• [ ] File a PR against against cattrs to access Attribute.alias during codegen iff available in attrs.

Non-goals:

• Modification of the existing private-attribute-naming logic, though could be tackled pre-release in a follow-up PR.

Pull Request Check List

• [x] Added tests for changed code. Our CI fails if coverage is not 100%.
• [ ] New features have been added to our Hypothesis testing strategy.
• [x] Changes or additions to public APIs are reflected in our type stubs (files ending in .pyi).
  • [x] ...and used in the stub test file tests/typing_example.py.
  • [x] If they've been added to attr/__init__.pyi, they've also been re-imported in attrs/__init__.pyi.
• [ ] Updated documentation for changed code.
  • [ ] New functions/classes have to be added to docs/api.rst by hand.
  • [x] Changes to the signature of @attr.s() have to be added by hand too.
  • [ ] Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives. Find the appropriate next version in our __init__.py file.
• [ ] Documentation in .rst files is written using semantic newlines.
• [ ] Changes (and possible deprecations) have news fragments in changelog.d.
• [ ] Consider granting push permissions to the PR branch, so maintainers can fix minor issues themselves without pestering you.

[hynek]

Anything you need from my end? 😇

[hynek]

w00t! Thanks for coming back! I'll try to be faster this time! :)

[asford]

Really appreciate your work on attrs. Thanks for being stoked on the contribution!

[Tinche]

Cool. Cattrs will be no problem, I can just bump the dependency to the latest version of attrs and implement it.

Mypy will be a bigger issue I think.

[hynek]

given alias is a dataclass transform feature, shouldn't it work OOB?

[Tinche]

Unsure, Mypy has a custom attrs plugin so I don't know if the dataclass_transform code path is in charge of this.

[hynek]

aw looks like you're right. pyright works: #1063

mypy doesn't:

Adding

AliasExample(without_alias=42, _with_alias=23)

gives me: tests/typing_example.py:134: error: Unexpected keyword argument "_with_alias" for "AliasExample"; did you mean "with_alias" or "without_alias"?

@Tinche 🐶🥺?

[Tinche]

Yeah, yeah. But we'd need to release attrs first.

[hynek]

yeah, it's super overdue too.

i'll try to get #1003 in ASAP (it's just an alias, so it should be just busywork) and push it out RSN.