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

• [X] 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.
• [x] 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.

[RNKuhns]

@hynek I've updated this to handle default factories and include a description of the functionality in the attrs by examples section of the documentation.

Let me know when you have a chance to take a look.

[codspeed-hq[bot]]

CodSpeed Performance Report

Merging #1276 will degrade performances by 28.49%

_{Comparing RNKuhns:repr_optionally_exclude_param_defaults (9f1963b) with main (f5683b8)}

Summary

❌ 3 regressions ✅ 5 untouched benchmarks

:warning: _Please fix the performance issues or acknowledge them on CodSpeed._

Benchmarks breakdown

	Benchmark	main	RNKuhns:repr_optionally_exclude_param_defaults	Change
❌	test_create_frozen_class	1.7 s	2.3 s	-25.32%
❌	test_create_simple_class	1.5 s	2.1 s	-28.06%
❌	test_create_simple_class_make_class	1.5 s	2 s	-28.49%

[hynek]

Hey sorry once again, for all the delays. :( Before starting investigating, do you have any idea why this PR slows down class creation (not instantiation) by almost 30%? That's quite a lot and sadly a rather critical benchmark in the whole space of creating classes. :|

[RNKuhns]

@hynek I do plan to circle back on this. I've just got a couple things going on at the moment.

[RNKuhns]

Hey sorry once again, for all the delays. :( Before starting investigating, do you have any idea why this PR slows down class creation (not instantiation) by almost 30%? That's quite a lot and sadly a rather critical benchmark in the whole space of creating classes. :|

Not a problem -- I'll take a look at this and work through what is driving those performance degradations.