Merge ~jugmac00/lazr.restful:apply-inclusive-naming into lazr.restful:main

[Jürgen Gmach]

Apply inclusive naming via the `woke` pre-commit hook

[Colin Watson (cjwatson)]

This technically changes a few bits of public API (`lazr.restful.metazcml.webservice_sanity_checks` and `lazr.restful.testing.webservice.Dummy*URL`). In practice I think this is fine and doesn't need a major version bump or anything - lazr.restful only has one known significant user (Launchpad itself) and that doesn't use any of the relevant names - but just in case I'd be inclined to at least make a note of it in NEWS and bump the version to 1.2.0.

review: Approve

[Jürgen Gmach (jugmac00)]

Thanks for the review!

When applying the changes, I quickly thought whether this affects public API or not, and looks like I erred on the wrong side :-)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 45fd4ba..f72d079 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -13,3 +13,7 @@ repos:
     rev: 3.9.2
     hooks:
     -   id: flake8
+-   repo: https://github.com/get-woke/woke
+    rev: v0.17.0
+    hooks:
+    -   id: woke-from-source
diff --git a/.woke.yaml b/.woke.yaml
new file mode 100644
index 0000000..424838e
--- /dev/null
+++ b/.woke.yaml
@@ -0,0 +1,228 @@
+
+# Based on Canonical's Guidelines
+# https://docs.google.com/document/d/1mJUa1VJHOMWa723dmKmNjSKGW-nlBv9xktzGZZwacVo/edit#heading=h.5efudb237qdb
+rules:
+  - name: whitelist
+    terms:
+      - whitelist
+      - white-list
+      - whitelisted
+      - white-listed
+    alternatives:
+      - allowlist
+      - inclusion list
+    severity: warning
+    note: "The underlying assumption of the whitelist/blacklist metaphor is that white = good and black = bad. Because colors in and of themselves have no predetermined meaning, any meaning we assign to them is cultural: for example, the color red in many Southeast Asian countries is lucky, and is often associated with events like marriages, whereas the color white carries the same connotations in many European countries. In the case of whitelist/blacklist, the terms originate in the publishing industry – one dominated by the USA and England, two countries which participated in slavery and which grapple with their racist legacies to this day."
+
+  - name: blacklist
+    terms:
+      - blacklist
+      - black-list
+      - blacklisted
+      - black-listed
+    alternatives:
+      - denylist
+      - blocklist
+      - exclusion list
+    severity: warning
+    note: "The underlying assumption of the whitelist/blacklist metaphor is that white = good and black = bad. Because colors in and of themselves have no predetermined meaning, any meaning we assign to them is cultural: for example, the color red in many Southeast Asian countries is lucky, and is often associated with events like marriages, whereas the color white carries the same connotations in many European countries. In the case of whitelist/blacklist, the terms originate in the publishing industry – one dominated by the USA and England, two countries which participated in slavery and which grapple with their racist legacies to this day."
+
+  - name: master-slave
+    terms:
+      - master-slave
+      - master/slave
+    alternatives:
+      - leader/follower
+      - main/replica
+      - primary/replica
+      - primary/standby
+      - primary/secondary
+
+  - name: slave
+    terms:
+      - slave
+    alternatives:
+      - follower
+      - replica
+      - standby
+
+  - name: grandfathered
+    terms:
+      - grandfathered
+    alternatives:
+      - legacy status
+      - legacied
+      - exempted
+      - carried
+      - brought forward
+      - rolled over
+
+  - name: man-hours
+    terms:
+      - man hours
+      - man-hours
+    alternatives:
+      - person hours
+      - engineer hours
+
+  - name: sanity
+    terms:
+      - sanity
+    alternatives:
+      - confidence
+      - quick check
+      - coherence check
+
+  - name: dummy
+    terms:
+      - dummy
+    alternatives:
+      - placeholder
+      - sample
+
+  - name: guys
+    terms:
+      - guys
+    alternatives:
+      - folks
+      - people
+      - you all
+      - y'all
+      - yinz
+
+  - name: whitebox
+    terms:
+      - white-box
+      - whitebox
+      - white box
+    alternatives:
+      - open-box
+
+  - name: blackbox
+    terms:
+      - black-box
+      - blackbox
+      - black box
+    alternatives:
+      - closed-box
+
+  - name: blackhat
+    terms:
+      - blackhat
+      - black-hat
+      - black hat
+    alternatives:
+      - attacker
+      - malicious actor
+
+  - name: whitehat
+    terms:
+      - whitehat
+      - white-hat
+      - white hat
+    alternatives:
+      - researcher
+      - security specialist
+
+  - name: illegal characters
+    terms:
+      - illegal characters
+    alternatives:
+      - invalid characters
+      - unsupported characters
+      - special characters
+
+  - name: native feature
+    terms:
+      - native feature
+    alternatives:
+      - core feature
+      - built-in feature
+
+  - name: native feature
+    terms:
+      - native feature
+    alternatives:
+      - core feature
+      - built-in feature
+
+  - name: chairman/foreman
+    terms:
+      - chairman
+      - foreman
+    alternatives:
+      - chair
+      - foreperson
+
+  - name: man in the middle
+    terms:
+      - man in the middle
+      - man-in-the-middle
+    alternatives:
+      - machine-in-the-middle
+      - person-in-the-middle
+      - system-in-the-middle
+      - intermediary attack
+
+  - name: middleman
+    terms:
+      - middleman
+    alternatives:
+      - middleperson
+      - intermediary
+
+  - name: manned
+    terms:
+      - manned
+    alternatives:
+      - crewed
+      - staffed
+      - monitored
+      - human operated
+
+  - name: mom test / girlfriend test
+    terms:
+      - mom test
+      - girlfriend test
+    alternatives:
+      - user test
+      - user friendly
+
+  - name: crazy
+    terms:
+      - crazy
+    alternatives:
+      - baffling
+      - unexplained
+      - errant
+
+  - name: cripples
+    terms:
+      - cripples
+    alternatives:
+      - slows down
+      - hinders
+      - obstructs
+
+  - name: crippling 
+    terms:
+      - crippling
+    alternatives:
+      - attenuating
+      - incapacitating
+
+  - name: stonith/stomith 
+    terms:
+      - stonith
+      - stomith
+    alternatives:
+      - fence failed nodes
+      - machines
+
+  - name: demilitarized zone 
+    terms:
+      - demilitarized zone
+      - dmz
+    alternatives:
+      - perimeter network
+      - passthrough network
\ No newline at end of file
diff --git a/NEWS.rst b/NEWS.rst
index 8a73089..3b8f8f3 100644
--- a/NEWS.rst
+++ b/NEWS.rst
@@ -2,12 +2,22 @@
 NEWS for lazr.restful
 =====================
 
