@shortlink-org/portolan 0.2.4 → 0.4.0

package/plugins/extract-django/rules_test.py

@@ -0,0 +1,158 @@
+"""The rules a model field states, read one option at a time."""
+
+import ast
+import unittest
+
+from domain import FieldDef
+from rules import rules_of
+
+
+class Module:
+    """The slice of a Module the rules reader touches: the tree and its classes."""
+
+    def __init__(self, tree: ast.Module):
+        self.tree = tree
+
+    def classes(self):
+        return [node for node in self.tree.body if isinstance(node, ast.ClassDef)]
+
+
+class Model:
+    def __init__(self, node: ast.ClassDef, module: Module):
+        self.node = node
+        self.module = module
+
+
+def fields(source: str):
+    """Every field of the last class in `source`, as the extractor reads it,
+    with the integer options it resolves ahead of time."""
+    tree = ast.parse(source)
+    node = [n for n in tree.body if isinstance(n, ast.ClassDef)][-1]
+    model = Model(node, Module(tree))
+    out = {}
+    for stmt in node.body:
+        if isinstance(stmt, ast.Assign) and isinstance(stmt.value, ast.Call):
+            name = stmt.targets[0].id
+            call = stmt.value
+            kind = call.func.attr if isinstance(call.func, ast.Attribute) else call.func.id
+            integers = {}
+            for kw in call.keywords:
+                if kw.arg == "max_length" and isinstance(kw.value, ast.Constant):
+                    integers["max_length"] = kw.value.value
+            out[name] = rules_of(FieldDef(name=name, kind=kind, call=call, node=stmt, integers=integers), model)
+    return out
+
+
+class Options(unittest.TestCase):
+    def test_the_options_become_rules_in_the_order_written(self):
+        got = fields(
+            "class Invoice(models.Model):\n"
+            "    number = models.CharField(max_length=32, unique=True, null=True)\n"
+            "    currency = models.CharField(unique=True, max_length=3)\n"
+        )
+        self.assertEqual(got["number"], {"rules": [{"name": "max_len", "value": "32"}, {"name": "unique"}]})
+        self.assertEqual(got["currency"], {"required": True, "rules": [{"name": "unique"}, {"name": "max_len", "value": "3"}]})
+
+    def test_the_field_class_speaks_first(self):
+        got = fields(
+            "class Line(models.Model):\n"
+            "    email = models.EmailField(max_length=254)\n"
+            "    quantity = models.PositiveIntegerField()\n"
+            "    site = models.URLField(blank=True)\n"
+            "    owner = models.UUIDField(default=uuid.uuid4)\n"
+        )
+        self.assertEqual(got["email"]["rules"], [{"name": "format", "value": "email"}, {"name": "max_len", "value": "254"}])
+        self.assertEqual(got["quantity"], {"required": True, "rules": [{"name": "gte", "value": "0"}]})
+        self.assertEqual(got["site"], {"rules": [{"name": "format", "value": "uri"}]})
+        self.assertEqual(got["owner"], {"rules": [{"name": "format", "value": "uuid"}]})
+
+    def test_validators_carry_their_bound(self):
+        got = fields(
+            "class Line(models.Model):\n"
+            "    rate = models.DecimalField(validators=[MinValueValidator(0), MaxValueValidator(limit_value=1)])\n"
+            "    code = models.CharField(validators=[RegexValidator(r'^[A-Z]{3}$'), RegexValidator('x', inverse_match=True), validators.MinLengthValidator(2)])\n"
+            "    other = models.CharField(validators=[custom(), MinValueValidator(LIMIT)])\n"
+        )
+        self.assertEqual(got["rate"]["rules"], [{"name": "gte", "value": "0"}, {"name": "lte", "value": "1"}])
+        self.assertEqual(got["code"]["rules"], [{"name": "pattern", "value": "^[A-Z]{3}$"}, {"name": "min_len", "value": "2"}])
+        self.assertEqual(got["other"], {"required": True})
+
+
+class Choices(unittest.TestCase):
+    def test_a_choices_class_is_read_by_its_stored_values(self):
+        got = fields(
+            "class Invoice(models.Model):\n"
+            "    class Status(models.TextChoices):\n"
+            "        DRAFT = 'draft', 'Draft'\n"
+            "        PAID = 'paid', 'Paid'\n"
+            "    status = models.CharField(max_length=16, choices=Status.choices, default=Status.DRAFT)\n"
+        )
+        self.assertEqual(got["status"], {"rules": [{"name": "max_len", "value": "16"}, {"name": "in", "value": "draft, paid"}]})
+
+    def test_a_module_level_class_and_an_integer_choices_read_the_same(self):
+        got = fields(
+            "class Priority(models.IntegerChoices):\n"
+            "    LOW = 1\n"
+            "    HIGH = 2, 'High'\n"
+            "class Ticket(models.Model):\n"
+            "    priority = models.IntegerField(choices=Priority.choices)\n"
+        )
+        self.assertEqual(got["priority"], {"required": True, "rules": [{"name": "in", "value": "1, 2"}]})
+
+    def test_literal_lists_bare_values_and_groups(self):
+        got = fields(
+            "SIZES = [('s', 'Small'), ('m', 'Medium')]\n"
+            "class Shirt(models.Model):\n"
+            "    size = models.CharField(choices=SIZES)\n"
+            "    fit = models.CharField(choices=['slim', 'regular'])\n"
+            "    colour = models.CharField(choices=[('Warm', [('red', 'Red')]), ('Cold', [('blue', 'Blue')])])\n"
+            "    made = models.CharField(choices=load_choices())\n"
+        )
+        self.assertEqual(got["size"]["rules"], [{"name": "in", "value": "s, m"}])
+        self.assertEqual(got["fit"]["rules"], [{"name": "in", "value": "slim, regular"}])
+        self.assertEqual(got["colour"]["rules"], [{"name": "in", "value": "red, blue"}])
+        self.assertEqual(got["made"], {"required": True})
+
+    def test_a_pair_naming_a_member_reads_its_value(self):
+        got = fields(
+            "class Kind(models.TextChoices):\n"
+            "    ORDER = 'order', 'Order'\n"
+            "class Invoice(models.Model):\n"
+            "    kind = models.CharField(choices=[(Kind.ORDER, 'An order')])\n"
+        )
+        self.assertEqual(got["kind"]["rules"], [{"name": "in", "value": "order"}])
+
+
+class Required(unittest.TestCase):
+    def test_the_model_fills_or_excuses_the_value(self):
+        got = fields(
+            "class Invoice(models.Model):\n"
+            "    id = models.BigAutoField(primary_key=True)\n"
+            "    order_id = models.UUIDField()\n"
+            "    number = models.CharField(max_length=32, null=True)\n"
+            "    note = models.TextField(blank=True)\n"
+            "    created = models.DateTimeField(auto_now_add=True)\n"
+            "    status = models.CharField(max_length=8, default='draft')\n"
+            "    paid = models.BooleanField()\n"
+            "    tags = models.ManyToManyField('Tag')\n"
+            "    invoice = models.ForeignKey('Invoice', on_delete=models.CASCADE)\n"
+        )
+        required = {name: value.get("required", False) for name, value in got.items()}
+        self.assertEqual(
+            required,
+            {
+                "id": False,
+                "order_id": True,
+                "number": False,
+                "note": False,
+                "created": False,
+                "status": False,
+                "paid": False,
+                "tags": False,
+                "invoice": True,
+            },
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

package/plugins/extract-django/store.py

@@ -345,7 +345,7 @@ def model_table(
         columns,
         indexes(model, name, by_field),
         {"aggregate": aggregate.id, "block": block} if aggregate is not None else None,
-        "aggregate-root" if aggregate is not None and model is aggregate.root else "child" if aggregate is not None else "",
+        "aggregate-root" if aggregate is not None and model is aggregate.root else "child" if aggregate is not None and aggregate.root is not None else "",
         meta_str(model, "verbose_name"),
     )
 

package/plugins/extract-django/transport.py

@@ -11,12 +11,13 @@ from __future__ import annotations
 import ast
 import re
 from dataclasses import dataclass, field as dc_field
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Tuple
 
+import verbs as verbs_module
 from apps import App
 from ids import slug
 from routing import Route, Routes
-from source import Module, const_str, doc, dotted, keyword, methods
+from source import Module, Project, const_str, doc, dotted, keyword, methods
 
 # The actions a ViewSet has without writing one.
 ACTIONS = {
@@ -61,6 +62,10 @@ class Endpoint:
     doc: str = ""
     use_cases: List[str] = dc_field(default_factory=list)
     path_parameters: Dict[str, str] = dc_field(default_factory=dict)
+    # Where the verb was read when the handler's name did not say it: a
+    # decorator, ``http_method_names``, a ``request.method`` branch or a
+    # project wrapper, with the file:line. Empty when the verb is unknown.
+    verb_source: str = ""
 
 
 def basenames(app: App) -> Dict[str, str]:
@@ -95,18 +100,29 @@ def view_name(name: str) -> str:
     return slug(name).replace("-", "_")
 
 
-def verb_of(node: ast.AST, action: str) -> str:
-    decorator = None
+HANDLER_NAMES = ("get", "post", "put", "patch", "delete")
+
+
+def verbs_of(node: ast.AST, action: str) -> Tuple[str, ...]:
+    """The verbs a handler answers by its own declaration: every method an
+    ``@action``/``@api_view`` lists, else what its conventional name means.
+    Empty for a handler whose name is the project's own."""
     for dec in getattr(node, "decorator_list", []):
         if isinstance(dec, ast.Call) and dotted(dec.func).split(".")[-1] in ("action", "api_view"):
-            decorator = dec
-    if decorator is not None:
-        methods_arg = keyword(decorator, "methods")
-        if methods_arg is None and decorator.args:
-            methods_arg = decorator.args[0]
-        if isinstance(methods_arg, (ast.List, ast.Tuple, ast.Set)) and methods_arg.elts:
-            return const_str(methods_arg.elts[0]).upper()
-    return ACTIONS.get(action, "" if action not in ("get", "post", "put", "patch", "delete") else action.upper())
+            listed = verbs_module.listed_verbs(dec)
+            if listed:
+                return listed
+    if action in ACTIONS:
+        return (ACTIONS[action],)
+    return (action.upper(),) if action in HANDLER_NAMES else ()
+
+
+def is_action(node: ast.AST) -> bool:
+    return any(isinstance(dec, ast.Call) and dotted(dec.func).split(".")[-1] == "action" for dec in getattr(node, "decorator_list", []))
+
+
+def is_api_view(node: ast.AST) -> bool:
+    return any(isinstance(dec, ast.Call) and dotted(dec.func).split(".")[-1] == "api_view" for dec in getattr(node, "decorator_list", []))
 
 
 def route_base(route: Route, fallback: str) -> str:
@@ -134,8 +150,10 @@ def action_path(route: Route, node: ast.AST, action: str) -> str:
     return base + ("/{id}" if detail else "") + ("/" + suffix if action not in ACTIONS else "") + "/"
 
 
-def endpoint(node: ast.AST, module: Module, view: str, action: str, verb: str, base: str, route: Optional[Route], description: str = "") -> Endpoint:
+def endpoint(node: ast.AST, module: Module, view: str, action: str, verb: str, base: str, route: Optional[Route], description: str = "", suffix: str = "", verb_source: str = "") -> Endpoint:
     ident = base if base == action or base.endswith("_" + action) else "%s_%s" % (base, action)
+    if suffix:
+        ident = "%s_%s" % (ident, suffix)
     return Endpoint(
         id=ident,
         action=action,
@@ -147,11 +165,30 @@ def endpoint(node: ast.AST, module: Module, view: str, action: str, verb: str, b
         route_source=route.source if route else "",
         doc=description,
         path_parameters=dict(route.parameters) if route else {},
+        verb_source=verb_source,
     )
 
 
-def read_endpoints(app: App, b, routes: Optional[Routes] = None) -> List[Endpoint]:
+def unknown_verb(b, route: Route) -> None:
+    b.warn(
+        route.source,
+        "%s is mounted as an HTTP view, but no HTTP verb is declared; the route is kept with its verb unknown and no operation is inferred for it. "
+        "Declare the verb with require_http_methods, @api_view, http_method_names or a branch on request.method" % route.view,
+    )
+
+
+def expand(handler: ast.AST, module: Module, view: str, action: str, verb_list: Tuple[str, ...], base: str, route: Optional[Route], description: str, verb_source: str) -> List[Endpoint]:
+    """One endpoint per verb. The first keeps the plain id; a second verb on
+    the same handler is told apart by the verb, ``planet_fetch_post``."""
+    out = []
+    for index, verb in enumerate(verb_list):
+        out.append(endpoint(handler, module, view, action, verb, base, route, description, suffix=verb.lower() if index else "", verb_source=verb_source))
+    return out
+
+
+def read_endpoints(app: App, b, routes: Optional[Routes] = None, project: Optional[Project] = None) -> List[Endpoint]:
     registered = basenames(app)
+    reader = verbs_module.Reader(project)
     out: List[Endpoint] = []
     for module in app.package("views"):
         for node in module.classes():
@@ -165,62 +202,71 @@ def read_endpoints(app: App, b, routes: Optional[Routes] = None) -> List[Endpoin
                 base = view_name(node.name)
                 b.warn(module.rel, "%s is registered by no router in %s/urls.py; its endpoints are named after the class" % (node.name, app.rel))
             handlers = {handler.name: handler for handler in methods(node)}
-            declared = []
+            method_routes: Dict[str, List[Route]] = {}
+            for route in mounted:
+                if "." in route.view:
+                    method_routes.setdefault(route.view.split(".", 1)[1], []).append(route)
+            # (action, verbs, handler, doc, where the verb was read)
+            declared: List[Tuple[str, Tuple[str, ...], ast.AST, str, str]] = []
             for handler in handlers.values():
                 if handler.name.startswith("_"):
                     continue
-                is_action = any(
-                    isinstance(dec, ast.Call) and dotted(dec.func).split(".")[-1] == "action" for dec in getattr(handler, "decorator_list", [])
-                )
-                if handler.name not in ACTIONS and not is_action and handler.name not in ("get", "post", "put", "patch", "delete"):
-                    # A plain Django class may expose an arbitrarily named
-                    # method directly in URLConf (`Planet.fetch`). The route
-                    # proves the HTTP entrypoint but, without a method
-                    # decorator or request-method branch, not one particular
-                    # verb. Keep it as a flow root and leave it out of the
-                    # inferred OpenAPI contract.
-                    if handler.name not in {
-                        route.view.split(".", 1)[1]
-                        for route in mounted
-                        if "." in route.view
-                    }:
-                        continue
-                declared.append((handler.name, verb_of(handler, handler.name), handler, doc(handler)))
+                verb_list = verbs_of(handler, handler.name)
+                verb_source = ""
+                if not verb_list and not is_action(handler) and handler.name not in method_routes:
+                    continue
+                if not verb_list:
+                    # A plain class may expose an arbitrarily named method
+                    # directly in URLConf (`Planet.fetch`). The route proves
+                    # the HTTP entrypoint; the verb is read off what the
+                    # handler, its class or a project wrapper declares, and
+                    # is left unknown - never guessed - when none of them does.
+                    evidence = reader.for_handler(module, handler, node)
+                    if evidence is not None:
+                        verb_list, verb_source = evidence.verbs, "%s at %s" % (evidence.rule, evidence.source)
+                    else:
+                        verb_list = ("",)
+                declared.append((handler.name, verb_list, handler, doc(handler), verb_source))
             inherited = []
             for inherited_base in bases:
                 inherited += GENERIC_ACTIONS.get(inherited_base, [])
             for action, verb in inherited:
-                same_direct_handler = mounted and all(not route.router for route in mounted) and any(item[1] == verb for item in declared)
+                same_direct_handler = mounted and all(not route.router for route in mounted) and any(verb in item[1] for item in declared)
                 if action not in handlers and not any(item[0] == action for item in declared) and not same_direct_handler:
-                    declared.append((action, verb, node, doc(node)))
+                    declared.append((action, (verb,), node, doc(node), ""))
             class_routes = routes.for_view(module.dotted, node.name) if routes else []
-            method_routes = {route.view.split(".", 1)[1]: route for route in mounted if "." in route.view}
             if not class_routes and not method_routes:
-                for action, verb, handler, description in declared:
-                    out.append(endpoint(handler, module, node.name, action, verb, base or view_name(node.name), None, description))
+                for action, verb_list, handler, description, verb_source in declared:
+                    out += expand(handler, module, node.name, action, verb_list, base or view_name(node.name), None, description, verb_source)
                 continue
-            for action, verb, handler, description in declared:
-                targets = class_routes or ([method_routes[action]] if action in method_routes else [])
-                for route in targets:
-                    if not verb:
-                        b.warn(
-                            route.source,
-                            "%s is mounted as an HTTP view, but no HTTP verb is declared; its flow is extracted and the route is omitted from inferred OpenAPI"
-                            % route.view,
-                        )
-                    out.append(endpoint(handler, module, node.name, action, verb, route_base(route, base or view_name(node.name)), route, description))
+            for action, verb_list, handler, description, verb_source in declared:
+                for route in class_routes or method_routes.get(action, []):
+                    if "" in verb_list:
+                        unknown_verb(b, route)
+                    out += expand(handler, module, node.name, action, verb_list, route_base(route, base or view_name(node.name)), route, description, verb_source)
         for node in module.functions():
             mounted = routes.for_view(module.dotted, node.name) if routes else []
-            if not mounted and not any(isinstance(dec, ast.Call) and dotted(dec.func).split(".")[-1] == "api_view" for dec in getattr(node, "decorator_list", [])):
+            if not mounted and not is_api_view(node):
                 continue
-            verb = verb_of(node, node.name)
-            if not verb:
+            verb_list = verbs_of(node, node.name)
+            verb_source = ""
+            if not verb_list:
+                evidence = reader.for_handler(module, node)
+                if evidence is not None:
+                    verb_list, verb_source = evidence.verbs, "%s at %s" % (evidence.rule, evidence.source)
+                elif mounted:
+                    verb_list = ("",)
+                else:
+                    continue
+            if not mounted:
+                for verb in verb_list:
+                    out.append(Endpoint(id=node.name, action=node.name, view="", verb=verb, node=node, module=module, doc=doc(node), verb_source=verb_source))
                 continue
-            if mounted:
-                for route in mounted:
-                    out.append(endpoint(node, module, "", verb.lower(), verb, route_base(route, node.name), route, doc(node)))
-            else:
-                out.append(Endpoint(id=node.name, action=node.name, view="", verb=verb, node=node, module=module, doc=doc(node)))
+            for route in mounted:
+                if "" in verb_list:
+                    unknown_verb(b, route)
+                for verb in verb_list:
+                    out.append(endpoint(node, module, "", verb.lower() or node.name, verb, route_base(route, node.name), route, doc(node), verb_source=verb_source))
     unique = {}
     for found in out:
         unique[(found.id, found.verb, found.path, found.module.rel)] = found

package/plugins/extract-django/verbs.py

@@ -0,0 +1,241 @@
+"""Which HTTP verb a mounted handler answers, read from what the code declares.
+
+A URLConf can mount any callable — ``path("planet/fetch", Planet.fetch)`` —
+and then the route table proves the path but says nothing about the verb.
+The verb is still written down somewhere in the handler, in one of the ways
+Django and DRF offer for it, and this module reads them in the order a
+reviewer would trust them:
+
+1. a decorator on the handler: DRF's ``@action(methods=…)`` and ``@api_view``,
+   Django's ``@require_http_methods([…])``, ``@require_GET``, ``@require_POST``
+   and ``@require_safe``, also through ``method_decorator(…)``;
+2. the same decorators on the class, ``@method_decorator(…, name="dispatch")``;
+3. the class's ``http_method_names``;
+4. a branch on ``request.method`` in the handler body;
+5. a project wrapper — a decorator or a function the handler hands ``request``
+   to — whose own body does one of the above, followed a bounded number of
+   levels deep.
+
+The first tier that speaks decides. Nothing here is guessed: a handler none
+of the tiers describes has no verb, and the caller says so rather than
+inventing one.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from typing import List, Optional, Set, Tuple
+
+from source import Module, Project, const_str, dotted, keyword, methods, node_name
+
+HTTP_VERBS = ("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "TRACE")
+
+# What a framework answers for every route regardless of the handler; listing
+# them never says what the handler is for, so they are dropped when any other
+# verb is named beside them.
+IMPLICIT = {"HEAD", "OPTIONS", "TRACE"}
+
+SHORTHAND = {"require_GET": ("GET",), "require_POST": ("POST",), "require_safe": ("GET",)}
+LISTED = ("require_http_methods", "action", "api_view")
+
+# How far a project wrapper is followed before the reader stops. Two levels
+# cover a decorator that wraps a decorator; anything deeper is a project that
+# should declare its verb where the handler is.
+DEPTH = 3
+
+
+@dataclass(frozen=True)
+class Evidence:
+    verbs: Tuple[str, ...]
+    rule: str  # "decorator", "class decorator", "http_method_names", "request.method", "wrapper <name>"
+    source: str  # file:line of what was read
+
+
+class Reader:
+    def __init__(self, project: Optional[Project]):
+        self.project = project
+
+    # --- the tiers -----------------------------------------------------------
+
+    def for_handler(self, module: Module, handler: ast.AST, owner: Optional[ast.ClassDef] = None) -> Optional[Evidence]:
+        found = self.decorators(module, handler, handler_name=getattr(handler, "name", ""))
+        if found is None and owner is not None:
+            found = self.decorators(module, owner, handler_name=getattr(handler, "name", ""), rule="class decorator")
+        if found is None and owner is not None:
+            found = self.method_names(module, owner)
+        if found is None:
+            found = self.branches(module, handler)
+        if found is None:
+            found = self.wrappers(module, handler, owner, DEPTH, set())
+        return found
+
+    def decorators(self, module: Module, node: ast.AST, handler_name: str = "", rule: str = "decorator") -> Optional[Evidence]:
+        for dec in getattr(node, "decorator_list", []) or []:
+            inner = dec
+            # ``method_decorator(require_POST)`` on a method, or on the class
+            # with ``name=`` saying which method; ``dispatch`` means every one.
+            if isinstance(inner, ast.Call) and dotted(inner.func).split(".")[-1] == "method_decorator" and inner.args:
+                applies_to = const_str(keyword(inner, "name"))
+                if rule == "class decorator" and applies_to not in ("", "dispatch", handler_name):
+                    continue
+                inner = inner.args[0]
+            verbs = listed_verbs(inner)
+            if verbs:
+                return Evidence(verbs, rule, module.where(dec))
+        return None
+
+    def method_names(self, module: Module, owner: ast.ClassDef) -> Optional[Evidence]:
+        for stmt in owner.body:
+            if not isinstance(stmt, (ast.Assign, ast.AnnAssign)):
+                continue
+            targets = stmt.targets if isinstance(stmt, ast.Assign) else [stmt.target]
+            if not any(isinstance(target, ast.Name) and target.id == "http_method_names" for target in targets):
+                continue
+            verbs = verbs_in(stmt.value)
+            if verbs:
+                return Evidence(verbs, "http_method_names", module.where(stmt))
+        return None
+
+    def branches(self, module: Module, node: ast.AST) -> Optional[Evidence]:
+        found: List[str] = []
+        where = ""
+        for compare in ast.walk(node):
+            if not isinstance(compare, ast.Compare):
+                continue
+            sides = [compare.left] + list(compare.comparators)
+            if not any(is_request_method(side) for side in sides):
+                continue
+            for side in sides:
+                for verb in verbs_in(side, filter_implicit=False):
+                    if verb not in found:
+                        found.append(verb)
+                        where = where or module.where(compare)
+        verbs = normalise(found)
+        return Evidence(verbs, "request.method", where) if verbs else None
+
+    def wrappers(self, module: Module, handler: ast.AST, owner: Optional[ast.ClassDef], depth: int, seen: Set[Tuple[str, str]]) -> Optional[Evidence]:
+        if depth <= 0 or self.project is None:
+            return None
+        candidates: List[Tuple[Module, ast.AST, Optional[ast.ClassDef], str]] = []
+        for dec in getattr(handler, "decorator_list", []) or []:
+            target = dec.func if isinstance(dec, ast.Call) else dec
+            resolved = self.callable_target(module, owner, target)
+            if resolved is not None:
+                candidates.append(resolved + (dotted(target),))
+        for call in ast.walk(handler):
+            if not isinstance(call, ast.Call) or not passes_request(call):
+                continue
+            resolved = self.callable_target(module, owner, call.func)
+            if resolved is not None:
+                candidates.append(resolved + (dotted(call.func),))
+        for target_module, target, target_owner, name in candidates:
+            key = (target_module.dotted, node_name(target) if not target_owner else target_owner.name + "." + node_name(target))
+            if key in seen:
+                continue
+            seen.add(key)
+            found = self.decorators(target_module, target) or self.calls(target_module, target) or self.branches(target_module, target)
+            if found is None:
+                found = self.wrappers(target_module, target, target_owner, depth - 1, seen)
+            if found is not None:
+                return Evidence(found.verbs, "wrapper %s" % name, found.source)
+        return None
+
+    def calls(self, module: Module, node: ast.AST) -> Optional[Evidence]:
+        """``return require_POST(view)`` inside a project decorator: the
+        framework decorator applied by hand rather than with ``@``."""
+        for call in ast.walk(node):
+            if not isinstance(call, ast.Call):
+                continue
+            for candidate in (call, call.func):
+                verbs = listed_verbs(candidate)
+                if verbs:
+                    return Evidence(verbs, "decorator", module.where(call))
+        return None
+
+    # --- names ---------------------------------------------------------------
+
+    def callable_target(self, module: Module, owner: Optional[ast.ClassDef], node: ast.AST) -> Optional[Tuple[Module, ast.AST, Optional[ast.ClassDef]]]:
+        """A project function or method this name refers to; nothing for a
+        framework name, a builtin or anything the imports do not explain."""
+        name = dotted(node)
+        if not name or self.project is None:
+            return None
+        parts = name.split(".")
+        if len(parts) == 2 and parts[0] in ("self", "cls") and owner is not None:
+            for item in methods(owner):
+                if item.name == parts[1]:
+                    return module, item, owner
+            return None
+        if len(parts) == 1:
+            hit = self.project.resolve(module, name)
+            if hit is None:
+                return None
+            target = function_in(hit[0], hit[1])
+            return (hit[0], target, None) if target is not None else None
+        imported = module.imports.get(parts[0])
+        if imported is None:
+            return None
+        target_module = self.project.module(".".join([imported.module] + ([] if imported.name == "*" else [imported.name]) + parts[1:-1]))
+        if target_module is None:
+            return None
+        target = function_in(target_module, parts[-1])
+        return (target_module, target, None) if target is not None else None
+
+
+def function_in(module: Module, name: str) -> Optional[ast.AST]:
+    for node in module.tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == name:
+            return node
+    return None
+
+
+def listed_verbs(node: ast.AST) -> Tuple[str, ...]:
+    """The verbs a framework decorator names, however it was imported:
+    ``@require_http_methods(["GET", "POST"])``, ``@action(methods=["post"])``,
+    ``@api_view(["GET"])``, or the ``require_POST`` shorthand."""
+    name = dotted(node.func if isinstance(node, ast.Call) else node).split(".")[-1]
+    if name in SHORTHAND:
+        return SHORTHAND[name]
+    if not isinstance(node, ast.Call) or name not in LISTED:
+        return ()
+    listed = keyword(node, "methods") or keyword(node, "request_method_list") or keyword(node, "http_method_names")
+    if listed is None and node.args:
+        listed = node.args[0]
+    if listed is None and name in ("action", "api_view"):
+        # DRF's documented default when the decorator names no methods.
+        return ("GET",)
+    return verbs_in(listed)
+
+
+def verbs_in(node: Optional[ast.AST], filter_implicit: bool = True) -> Tuple[str, ...]:
+    """The HTTP verbs a literal spells, upper-cased; anything that is not one
+    is left out, so ``["get", "frobnicate"]`` reads as GET alone."""
+    if node is None:
+        return ()
+    items = node.elts if isinstance(node, (ast.List, ast.Tuple, ast.Set)) else [node]
+    found = [const_str(item).upper() for item in items if const_str(item)]
+    return normalise(found) if filter_implicit else tuple(verb for verb in found if verb in HTTP_VERBS)
+
+
+def normalise(found: List[str]) -> Tuple[str, ...]:
+    verbs = [verb for verb in found if verb in HTTP_VERBS]
+    explicit = [verb for verb in verbs if verb not in IMPLICIT]
+    out: List[str] = []
+    for verb in explicit or verbs:
+        if verb not in out:
+            out.append(verb)
+    return tuple(out)
+
+
+def is_request_method(node: ast.AST) -> bool:
+    """``request.method``, ``self.request.method``, or either through
+    ``.upper()``/``.lower()``."""
+    if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr in ("upper", "lower") and not node.args:
+        node = node.func.value
+    return dotted(node).endswith("request.method")
+
+
+def passes_request(call: ast.Call) -> bool:
+    values = list(call.args) + [kw.value for kw in call.keywords]
+    return any(dotted(value) in ("request", "self.request") for value in values)