[doc] fix doc to work in all known repos.

recipe_engine/recipe_api.py

 # Copyright 2016 The LUCI Authors. All rights reserved.
 # Use of this source code is governed under the Apache License, Version 2.0
 # that can be found in the LICENSE file.
 
 from __future__ import absolute_import
 import bisect
 import collections
 import contextlib
 import copy
+import json
 import keyword
 import re
 import types
 
 from functools import wraps
 
 from .recipe_test_api import DisabledTestData, ModuleTestData
 from .config import Single
 
 from .util import ModuleInjectionSite
@@ skipping 868 matching lines @@
     regex = r'^[a-zA-Z][a-zA-Z0-9_]*$' if is_param_name else (
         r'^[a-zA-Z][.\w-]*$')
     return bool(re.match(regex, name))
 
   def __init__(self, default, help, kind, name, property_type, module,
                param_name=None):
     """
     Constructor for BoundProperty.
 
     Args:
-      default: The default value for this Property. Note: A default
-               value of None is allowed. To have no default value, omit
-               this argument.
+      default: The default value for this Property. Must be JSON-encodable or
+               PROPERTY_SENTINEL.
       help: The help text for this Property.
       kind: The type of this Property. You can either pass in a raw python
             type, or a Config Type, using the recipe engine config system.
       name: The name of this Property.
       param_name: The name of the python function parameter this property
                   should be stored in. Can be used to allow for dotted property
                   names, e.g.
         PROPERTIES = {
           'foo.bar.bam': Property(param_name="bizbaz")
         }
       module: The module this Property is a part of.
     """
     if not BoundProperty.legal_name(name):
       raise ValueError("Illegal name '{}'.".format(name))
 
     param_name = param_name or name
     if not BoundProperty.legal_name(param_name, is_param_name=True):
       raise ValueError("Illegal param_name '{}'.".format(param_name))
 
+    if default is not PROPERTY_SENTINEL:
+      try:
+        json.dumps(default)
+      except:
+        raise TypeError('default=%r is not json-encodable' % (default,))
+
     self.__default = default
     self.__help = help
     self.__kind = kind
     self.__name = name
     self.__property_type = property_type
     self.__param_name = param_name
     self.__module = module
 
   @property
   def name(self):
     return self.__name
 
   @property
   def param_name(self):
     return self.__param_name
 
   @property
   def default(self):
-    return self.__default
+    if self.__default is PROPERTY_SENTINEL:
+      return self.__default
+    return copy.deepcopy(self.__default)
 
   @property
   def kind(self):
     return self.__kind
 
   @property
   def help(self):
     return self.__help
 
   @property
@@ skipping 11 matching lines @@
     Returns:
       The value to use for this property. Raises an error if
       this property has no valid interpretation.
     """
     if value is not PROPERTY_SENTINEL:
       if self.kind is not None:
         # The config system handles type checking for us here.
         self.kind.set_val(value)
       return value
 
-    if self.default is not PROPERTY_SENTINEL:
+    if self.__default is not PROPERTY_SENTINEL:
       return self.default
 
     raise ValueError(
       "No default specified and no value provided for '{}' from {} '{}'".format(
         self.name, self.__property_type, self.module))
 
 class Property(object):
   def __init__(self, default=PROPERTY_SENTINEL, help="", kind=None,
                param_name=None):
     """
     Constructor for Property.
 
     Args:
       default: The default value for this Property. Note: A default
                value of None is allowed. To have no default value, omit
-               this argument.
+               this argument. This must be a valid JSON-encodable object.
       help: The help text for this Property.
       kind: The type of this Property. You can either pass in a raw python
             type, or a Config Type, using the recipe engine config system.
     """
+    if default is not PROPERTY_SENTINEL:
+      try:
+        json.dumps(default)
+      except:
+        raise TypeError('default=%r is not json-encodable' % (default,))

[iannucci, 2017/05/03 00:05:34]

These changes are to assert that any Property defined by a recipe or module only
provides default values which are actually json-compatible. This is generally
true, but apparently depot_tools has one instance where it provides a FrozenDict
as a default value.

+
     self._default = default
     self.help = help
     self.param_name = param_name
 
     if isinstance(kind, type):
       if kind in (str, unicode):
         kind = basestring
       kind = Single(kind)
     self.kind = kind
 
   def bind(self, name, property_type, module):
     """
     Gets the BoundProperty version of this Property. Requires a name.
     """
     return BoundProperty(
         self._default, self.help, self.kind, name, property_type, module,
         self.param_name)
 
 class UndefinedPropertyException(TypeError):
   pass