Provide option in attrs.define to allow users to exclude parameters set to default value from repr

[RNKuhns]

Summary

This PR provides functionality in line with #1193.

It adds a new parameter to attrs.define to allow users to toggle on/off the ability to create classes that dynamically generate their repr to include only parameters set to values other than their default. The added parameter is set to a default value that maintains the existing functionality (always have static repr).

The functionality is designed to work such as follows:

@attrs.define(kw_only=True, only_non_default_attr_in_repr=True)
class SomeClass:

    something: int | None = attrs.field(default=None, repr=True)
    something_else: bool = attrs.field(default=False, repr=True)
    another: float | None = attrs.field(default=11.0, init=False, repr=False)


some_class = SomeClass(something=7)
SomeClass(something=7)


# If we wanted to exclude the something param from the repr in the field def we still can
@attrs.define(kw_only=True, only_non_default_attr_in_repr=True)
class SomeClass:

    something: int | None = attrs.field(default=None, repr=False)
    something_else: bool = attrs.field(default=False, repr=True)
    another: float | None = attrs.field(default=11.0, init=False, repr=False)


some_class = SomeClass(something=7)
SomeClass()


# The default is equivalent of only_non_default_attr_in_repr=False, so existing behavior is default
@attrs.define(kw_only=True)
class SomeClass:

    something: int | None = attrs.field(default=None)
    something_else: bool = attrs.field(default=False)
    another: float | None = attrs.field(default=11.0, init=False, repr=False)


some_class = SomeClass(something=7)
SomeClass(something=7, something_else=False)


# The use of repr in a field works just like it did before so we can exclude individual attributes
# from the repr (or pass custom callable)
@attrs.define(kw_only=True)
class SomeClass:

    something: int | None = attrs.field(default=None, repr=False)
    something_else: bool = attrs.field(default=False)
    another: float | None = attrs.field(default=11.0, init=False)


some_class = SomeClass(something=7)
SomeClass(something_else=False, another=11.0)

@hynek I'll look into creating some simple test cases (like above examples) to test cases for this. But I'd appreciate some feedback on whether this approach makes sense to you before I finish up with that.

Note there might be some nuisance edits to the _make.py that ruff made when I saved the file in my setup, but these should be minor.

Pull Request Check List

• Do not open pull requests from your main branch – use a separate branch!
  • There's a ton of footguns waiting if you don't heed this warning. You can still go back to your project, create a branch from your main branch, push it, and open the pull request from the new branch.
  • This is not a pre-requisite for your your pull request to be accepted, but you have been warned.
• Added tests for changed code.
  Our CI fails if coverage is not 100%.
• New features have been added to our Hypothesis testing strategy.
• Changes or additions to public APIs are reflected in our type stubs (files ending in .pyi).
  • ...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.
• [ X] Updated documentation for changed code.
  • [ X] 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.
  • [ X] Changed/added classes/methods/functions have appropriate versionadded, versionchanged, or deprecated directives.
    The next version is the second number in the current release + 1.
    The first number represents the current year.
    So if the current version on PyPI is 22.2.0, the next version is gonna be 22.3.0.
    If the next version is the first in the new year, it'll be 23.1.0.
• [ X] Documentation in .rst and .md 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.

[RNKuhns]

Note that I'll also add examples to the docs before this is finalized/merged if the concept moves forward.

[RNKuhns]

@hynek I know you are probably busy, but I just wanted to check in to see if you had a chance to take a look and provide feedback.

[hynek]

yeah sorry I'm swamped right now, as you can tell in my own PR #1267 that hasn't moved in a while. I don't have the headspace for bigger changes right now, but it won't get lost as long as you leave it open. I hope to be able to clean up the trackers before leaving for PyCon US (2024 – just in case ;))

[RNKuhns]

yeah sorry I'm swamped right now, as you can tell in my own PR #1267 that hasn't moved in a while. I don't have the headspace for bigger changes right now, but it won't get lost as long as you leave it open. I hope to be able to clean up the trackers before leaving for PyCon US (2024 – just in case ;))

No problem at all! I'll leave it open and add some of the finishing touches (tests cases, docs) as I have time on the next week or two.