-1.1.1
+1.2.0
 =====
 
 - Add support for Python 3.9 and 3.10.
 - Add basic pre-commit configuration.
 - Publish docs on Read the Docs.
+- Apply inclusive naming via the woke pre-commit hook. The following API
+  changes were performed:
+  ``lazr.restful.metazcml.webservice_sanity_checks``
+  => ``lazr.restful.metazcml.webservice_coherence_checks``,
+  ``lazr.restful.testing.webservice.DummyURL``
+  => ``lazr.restful.testing.webservice.StubAbsoluteURL``,
+  ``lazr.restful.testing.webservice.DummyAbsoluteURL``
+  => ``lazr.restful.testing.webservice.StubAbsoluteURL``,
+  ``lazr.restful.testing.webservice.DummyRootResourceURL``
+  => ``lazr.restful.testing.webservice.StubRootResourceURL``
 
 1.1.0 (2021-10-07)
 ==================
diff --git a/src/lazr/restful/configure.zcml b/src/lazr/restful/configure.zcml
index 107c0fe..d6e0416 100644
--- a/src/lazr/restful/configure.zcml
+++ b/src/lazr/restful/configure.zcml
@@ -20,7 +20,7 @@
     </class>
 
     <subscriber for="zope.processlifetime.IProcessStarting"
-        handler="lazr.restful.metazcml.webservice_sanity_checks" />
+        handler="lazr.restful.metazcml.webservice_coherence_checks" />
 
     <!--
     XXX flacoste 2008/05/09 bug=185958:
diff --git a/src/lazr/restful/docs/absoluteurl.rst b/src/lazr/restful/docs/absoluteurl.rst
index 76de5db..3c6fe25 100644
--- a/src/lazr/restful/docs/absoluteurl.rst
+++ b/src/lazr/restful/docs/absoluteurl.rst
@@ -128,14 +128,14 @@ http://top-level/child-part1/child-part2/grandchild
 AbsoluteURL won't work, but lazr.restful's MultiplePathPartAbsoluteURL
 will.
 
-To test this, we'll start with a DummyRootResource and its absolute
-URL generator, DummyRootResourceURL.
+To test this, we'll start with a StubRootResource and its absolute
+URL generator, StubRootResourceURL.
 
     >>> from lazr.restful.testing.webservice import (
-    ...     DummyRootResource, DummyRootResourceURL)
+    ...     StubRootResource, StubRootResourceURL)
     >>> from zope.component import getSiteManager
     >>> sm = getSiteManager()
-    >>> sm.registerAdapter(DummyRootResourceURL)
+    >>> sm.registerAdapter(StubRootResourceURL)
 
 We'll load the basic lazr.restful site configuration.
 
