Return ResourceRoute from .set_options_route() (aio-libs#12917)

Author: Dreamsorcerer

CHANGES/12917.feature.rst

@@ -0,0 +1,2 @@
+Changed ``StaticResource.set_options_route()`` to return the
+created ``ResourceRoute``, matching ``Resource.add_route`` -- by :user:`Dreamsorcerer`.

aiohttp/web_urldispatcher.py

@@ -588,13 +588,15 @@ def get_info(self) -> _InfoDict:
             "routes": self._routes,
         }
 
-    def set_options_route(self, handler: Handler) -> None:
+    def set_options_route(self, handler: Handler) -> "ResourceRoute":
         if "OPTIONS" in self._routes:
             raise RuntimeError("OPTIONS route was set already")
-        self._routes["OPTIONS"] = ResourceRoute(
+        route = ResourceRoute(
             "OPTIONS", handler, self, expect_handler=self._expect_handler
         )
+        self._routes["OPTIONS"] = route
         self._allowed_methods.add("OPTIONS")
+        return route
 
     async def resolve(self, request: Request) -> _Resolve:
         path = request.rel_url.path_safe

docs/web_reference.rst

@@ -2247,6 +2247,21 @@ Resource classes hierarchy::
 
          if file not found has no impact
 
+   .. method:: set_options_route(handler)
+
+      Register *handler* as the ``OPTIONS`` route for this resource.
+
+      Raises :exc:`RuntimeError` if an ``OPTIONS`` route was already set.
+
+      :param handler: a :ref:`web-handler<aiohttp-web-handler>` for
+                      ``OPTIONS`` requests.
+
+      :return: the newly created :class:`ResourceRoute`.
+
+      .. versionchanged:: 3.15
+
+         Now returns the created :class:`ResourceRoute` instead of ``None``.
+
 
 .. class:: PrefixedSubAppResource
    :canonical: aiohttp.web_urldispatcher.PrefixedSubAppResource

tests/test_urldispatch.py

@@ -559,7 +559,11 @@ async def test_add_static_set_options_route(router: web.UrlDispatcher) -> None:
     async def handler(request: web.Request) -> NoReturn:
         assert False
 
-    resource.set_options_route(handler)
+    route = resource.set_options_route(handler)
+    assert isinstance(route, web.ResourceRoute)
+    assert route.method == hdrs.METH_OPTIONS
+    assert route.handler is handler
+    assert route.resource is resource
     mapping, allowed_methods = await resource.resolve(
         make_mocked_request("OPTIONS", "/st/path")
     )
@@ -1296,7 +1300,12 @@ def test_frozen_app_on_subapp(app: web.Application) -> None:
 def test_set_options_route(router: web.UrlDispatcher) -> None:
     resource = router.add_static("/static", pathlib.Path(aiohttp.__file__).parent)
     assert all(r.method != "OPTIONS" for r in resource)
-    resource.set_options_route(make_handler())
+    handler = make_handler()
+    route = resource.set_options_route(handler)
+    assert isinstance(route, web.ResourceRoute)
+    assert route.method == "OPTIONS"
+    assert route.handler is handler
+    assert route in list(resource)
     assert any(r.method == "OPTIONS" for r in resource)
 
     with pytest.raises(RuntimeError):