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:

  1. Makes all values in TypedDict an object instead of a str. (Note
    that we don't use Any, as that bypasses any type checking when,
    say, reassigning the value, and we want consistency).

  2. 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 or cast as appropriate.)

  3. Updates the function signatures and documentation for all
    implementations to be consistent with each other.

  4. 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.