Formalize types, content, and documentation for revision specs.
Review Request #12586 — Created Sept. 7, 2022 and submitted
Revision specs are a nice way for a SCMClient to convert user-provided
input to formal values that the SCMClient can use to determine
revisions. While most SCMClients use the same keys (
tip, and a
few others), they have different needs when it comes to values (some use
strings, some integers, and in the case of TFS, lists or tuples of
values). On top of that, SOS needs its own special keys.
A previous attempt was made at creating a
describe the possible keys, but this was limiting in types of values,
assuming they were all strings.
TypedDictalso has no support for
This change does a few things:
Makes all values in
objectinstead of a
that we don't use
Any, as that bypasses any type checking when,
say, reassigning the value, and we want consistency).
Adds a flexible
extrakey that can be used for things like SOS's
changeset and selection stuff. (Clients can define their own
TypedDictfor their needs and set it or
Updates the function signatures and documentation for all
implementations to be consistent with each other.
Fixes up some code affected by the type definitions, helping ensure
we're putting the right types in the keys.
This will ensure we don't hit any issues going forward with assumptions
around keys, types, and values in usage of revision specs, and can make
informed decisions on when to support a new top-level key.
Unit tests pass.
Verified the type checker was happy in typed code using
SCMClientRevisionSpec(there's lots of other code using it that hasn't
yet been updated though).
Posted a change using this code.
Added missing SOS unit test updates.
Revision 2 (+1084 -706)