@@ -154,14 +154,14 @@ We'll load the basic lazr.restful site configuration.
     ... """)
     >>> load_config()
 
-Here's a child of DummyRootResource that implements
+Here's a child of StubRootResource that implements
 IMultiplePathPartLocation.
 
     >>> from zope.interface import implementer
     >>> from lazr.restful.simple import IMultiplePathPartLocation
     >>> @implementer(IMultiplePathPartLocation)
     ... class ChildResource:
-    ...     __parent__ = DummyRootResource()
+    ...     __parent__ = StubRootResource()
     ...     __path_parts__ = ["child-part1", "child-part2"]
 
 The ChildResource's URL includes one URL part from the root resource,
@@ -169,7 +169,7 @@ followed by two from the ChildResource itself.
 
     >>> resource = ChildResource()
     >>> print(str(getMultiAdapter((resource, request), IAbsoluteURL)))
-    http://dummyurl/child-part1/child-part2
+    http://exampleurl/child-part1/child-part2
 
 Now let's put an object underneath the child resource that implements
 ILocation, as most resources will.
@@ -186,7 +186,7 @@ GrandchildResource itself.
 
     >>> print(str(getMultiAdapter(
     ...     (GrandchildResource(), request), IAbsoluteURL)))
-    http://dummyurl/child-part1/child-part2/grandchild
+    http://exampleurl/child-part1/child-part2/grandchild
 
 Edge cases and error handling
 =============================
@@ -196,7 +196,7 @@ It even escapes slashes, if a slash shows up inside a path part.
 
     >>> resource.__path_parts__ = ["!foo!", "bar/baz"]
     >>> print(str(getMultiAdapter((resource, request), IAbsoluteURL)))
-    http://dummyurl/%21foo%21/bar%2Fbaz
+    http://exampleurl/%21foo%21/bar%2Fbaz
 
 If the __path_parts__ is not iterable, an attempt to get the URL
 raises an exception:
diff --git a/src/lazr/restful/docs/django.rst b/src/lazr/restful/docs/django.rst
index 2c6d52e..2ad1df2 100644
--- a/src/lazr/restful/docs/django.rst
+++ b/src/lazr/restful/docs/django.rst
@@ -138,10 +138,10 @@ Here's some setup; a root resource that has its own AbsoluteURL
 implementation.
 
     >>> from lazr.restful.testing.webservice import (
-    ...     DummyRootResource, DummyRootResourceURL)
+    ...     StubRootResource, StubRootResourceURL)
     >>> from zope.component import getSiteManager
     >>> sm = getSiteManager()
-    >>> sm.registerAdapter(DummyRootResourceURL)
+    >>> sm.registerAdapter(StubRootResourceURL)
 
 Now here's a subordinate resource that just implements IDjangoLocatino.
 
@@ -152,7 +152,7 @@ Now here's a subordinate resource that just implements IDjangoLocatino.
     ...
     ...     @property
     ...     def __parent_object__(self):
-    ...         return DummyRootResource()
+    ...         return StubRootResource()
     ...
     ...     @property
     ...     def __url_path__(self):
@@ -177,7 +177,7 @@ get its full URL.
     >>> from lazr.restful.simple import Request
     >>> request = Request("", {})
     >>> print(str(getMultiAdapter((resource, request), IAbsoluteURL)))
-    http://dummyurl/myname
+    http://exampleurl/myname
 
 
 ObjectDoesNotExist
diff --git a/src/lazr/restful/docs/webservice-declarations.rst b/src/lazr/restful/docs/webservice-declarations.rst
index f9d932a..2db2286 100644
--- a/src/lazr/restful/docs/webservice-declarations.rst
+++ b/src/lazr/restful/docs/webservice-declarations.rst
@@ -240,10 +240,10 @@ interface:
 It's an error to try to export a collection without marking a method as
 exporting the default content.
 
-    >>> class IDummyInterface(Interface):
+    >>> class ISampleInterface(Interface):
     ...     pass
 
-    >>> @exported_as_webservice_collection(IDummyInterface)
+    >>> @exported_as_webservice_collection(ISampleInterface)
     ... class MissingDefaultContent(Interface):
     ...     pass
     Traceback (most recent call last):
@@ -253,7 +253,7 @@ exporting the default content.
 
 As it is an error, to mark more than one method:
 
-    >>> @exported_as_webservice_collection(IDummyInterface)
+    >>> @exported_as_webservice_collection(ISampleInterface)
     ... class TwoDefaultContent(Interface):
     ...     @collection_default_content()
     ...     def getAll1():
@@ -268,7 +268,7 @@ As it is an error, to mark more than one method:
 
 exported_as_webservice_collection() can only be used on Interface.
 
-    >>> @exported_as_webservice_collection(IDummyInterface)
+    >>> @exported_as_webservice_collection(ISampleInterface)
     ... class NotAnInterface(object):
     ...     pass
     Traceback (most recent call last):
@@ -834,7 +834,7 @@ Setup
 Before we can continue, we must define a web service configuration
 object. Each web service needs to have one of these registered
 utilities providing basic information about the web service. This one
-is just a dummy.
+is just a sample.
 
     >>> from zope.component import provideUtility
     >>> from zope.security.interfaces import Unauthorized
diff --git a/src/lazr/restful/docs/webservice-marshallers.rst b/src/lazr/restful/docs/webservice-marshallers.rst
index 71ea4e2..20028f3 100644
--- a/src/lazr/restful/docs/webservice-marshallers.rst
+++ b/src/lazr/restful/docs/webservice-marshallers.rst
@@ -5,7 +5,7 @@ LAZR defines an interface for converting between the values that
 come in on an HTTP request, and the object values appropriate for schema
 fields. This is similar to Zope's widget interface, but much smaller.
 
-To test the various marshallers we create a dummy request and
+To test the various marshallers we create a stub request and
 application root.
 
     >>> from lazr.restful.testing.webservice import WebServiceTestPublication
diff --git a/src/lazr/restful/docs/webservice.rst b/src/lazr/restful/docs/webservice.rst
index ba97e44..6397038 100644
--- a/src/lazr/restful/docs/webservice.rst
+++ b/src/lazr/restful/docs/webservice.rst
@@ -1502,7 +1502,7 @@ structure, and the response's Content-Type header is set to
 application/json. These examples show how different return values are
 serialized.
 
-    >>> class DummyOperation(ResourceGETOperation):
+    >>> class SampleOperation(ResourceGETOperation):
     ...
     ...     params = ()
     ...     result = None
@@ -1511,17 +1511,17 @@ serialized.
     ...     def call(self):
     ...         return self.result
 
-    >>> def make_dummy_operation_request(result):
+    >>> def make_sample_operation_request(result):
     ...    request = create_web_service_request('/beta/')
     ...    ignore = request.traverse(app)
-    ...    operation = DummyOperation(None, request)
+    ...    operation = SampleOperation(None, request)
     ...    operation.result = result
     ...    return request, operation
 
 Scalar Python values like strings and booleans are serialized as you'd
 expect.
 
-    >>> request, operation = make_dummy_operation_request("A string.")
+    >>> request, operation = make_sample_operation_request("A string.")
     >>> print(operation())
     "A string."
     >>> request.response.getStatus()
@@ -1529,26 +1529,26 @@ expect.
     >>> print(request.response.getHeader('Content-Type'))
     application/json
 
-    >>> request, operation = make_dummy_operation_request(True)
+    >>> request, operation = make_sample_operation_request(True)
     >>> operation()
     'true'
 
-    >>> request, operation = make_dummy_operation_request(10)
+    >>> request, operation = make_sample_operation_request(10)
     >>> operation()
     '10'
 
-    >>> request, operation = make_dummy_operation_request(None)
+    >>> request, operation = make_sample_operation_request(None)
     >>> operation()
     'null'
 
-    >>> request, operation = make_dummy_operation_request(1.3)
+    >>> request, operation = make_sample_operation_request(1.3)
     >>> operation()
     '1.3'
 
 When a named operation returns an object that has an ``IEntry``
 implementation, the object is serialized to a JSON hash.
 
-    >>> request, operation = make_dummy_operation_request(D2)
+    >>> request, operation = make_sample_operation_request(D2)
     >>> operation()
     '{...}'
 
@@ -1557,18 +1557,18 @@ objects with ``IEntry`` implementations. Here's a dictionary that contains
 a ``Dish`` object. The ``Dish`` object is serialized as a JSON dictionary
 within the larger dictionary.
 
-    >>> request, operation = make_dummy_operation_request({'dish': D2})
+    >>> request, operation = make_sample_operation_request({'dish': D2})
     >>> operation()
     '{"dish": {...}}'
 
 When a named operation returns a list or tuple of objects, we serve
 the whole thing as a JSON list.
 
-    >>> request, operation = make_dummy_operation_request([1,2,3])
+    >>> request, operation = make_sample_operation_request([1,2,3])
     >>> operation()
     '[1, 2, 3]'
 
-    >>> request, operation = make_dummy_operation_request((C1_D1, C2_D1))
+    >>> request, operation = make_sample_operation_request((C1_D1, C2_D1))
     >>> operation()
     '[{...}, {...}]'
 
@@ -1579,7 +1579,7 @@ results. In this case we do the same thing we do when serving a
 collection resource. We fetch one batch of results and represent it as
 a JSON hash containing a list of entries.
 
-    >>> class DummyResultSet(object):
+    >>> class StubResultSet(object):
     ...     results = [C1_D1, C2_D1]
     ...
     ...     def __iter__(self):
@@ -1591,8 +1591,8 @@ a JSON hash containing a list of entries.
     ...     def __getitem__(self, index):
     ...         return self.results[index]
 
-    >>> recipes = DummyResultSet()
-    >>> request, operation = make_dummy_operation_request(recipes)
+    >>> recipes = StubResultSet()
+    >>> request, operation = make_sample_operation_request(recipes)
     >>> response = operation()
     >>> pprint_collection(simplejson.loads(response))
     start: ...
@@ -1607,7 +1607,7 @@ When a named operation returns an object that has an ``ICollection``
 implementation, the result is similar: we return a JSON hash describing one
 batch from the collection.
 
-    >>> request, operation = make_dummy_operation_request(DishSet())
+    >>> request, operation = make_sample_operation_request(DishSet())
     >>> response = operation()
     >>> pprint_collection(simplejson.loads(response))
     resource_type_link: 'http://api.cookbooks.dev/beta/#dishes'
@@ -1624,20 +1624,20 @@ batch from the collection.
 If the return value can't be converted into JSON, you'll get an
 exception.
 
-    >>> request, operation = make_dummy_operation_request(object())
+    >>> request, operation = make_sample_operation_request(object())
     >>> operation()
     Traceback (most recent call last):
     ...
     TypeError: Could not serialize object <object...> to JSON.
 
-    >>> request, operation = make_dummy_operation_request(
+    >>> request, operation = make_sample_operation_request(
     ...     {'anobject' : object()})
     >>> operation()
     Traceback (most recent call last):
     ...
     TypeError: Could not serialize object {'anobject': <object...>} to JSON.
 
-    >>> request, operation = make_dummy_operation_request([object()])
+    >>> request, operation = make_sample_operation_request([object()])
     >>> operation()
     Traceback (most recent call last):
     ...
diff --git a/src/lazr/restful/example/base/configure.zcml b/src/lazr/restful/example/base/configure.zcml
index bb5b7a4..4891ee2 100644
--- a/src/lazr/restful/example/base/configure.zcml
+++ b/src/lazr/restful/example/base/configure.zcml
@@ -8,7 +8,7 @@
   <grok:grok package="lazr.restful.example.base" />
 
   <subscriber for="zope.processlifetime.IProcessStarting"
-      handler="lazr.restful.metazcml.webservice_sanity_checks" />
+      handler="lazr.restful.metazcml.webservice_coherence_checks" />
 
   <!--Registering these two adapters will cause web_link to show up in
       representations.-->
@@ -23,7 +23,7 @@
       for="zope.location.interfaces.ILocation
            lazr.restful.interfaces.IWebBrowserOriginatingRequest"
       provides="zope.traversing.browser.interfaces.IAbsoluteURL"
-      factory="lazr.restful.testing.webservice.DummyAbsoluteURL" />
+      factory="lazr.restful.testing.webservice.StubAbsoluteURL" />
 
 
   <!--Security configuration-->
diff --git a/src/lazr/restful/example/base/tests/collection.txt b/src/lazr/restful/example/base/tests/collection.txt
index 2c5c335..08009ad 100644
--- a/src/lazr/restful/example/base/tests/collection.txt
+++ b/src/lazr/restful/example/base/tests/collection.txt
@@ -137,7 +137,7 @@ The elements of a collection can be looked up by unique identifier:
     resource_type_link: 'http://...#cookbook'
     revision_number: 0
     self_link: 'http://.../cookbooks/The%20Joy%20of%20Cooking'
-    web_link: 'http://dummyurl/'
+    web_link: 'http://exampleurl/'
 
 A collection may be scoped to an element:
 
diff --git a/src/lazr/restful/example/base/tests/entry.txt b/src/lazr/restful/example/base/tests/entry.txt
index 5b72ba6..ba48787 100644
--- a/src/lazr/restful/example/base/tests/entry.txt
+++ b/src/lazr/restful/example/base/tests/entry.txt
@@ -135,7 +135,7 @@ have non-ascii values.
 But it's possible to define a custom HTML view for a particular object
 type. Here's a simple view that serves some hard-coded HTML.
 
-    >>> class DummyView:
+    >>> class StubView:
     ...
     ...     def __init__(*args):
     ...         pass
@@ -153,12 +153,12 @@ ICookbook entry...
     >>> from zope.component import getGlobalSiteManager
     >>> manager = getGlobalSiteManager()
     >>> manager.registerAdapter(
-    ...      factory=DummyView,
+    ...      factory=StubView,
     ...      required=[ICookbook, IWebServiceClientRequest],
     ...      provided=IInterface, name=view_name)
 
 ...and the XHTML representation of an ICookbook will be the result of
-calling a DummyView object.
+calling a StubView object.
 
     >>> print(webservice.get(greens_url, 'application/xhtml+xml'))
     HTTP/1.1 200 Ok
@@ -170,7 +170,7 @@ we just defined.
 
     >>> from zope.component import getGlobalSiteManager
     >>> ignored = getGlobalSiteManager().unregisterAdapter(
-    ...      factory=DummyView,
+    ...      factory=StubView,
     ...      required=[ICookbook, IWebServiceClientRequest],
     ...      provided=IInterface, name=view_name)
 
@@ -572,7 +572,7 @@ designed for Ajax.
 
     >>> from lazr.restful.testing.webservice import WebServiceAjaxCaller
     >>> ajax = WebServiceAjaxCaller(domain='cookbooks.dev')
-    >>> etag = 'dummy-etag'
+    >>> etag = 'sample-etag'
     >>> response = ajax.get(greens_url, headers={'If-None-Match' : etag})
     >>> etag = response.getheader("Etag")
     >>> print(ajax.get(greens_url, headers={'If-None-Match' : etag}))
@@ -863,7 +863,7 @@ about an attempt to modify a read-only attribute.
 The two 400 error codes below are caused by a failure to understand
 the assertion. The string used in the assertion might not be a date.
 
-    >>> print(patch_greens_copyright_date('dummy'))
+    >>> print(patch_greens_copyright_date('sample'))
     HTTP/1.1 400 Bad Request
     ...
     copyright_date: Value doesn't look like a date.
@@ -959,7 +959,7 @@ attribute, but it has to be the same as the current value.
 You can't change the link to an entry's associated collection.
 
     >>> print(modify_cookbook('Everyday Greens',
-    ...                       {'recipes_collection_link' : 'dummy'},
+    ...                       {'recipes_collection_link' : 'placeholder'},
     ...                       'PATCH'))
     HTTP/1.1 400 Bad Request
     ...
@@ -978,7 +978,7 @@ collection link; you just can't _change_ the value.
 You can't directly change an entry's URL address.
 
     >>> print(modify_cookbook('Everyday Greens',
-    ...                       {'self_link' : 'dummy'}, 'PATCH'))
+    ...                       {'self_link' : 'placeholder'}, 'PATCH'))
     HTTP/1.1 400 Bad Request
     ...
     self_link: You tried to modify a read-only attribute.
@@ -986,7 +986,7 @@ You can't directly change an entry's URL address.
 You can't directly change an entry's ETag.
 
     >>> print(modify_cookbook('Everyday Greens',
-    ...                       {'http_etag' : 'dummy'}, 'PATCH'))
+    ...                       {'http_etag' : 'placeholder'}, 'PATCH'))
     HTTP/1.1 400 Bad Request
     ...
     http_etag: You tried to modify a read-only attribute.
@@ -994,7 +994,7 @@ You can't directly change an entry's ETag.
 You can't change an entry's resource type.
 
     >>> print(modify_cookbook('Everyday Greens',
-    ...                       {'resource_type_link' : 'dummy'}, 'PATCH'))
+    ...                       {'resource_type_link' : 'placeholder'}, 'PATCH'))
     HTTP/1.1 400 Bad Request
     ...
     resource_type_link: You tried to modify a read-only attribute.
@@ -1004,7 +1004,7 @@ though it were the actual object. A cookbook has a
 'recipes_collection_link', but it doesn't have 'recipes' directly.
 
     >>> print(modify_cookbook(
-    ...     'Everyday Greens', {'recipes' : 'dummy'}, 'PATCH'))
+    ...     'Everyday Greens', {'recipes' : 'placeholder'}, 'PATCH'))
     HTTP/1.1 400 Bad Request
     ...
     recipes: You tried to modify a nonexistent attribute.
@@ -1013,7 +1013,7 @@ A recipe has a 'dish_link', but it doesn't have a 'dish' directly.
 
     >>> url = quote('/cookbooks/The Joy of Cooking/Roast chicken')
     >>> print(webservice.patch(url, 'application/json',
-    ...     simplejson.dumps({'dish' : 'dummy'})))
+    ...     simplejson.dumps({'dish' : 'placeholder'})))
     HTTP/1.1 400 Bad Request
     ...
     dish: You tried to modify a nonexistent attribute.
@@ -1030,7 +1030,7 @@ you can't set a required value to None.
 And of course you can't modify attributes that don't exist.
 
     >>> print(modify_cookbook(
-    ...     'Everyday Greens', {'nonesuch' : 'dummy'}, 'PATCH'))
+    ...     'Everyday Greens', {'nonesuch' : 'placeholder'}, 'PATCH'))
     HTTP/1.1 400 Bad Request
     ...
     nonesuch: You tried to modify a nonexistent attribute.
diff --git a/src/lazr/restful/example/base/tests/field.txt b/src/lazr/restful/example/base/tests/field.txt
index 267b255..aa09231 100644
--- a/src/lazr/restful/example/base/tests/field.txt
+++ b/src/lazr/restful/example/base/tests/field.txt
@@ -284,7 +284,7 @@ value it's given.
   >>> from lazr.restful.testing.webservice import simple_renderer
   >>> @component.adapter(ICookbook, ITextLine, IWebServiceClientRequest)
   ... @implementer(IFieldHTMLRenderer)
-  ... def dummy_renderer(context, field, request):
+  ... def fake_renderer(context, field, request):
   ...     """Bold the original string and add a snowman."""
   ...     return simple_renderer
 
@@ -298,10 +298,10 @@ ITextLine field of an IPerson entry...
 
   >>> from zope.component import getGlobalSiteManager
   >>> manager = getGlobalSiteManager()
-  >>> manager.registerAdapter(dummy_renderer)
+  >>> manager.registerAdapter(fake_renderer)
 
 ...and the XHTML representation of an ICookbook's description will be the
-result of calling a dummy_renderer object.
+result of calling a fake_renderer object.
 
   >>> from lazr.restful.testing.helpers import encode_response
   >>> response = webservice.get(field_url, 'application/xhtml+xml')
@@ -377,7 +377,7 @@ Cleanup
 Before we continue, here's some cleanup code to remove the custom
 renderer we just defined.
 
-  >>> ignored = getGlobalSiteManager().unregisterAdapter(dummy_renderer)
+  >>> ignored = getGlobalSiteManager().unregisterAdapter(fake_renderer)
 
 Compare the HTML generated by the custom renderer, to the XHTML
 generated now that the default adapter is back in place.
@@ -407,12 +407,12 @@ a view on ICookbook called "description".
 
   >>> @component.adapter(ICookbook, ITextLine, IWebServiceClientRequest)
   ... @implementer(IFieldHTMLRenderer)
-  ... def dummy_renderer(context, field, request):
+  ... def fake_renderer(context, field, request):
   ...     """Bold the original string, add a snowman, and encode UTF-8."""
   ...     def render(value):
   ...         return (u"\N{SNOWMAN} <b>%s</b>" % value).encode("utf-8")
   ...     return render
-  >>> manager.registerAdapter(dummy_renderer, name='description')
+  >>> manager.registerAdapter(fake_renderer, name='description')
 
 This renderer is identical to the one shown earlier, except that it
 returns UTF-8 instead of Unicode.
@@ -446,7 +446,7 @@ representations of that entry's fields.
 Before we continue, here's some code to unregister the view.
 
   >>> ignored = getGlobalSiteManager().unregisterAdapter(
-  ...      dummy_renderer, name='description')
+  ...      fake_renderer, name='description')
 
   >>> print(webservice.get(field_url, 'application/xhtml+xml'))
   HTTP/1.1 200 Ok
diff --git a/src/lazr/restful/example/base/tests/representation-cache.txt b/src/lazr/restful/example/base/tests/representation-cache.txt
index 89d35f6..7870eac 100644
--- a/src/lazr/restful/example/base/tests/representation-cache.txt
+++ b/src/lazr/restful/example/base/tests/representation-cache.txt
@@ -207,7 +207,7 @@ POST did.
     >>> from lazr.restful.example.base.root import COOKBOOKS
     >>> cookbook = [cookbook for cookbook in COOKBOOKS
     ...             if cookbook.name == "Everyday Greens"][0]
-    >>> cache.set(cookbook, json, 'devel', "Dummy value.")
+    >>> cache.set(cookbook, json, 'devel', "Sample value.")
     >>> print(list(dictionary.keys())[0])
     http://.../devel/cookbooks/Everyday%20Greens,application/json
 
diff --git a/src/lazr/restful/metazcml.py b/src/lazr/restful/metazcml.py
index 95d5e4c..a61ab91 100644
--- a/src/lazr/restful/metazcml.py
+++ b/src/lazr/restful/metazcml.py
@@ -53,7 +53,7 @@ from lazr.restful.utils import VersionedObject
 
 
 # Keep track of entry and operation registrations so we can
-# sanity-check them later.
+# coherence-check them later.
 REGISTERED_ENTRIES = []
 REGISTERED_OPERATIONS = []
 
@@ -332,7 +332,7 @@ def register_webservice(context, module):
 
 
 @adapter(IProcessStarting)
-def webservice_sanity_checks(registration):
+def webservice_coherence_checks(registration):
     """Ensure the web service contains no references to unpublished objects.
 
     We are worried about fields that link to unpublished objects, and
