Formalize types, content, and documentation for revision specs.
Review Request #12586 — Created Sept. 7, 2022 and submitted — Latest diff uploaded
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 (base
,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
TypedDict
that could
describe the possible keys, but this was limiting in types of values,
assuming they were all strings.TypedDict
also has no support for
arbitrary keys.This change does a few things:
Makes all values in
TypedDict
anobject
instead of astr
. (Note
that we don't useAny
, as that bypasses any type checking when,
say, reassigning the value, and we want consistency).Adds a flexible
extra
key that can be used for things like SOS's
changeset and selection stuff. (Clients can define their own
TypedDict
for their needs and set it orcast
as appropriate.)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.