Skip to content
Permalink
Browse files

C++ Error documentation additions (#620)

* Added starter tables outlining the C++ error enum values and their meanings. Some are left un-filled and should be elaborated on.

* Added documentation for C++ read errors in schema implementation

* Applied code review notes for CXX docs

* Updated cxx reader error docs to be more succinct.
  • Loading branch information
reinecke authored and ssteinbach committed Dec 13, 2019
1 parent eec7993 commit a60120b6b536c0abde240f6178b97b4e3941b70a
Showing with 67 additions and 1 deletion.
  1. +67 −1 docs/cxx/cxx.rst
@@ -123,6 +123,25 @@ well: ::
Even when we define more complex properties, the reading/writing code is as
simple as shown above, in almost all cases.

When an error is encountered in reading, ``read_from`` should set the error
on the ``Reader`` instance and return ``false``: ::

bool Marker::read_from(Reader& reader) {
if (!reader.read(“color”, &_color)) {
return false;
}
if (_color == “invalid_value”) {
reader.error( ErrorStatus(ErrorStatus::JSON_PARSE_ERROR,
“invalid_value not allowed for color”));
return false;
}
return reader.read(“marked_range”, &_marked_range) &&
Parent::read_from(reader);
}

This is a contrived example but it describes the basic mechanics. Adjust the
details above as appropriate for your case.

.. Note::
Properties are written to the JSON file in the order they are written
to from within ``write_to()``. But the reading code need not be in the same order,
@@ -159,7 +178,7 @@ Creating and manipulating schema objects is also simple: ::
...
}
}


Serializable Data
+++++++++++++++++
@@ -550,6 +569,53 @@ to allow constructors to "fail" gracefully. Accordingly, a class like
but requires a call to ``set_children()`` after construction. Neither the
Python API (nor the Swift API) would be subject to this limitation.

The OpenTime and OpenTimelineIO libraries both have their own error
definitions. The tables below outline the errors, which python exceptions they
raise, and what their semantic meaning is.

.. csv-table:: OpenTime Errors
:header: "Value", "Python Exception Type", "Meaning"

OK, n/a, No Error
INVALID_TIMECODE_RATE, ``ValueError``, "Timecode rate isn't a valid SMPTE rate"
NON_DROPFRAME_RATE, ``ValueError``, "Timecode rate isn't valid for SMPTE Drop-Frame Timecode"
INVALID_TIMECODE_STRING, ``ValueError``, "String is not properly formatted SMPTE timecode string"
TIMECODE_RATE_MISMATCH, ``ValueError``, " Timecode string has a frame number higher than the frame rate"
INVALID_TIME_STRING, ``ValueError``,
NEGATIVE_VALUE, ``ValueError``,
INVALID_RATE_FOR_DROP_FRAME_TIMECODE, ``ValueError``, "Timecode rate isn't valid for SMPTE Drop-Frame Timecode"

.. csv-table:: OpenTimelineIO error codes
:header: "Value", "Python Exception Type", "Meaning"

OK, n/a, No Error
NOT_IMPLEMENTED, ``NotImplementedError``, "A feature is known but deliberately unimplemented"
UNRESOLVED_OBJECT_REFERENCE, ``ValueError``, "An object reference is unresolved while reading"
DUPLICATE_OBJECT_REFERENCE, ``ValueError``, "An object reference is duplicated while reading"
MALFORMED_SCHEMA, ``ValueError``, "The Schema string was invalid"
JSON_PARSE_ERROR, ``ValueError``, "Malformed JSON encountered when parsing"
CHILD_ALREADY_PARENTED, ``ValueError``, "Attempted to add a child to a collection when it's already a member of another collection instance"

FILE_OPEN_FAILED, ``ValueError``, "failed to open file for reading"
FILE_WRITE_FAILED, ``ValueError``, "failed to open file for writing"
SCHEMA_ALREADY_REGISTERED, ``ValueError``,
SCHEMA_NOT_REGISTERED, ``ValueError``,
SCHEMA_VERSION_UNSUPPORTED, ``UnsupportedSchemaError``,
KEY_NOT_FOUND, ``KeyError``, "The key used for a mapping doesn't exist in the collection"
ILLEGAL_INDEX, ``IndexError``, "The collection index is out of bounds"
TYPE_MISMATCH, ``ValueError``,
INTERNAL_ERROR, ``ValueError``, "Internal error (aka this is a bug)"
NOT_AN_ITEM, ``ValueError``,
NOT_A_CHILD_OF, ``NotAChildError``,
NOT_A_CHILD, ``NotAChildError``,
NOT_DESCENDED_FROM, ``NotAChildError``,
CANNOT_COMPUTE_AVAILABLE_RANGE, ``CannotComputeAvailableRangeError``,
INVALID_TIME_RANGE, ``ValueError``,
OBJECT_WITHOUT_DURATION, ``ValueError``,
CANNOT_TRIM_TRANSITION, ``ValueError``,

.. todo:: Add a section discussing how to add additional error types.

Thread Safety
++++++++++++++

0 comments on commit a60120b

Please sign in to comment.
You can’t perform that action at this time.