@@ -408,7 +408,7 @@ def webservice_sanity_checks(registration):
 def _extract_reference_type(field):
     """Determine what kind of object the given field is a reference to.
 
-    This is a helper method used by the sanity checker.
+    This is a helper method used by the coherence checker.
 
     :return: A 2-tuple (reference_type, human_readable): If
     `field` is a reference to a scalar entry, human_readable is
@@ -429,7 +429,7 @@ def _extract_reference_type(field):
 
 def _assert_interface_registered_for_version(
     version, interface, available_registrations, error_message_insert):
-    """A helper method for the sanity checker.
+    """A helper method for the coherence checker.
 
     See if the given entry interface is published in the given version
     (as determined by the contents of `available_registrations`), and
diff --git a/src/lazr/restful/testing/helpers.py b/src/lazr/restful/testing/helpers.py
index 546693a..e8656f6 100644
--- a/src/lazr/restful/testing/helpers.py
+++ b/src/lazr/restful/testing/helpers.py
@@ -8,7 +8,7 @@ from zope.configuration import xmlconfig
 from zope.interface import implementer
 
 from lazr.restful.interfaces import IWebServiceConfiguration
-from lazr.restful.metazcml import webservice_sanity_checks
+from lazr.restful.metazcml import webservice_coherence_checks
 from lazr.restful.simple import (
     Request,
     RootResource,
@@ -36,7 +36,7 @@ def register_test_module(name, *contents):
               <webservice:register module="lazr.restful.%s" />
             </configure>
             """ % name)
