Formalize types, content, and documentation for revision specs.

Review Request #12586 — Created Sept. 7, 2022 and submitted

Information

RBTools
release-4.x

Reviewers

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.

Summary ID
Formalize types, content, and documentation for revision specs.
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.
7bd6e6d7757faa9320afe63a42eea16b1429af1b
david
  1. Ship It!
  2. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-4.x (2dd47f8)