Add default args to Signed constructors #1922

jku · 2022-03-24T09:32:32Z

Tweak the constructor signatures to make creating brand new Metadata easier (the constructors were originally designed for deserialization purposes). Modify examples and tests to use the new constructor args.

The changes are backwards compatible. Resulting API is much easier to use for creating new Metadata. The API is still a bit unusual but not difficult to learn IMO:

targets = Metadata(Targets())

There are some noteworthy cases:

expires does not have a reasonable default value and I planned to leave it a required argument. That would have broken backwards compat however as order of arguments would have had to change. So expires now defaults to an arbitrary 1 day in future EDIT: changed to utcnow() so default is expired metadata
consistent_snapshot defaults to True but None is still possible to indicate Metadata does not contain the field at all
spec_version defaults to whatever is the current library supported version

Only the core metadata classes we're updated. There are other classes that would probably benefit from a better constructor, like Delegations, but those were not handled yet.

Fixes #1459

Please verify and check that the pull request fulfills the following
requirements:

The code follows the Code Style Guidelines
Tests have been added for the bug fix or new feature
Docs have been added for the bug fix or new feature

This allows creating new metadata with less boilerplate: root = Metadata(Root()) targets = Metadata(Targets()) Set reasonable default values for all the arguments -- version to 1, spec_version to current supported version, etc. Expires does not have a good default value and my original plan was to require expires argument to be set. That would mean an incompatible API change though as arguments before expires would be now optional... So expires now defaults to an arbitrary value of 1 day from moment of creation. One noteworthy special case is consistent_snapshot where the default value is True (since that's what we want people to use for new metadata) but None is also used to imply that metadata does not contain the field at all. Signed-off-by: Jussi Kukkonen <[email protected]>

Signed-off-by: Jussi Kukkonen <[email protected]>

jku · 2022-03-24T09:33:47Z

Tests have been added for the bug fix or new feature

The generated tests and serialization tests do a good job testing this I believe.

Docs have been added for the bug fix or new feature

Metadata docstring should maybe be improved to show an example of creating a new Metadata...

coveralls · 2022-03-24T09:37:22Z

Pull Request Test Coverage Report for Build 2089353376

24 of 24 (100.0%) changed or added relevant lines in 3 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.02%) to 98.326%

Totals
Change from base Build 2088921056:	0.02%
Covered Lines:	1187
Relevant Lines:	1203

💛 - Coveralls

tuf/api/metadata.py

MVrachev

Overall, the changes are great with a few comments.

I am wondering whether we should simplify and use the default attribute values in the examples scripts?
For those examples, I think we all agree the most important priority is that the code is easy to understand.
Otherwise, the simplifications are great, no doubt.

tuf/api/metadata.py

tests/generated_data/generate_md.py

MVrachev · 2022-03-24T10:38:07Z

tests/generated_data/generate_md.py

+    md_timestamp = Metadata(Timestamp(expires=EXPIRY))
+    md_snapshot = Metadata(Snapshot(expires=EXPIRY))
+    md_targets = Metadata(Targets(expires=EXPIRY))


I really like you don't have to create temporary Signed objects but you can't directly instantiate a Metadata object with populated default Signed fields as well.
Really cool!

Signed-off-by: Jussi Kukkonen <[email protected]>

If argument is an empty container, we want to use the given empty container. Only create a new container if argument is None. Signed-off-by: Jussi Kukkonen <[email protected]>

This means the metadata is by default expired: this seems like a fine default since we only allow a default value for practical reasons (not allowing it would mean backwards incompatible API change). Signed-off-by: Jussi Kukkonen <[email protected]>

jku · 2022-03-24T14:22:27Z

I believe all comments we're resolved with additional commits:

more docs for the default values
more care taken with empty containers as args (this issue is theoretically there for unrecognised_fields as well btw)
expires default is utcnow() (so expired out of the gate)
some unused variables cleaned up

jku · 2022-03-24T14:23:45Z

I am wondering whether we should simplify and use the default attribute values in the examples scripts?

I believe this is done, if you have specific place you're thinking of let me know.

tuf/api/metadata.py

MVrachev · 2022-03-25T17:59:56Z

I am wondering whether we should simplify and use the default attribute values in the examples scripts?

I believe this is done, if you have specific place you're thinking of let me know.

I am sorry, I think I was unclear.
I meant do we want to change anything inside the examples folders at all?
My point was that the primary purpose of all examples scripts is to be easily understandable and this new syntax using the default values could hide some details.

jku · 2022-03-28T07:06:54Z

examples scripts is to be easily understandable and this new syntax using the default values could hide some details.