-        webservice_sanity_checks(None)
+        webservice_coherence_checks(None)
     except Exception as e:
         del sys.modules['lazr.restful.' + name]
         raise e
diff --git a/src/lazr/restful/testing/webservice.py b/src/lazr/restful/testing/webservice.py
index be79781..c834bfb 100644
--- a/src/lazr/restful/testing/webservice.py
+++ b/src/lazr/restful/testing/webservice.py
@@ -7,8 +7,8 @@ from __future__ import absolute_import, print_function
 __metaclass__ = type
 __all__ = [
     'create_web_service_request',
-    'DummyAbsoluteURL',
-    'DummyRootResourceURL',
+    'StubAbsoluteURL',
+    'StubRootResourceURL',
     'FakeRequest',
     'FakeResponse',
     'IGenericEntry',
@@ -733,7 +733,7 @@ class IGenericCollection(Interface):
 
 
 @implementer(IServiceRootResource)
-class DummyRootResource:
+class StubRootResource:
     """A root resource that does nothing."""
 
     def getTopLevelPublications(self, request):
@@ -741,9 +741,9 @@ class DummyRootResource:
 
 
 @implementer(IAbsoluteURL)
-class DummyAbsoluteURL:
+class StubAbsoluteURL:
     """Implements IAbsoluteURL for when you don't care what the URL is."""
-    URL = 'http://dummyurl/'
+    URL = 'http://exampleurl/'
 
     def __init__(self, *args):
         pass
@@ -754,11 +754,11 @@ class DummyAbsoluteURL:
     __call__ = __str__
 
 
-@adapter(DummyRootResource, IWebServiceClientRequest)
-class DummyRootResourceURL(DummyAbsoluteURL):
-    """A dummy IAbsoluteURL implementation for a DummyRootResource."""
+@adapter(StubRootResource, IWebServiceClientRequest)
+class StubRootResourceURL(StubAbsoluteURL):
+    """A stub IAbsoluteURL implementation for a StubRootResource."""
 
-    URL = 'http://dummyurl'
+    URL = 'http://exampleurl'
 
 
 def simple_renderer(value):
diff --git a/src/lazr/restful/tests/test_declarations.py b/src/lazr/restful/tests/test_declarations.py
index 12d380c..37547d1 100644
--- a/src/lazr/restful/tests/test_declarations.py
+++ b/src/lazr/restful/tests/test_declarations.py
@@ -90,7 +90,7 @@ class ContributingInterfacesTestCase(TestCaseWithWebServiceFixtures):
         sm.registerAdapter(ProductToHasBugsAdapter)
         sm.registerAdapter(ProjectToHasBugsAdapter)
         sm.registerAdapter(ProductToHasBranchesAdapter)
-        sm.registerAdapter(DummyFieldMarshaller)
+        sm.registerAdapter(StubFieldMarshaller)
         self.one_zero_request = self.fake_request('1.0')
         self.two_zero_request = self.fake_request('2.0')
         self.product = Product()
@@ -304,13 +304,13 @@ class ContributingInterfacesTestCase(TestCaseWithWebServiceFixtures):
         # Contributing interfaces are not exported by themselves -- they only
         # contribute their exported fields/operations to other entries.
         @implementer(IHasBranches)
-        class DummyHasBranches:
+        class StubHasBranches:
             pass
-        dummy = DummyHasBranches()
+        stub = StubHasBranches()
         register_test_module('testmod', IBranch, IProduct, IHasBranches)
         self.assertRaises(
             ComponentLookupError,
-            getMultiAdapter, (dummy, self.one_zero_request), IEntry)
+            getMultiAdapter, (stub, self.one_zero_request), IEntry)
 
     def test_cannot_contribute_to_non_exported_interface(self):
         # A contributing interface can only contribute to exported interfaces.
