nautobot 2.4.4__py3-none-any.whl → 2.4.6__py3-none-any.whl

nautobot/ipam/utils/testing.py

@@ -0,0 +1,177 @@
+"""Utilities for testing IPAM functionality, including data migrations."""
+
+import random
+
+from django.apps import apps
+from netaddr import IPNetwork
+
+# Calculate the probabilities to use for the maybe_subdivide() function defined below.
+
+# Frequency of IPv4 (leaf, network) Prefixes by each given mask length in a "realistic" data set.
+# Based loosely on a survey of one large real-world deployment's IP space usage
+FREQUENCY_BY_MASK_LENGTH = [
+    0,  # /0
+    0,
+    0,
+    0,
+    0,  # /4
+    0,
+    0,
+    0,
+    0,  # /8
+    0,
+    0,
+    0,
+    0,  # /12
+    1,
+    2,
+    4,
+    16,  # /16
+    8,
+    12,
+    16,
+    20,  # /20
+    120,
+    150,
+    400,
+    5000,  # /24
+    13000,
+    16000,
+    19000,
+    17000,  # /28
+    16000,
+    32000,
+    4000,
+    1200,  # /32
+]
+
+# Amount of IP space needed at each mask length (frequency at this length, plus the rollup of subdivided nets)
+#   Start calculation from the /32 frequency:
+CUMULATIVE_BY_MASK_LENGTH = [FREQUENCY_BY_MASK_LENGTH[-1]]
+#   Then work backwards to each parent mask length
+for mask_len in range(len(FREQUENCY_BY_MASK_LENGTH) - 2, -1, -1):  # 31, ... 0
+    CUMULATIVE_BY_MASK_LENGTH.append(CUMULATIVE_BY_MASK_LENGTH[-1] // 2 + FREQUENCY_BY_MASK_LENGTH[mask_len])
+#   Reverse the list to get order by ascending prefix length, same as FREQUENCY_BY_MASK_LENGTH
+CUMULATIVE_BY_MASK_LENGTH.reverse()
+
+# Chance to stop subdividing at any given prefix length and create a network Prefix with this length
+CHANCE_TO_STOP = [
+    0 if not cumulative else frequency / cumulative
+    for frequency, cumulative in zip(FREQUENCY_BY_MASK_LENGTH, CUMULATIVE_BY_MASK_LENGTH)
+]
+
+
+def maybe_subdivide(network):
+    """
+    Generator for recursively and probabilistically subdividing a network into subnets.
+
+    Yields:
+        IPNetwork: each constructed subdivision of the given network
+    """
+    if random.random() < CHANCE_TO_STOP[network.prefixlen]:  # noqa: S311  # suspicious-non-cryptographic-random-usage
+        # Do not subdivide any further
+        yield network
+    else:
+        # Split it into its two child networks and recurse
+        subnets = network.subnet(network.prefixlen + 1)
+        for subnet in subnets:
+            yield from maybe_subdivide(subnet)
+
+
+def maybe_random_instance(queryset, chance_of_none=0.75):
+    """
+    Helper function - randomly return either a random instance of the given queryset or None.
+    """
+    if random.random() < chance_of_none:  # noqa: S311  # suspicious-non-cryptographic-random-usage
+        return None
+    return random.choice(queryset)  # noqa: S311  # suspicious-non-cryptographic-random-usage
+
+
+def create_prefixes_and_ips(initial_subnet: str, apps=apps, seed="Nautobot"):  # pylint: disable=redefined-outer-name
+    """
+    Create many (Nautobot 1.x) Prefix and IPAddress records under a given initial_subnet.
+
+    The specific records created are pseudo-random (consistent for any given `initial_subnet` and `seed` values),
+    but will *in general* consist of about 95% coverage of the subnet by non-overlapping Prefix partitions and about
+    5% coverage of the subnet by individual IPAddress records. Additionally, about 10% of Prefixes and IPAddresses
+    respectively will be duplicated one or more times.
+
+    Args:
+        initial_subnet (str): The parent subnet ("10.0.0.0/16") that will encompass the Prefix and IPAddress records.
+        apps: Django application registry containing definitions of the (historical) Prefix, IPAddress, etc. models.
+        seed: Random generator seed to ensure reproducible pseudo-random construction of the data.
+    """
+    IPAddress = apps.get_model("ipam", "IPAddress")
+    Prefix = apps.get_model("ipam", "Prefix")
+    Status = apps.get_model("extras", "Status")
+    Tenant = apps.get_model("tenancy", "Tenant")
+    VRF = apps.get_model("ipam", "VRF")
+
+    print(f"Seeding the PRNG with seed {seed}")
+    random.seed(seed)  # suspicious-non-cryptographic-random-usage
+
+    status_active, _ = Status.objects.get_or_create(name="Active", defaults={"slug": "active"})
+
+    for i in range(1, 11):
+        Tenant.objects.create(name=f"{initial_subnet} Tenant {i}")
+        VRF.objects.create(name=f"{initial_subnet} VRF {i}", enforce_unique=False)  # TODO should some enforce_unique?
+
+    all_tenants = list(Tenant.objects.all())
+    all_vrfs = list(VRF.objects.all())
+
+    print(f"Creating Prefixes to subdivide {initial_subnet}")
+    unique_prefix_count = 0
+    duplicate_prefix_count = 0
+    for subnet in maybe_subdivide(IPNetwork(initial_subnet)):
+        if random.random() < 0.95:  # noqa: S311  # suspicious-non-cryptographic-random-usage
+            # 95% chance to create any given Prefix
+            Prefix.objects.create(
+                network=str(subnet.network),
+                broadcast=str(subnet.broadcast if subnet.broadcast else subnet[-1]),
+                prefix_length=subnet.prefixlen,
+                status=status_active,
+                tenant=maybe_random_instance(all_tenants),
+                vrf=maybe_random_instance(all_vrfs),
+            )
+            unique_prefix_count += 1
+            while random.random() < 0.1:  # noqa: S311  # suspicious-non-cryptographic-random-usage
+                # 10% repeating chance to create a duplicate(s) of this Prefix
+                Prefix.objects.create(
+                    network=str(subnet.network),
+                    broadcast=str(subnet.broadcast if subnet.broadcast else subnet[-1]),
+                    prefix_length=subnet.prefixlen,
+                    status=status_active,
+                    tenant=maybe_random_instance(all_tenants),
+                    vrf=maybe_random_instance(all_vrfs),
+                )
+                duplicate_prefix_count += 1
+    print(f"Created {unique_prefix_count} unique Prefixes and {duplicate_prefix_count} duplicates")
+
+    print(f"Creating IPAddresses within {initial_subnet}")
+    unique_ip_count = 0
+    duplicate_ip_count = 0
+    for ip in IPNetwork(initial_subnet):
+        if random.random() < 0.05:  # noqa: S311  # suspicious-non-cryptographic-random-usage
+            # 5% chance to create any given IP address
+            network = IPNetwork(ip)
+            IPAddress.objects.create(
+                host=str(network.ip),
+                broadcast=str(network.broadcast if network.broadcast else network[-1]),
+                prefix_length=network.prefixlen,
+                status=status_active,
+                tenant=maybe_random_instance(all_tenants),
+                vrf=maybe_random_instance(all_vrfs),
+            )
+            unique_ip_count += 1
+            while random.random() < 0.1:  # noqa: S311  # suspicious-non-cryptographic-random-usage
+                # 10% repeating chance to create a duplicate(s) of this IP
+                IPAddress.objects.create(
+                    host=str(network.ip),
+                    broadcast=str(network.broadcast if network.broadcast else network[-1]),
+                    prefix_length=network.prefixlen,
+                    status=status_active,
+                    tenant=maybe_random_instance(all_tenants),
+                    vrf=maybe_random_instance(all_vrfs),
+                )
+                duplicate_ip_count += 1
+    print(f"Created {unique_ip_count} unique IPAddresses and {duplicate_ip_count} duplicates")

nautobot/ipam/views.py

@@ -16,6 +16,8 @@ from django.utils.http import urlencode
 from django.views.generic import View
 from django_tables2 import RequestConfig
 import netaddr
+from rest_framework.decorators import action
+from rest_framework.response import Response
 
 from nautobot.cloud.tables import CloudNetworkTable
 from nautobot.core.constants import MAX_PAGE_SIZE_DEFAULT
@@ -63,27 +65,7 @@ logger = logging.getLogger(__name__)
 #
 
 
-def get_namespace_related_counts(instance, request):
-    """Return counts of all IPAM objects related to the given Namespace."""
-    return {
-        "vrf_count": instance.vrfs.restrict(request.user, "view").count(),
-        "prefix_count": instance.prefixes.restrict(request.user, "view").count(),
-        "ip_address_count": instance.ip_addresses.restrict(request.user, "view").count(),
-    }
-
-
-class NamespaceUIViewSet(
-    view_mixins.ObjectDetailViewMixin,
-    view_mixins.ObjectListViewMixin,
-    view_mixins.ObjectEditViewMixin,
-    view_mixins.ObjectDestroyViewMixin,
-    view_mixins.ObjectChangeLogViewMixin,
-    view_mixins.ObjectBulkCreateViewMixin,  # 3.0 TODO: remove, no longer used
-    view_mixins.ObjectBulkDestroyViewMixin,
-    view_mixins.ObjectBulkUpdateViewMixin,
-    view_mixins.ObjectNotesViewMixin,
-):
-    lookup_field = "pk"
+class NamespaceUIViewSet(NautobotUIViewSet):
     form_class = forms.NamespaceForm
     bulk_update_form_class = forms.NamespaceBulkEditForm
     filterset_class = filters.NamespaceFilterSet
@@ -91,134 +73,95 @@ class NamespaceUIViewSet(
     queryset = Namespace.objects.all()
     serializer_class = serializers.NamespaceSerializer
     table_class = tables.NamespaceTable
+    object_detail_content = object_detail.ObjectDetailContent(
+        panels=(object_detail.ObjectFieldsPanel(section=SectionChoices.LEFT_HALF, weight=100, fields="__all__"),),
+        extra_tabs=(
+            object_detail.DistinctViewTab(
+                weight=800,
+                tab_id="vrfs",
+                label="VRFs",
+                url_name="ipam:namespace_vrfs",
+                related_object_attribute="vrfs",
+            ),
+            object_detail.DistinctViewTab(
+                weight=900,
+                tab_id="prefixes",
+                label="Prefixes",
+                url_name="ipam:namespace_prefixes",
+                related_object_attribute="prefixes",
+            ),
+            object_detail.DistinctViewTab(
+                weight=1000,
+                tab_id="ip_addresses",
+                label="IP Addresses",
+                url_name="ipam:namespace_ip_addresses",
+                related_object_attribute="ip_addresses",
+            ),
+        ),
+    )
 
     def get_extra_context(self, request, instance):
         context = super().get_extra_context(request, instance)
-
-        if self.action == "retrieve":
-            context.update(get_namespace_related_counts(instance, request))
-
+        context.update({"object_detail_content": self.object_detail_content})
         return context
 
+    @action(detail=True, url_path="vrfs")
+    def vrfs(self, request, *args, **kwargs):
+        instance = self.get_object()
+        vrfs = instance.vrfs.restrict(request.user, "view")
+        vrf_table = tables.VRFTable(
+            data=vrfs,
+            user=request.user,
+            exclude=["namespace"],
+        )
+        if request.user.has_perm("ipam.change_vrf") or request.user.has_perm("ipam.delete_vrf"):
+            vrf_table.columns.show("pk")
 
-class NamespaceIPAddressesView(generic.ObjectView):
-    queryset = Namespace.objects.all()
-    template_name = "ipam/namespace_ipaddresses.html"
-
-    def get_extra_context(self, request, instance):
-        # Find all IPAddresses belonging to this Namespace
-        ip_addresses = instance.ip_addresses.restrict(request.user, "view").select_related("role", "status", "tenant")
-
-        ip_address_table = tables.IPAddressTable(ip_addresses, exclude=["namespace"])
-        if request.user.has_perm("ipam.change_ipaddress") or request.user.has_perm("ipam.delete_ipaddress"):
-            ip_address_table.columns.show("pk")
-
-        paginate = {
-            "paginator_class": EnhancedPaginator,
-            "per_page": get_paginate_count(request),
-        }
-        RequestConfig(request, paginate).configure(ip_address_table)
-
-        # Compile permissions list for rendering the object table
-        permissions = {
-            "add": request.user.has_perm("ipam.add_ipaddress"),
-            "change": request.user.has_perm("ipam.change_ipaddress"),
-            "delete": request.user.has_perm("ipam.delete_ipaddress"),
-        }
-        bulk_querystring = f"namespace={instance.id}"
-
-        context = super().get_extra_context(request, instance)
-        context.update(
+        RequestConfig(
+            request, paginate={"paginator_class": EnhancedPaginator, "per_page": get_paginate_count(request)}
+        ).configure(vrf_table)
+        return Response(
             {
-                "ip_address_table": ip_address_table,
-                "permissions": permissions,
-                "bulk_querystring": bulk_querystring,
-                "active_tab": "ip-addresses",
+                "vrf_table": vrf_table,
+                "active_tab": "vrfs",
             }
         )
-        context.update(get_namespace_related_counts(instance, request))
 
-        return context
-
-
-class NamespacePrefixesView(generic.ObjectView):
-    queryset = Namespace.objects.all()
-    template_name = "ipam/namespace_prefixes.html"
-
-    def get_extra_context(self, request, instance):
-        # Find all Prefixes belonging to this Namespace
+    @action(detail=True, url_path="prefixes")
+    def prefixes(self, request, *args, **kwargs):
+        instance = self.get_object()
         prefixes = instance.prefixes.restrict(request.user, "view").select_related("status")
-
-        prefix_table = tables.PrefixTable(prefixes, exclude=["namespace"])
+        prefix_table = tables.PrefixTable(data=prefixes, user=request.user, exclude=["namespace"])
         if request.user.has_perm("ipam.change_prefix") or request.user.has_perm("ipam.delete_prefix"):
             prefix_table.columns.show("pk")
 
-        paginate = {
-            "paginator_class": EnhancedPaginator,
-            "per_page": get_paginate_count(request),
-        }
-        RequestConfig(request, paginate).configure(prefix_table)
-
-        # Compile permissions list for rendering the object table
-        permissions = {
-            "add": request.user.has_perm("ipam.add_prefix"),
-            "change": request.user.has_perm("ipam.change_prefix"),
-            "delete": request.user.has_perm("ipam.delete_prefix"),
-        }
-        bulk_querystring = f"namespace={instance.id}"
-
-        context = super().get_extra_context(request, instance)
-        context.update(
+        RequestConfig(
+            request, paginate={"paginator_class": EnhancedPaginator, "per_page": get_paginate_count(request)}
+        ).configure(prefix_table)
+        return Response(
             {
                 "prefix_table": prefix_table,
-                "permissions": permissions,
-                "bulk_querystring": bulk_querystring,
                 "active_tab": "prefixes",
             }
         )
-        context.update(get_namespace_related_counts(instance, request))
-
-        return context
-
-
-class NamespaceVRFsView(generic.ObjectView):
-    queryset = Namespace.objects.all()
-    template_name = "ipam/namespace_vrfs.html"
-
-    def get_extra_context(self, request, instance):
-        # Find all VRFs belonging to this Namespace
-        vrfs = instance.vrfs.restrict(request.user, "view")
-
-        vrf_table = tables.VRFTable(vrfs, exclude=["namespace"])
-        if request.user.has_perm("ipam.change_vrf") or request.user.has_perm("ipam.delete_vrf"):
-            vrf_table.columns.show("pk")
-
-        paginate = {
-            "paginator_class": EnhancedPaginator,
-            "per_page": get_paginate_count(request),
-        }
-        RequestConfig(request, paginate).configure(vrf_table)
 
-        # Compile permissions list for rendering the object table
-        permissions = {
-            "add": request.user.has_perm("ipam.add_vrf"),
-            "change": request.user.has_perm("ipam.change_vrf"),
-            "delete": request.user.has_perm("ipam.delete_vrf"),
-        }
-        bulk_querystring = f"namespace={instance.id}"
+    @action(detail=True, url_path="ip-addresses", url_name="ip_addresses")
+    def ip_addresses(self, request, *args, **kwargs):
+        instance = self.get_object()
+        ip_addresses = instance.ip_addresses.restrict(request.user, "view").select_related("role", "status", "tenant")
+        ip_address_table = tables.IPAddressTable(data=ip_addresses, user=request.user, exclude=["namespace"])
+        if request.user.has_perm("ipam.change_ipaddress") or request.user.has_perm("ipam.delete_ipaddress"):
+            ip_address_table.columns.show("pk")
 
-        context = super().get_extra_context(request, instance)
-        context.update(
+        RequestConfig(
+            request, paginate={"paginator_class": EnhancedPaginator, "per_page": get_paginate_count(request)}
+        ).configure(ip_address_table)
+        return Response(
             {
-                "vrf_table": vrf_table,
-                "permissions": permissions,
-                "bulk_querystring": bulk_querystring,
-                "active_tab": "vrfs",
+                "ip_address_table": ip_address_table,
+                "active_tab": "ip_addresses",
             }
         )
-        context.update(get_namespace_related_counts(instance, request))
-
-        return context
 
 
 #
@@ -325,49 +268,32 @@ class RouteTargetUIViewSet(NautobotUIViewSet):
 #
 
 
-class RIRListView(generic.ObjectListView):
-    queryset = RIR.objects.all()
-    filterset = filters.RIRFilterSet
-    filterset_form = forms.RIRFilterForm
-    table = tables.RIRTable
-
-
-class RIRView(generic.ObjectView):
-    queryset = RIR.objects.all()
-
-    def get_extra_context(self, request, instance):
-        # Prefixes
-        assigned_prefixes = Prefix.objects.restrict(request.user, "view").filter(rir=instance).select_related("tenant")
-
-        assigned_prefix_table = tables.PrefixTable(assigned_prefixes, hide_hierarchy_ui=True)
-
-        paginate = {
-            "paginator_class": EnhancedPaginator,
-            "per_page": get_paginate_count(request),
-        }
-        RequestConfig(request, paginate).configure(assigned_prefix_table)
-
-        return {"assigned_prefix_table": assigned_prefix_table, **super().get_extra_context(request, instance)}
-
-
-class RIREditView(generic.ObjectEditView):
+class RIRUIViewSet(NautobotUIViewSet):
+    bulk_update_form_class = forms.RIRBulkEditForm
+    filterset_class = filters.RIRFilterSet
+    filterset_form_class = forms.RIRFilterForm
+    form_class = forms.RIRForm
     queryset = RIR.objects.all()
-    model_form = forms.RIRForm
-
+    serializer_class = serializers.RIRSerializer
+    table_class = tables.RIRTable
 
-class RIRDeleteView(generic.ObjectDeleteView):
-    queryset = RIR.objects.all()
-
-
-class RIRBulkImportView(generic.BulkImportView):  # 3.0 TODO: remove, unused
-    queryset = RIR.objects.all()
-    table = tables.RIRTable
-
-
-class RIRBulkDeleteView(generic.BulkDeleteView):
-    queryset = RIR.objects.all()
-    filterset = filters.RIRFilterSet
-    table = tables.RIRTable
+    object_detail_content = object_detail.ObjectDetailContent(
+        panels=(
+            object_detail.ObjectFieldsPanel(
+                section=SectionChoices.LEFT_HALF,
+                weight=100,
+                fields="__all__",
+            ),
+            object_detail.ObjectsTablePanel(
+                section=SectionChoices.FULL_WIDTH,
+                weight=100,
+                table_title="Assigned Prefixes",
+                table_class=tables.PrefixTable,
+                table_filter="rir",
+                hide_hierarchy_ui=True,
+            ),
+        ),
+    )
 
 
 #
@@ -1373,19 +1299,7 @@ class VLANBulkDeleteView(generic.BulkDeleteView):
 #
 
 
-class ServiceListView(generic.ObjectListView):
-    queryset = Service.objects.all()
-    filterset = filters.ServiceFilterSet
-    filterset_form = forms.ServiceFilterForm
-    table = tables.ServiceTable
-    action_buttons = ("add", "import", "export")
-
-
-class ServiceView(generic.ObjectView):
-    queryset = Service.objects.prefetch_related("ip_addresses")
-
-
-class ServiceEditView(generic.ObjectEditView):
+class ServiceEditView(generic.ObjectEditView):  # This view is used to assign services to devices and VMs
     queryset = Service.objects.prefetch_related("ip_addresses")
     model_form = forms.ServiceForm
     template_name = "ipam/service_edit.html"
@@ -1401,23 +1315,30 @@ class ServiceEditView(generic.ObjectEditView):
         return obj
 
 
-class ServiceBulkImportView(generic.BulkImportView):  # 3.0 TODO: remove, unused
-    queryset = Service.objects.all()
-    table = tables.ServiceTable
+class ServiceUIViewSet(NautobotUIViewSet):  # 3.0 TODO: remove, unused BulkImportView
+    model = Service
+    bulk_update_form_class = forms.ServiceBulkEditForm
+    filterset_class = filters.ServiceFilterSet
+    filterset_form_class = forms.ServiceFilterForm
+    form_class = forms.ServiceForm
+    queryset = Service.objects.select_related("device", "virtual_machine").prefetch_related("ip_addresses")
+    serializer_class = serializers.ServiceSerializer
+    table_class = tables.ServiceTable
 
-
-class ServiceDeleteView(generic.ObjectDeleteView):
-    queryset = Service.objects.all()
-
-
-class ServiceBulkEditView(generic.BulkEditView):
-    queryset = Service.objects.select_related("device", "virtual_machine")
-    filterset = filters.ServiceFilterSet
-    table = tables.ServiceTable
-    form = forms.ServiceBulkEditForm
-
-
-class ServiceBulkDeleteView(generic.BulkDeleteView):
-    queryset = Service.objects.select_related("device", "virtual_machine")
-    filterset = filters.ServiceFilterSet
-    table = tables.ServiceTable
+    object_detail_content = object_detail.ObjectDetailContent(
+        panels=(
+            object_detail.ObjectFieldsPanel(
+                section=SectionChoices.LEFT_HALF,
+                weight=100,
+                fields=["name", "parent", "protocol", "port_list", "description"],
+            ),
+            object_detail.ObjectsTablePanel(
+                weight=200,
+                section=SectionChoices.RIGHT_HALF,
+                table_class=tables.IPAddressTable,
+                table_filter="services",
+                select_related_fields=["tenant", "status", "role"],
+                add_button_route=None,
+            ),
+        )
+    )

nautobot/project-static/docs/code-reference/nautobot/apps/jobs.html

@@ -7419,6 +7419,15 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#nautobot.apps.jobs.BaseJob.fail" class="md-nav__link">
+    <span class="md-ellipsis">
+      fail
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -9776,6 +9785,15 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#nautobot.apps.jobs.BaseJob.fail" class="md-nav__link">
+    <span class="md-ellipsis">
+      fail
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -10624,11 +10642,13 @@ during a approval review workflow.</p>
       <tbody>
           <tr class="doc-section-item">
             <td>
-                  <code>None</code>
+                  <code>Any</code>
             </td>
             <td>
               <div class="doc-md-description">
-                <p>The return value of this handler is ignored.</p>
+                <p>The return value of this handler is ignored normally, <strong>except</strong> if <code>self.fail()</code> is called herein,
+in which case the return value will be used as the overall JobResult return value
+since <code>self.run()</code> will <strong>not</strong> be called in such a case.</p>
               </div>
             </td>
           </tr>
@@ -10835,6 +10855,23 @@ path would consider this a failure of the job execution, as described in <code>n
 <div class="doc doc-object doc-function">
 
 
+<h3 id="nautobot.apps.jobs.BaseJob.fail" class="doc doc-heading">
+            <code class="highlight language-python"><span class="n">fail</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span></code>
+
+<a href="#nautobot.apps.jobs.BaseJob.fail" class="headerlink" title="Permanent link">&para;</a></h3>
+
+
+    <div class="doc doc-contents ">
+
+        <p>Mark this job as failed without immediately raising an exception and aborting.</p>
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
 <h3 id="nautobot.apps.jobs.BaseJob.file_path" class="doc doc-heading">
             <code class="highlight language-python"><span class="n">file_path</span><span class="p">()</span></code>
 
@@ -10914,11 +10951,12 @@ path would consider this a failure of the job execution, as described in <code>n
                 <code>exc</code>
             </td>
             <td>
-                  <code>Exception</code>
+                  <code>Any</code>
             </td>
             <td>
               <div class="doc-md-description">
-                <p>The exception raised by the task.</p>
+                <p>Exception raised by the task (if any) <strong>or</strong> return value from the task, if it failed cleanly,
+such as if the Job called <code>self.fail()</code> rather than raising an exception.</p>
               </div>
             </td>
             <td>
@@ -10982,7 +11020,7 @@ path would consider this a failure of the job execution, as described in <code>n
             </td>
             <td>
               <div class="doc-md-description">
-                <p>Exception information.</p>
+                <p>Exception information, or None.</p>
               </div>
             </td>
             <td>