If there is a specific case where this is true I'm willing to discuss. I just don't see one, everything seems to have a fairly obvious default value apart from expiry.

lukpueh

I love the change! Please fix typo (see inline) and this is good to go.

The comment about the docstring is not a blocker nor is this one:
Re beeing more careful with empty containers (d8c0f3b), should we also update all the unrecognized_fields or {} in Metadata constructors?

tuf/api/metadata.py

jku · 2022-04-04T09:07:59Z

Force pushed with the documentation commit amended with three fixes for issues pointed out in comments (the last three resolved discussions).

Re beeing more careful with empty containers (d8c0f3b), should we also update all the unrecognized_fields or {} in Metadata constructors?

I'll file an issue: it's pretty minor but strictly speaking yes we should

tuf/api/metadata.py

Signed-off-by: Jussi Kukkonen <[email protected]>

jku · 2022-04-04T10:51:53Z

Once more, force-pushed with a fix for latest resolved review comment

lukpueh

Thanks!

Jussi Kukkonen added 3 commits March 23, 2022 17:25

tests: Use the default Metadata constructor args

220e854

Signed-off-by: Jussi Kukkonen <[email protected]>

examples: Use the constructor default arguments

8071806

Signed-off-by: Jussi Kukkonen <[email protected]>

jku commented Mar 24, 2022

View reviewed changes

tuf/api/metadata.py Outdated Show resolved Hide resolved

MVrachev reviewed Mar 24, 2022

View reviewed changes

Jussi Kukkonen added 3 commits March 24, 2022 14:20

tests: Remove unused variables from generate_md

4392574

Signed-off-by: Jussi Kukkonen <[email protected]>

Metadata API: Be more careful with container args

d8c0f3b

If argument is an empty container, we want to use the given empty container. Only create a new container if argument is None. Signed-off-by: Jussi Kukkonen <[email protected]>

MVrachev reviewed Mar 25, 2022

View reviewed changes

tuf/api/metadata.py Outdated Show resolved Hide resolved

lukpueh requested changes Apr 1, 2022

View reviewed changes

tuf/api/metadata.py Outdated Show resolved Hide resolved

tuf/api/metadata.py Outdated Show resolved Hide resolved

jku force-pushed the constructor-defaults branch from 8148efb to 8039d99 Compare April 4, 2022 09:06

jku requested a review from lukpueh April 4, 2022 09:21

lukpueh reviewed Apr 4, 2022

View reviewed changes

tuf/api/metadata.py Outdated Show resolved Hide resolved

Metadata API: Document constructor default arguments

0d3bb68

Signed-off-by: Jussi Kukkonen <[email protected]>

jku force-pushed the constructor-defaults branch from 8039d99 to 0d3bb68 Compare April 4, 2022 10:50

lukpueh approved these changes Apr 4, 2022

View reviewed changes

lukpueh merged commit b350847 into theupdateframework:develop Apr 4, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add default args to Signed constructors #1922

Add default args to Signed constructors #1922

jku commented Mar 24, 2022 •

edited

Loading

jku commented Mar 24, 2022 •

edited

Loading

coveralls commented Mar 24, 2022 •

edited

Loading

MVrachev left a comment •

edited

Loading

MVrachev Mar 24, 2022

jku commented Mar 24, 2022

jku commented Mar 24, 2022

MVrachev commented Mar 25, 2022

jku commented Mar 28, 2022

lukpueh left a comment

jku commented Apr 4, 2022 •

edited

Loading

jku commented Apr 4, 2022

lukpueh left a comment

Add default args to Signed constructors #1922

Add default args to Signed constructors #1922

Conversation

jku commented Mar 24, 2022 • edited Loading

jku commented Mar 24, 2022 • edited Loading

coveralls commented Mar 24, 2022 • edited Loading

Pull Request Test Coverage Report for Build 2089353376

💛 - Coveralls

MVrachev left a comment • edited Loading

Choose a reason for hiding this comment

MVrachev Mar 24, 2022

Choose a reason for hiding this comment

jku commented Mar 24, 2022

jku commented Mar 24, 2022

MVrachev commented Mar 25, 2022

jku commented Mar 28, 2022

lukpueh left a comment

Choose a reason for hiding this comment

jku commented Apr 4, 2022 • edited Loading

jku commented Apr 4, 2022

lukpueh left a comment

Choose a reason for hiding this comment

jku commented Mar 24, 2022 •

edited

Loading

jku commented Mar 24, 2022 •

edited

Loading

coveralls commented Mar 24, 2022 •

edited

Loading

MVrachev left a comment •

edited

Loading

jku commented Apr 4, 2022 •

edited

Loading