@@ -760,7 +760,7 @@ class ProductToHasBranchesAdapter(object):
 # marshaller so that the adapter lookup doesn't fail and cause an error on the
 # test.
 @adapter(Interface, IHTTPRequest)
-class DummyFieldMarshaller(SimpleFieldMarshaller):
+class StubFieldMarshaller(SimpleFieldMarshaller):
     pass
 
 
@@ -1110,7 +1110,7 @@ class TestRequireExplicitVersions(TestCaseWithWebServiceFixtures):
             'GET_IFieldExplicitOperationDefinition_explicitly_in_10_1_0')
 
 
-# Classes for TestSanityChecking
+# Classes for TestCoherenceChecking
 
 class INotPublished(Interface):
     pass
@@ -1192,23 +1192,25 @@ class IReferencesPublishedAndThenRemoved(Interface):
     field = exported(Reference(schema=IPublishedAndThenRemoved))
 
 
-class TestSanityChecking(TestCaseWithWebServiceFixtures):
-    """Test lazr.restful's sanity checking upon web service registration."""
+class TestCoherenceChecking(TestCaseWithWebServiceFixtures):
+    """
+    Test lazr.restful's coherence checking upon web service registration.
+    """
 
-    def _test_fails_sanity_check(
+    def _test_fails_coherence_check(
         self, expect_failure_in_version, expect_failure_for_reason,
             expect_failure_due_to_interface, *classes):
         """Verify that the given interfaces can't become a web service.
 
-        The given set of interfaces are expected to fail the sanity
+        The given set of interfaces are expected to fail the coherence
         check because they include an annotation that makes some
         version of the web service reference an entry not defined in
         that version (or at all).
 
         :param expect_failure_in_version: Which version of the web
-           service will fail the sanity check.
+           service will fail the coherence check.
         :param expect_failure_for_reason: The reason that will be given
-           for failing the sanity check.
+           for failing the coherence check.
         :param expect_failure_due_to_interface: The interface that will
            cause the failure due to not being published in
            `expect_failure_in_version`.
@@ -1229,13 +1231,13 @@ class TestSanityChecking(TestCaseWithWebServiceFixtures):
         self.assertEqual(str(exception), expected_message)
 
     def test_reference_to_unpublished_object_fails(self):
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("IReferencesNotPublishedEntry_1_0.field is INotPublished"),
             INotPublished, IReferencesNotPublished)
 
     def test_reference_to_object_published_later_fails(self):
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("IReferencesPublishedTooLateEntry_1_0.field is "
              "IPublishedTooLate"),
@@ -1245,8 +1247,8 @@ class TestSanityChecking(TestCaseWithWebServiceFixtures):
         # This setup is acceptable in version 1.0, but in version 2.0
         # IPublishedAndThenRemoved is gone. This puts
         # IReferencesPublishedAndThenRemoved in violation of the
-        # sanity check in 2.0, even though it hasn't changed since 1.0.
-        self._test_fails_sanity_check(
+        # coherence check in 2.0, even though it hasn't changed since 1.0.
+        self._test_fails_coherence_check(
             '2.0',
             ("IReferencesPublishedAndThenRemovedEntry_2_0.field is "
              "IPublishedAndThenRemoved"),
@@ -1272,7 +1274,7 @@ class TestSanityChecking(TestCaseWithWebServiceFixtures):
     def test_reference_to_collection_of_unpublished_objects_fails(self):
         # An entry may define a field that's a scoped collection of
         # unpublished entries.
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("IReferencesCollectionOfNotPublishedEntry_1_0.field is a "
              "collection of INotPublished"),
@@ -1280,14 +1282,14 @@ class TestSanityChecking(TestCaseWithWebServiceFixtures):
 
     def test_operation_returning_unpublished_object_fails(self):
         # An operation may return an unpublished entry.
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("named operation get_impossible_object returns INotPublished"),
             INotPublished, IOperationReturnsNotPublished)
 
     def test_operation_returning_collection_of_unpublished_object_fails(self):
         # An operation may return a collection of unpublished entries.
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("named operation get_impossible_objects returns a collection "
              "of INotPublished"),
@@ -1295,7 +1297,7 @@ class TestSanityChecking(TestCaseWithWebServiceFixtures):
 
     def test_operation_taking_unpublished_argument_fails(self):
         # An operation may take an unpublished entry as an argument.
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("named operation use_impossible_object accepts INotPublished"),
             INotPublished, IOperationAcceptsNotPublished)
@@ -1303,7 +1305,7 @@ class TestSanityChecking(TestCaseWithWebServiceFixtures):
     def test_operation_taking_unpublished_collection_argument_fails(self):
         # An operation may take a collection of unpublished entries as
         # an argument.
-        self._test_fails_sanity_check(
+        self._test_fails_coherence_check(
             '1.0',
             ("named operation use_impossible_objects accepts a collection "
              "of INotPublished"),
diff --git a/src/lazr/restful/tests/test_webservice.py b/src/lazr/restful/tests/test_webservice.py
index 9321eb7..86eb3db 100644
--- a/src/lazr/restful/tests/test_webservice.py
+++ b/src/lazr/restful/tests/test_webservice.py
@@ -69,7 +69,7 @@ from lazr.restful.declarations import (
     )
 from lazr.restful.testing.webservice import (
     create_web_service_request,
-    DummyAbsoluteURL,
+    StubAbsoluteURL,
     IGenericCollection,
     IGenericEntry,
     simple_renderer,
@@ -150,11 +150,11 @@ class EntryTestCase(WebServiceTestCase):
     default_media_type = "application/json"
 
     @implementer(IWebBrowserOriginatingRequest)
-    class DummyWebsiteRequest:
+    class StubWebsiteRequest:
         """A request to the website, as opposed to the web service."""
 
-    class DummyWebsiteURL(DummyAbsoluteURL):
-        """A web-centric implementation of the dummy URL."""
+    class StubWebsiteURL(StubAbsoluteURL):
+        """A web-centric implementation of the stub URL."""
         URL = 'http://www.website.url/'
 
     @contextmanager
@@ -210,7 +210,7 @@ class EntryTestCase(WebServiceTestCase):
     def _register_url_adapter(self, entry_interface):
         """Register an IAbsoluteURL implementation for an interface."""
         getGlobalSiteManager().registerAdapter(
-            DummyAbsoluteURL, [entry_interface, IWebServiceClientRequest],
+            StubAbsoluteURL, [entry_interface, IWebServiceClientRequest],
             IAbsoluteURL)
 
     def _register_website_url_space(self, entry_interface):
@@ -221,7 +221,7 @@ class EntryTestCase(WebServiceTestCase):
         # web page requests.
         def web_service_request_to_website_request(service_request):
             """Create a corresponding request to the website."""
-            return self.DummyWebsiteRequest()
+            return self.StubWebsiteRequest()
 
         getGlobalSiteManager().registerAdapter(
             web_service_request_to_website_request,
@@ -230,7 +230,7 @@ class EntryTestCase(WebServiceTestCase):
         # Next, set up a distinctive URL, and register it as the
         # website URL for the given entry interface.
         getGlobalSiteManager().registerAdapter(
-            self.DummyWebsiteURL,
+            self.StubWebsiteURL,
             [entry_interface, IWebBrowserOriginatingRequest],
             IAbsoluteURL)
 
@@ -282,9 +282,9 @@ class TestEntryWebLink(EntryTestCase):
         # 'web_link'.
         with self.entry_resource(IHasOneField, HasOneField, "") as resource:
             representation = resource.toDataForJSON()
-            self.assertEqual(representation['self_link'], DummyAbsoluteURL.URL)
+            self.assertEqual(representation['self_link'], StubAbsoluteURL.URL)
             self.assertEqual(
-                representation['web_link'], self.DummyWebsiteURL.URL)
+                representation['web_link'], self.StubWebsiteURL.URL)
 
     def test_wadl_includes_web_link_when_available(self):
         # If an entry includes a web_link, this information will
@@ -314,7 +314,7 @@ class TestEntryWebLink(EntryTestCase):
         with self.entry_resource(IHasOneField, HasOneField, "") as resource:
             representation = resource.toDataForJSON()
             self.assertEqual(
-                representation['self_link'], DummyAbsoluteURL.URL)
+                representation['self_link'], StubAbsoluteURL.URL)
             self.assertFalse('web_link' in representation)
 
     def test_wadl_omits_web_link_when_not_available(self):
@@ -350,7 +350,7 @@ class TestSuppressWebLink(EntryTestCase):
             resource):
             representation = resource.toDataForJSON()
             self.assertEqual(
-                representation['self_link'], DummyAbsoluteURL.URL)
+                representation['self_link'], StubAbsoluteURL.URL)
             self.assertFalse('web_link' in representation)
 
 
@@ -991,7 +991,7 @@ class NotificationsProviderTest(EntryTestCase):
     testmodule_objects = [HasOneField, IHasOneField]
 
     @implementer(INotificationsProvider)
-    class DummyWebsiteRequestWithNotifications:
+    class StubWebsiteRequestWithNotifications:
         """A request to the website, as opposed to the web service."""
 
         @property
@@ -1013,7 +1013,7 @@ class NotificationsProviderTest(EntryTestCase):
         # web service requests with notifications.
         def web_service_request_to_notification_request(service_request):
             """Create a corresponding request to the website."""
-            return self.DummyWebsiteRequestWithNotifications()
+            return self.StubWebsiteRequestWithNotifications()
 
         getGlobalSiteManager().registerAdapter(
             web_service_request_to_notification_request,