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

nautobot/extras/tests/test_relationships.py

@@ -1784,7 +1784,7 @@ class RelationshipJobTestCase(RequiredRelationshipTestMixin, TransactionTestCase
 
         pk_list = [str(vlan.id) for vlan in vlans]
         job_result = self.create_job(pk_list)
-        self.assertEqual(job_result.status, JobResultStatusChoices.STATUS_FAILURE)
+        self.assertJobResultStatus(job_result, JobResultStatusChoices.STATUS_FAILURE)
         error_log = JobLogEntry.objects.get(job_result=job_result, log_level=LogLevelChoices.LOG_ERROR)
         self.assertIn("VLANs require at least one device, but no devices exist yet.", error_log.message)
 
@@ -1793,7 +1793,7 @@ class RelationshipJobTestCase(RequiredRelationshipTestMixin, TransactionTestCase
 
         # Try editing all 6 VLANs without adding the required device(fails):
         job_result = self.create_job(pk_list)
-        self.assertEqual(job_result.status, JobResultStatusChoices.STATUS_FAILURE)
+        self.assertJobResultStatus(job_result, JobResultStatusChoices.STATUS_FAILURE)
         error_log = JobLogEntry.objects.get(job_result=job_result, log_level=LogLevelChoices.LOG_ERROR)
         self.assertIn(
             '6 VLANs require a device for the required relationship \\"VLANs require at least one Device',
@@ -1802,7 +1802,7 @@ class RelationshipJobTestCase(RequiredRelationshipTestMixin, TransactionTestCase
 
         # Try editing 3 VLANs without adding the required device(fails):
         job_result = self.create_job(pk_list[:3])
-        self.assertEqual(job_result.status, JobResultStatusChoices.STATUS_FAILURE)
+        self.assertJobResultStatus(job_result, JobResultStatusChoices.STATUS_FAILURE)
         error_log = JobLogEntry.objects.get(job_result=job_result, log_level=LogLevelChoices.LOG_ERROR)
         self.assertIn(
             'These VLANs require a device for the required relationship \\"VLANs require at least one Device',
@@ -1813,11 +1813,11 @@ class RelationshipJobTestCase(RequiredRelationshipTestMixin, TransactionTestCase
 
         # Try editing 6 VLANs and adding the required device (succeeds):
         job_result = self.create_job(pk_list, add_cr_vlans_devices_m2m__source=[str(device_for_association.id)])
-        self.assertEqual(job_result.status, JobResultStatusChoices.STATUS_SUCCESS)
+        self.assertJobResultStatus(job_result)
 
         # Try editing 6 VLANs and removing the required device (fails):
         job_result = self.create_job(pk_list, remove_cr_vlans_devices_m2m__source=[str(device_for_association.id)])
-        self.assertEqual(job_result.status, JobResultStatusChoices.STATUS_FAILURE)
+        self.assertJobResultStatus(job_result, JobResultStatusChoices.STATUS_FAILURE)
         error_log = JobLogEntry.objects.get(job_result=job_result, log_level=LogLevelChoices.LOG_ERROR)
         self.assertIn(
             '6 VLANs require a device for the required relationship \\"VLANs require at least one Device',

nautobot/extras/views.py

@@ -2062,7 +2062,13 @@ def get_annotated_jobresult_queryset():
             error_log_count=count_related(
                 JobLogEntry,
                 "job_result",
-                filter_dict={"log_level__in": [LogLevelChoices.LOG_ERROR, LogLevelChoices.LOG_CRITICAL]},
+                filter_dict={
+                    "log_level__in": [
+                        LogLevelChoices.LOG_FAILURE,
+                        LogLevelChoices.LOG_ERROR,
+                        LogLevelChoices.LOG_CRITICAL,
+                    ],
+                },
             ),
         )
     )

nautobot/ipam/forms.py

@@ -262,6 +262,21 @@ class RIRFilterForm(NautobotFilterForm):
     )
 
 
+class RIRBulkEditForm(NautobotBulkEditForm):
+    pk = forms.ModelMultipleChoiceField(queryset=RIR.objects.all(), widget=forms.MultipleHiddenInput())
+    is_private = forms.NullBooleanField(
+        required=False,
+        label="Private",
+        widget=StaticSelect2(choices=BOOLEAN_WITH_BLANK_CHOICES),
+    )
+    description = forms.CharField(max_length=CHARFIELD_MAX_LENGTH, required=False)
+
+    class Meta:
+        nullable_fields = [
+            "description",
+        ]
+
+
 #
 # Prefixes
 #

nautobot/ipam/querysets.py

@@ -405,6 +405,12 @@ class IPAddressQuerySet(BaseNetworkQuerySet):
         namespace = kwargs.pop("namespace", None)
         host = kwargs.get("host")
         mask_length = kwargs.get("mask_length")
+        address = kwargs.get("address")
+        if host is None and address is not None:
+            address = netaddr.IPNetwork(address)
+            host = str(address.ip)
+            mask_length = address.prefixlen
+
         # If `host` or `mask_length` is None skip; then there is no way of getting the closest parent;
         if parent is None and host is not None and mask_length is not None:
             if namespace is None:

nautobot/ipam/templates/ipam/rir.html

@@ -1,44 +1,2 @@
 {% extends 'generic/object_retrieve.html' %}
-{% load helpers %}
-
-{% block content_left_page %}
-        <div class="panel panel-default">
-            <div class="panel-heading">
-                <strong>RIR</strong>
-            </div>
-            <table class="table table-hover panel-body attr-table">
-                <tr>
-                    <td>Description</td>
-                    <td>{{ object.description|placeholder }}</td>
-                </tr>
-                <tr>
-                    <td>Private</td>
-                    <td>{{ object.is_private | render_boolean }}</td>
-                </tr>
-                <tr>
-                    <td>Assigned Prefixes</td>
-                    <td>
-                        <a href="{% url 'ipam:prefix_list' %}?rir={{ object.name }}">{{ assigned_prefix_table.rows|length }}</a>
-                    </td>
-                </tr>
-            </table>
-        </div>
-{% endblock content_left_page %}
-
-{% block content_full_width_page %}
-        <div class="panel panel-default">
-            <div class="panel-heading">
-                <strong>Assigned Prefixes</strong>
-            </div>
-            {% include 'inc/table.html' with table=assigned_prefix_table %}
-            {% if perms.ipam.add_prefix %}
-                <div class="panel-footer text-right noprint">
-                    <a href="{% url 'ipam:prefix_add' %}?rir={{ object.pk }}" class="btn btn-xs btn-primary">
-                        <span class="mdi mdi-plus-thick" aria-hidden="true"></span> Add prefix
-                    </a>
-                </div>
-            {% endif %}
-        </div>
-        {% include 'inc/paginator.html' with paginator=assigned_prefix_table.paginator page=assigned_prefix_table.page %}
-        <div class="row"></div>
-{% endblock content_full_width_page %}
+{% comment %}3.0 TODO: remove this template, which only exists for backward compatibility with 2.4 and earlier{% endcomment %}

nautobot/ipam/tests/test_models.py

@@ -1301,6 +1301,22 @@ class TestIPAddress(ModelTestCases.BaseModelTestCase):
                 str(err.exception),
             )
 
+    def test_get_or_create_address_kwarg(self):
+        status = Status.objects.get(name="Active")
+        namespace = Namespace.objects.create(name="Test IPAddress get_or_create with address kwarg")
+        Prefix.objects.create(prefix="10.0.0.0/24", namespace=namespace, status=status)
+        ip_address, created = IPAddress.objects.get_or_create(
+            address="10.0.0.40/32", namespace=namespace, defaults={"status": status}
+        )
+        self.assertEqual(ip_address.host, "10.0.0.40")
+        self.assertEqual(ip_address.mask_length, 32)
+        self.assertTrue(created)
+        _, created = IPAddress.objects.get_or_create(
+            address="10.0.0.40/32", namespace=namespace, defaults={"status": status}
+        )
+        self.assertFalse(created)
+        self.assertTrue(IPAddress.objects.filter(address="10.0.0.40/32", parent__namespace=namespace).exists())
+
     def test_create_field_population(self):
         """Test that the various ways of creating an IPAddress result in correctly populated fields."""
         if self.namespace != get_default_namespace():

nautobot/ipam/urls.py

@@ -7,7 +7,6 @@ from . import views
 from .models import (
     IPAddress,
     Prefix,
-    RIR,
     Service,
     VLAN,
     VLANGroup,
@@ -20,28 +19,9 @@ router.register("ip-address-to-interface", views.IPAddressToInterfaceUIViewSet)
 router.register("namespaces", views.NamespaceUIViewSet)
 router.register("route-targets", views.RouteTargetUIViewSet)
 router.register("vrfs", views.VRFUIViewSet)
+router.register("rirs", views.RIRUIViewSet)
 
 urlpatterns = [
-    # RIRs
-    path("rirs/", views.RIRListView.as_view(), name="rir_list"),
-    path("rirs/add/", views.RIREditView.as_view(), name="rir_add"),
-    path("rirs/import/", views.RIRBulkImportView.as_view(), name="rir_import"),  # 3.0 TODO: remove, unused
-    path("rirs/delete/", views.RIRBulkDeleteView.as_view(), name="rir_bulk_delete"),
-    path("rirs/<uuid:pk>/", views.RIRView.as_view(), name="rir"),
-    path("rirs/<uuid:pk>/edit/", views.RIREditView.as_view(), name="rir_edit"),
-    path("rirs/<uuid:pk>/delete/", views.RIRDeleteView.as_view(), name="rir_delete"),
-    path(
-        "rirs/<uuid:pk>/changelog/",
-        ObjectChangeLogView.as_view(),
-        name="rir_changelog",
-        kwargs={"model": RIR},
-    ),
-    path(
-        "rirs/<uuid:pk>/notes/",
-        ObjectNotesView.as_view(),
-        name="rir_notes",
-        kwargs={"model": RIR},
-    ),
     # Namespaces
     path(
         "namespaces/<uuid:pk>/ip-addresses/",

nautobot/ipam/views.py

@@ -325,49 +325,32 @@ class RouteTargetUIViewSet(NautobotUIViewSet):
 #
 
 
-class RIRListView(generic.ObjectListView):
+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()
-    filterset = filters.RIRFilterSet
-    filterset_form = forms.RIRFilterForm
-    table = tables.RIRTable
+    serializer_class = serializers.RIRSerializer
+    table_class = 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):
-    queryset = RIR.objects.all()
-    model_form = forms.RIRForm
-
-
-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,
+            ),
+        ),
+    )
 
 
 #

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>

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

@@ -8238,6 +8238,15 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#nautobot.apps.testing.NautobotTestCaseMixin.assertJobResultStatus" class="md-nav__link">
+    <span class="md-ellipsis">
+      assertJobResultStatus
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -11423,6 +11432,15 @@
     </span>
   </a>
   
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#nautobot.apps.testing.NautobotTestCaseMixin.assertJobResultStatus" class="md-nav__link">
+    <span class="md-ellipsis">
+      assertJobResultStatus
+    </span>
+  </a>
+  
 </li>
         
           <li class="md-nav__item">
@@ -14322,6 +14340,23 @@ in the dictionary.</p>
 <div class="doc doc-object doc-function">
 
 
+<h3 id="nautobot.apps.testing.NautobotTestCaseMixin.assertJobResultStatus" class="doc doc-heading">
+            <code class="highlight language-python"><span class="n">assertJobResultStatus</span><span class="p">(</span><span class="n">job_result</span><span class="p">,</span> <span class="n">expected_status</span><span class="o">=</span><span class="n">JobResultStatusChoices</span><span class="o">.</span><span class="n">STATUS_SUCCESS</span><span class="p">)</span></code>
+
+<a href="#nautobot.apps.testing.NautobotTestCaseMixin.assertJobResultStatus" class="headerlink" title="Permanent link">&para;</a></h3>
+
+
+    <div class="doc doc-contents ">
+
+        <p>Assert that the given job_result has the expected_status, or print the job logs to aid in debugging.</p>
+
+    </div>
+
+</div>
+
+<div class="doc doc-object doc-function">
+
+
 <h3 id="nautobot.apps.testing.NautobotTestCaseMixin.assertQuerysetEqualAndNotEmpty" class="doc doc-heading">
             <code class="highlight language-python"><span class="n">assertQuerysetEqualAndNotEmpty</span><span class="p">(</span><span class="n">qs</span><span class="p">,</span> <span class="n">values</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>
 

nautobot/project-static/docs/development/jobs/index.html

@@ -9943,6 +9943,10 @@
 <td><a href="#dryrun_default">metadata property</a></td>
 </tr>
 <tr>
+<td><code>fail</code></td>
+<td><a href="#marking-a-job-as-failed">helper method</a></td>
+</tr>
+<tr>
 <td><code>file_path</code></td>
 <td>deprecated class property</td>
 </tr>
@@ -10367,7 +10371,7 @@ Another example of using the nested reference would be to access <a href="../../
 </details>
 <h4 id="the-before_start-method">The <code>before_start()</code> Method<a class="headerlink" href="#the-before_start-method" title="Permanent link">&para;</a></h4>
 <p>The <code>before_start()</code> method may optionally be implemented to perform any appropriate Job-specific setup before the <code>run()</code> method is called. It has the signature <code>before_start(self, task_id, args, kwargs)</code> for historical reasons; the <code>task_id</code> parameter will always be identical to <code>self.request.id</code>, the <code>args</code> parameter will generally be empty, and any user-specified variables passed into the Job execution will be present in the <code>kwargs</code> parameter.</p>
-<p>The return value from <code>before_start()</code> is ignored, but if it raises any exception, the Job execution will be marked as a failure and <code>run()</code> will not be called.</p>
+<p>The return value from <code>before_start()</code> is ignored, but if it raises any exception, the Job result status will be marked as <code>FAILURE</code> and <code>run()</code> will not be called.</p>
 <h4 id="the-run-method">The <code>run()</code> Method<a class="headerlink" href="#the-run-method" title="Permanent link">&para;</a></h4>
 <p>The <code>run()</code> method is the primary worker of any Job, and must be implemented. After the <code>self</code> argument, it should accept keyword arguments for any variables defined on the Job:</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-18-1" name="__codelineno-18-1" href="#__codelineno-18-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">StringVar</span><span class="p">,</span> <span class="n">IntegerVar</span><span class="p">,</span> <span class="n">ObjectVar</span>
@@ -10389,13 +10393,13 @@ Another example of using the nested reference would be to access <a href="../../
 <p class="admonition-title">Be cautious around bulk operations</p>
 <p>The Django ORM provides methods to create/edit many objects at once, namely <code>bulk_create()</code> and <code>update()</code>. These are best avoided in most cases as they bypass a model's built-in validation and can easily lead to database corruption if not used carefully.</p>
 </div>
-<p>If <code>run()</code> returns any value (even the implicit <code>None</code>), the Job execution will be marked as a success and the returned value will be stored in the associated JobResult database record. Conversely, if <code>run()</code> raises any exception, the Job execution will be marked as a failure and the traceback will be stored in the JobResult.</p>
+<p>If <code>run()</code> returns any value (even the implicit <code>None</code>), the returned value will be stored in the associated JobResult database record. (The Job Result will be marked as <code>SUCCESS</code> unless the <code>fail()</code> method was called at some point during <code>run()</code>, in which case it will be marked as <code>FAILURE</code>.) Conversely, if <code>run()</code> raises any exception, the Job execution will be marked as <code>FAILURE</code> and the traceback will be stored in the JobResult.</p>
 <h4 id="the-on_success-method">The <code>on_success()</code> Method<a class="headerlink" href="#the-on_success-method" title="Permanent link">&para;</a></h4>
 <p>If both <code>before_start()</code> and <code>run()</code> are successful, the <code>on_success()</code> method will be called next, if implemented. It has the signature <code>on_success(self, retval, task_id, args, kwargs)</code>; as with <code>before_start()</code> the <code>task_id</code> and <code>args</code> parameters can generally be ignored, while <code>retval</code> is the return value from <code>run()</code>, and <code>kwargs</code> will contain the user-specified variables passed into the Job execution.</p>
 <h4 id="the-on_failure-method">The <code>on_failure()</code> Method<a class="headerlink" href="#the-on_failure-method" title="Permanent link">&para;</a></h4>
-<p>If either <code>before_start()</code> or <code>run()</code> raises any unhandled exception, the <code>on_failure()</code> method will be called next, if implemented. It has the signature <code>on_failure(self, exc, task_id, args, kwargs, einfo)</code>; of these parameters, the <code>exc</code> will contain the exception that was raised, and <code>kwargs</code> will contain the user-specified variables passed into the Job.</p>
+<p>If either <code>before_start()</code> or <code>run()</code> raises any unhandled exception, or reports a failure overall through <code>fail()</code>, the <code>on_failure()</code> method will be called next, if implemented. It has the signature <code>on_failure(self, exc, task_id, args, kwargs, einfo)</code>; of these parameters, the <code>exc</code> will contain the exception that was raised (if any) or the return value from <code>before_start()</code> or <code>run()</code> (otherwise), and <code>kwargs</code> will contain the user-specified variables passed into the Job.</p>
 <h4 id="the-after_return-method">The <code>after_return()</code> Method<a class="headerlink" href="#the-after_return-method" title="Permanent link">&para;</a></h4>
-<p>Regardless of the overall Job execution success or failure, the <code>after_return()</code> method will be called after <code>on_success()</code> or <code>on_failure()</code>. It has the signature <code>after_return(self, status, retval, task_id, args, kwargs, einfo)</code>; the <code>status</code> will indicate success or failure (using the <code>JobResultStatusChoices</code> enum), <code>retval</code> is <em>either</em> the return value from <code>run()</code> (on success) or the exception raised (on failure), and once again <code>kwargs</code> contains the user variables.</p>
+<p>Regardless of the overall Job execution success or failure, the <code>after_return()</code> method will be called after <code>on_success()</code> or <code>on_failure()</code>. It has the signature <code>after_return(self, status, retval, task_id, args, kwargs, einfo)</code>; the <code>status</code> will indicate success or failure (using the <code>JobResultStatusChoices</code> enum), <code>retval</code> is <em>either</em> the return value from <code>run()</code> or the exception raised, and once again <code>kwargs</code> contains the user variables.</p>
 <h3 id="logging">Logging<a class="headerlink" href="#logging" title="Permanent link">&para;</a></h3>
 <details class="version-changed">
 <summary>Changed in version 2.0.0</summary>
@@ -10416,7 +10420,7 @@ Another example of using the nested reference would be to access <a href="../../
 <a id="__codelineno-19-2" name="__codelineno-19-2" href="#__codelineno-19-2"></a>
 <a id="__codelineno-19-3" name="__codelineno-19-3" href="#__codelineno-19-3"></a><span class="k">class</span> <span class="nc">MyJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
 <a id="__codelineno-19-4" name="__codelineno-19-4" href="#__codelineno-19-4"></a>    <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-19-5" name="__codelineno-19-5" href="#__codelineno-19-5"></a>        <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;This job is running!&quot;</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;grouping&quot;</span><span class="p">:</span> <span class="s2">&quot;myjobisrunning&quot;</span><span class="p">,</span> <span class="s2">&quot;object&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">job_result</span><span class="p">})</span>
+<a id="__codelineno-19-5" name="__codelineno-19-5" href="#__codelineno-19-5"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;This job is running!&quot;</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;grouping&quot;</span><span class="p">:</span> <span class="s2">&quot;myjobisrunning&quot;</span><span class="p">,</span> <span class="s2">&quot;object&quot;</span><span class="p">:</span> <span class="bp">self</span><span class="o">.</span><span class="n">job_result</span><span class="p">})</span>
 </code></pre></div>
 </div>
 <p>To skip writing a log entry to the database, set the <code>skip_db_logging</code> key in the "extra" kwarg to <code>True</code> when calling the log function. The output will still be written to the console.</p>
@@ -10427,7 +10431,7 @@ Another example of using the nested reference would be to access <a href="../../
 <a id="__codelineno-20-2" name="__codelineno-20-2" href="#__codelineno-20-2"></a>
 <a id="__codelineno-20-3" name="__codelineno-20-3" href="#__codelineno-20-3"></a><span class="k">class</span> <span class="nc">MyJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
 <a id="__codelineno-20-4" name="__codelineno-20-4" href="#__codelineno-20-4"></a>    <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-20-5" name="__codelineno-20-5" href="#__codelineno-20-5"></a>        <span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;This job is running!&quot;</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;skip_db_logging&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span>
+<a id="__codelineno-20-5" name="__codelineno-20-5" href="#__codelineno-20-5"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;This job is running!&quot;</span><span class="p">,</span> <span class="n">extra</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;skip_db_logging&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span>
 </code></pre></div>
 </div>
 <p>Markdown rendering is supported for log messages, as well as <a href="../../user-guide/platform-functionality/template-filters.html#render_markdown">a limited subset of HTML</a>.</p>
@@ -10444,8 +10448,12 @@ Another example of using the nested reference would be to access <a href="../../
 <p>The <code>AbortTransaction</code> class was moved from the <code>nautobot.utilities.exceptions</code> module to <code>nautobot.core.exceptions</code>. Jobs should generally import it from <code>nautobot.apps.exceptions</code> if needed.</p>
 </details>
 <details class="version-added">
-<summary>Added in version 2.4.0</summary>
-<p>You can now use <code>self.logger.success()</code> to set the log level to <code>SUCCESS</code>.</p>
+<summary>Added in version 2.4.0 — <code>logger.success()</code> added</summary>
+<p>You can now use <code>self.logger.success()</code> to log a message at the level <code>SUCCESS</code>, which is located between the standard <code>INFO</code> and <code>WARNING</code> log levels.</p>
+</details>
+<details class="version-added">
+<summary>Added in version 2.4.5 — <code>logger.failure()</code> added</summary>
+<p>You can now use <code>self.logger.failure()</code> to log a message at the level <code>FAILURE</code>, which is located between the standard <code>WARNING</code> and <code>ERROR</code> log levels.</p>
 </details>
 <h3 id="file-output">File Output<a class="headerlink" href="#file-output" title="Permanent link">&para;</a></h3>
 <details class="version-added">
@@ -10462,17 +10470,22 @@ Another example of using the nested reference would be to access <a href="../../
 <p>The above Job when run will create two files, "greeting.txt" and "farewell.txt", that will be made available for download from the JobResult detail view's "Advanced" tab and via the REST API. These files will persist indefinitely, but can automatically be deleted if the JobResult itself is deleted; they can also be deleted manually by an administrator via the "File Proxies" link in the Admin UI.</p>
 <p>The maximum size of any single created file (or in other words, the maximum number of bytes that can be passed to <code>self.create_file()</code>) is controlled by the <a href="../../user-guide/administration/configuration/settings.html#job_create_file_max_size"><code>JOB_CREATE_FILE_MAX_SIZE</code></a> system setting. A <code>ValueError</code> exception will be raised if <code>create_file()</code> is called with an overly large <code>content</code> value.</p>
 <h3 id="marking-a-job-as-failed">Marking a Job as Failed<a class="headerlink" href="#marking-a-job-as-failed" title="Permanent link">&para;</a></h3>
-<p>To mark a Job as failed, raise an exception from within the <code>run()</code> method. The exception message will be logged to the traceback of the Job Result. The Job Result status will be set to <code>failed</code>. To output a Job log message you can use the <code>self.logger.error()</code> method.</p>
-<p>As an example, the following Job will fail if the user does not put the word "Taco" in <code>var1</code>:</p>
+<p>Any uncaught exception raised from within the <code>run()</code> method will abort the <code>run()</code> method immediately (as usual in Python), and will result in the Job Result status being marked as <code>FAILURE</code>. The exception message and traceback will be recorded in the Job Result.</p>
+<p>Alternatively, in Nautobot v2.4.5 and later, you can more "cleanly" fail a Job by calling <code>self.fail(...)</code> and then either returning immediately from the <code>run()</code> method or continuing with the execution of the Job, as desired. In this case, after the <code>run()</code> method completes, the Job Result status will be automatically marked as <code>FAILURE</code> and no exception or traceback will be recorded.</p>
+<p>As an example, the following Job will abort if the user does not put the word "Taco" in <code>occasion</code>, and fail (but not abort) if the variable does not additionally contain "Tuesday":</p>
 <div class="highlight"><pre><span></span><code><a id="__codelineno-22-1" name="__codelineno-22-1" href="#__codelineno-22-1"></a><span class="kn">from</span> <span class="nn">nautobot.apps.jobs</span> <span class="kn">import</span> <span class="n">Job</span><span class="p">,</span> <span class="n">StringVar</span>
 <a id="__codelineno-22-2" name="__codelineno-22-2" href="#__codelineno-22-2"></a>
 <a id="__codelineno-22-3" name="__codelineno-22-3" href="#__codelineno-22-3"></a><span class="k">class</span> <span class="nc">MyJob</span><span class="p">(</span><span class="n">Job</span><span class="p">):</span>
-<a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a>    <span class="n">var1</span> <span class="o">=</span> <span class="n">StringVar</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
+<a id="__codelineno-22-4" name="__codelineno-22-4" href="#__codelineno-22-4"></a>    <span class="n">occasion</span> <span class="o">=</span> <span class="n">StringVar</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
 <a id="__codelineno-22-5" name="__codelineno-22-5" href="#__codelineno-22-5"></a>
-<a id="__codelineno-22-6" name="__codelineno-22-6" href="#__codelineno-22-6"></a>    <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">var1</span><span class="p">):</span>
-<a id="__codelineno-22-7" name="__codelineno-22-7" href="#__codelineno-22-7"></a>        <span class="k">if</span> <span class="n">var1</span> <span class="o">!=</span> <span class="s2">&quot;Taco&quot;</span><span class="p">:</span>
-<a id="__codelineno-22-8" name="__codelineno-22-8" href="#__codelineno-22-8"></a>            <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">&quot;var1 must be &#39;Taco&#39;&quot;</span><span class="p">)</span>
+<a id="__codelineno-22-6" name="__codelineno-22-6" href="#__codelineno-22-6"></a>    <span class="k">def</span> <span class="nf">run</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">occasion</span><span class="p">):</span>
+<a id="__codelineno-22-7" name="__codelineno-22-7" href="#__codelineno-22-7"></a>        <span class="k">if</span> <span class="ow">not</span> <span class="n">occasion</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">&quot;Taco&quot;</span><span class="p">):</span>
+<a id="__codelineno-22-8" name="__codelineno-22-8" href="#__codelineno-22-8"></a>            <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">failure</span><span class="p">(</span><span class="s2">&quot;The occasion must begin with &#39;Taco&#39;&quot;</span><span class="p">)</span>
 <a id="__codelineno-22-9" name="__codelineno-22-9" href="#__codelineno-22-9"></a>            <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s2">&quot;Argument input validation failed.&quot;</span><span class="p">)</span>
+<a id="__codelineno-22-10" name="__codelineno-22-10" href="#__codelineno-22-10"></a>        <span class="k">if</span> <span class="ow">not</span> <span class="n">occasion</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="s2">&quot; Tuesday&quot;</span><span class="p">):</span>
+<a id="__codelineno-22-11" name="__codelineno-22-11" href="#__codelineno-22-11"></a>            <span class="bp">self</span><span class="o">.</span><span class="n">fail</span><span class="p">(</span><span class="s2">&quot;It&#39;s supposed to be Tuesday&quot;</span><span class="p">)</span>
+<a id="__codelineno-22-12" name="__codelineno-22-12" href="#__codelineno-22-12"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">logger</span><span class="o">.</span><span class="n">info</span><span class="p">(</span><span class="s2">&quot;Today is </span><span class="si">%s</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">occasion</span><span class="p">)</span>
+<a id="__codelineno-22-13" name="__codelineno-22-13" href="#__codelineno-22-13"></a>        <span class="k">return</span> <span class="n">occasion</span>
 </code></pre></div>
 <h3 id="accessing-user-and-job-result">Accessing User and Job Result<a class="headerlink" href="#accessing-user-and-job-result" title="Permanent link">&para;</a></h3>
 <details class="version-changed">