object inspection: produce deterministic descriptions for nested collection datastructures

[jayaddison]

Feature or Bugfix

• Bugfix

Purpose

• Improve deterministic reproducibility of documentation

Detail

• util.inspect.object_description already attempts to sort collections, but this can fail
• This changeset handles the failure case by using string-based object descriptions as a fallback deterministic sort ordering
• This changeset also adds recursive object-description calls for list and tuple datatypes

Relates

• May resolve util.inspect.object_description: does not emit reliable ordering for a set nested within another collection #11198

[jayaddison]

(force-pushed to edit my commit authorship because I remembered that puzzling over this originated from use of alembic at work)

[AA-Turner]

Is this ready to merge?

A

[jayaddison]

@AA-Turner I think so, but I'd like to wait until the other changes I have pending for 6.2 are sorted out before merging this one.

(it takes me quite a while to regain context when re-reading about each change, and so I think I can better-support a small number of changes introduced gradually)

[jayaddison]

I'll try to be a bit more precise than my previous message: I'd like to wait until after the 6.2.0 release, before this can be merged.

[jayaddison]

@AA-Turner do we have any mechanisms to monitor memory usage and/or runtime performance impact of pull requests?

I'm now comfortable with this being merged, but would be more confident if we had some performance statistics available (in particular, it's the collection of seen object identifiers in one of the post-approval commits that I'm wondering about).

[david-a-wheeler]

I'm really glad to see this work to deterministically reproduce documents. Thank you!

[jayaddison]

I'm now comfortable with this being merged, but would be more confident if we had some performance statistics available (in particular, it's the collection of seen object identifiers in one of the post-approval commits that I'm wondering about).

Maybe slightly off-topic, but from looking into pytest-compatible performance testing tools: pytest-austin looks potentially promising to me. I might try it out for some unrelated projects, although would also be glad to help try it out here if that'd be useful.

The pytest-austin repository itself hasn't had much commit/contributor activity, but I don't think that's a negative indicator; it pulls-in a related dependency, austin, to perform the measurement tasks, and that does appear to be actively maintained.

[paravoid]

I'll try to be a bit more precise than my previous message: I'd like to wait until after the 6.2.0 release, before this can be merged.

Should this be merged now then? Thanks!

[jayaddison]

This can be merged in my opinion - I've re-reviewed the changes to confirm my sense about that. Whether it should be merged remains up to the maintainers.

[david-a-wheeler]

Thanks so much for considering this! Making descriptions deterministic will make it easier to determine if a given package really was generated by its claimed source. I hope this (or something like it) will be merged.

[jayaddison]

Thanks @david-a-wheeler - to be transparent: I can't guarantee that this resolves the only remaining source of non-replicable documentation; there may be other scenarios where generated documentation can differ. Similarly, it may not be the best possible approach to making these descriptions deterministic; but it's an improvement, I think.

[david-a-wheeler]

@jayaddison - I understand. Improvements are improvements, though!

[AA-Turner]

Thanks @jayaddison @lamby @paravoid!

A

[jayaddison]

Thank you, @AA-Turner!