Rename wants tool to provides

Due to contraints imposed by cherrypy, the supported formats can't be
provided as decorator args.

.pylintrc

@@ -269,7 +269,7 @@ contextmanager-decorators=contextlib.contextmanager
 # List of members which are set dynamically and missed by pylint inference
 # system, and so shouldn't trigger E1101 when accessed. Python regular
 # expressions are accepted.
-generated-members=cherrypy.tools.capture, cherrypy.tools.wants, cherrypy.tools.etag
+generated-members=cherrypy.tools.capture, cherrypy.tools.provides, cherrypy.tools.etag
 
 # Tells whether missing members accessed in mixin class should be ignored. A
 # mixin class is detected if its name ends with "mixin" (case insensitive).

apps/alturl/main.py

@@ -12,7 +12,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*args) -> str:
         """Dispatch to a site-specific handler."""
 

apps/applog/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display a list of recent log entries"""
 

apps/bookmarklets/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     @cherrypy.tools.etag()
     def GET(*_args, **_kwargs):
         """Present a static list of bookmarklets"""

apps/bookmarks/main.py

@@ -24,7 +24,7 @@ def check_wayback_availability(url):
         closest_snapshot = snapshots.get("closest", {})
         return closest_snapshot
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(self, *args, **kwargs):
         """Display a list of recently bookmarked URLs, or URLs matching a
         search.

apps/bounce/main.py

@@ -73,7 +73,7 @@ def host_to_keyword(self, host):
 
         return "live"
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(self, *_args, **kwargs):
         """Display all the URLs in a group."""
 

apps/calls/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display a list of recent calls"""
 

apps/captures/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display a list of recent captures, or captures matching a URI path.
         """

apps/grids/main.py

@@ -12,7 +12,7 @@ class Controller:
     exposed = True
     show_on_homepage = True
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(self, *_args, **kwargs):
         """Display the list of available grids, or the current grid"""
 

apps/headers/main.py

@@ -11,7 +11,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants()
+    @cherrypy.tools.provides(formats=("json", "text", "html"))
     def GET(*_args, **_kwargs):
         """Display the headers of the current request"""
 

apps/headers/main_test.py

@@ -80,6 +80,7 @@ def test_custom_header(self):
             as_json=True
         )
 
+        print(response.body)
         _, value = next(
             pair
             for pair in response.body

apps/headlines/main.py

@@ -11,7 +11,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display a list of headlines."""
 

apps/homepage/main.py

@@ -55,7 +55,7 @@ def catalog_apps(self, apps):
 
         return catalog
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     @cherrypy.tools.etag()
     def GET(self, *_args, **_kwargs) -> str:
         """List all available applications.

apps/htmlhead/main.py

@@ -11,7 +11,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **_kwargs):
         """Present a form for specifying a URL to fetch."""
 
@@ -21,7 +21,7 @@ def GET(*_args, **_kwargs):
         ).pop()
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def POST(url=None, username=None, password=None):
         """Request an HTML page and display its the contents of its head
         section.

apps/ip/main.py

@@ -11,7 +11,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants()
+    @cherrypy.tools.provides(formats=("json", "text", "html"))
     def GET(*_args, **_kwargs):
         """Display the client's local IP, and the server's external IP"""
 

apps/later/main.py

@@ -11,7 +11,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display a form for for bookmarking a URL"""
 

apps/phone/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """
         Display information about the specified number, or a search form to

apps/redirect/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = False
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **_kwargs):
         """Perform a client-side redirect to the URL specified in the
         querystring.

apps/registry/main.py

