Add a more formal concept of field types for API resources.
Review Request #9682 — Created Feb. 20, 2018 and submitted
When defining fields for a resource's response, or fields accepted
during a request, we previously made use of some standard Python 2.7
primitives, such as
int, and some special values
tuplecontaining possible choices for a value. These
were only handled in Djblets by the
which had built-in support for specific types. Resources were free to
list fields as well, but they didn't do anything special with them
(though consuming applications could, for documentation purposes).
The real problem was that these types weren't all compatible with
Python 3. For instance,
filedoes not exist. It was also just not very
future-proof in general, and while it served us well for a while,
there's more we can do with a new model.
This change introduces a new concept of field types, which are classes
that know how to do things like validate and normalize a value coming in
from a request, and generate a description of the type (intended for
documentation purposes). With these,
needs to know about specific types, and can therefore be more simple and
Field types plug right into a field info dictionary's
where the old legacy types were. When instantiated (which happens on
demand, not during field list definition), they're passed the field info
dictionary, which may contain other data useful for that field type
(such as a list of choices, or a resource path/class).
There's a handful of built-in types, some geared more for documentation
ResourceFieldType) and some for more specialized
handling of common request values (like
Existing dictionaries with legacy types going into
@webapi_request_fieldsare still supported. Legacy types are
automatically converted into the new types the first time the function
Going forward, we'll be able to use this to help further separate out
field validation/normalization from API logic in Review Board and in
Djblets unit tests pass.
Converted all of Review Board to the new field types (upcoming change)
and verified that all unit tests pass and all docs generated correctly.
Built the new docs. Didn't see any errors.
Added missing modules.
Revision 2 (+1464 -97)
Checks run (2 succeeded)
- Fixed a dependency ordering problem.
- Removed an unwanted blank line.
- Added a missing module docstring.
- Added the new module to the code reference docs.
ExtensionResourceto use the new types.
Revision 3 (+1479 -110)
Checks run (2 succeeded)