Some PEAK API's use the special objects "NOT_GIVEN" and "NOT_FOUND"to represent special kinds of ``null" values. "NOT_FOUND" is often used as a return value that signifies a desired item was ``not found" in a cache, registry, or other mapping. This is often done in preference to raising a KeyError for both performance and semantic clarity. A KeyError could have been caused by some failure internal to an object, while returning "NOT_FOUND" indicates the method was successfully executed, but the item was simply not found.
"NOT_GIVEN" is rarely used as a return value; its primary purpose is to be a default value for argument(s) to a function or method. It's used in place of "None" as a default value, when the argument could legitimately have a value of "None" or even "NOT_FOUND". A function can tell whether a value was supplied, by whether the argument is the "NOT_GIVEN" object. You'll probably never need to supply this value to a PEAK API call, or return it from a method, but you may find it useful in defining your own APIs.
Note that you should only compare "NOT_GIVEN" and "NOT_FOUND" using the Python "is" operator, e.g. "if someParam is NOT_GIVEN: doSomething()".