@@ -11,7 +11,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants()
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display a UI to search for entries and add new ones."""
 

apps/reminder/main.py

@@ -14,7 +14,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **_kwargs):
         """Display scheduled reminders, and a form to create new ones."""
 

apps/speak/main.py

@@ -10,7 +10,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **_kwargs):
         """Present an interface for on-demand muting of the speech service."""
 

apps/startpage/main.py

@@ -73,7 +73,7 @@ def edit_page(self, page_name, page_content=None):
         }
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     @cherrypy.tools.etag()
     def render_page(page_name, page_record):
         """Render INI page content to HTML."""
@@ -139,7 +139,7 @@ def render_worker():
             content_type="application/javascript"
         )
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(self, *args, **kwargs):
         """Render a page or present the edit form."""
 

apps/transform/main.py

@@ -49,7 +49,7 @@ def list_of_transforms(self):
         """Shape the list of transforms into a list of keys"""
         return sorted(self.transforms.keys())
 
-    @cherrypy.tools.wants()
+    @cherrypy.tools.provides(formats=("json", "text", "html"))
     def GET(self, *_args, **_kwargs):
         """The default view presents the available transformation methods"""
 
@@ -67,7 +67,7 @@ def GET(self, *_args, **_kwargs):
             transforms=self.list_of_transforms()
         ).pop()
 
-    @cherrypy.tools.wants()
+    @cherrypy.tools.provides(formats=("json", "text", "html"))
     def POST(self, transform, value=''):
         """Perform a transformation and display the result"""
 

apps/visitors/main.py

@@ -17,7 +17,7 @@ class Controller:
     exposed = True
     show_on_homepage = True
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(self, *_args, **kwargs):
         """Display a search interface, and the results of the default query"""
 

apps/wakeup/main.py

@@ -12,7 +12,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_args, **kwargs):
         """Display the list of hosts eligible for wakeup."""
 
@@ -40,7 +40,7 @@ def GET(*_args, **kwargs):
         ).pop()
 
     @staticmethod
-    @cherrypy.tools.wants()
+    @cherrypy.tools.provides(formats=("text", "html"))
     def POST(*_args, **kwargs):
         """Send a WoL packet to the mac address of the specified host."""
 

apps/weather/main.py

@@ -13,7 +13,7 @@ class Controller:
     exposed = True
     show_on_homepage = True
 
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(self, *args, **_kwargs):
         """Display selected parts of the most recent Darksky API query"""
 

apps/whois/main.py

@@ -14,7 +14,7 @@ class Controller:
     show_on_homepage = True
 
     @staticmethod
-    @cherrypy.tools.wants(only="html")
+    @cherrypy.tools.provides(formats=("html",))
     def GET(*_, **kwargs):
         """Display a search form and lookup results."""
 

medley.py

@@ -47,7 +47,7 @@
 import plugins.url
 import tools.capture
 import tools.etag
-import tools.wants
+import tools.provides
 
 # pylint: disable=too-many-statements
 @plugins.decorators.log_runtime
@@ -124,7 +124,7 @@ def setup() -> None:
     # Tools
     cherrypy.tools.capture = tools.capture.Tool()
     cherrypy.tools.etag = tools.etag.Tool()
-    cherrypy.tools.wants = tools.wants.Tool()
+    cherrypy.tools.provides = tools.provides.Tool()
 
     # Mount the apps
     for app in os.listdir(app_root):

testing/cptestcase.py

@@ -17,12 +17,12 @@ class is a way of simulating an incoming request against a server that
 import json
 import cherrypy
 import tools.capture
-import tools.wants
+import tools.provides
 import tools.etag
 
 cherrypy.config.update({'environment': "test_suite"})
 cherrypy.tools.capture = tools.capture.Tool()
-cherrypy.tools.wants = tools.wants.Tool()
+cherrypy.tools.provides = tools.provides.Tool()
 cherrypy.tools.etag = tools.etag.Tool()
 
 # Don't start the HTTP server

tools/wants.py → tools/provides.py

@@ -1,37 +1,39 @@
-"""Identify the desired content type of a request."""
+"""A Cherrypy tool to make it easier to work with the Accept header."""
 
 import pathlib
+import typing
 import cherrypy
 
 
 class Tool(cherrypy.Tool):
-    """A Cherrypy tool to make it easier to work with the Accept header."""
+    """Reconcile the desired content type of a request with what the
+    application supports.
+
+    """
 
     def __init__(self) -> None:
         cherrypy.Tool.__init__(
             self,
             "before_request_body",
-            self.wants,
+            self.provides,
             priority=10
         )
 
     @staticmethod
-    def wants(*_args, **kwargs) -> None:
-        """Reshape the accept header as a custom request property.
+    def provides(formats: typing.Tuple[str]) -> None:
+        """Populate a custom request property with a keyword describing the
+        client's desired content format.
 
-        Preference weights (;q=) are not considered.
+        Preference weights in the Accept header (;q=) are not considered.
 
         If a JSON or TXT file extension is specified in the request
         path, it takes precedence.
 
         Callers can indicate what content types are supported by
-        setting the keyword argument "only" to a space-delimited list
-        of keywords.
+        passing known keywords via *args.
 
         """
 
-        only_wants = kwargs.get("only")
-
         accept = cherrypy.request.headers.get("Accept", "*/*")
 
         request_path = pathlib.Path(cherrypy.request.path_info)
@@ -52,5 +54,5 @@ def wants(*_args, **kwargs) -> None:
             cherrypy.request.wants = "json"
             response_headers["Content-Type"] = "application/json"
 
-        if only_wants and cherrypy.request.wants not in only_wants:
+        if cherrypy.request.wants not in formats:
             raise cherrypy.HTTPError(406)