nautobot.apps.utils
¶
Nautobot utility functions.
nautobot.apps.utils.ChangeLoggedModelsQuery
¶
Bases: FeaturedQueryMixin
Helper class to get ContentType for models that implements the to_objectchange method for change logging.
Source code in nautobot/extras/utils.py
list_subclasses()
¶
Return a list of classes that implement the to_objectchange method
nautobot.apps.utils.FeatureQuery
¶
Helper class that delays evaluation of the registry contents for the functionality store until it has been populated.
Source code in nautobot/extras/utils.py
as_dict()
¶
Given an extras feature, return a dict of app_label: [models] for content type lookup
get_choices()
¶
Given an extras feature, return a list of 2-tuple of (model_label, pk)
suitable for use as choices
on a choice field:
>>> FeatureQuery('statuses').get_choices()
[('dcim.device', 13), ('dcim.rack', 34)]
Source code in nautobot/extras/utils.py
get_query()
¶
Given an extras feature, return a Q object for content type lookup
Source code in nautobot/extras/utils.py
list_subclasses()
¶
nautobot.apps.utils.FeaturedQueryMixin
¶
Mixin class that gets a list of featured models.
Source code in nautobot/extras/utils.py
__call__()
¶
Given an extras feature, return a Q object for content type lookup
nautobot.apps.utils.GitRepo
¶
Source code in nautobot/core/utils/git.py
56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 |
|
head
property
¶
Current checked out repository head commit.
__init__(path, url, clone_initially=True)
¶
Ensure that we have a clone of the given remote Git repository URL at the given local directory path.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
path |
str
|
path to git repo |
required |
url |
str
|
git repo url |
required |
clone_initially |
bool
|
True if the repo needs to be cloned |
True
|
Source code in nautobot/core/utils/git.py
checkout(branch, commit_hexsha=None)
¶
Check out the given branch, and optionally the specified commit within that branch.
Returns:
Type | Description |
---|---|
(str, bool)
|
commit_hexsha the repo contains now, whether any change occurred |
Source code in nautobot/core/utils/git.py
nautobot.apps.utils.RoleModelsQuery
¶
Bases: FeaturedQueryMixin
Helper class to get ContentType models that implements role.
Source code in nautobot/extras/utils.py
list_subclasses()
¶
Return a list of classes that implements roles e.g roles = ...
Source code in nautobot/extras/utils.py
nautobot.apps.utils.TaggableClassesQuery
¶
Bases: FeaturedQueryMixin
Helper class to get ContentType models that implements tags(TagsField)
Source code in nautobot/extras/utils.py
list_subclasses()
¶
Return a list of classes that has implements tags e.g tags = TagsField(...)
Source code in nautobot/extras/utils.py
nautobot.apps.utils.build_lookup_label(field_name, _verbose_name)
¶
Return lookup expr with its verbose name
Parameters:
Name | Type | Description | Default |
---|---|---|---|
field_name |
str
|
Field name e.g name__iew |
required |
_verbose_name |
str
|
The verbose name for the lookup expr which is suffixed to the field name e.g iew -> iendswith |
required |
Examples:
Source code in nautobot/core/utils/filtering.py
nautobot.apps.utils.check_if_key_is_graphql_safe(model_name, key, field_name='key')
¶
Helper method to check if a key field is Python/GraphQL safe. Used in CustomField, ComputedField and Relationship models.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.class_deprecated(message)
¶
Decorator to mark a class as deprecated with a custom message about what to do instead of subclassing it.
Source code in nautobot/core/utils/deprecation.py
nautobot.apps.utils.class_deprecated_in_favor_of(replacement_class)
¶
Decorator to mark a class as deprecated and suggest a replacement class if it is subclassed from.
Source code in nautobot/core/utils/deprecation.py
nautobot.apps.utils.convert_git_diff_log_to_list(logs)
¶
Convert Git diff log into a list splitted by \n
Example:
>>> git_log = "M index.html
R sample.txt" >>> print(convert_git_diff_log_to_list(git_log)) ["Modification - index.html", "Renaming - sample.txt"]
Source code in nautobot/core/utils/git.py
nautobot.apps.utils.convert_querydict_to_factory_formset_acceptable_querydict(request_querydict, filterset)
¶
Convert request QueryDict/GET into an acceptable factory formset QueryDict
while discarding querydict
params which are not part of filterset_class
params
Parameters:
Name | Type | Description | Default |
---|---|---|---|
request_querydict |
QueryDict
|
QueryDict to convert |
required |
filterset |
FilterSet
|
Filterset class |
required |
Examples:
>>> convert_querydict_to_factory_formset_acceptable_querydict({"status": ["active", "decommissioning"], "name__ic": ["location"]},)
>>> {
... 'form-TOTAL_FORMS': [3],
... 'form-INITIAL_FORMS': ['0'],
... 'form-MIN_NUM_FORMS': [''],
... 'form-MAX_NUM_FORMS': [''],
... 'form-0-lookup_field': ['status'],
... 'form-0-lookup_type': ['status'],
... 'form-0-value': ['active', 'decommissioning'],
... 'form-1-lookup_field': ['name'],
... 'form-1-lookup_type': ['name__ic'],
... 'form-1-value': ['location']
... }
Source code in nautobot/core/utils/requests.py
nautobot.apps.utils.custom_validator_clean(model_clean_func)
¶
Decorator that wraps a models existing clean method to also execute registered plugin custom validators
:param model_clean_func: The original model clean method which is to be wrapped
Source code in nautobot/extras/plugins/validators.py
nautobot.apps.utils.deepmerge(original, new)
¶
Deep merge two dictionaries (new into original) and return a new dict
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.ensure_content_type_and_field_name_in_query_params(query_params)
¶
Ensure query_params
includes content_type
and field_name
and content_type
is a valid ContentType.
Return the 'ContentTypes' model and 'field_name' if validation was successful.
Source code in nautobot/core/utils/requests.py
nautobot.apps.utils.fixup_null_statuses(*, model, model_contenttype, status_model)
¶
For instances of model that have an invalid NULL status field, create and use a special status_model instance.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.flatten_dict(d, prefix='', separator='.')
¶
Flatten nested dictionaries into a single level by joining key names with a separator.
:param d: The dictionary to be flattened :param prefix: Initial prefix (if any) :param separator: The character to use when concatenating key names
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.flatten_iterable(iterable)
¶
Flatten a nested iterable such as a list of lists, keeping strings intact.
:param iterable: The iterable to be flattened :returns: generator
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.foreground_color(bg_color)
¶
Return the ideal foreground color (black or white) for a given background color in hexadecimal RGB format.
Source code in nautobot/core/utils/color.py
nautobot.apps.utils.generate_signature(request_body, secret)
¶
Return a cryptographic signature that can be used to verify the authenticity of webhook data.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.get_all_lookup_expr_for_field(model, field_name)
¶
Return all lookup expressions for field_name
in model
filterset
Source code in nautobot/core/utils/filtering.py
nautobot.apps.utils.get_base_template(base_template, model)
¶
Returns the name of the base template, if the base_template is not None
Otherwise, default to using "NautobotUIViewSet
exists.
If both templates do not exist, fall back to "base.html".
Source code in nautobot/extras/utils.py
nautobot.apps.utils.get_celery_queues()
¶
Return a dictionary of celery queues and the number of workers active on the queue in the form {queue_name: num_workers}
Source code in nautobot/extras/utils.py
nautobot.apps.utils.get_changes_for_model(model)
¶
Return a queryset of ObjectChanges for a model or instance. The queryset will be filtered by the model class. If an instance is provided, the queryset will also be filtered by the instance id.
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_filter_field_label(filter_field)
¶
Return a label for a given field name and value.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filter_field |
Filter
|
The filter to get a label for |
required |
Returns:
Type | Description |
---|---|
str
|
The label for the given field |
Source code in nautobot/core/utils/filtering.py
nautobot.apps.utils.get_filterable_params_from_filter_params(filter_params, non_filter_params, filterset)
¶
Remove any non_filter_params
and fields that are not a part of the filterset from filter_params
to return only queryset filterable parameters.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filter_params |
QueryDict
|
Filter param querydict |
required |
non_filter_params |
list
|
Non queryset filterable params |
required |
filterset |
FilterSet
|
The FilterSet class |
required |
Returns:
Type | Description |
---|---|
QueryDict
|
Filter param querydict with only queryset filterable params |
Source code in nautobot/core/utils/requests.py
nautobot.apps.utils.get_filterset_for_model(model)
¶
Return the FilterSet
class associated with a given model
.
The FilterSet
class is expected to be in the filters
module within the application
associated with the model and its name is expected to be {ModelName}FilterSet
.
If a matching FilterSet
is not found, this will return None
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model |
BaseModel
|
A model class |
required |
Returns:
Type | Description |
---|---|
Union[FilterSet, None]
|
Either the |
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_filterset_parameter_form_field(model, parameter, filterset=None)
¶
Return the relevant form field instance for a filterset parameter e.g DynamicModelMultipleChoiceField, forms.IntegerField e.t.c
Source code in nautobot/core/utils/filtering.py
85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 |
|
nautobot.apps.utils.get_form_for_model(model, form_prefix='')
¶
Return the Form
class associated with a given model
.
The Form
class is expected to be in the forms
module within the application
associated with the model and its name is expected to be {ModelName}{form_prefix}Form
.
If a matching Form
is not found, this will return None
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
form_prefix |
str
|
An additional prefix for the form name (e.g. |
''
|
Returns:
Type | Description |
---|---|
Union[Form, None]
|
Either the |
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_latest_release(pre_releases=False)
¶
Get latest known Nautobot release from cache, or if not available, queue up a background task to populate the cache.
Returns:
Type | Description |
---|---|
(Version, str)
|
Latest release version and the release URL, if found in the cache |
(unknown, None)
|
If not present in the cache at this time |
Source code in nautobot/core/releases.py
nautobot.apps.utils.get_model_from_name(model_name)
¶
Given a full model name in dotted format (example: dcim.model
), a model class is returned if valid.
:param model_name: Full dotted name for a model as a string (ex: dcim.model
)
:type model_name: str
:raises TypeError: If given model name is not found.
:return: Found model.
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_only_new_ui_ready_routes(patterns, prefix='')
¶
Recursively traverses Django URL patterns to find routes associated with view classes
that have the use_new_ui
attribute set to True
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
patterns |
list
|
List of URL patterns to traverse. |
required |
prefix |
str
|
URL pattern prefix to include when constructing route patterns. |
''
|
Returns:
Type | Description |
---|---|
list
|
A list of route patterns associated with view classes that use the new UI. |
Source code in nautobot/core/utils/navigation.py
nautobot.apps.utils.get_permission_for_model(model, action)
¶
Resolve the named permission for a given model (or instance) and action (e.g. view or add).
:param model: A model or instance :param action: View, add, change, or delete (string)
Source code in nautobot/core/utils/permissions.py
nautobot.apps.utils.get_related_class_for_model(model, module_name, object_suffix)
¶
Return the appropriate class associated with a given model matching the module_name
and
object_suffix
.
The given model
can either be a model class, a model instance, or a dotted representation (ex: dcim.device
).
The object class is expected to be in the module within the application
associated with the model and its name is expected to be {ModelName}{object_suffix}
.
If a matching class is not found, this will return None
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model |
Union[BaseModel, str]
|
A model class, instance, or dotted representation |
required |
module_name |
str
|
The name of the module to search for the object class |
required |
object_suffix |
str
|
The suffix to append to the model name to find the object class |
required |
Returns:
Type | Description |
---|---|
Union[BaseModel, str]
|
Either the matching object class or None |
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_route_for_model(model, action, api=False)
¶
Return the URL route name for the given model and action. Does not perform any validation. Supports both core and plugin routes.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model |
(models.Model, str)
|
Class, Instance, or dotted string of a Django Model |
required |
action |
str
|
name of the action in the route |
required |
api |
bool
|
If set, return an API route. |
False
|
Returns:
Type | Description |
---|---|
str
|
return the name of the view for the model/action provided. |
Examples:
>>> get_route_for_model(Device, "list")
"dcim:device_list"
>>> get_route_for_model(Device, "list", api=True)
"dcim-api:device-list"
>>> get_route_for_model("dcim.location", "list")
"dcim:location_list"
>>> get_route_for_model("dcim.location", "list", api=True)
"dcim-api:location-list"
>>> get_route_for_model(ExampleModel, "list")
"plugins:example_plugin:examplemodel_list"
>>> get_route_for_model(ExampleModel, "list", api=True)
"plugins-api:example_plugin-api:examplemodel-list"
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_settings_or_config(variable_name)
¶
Get a value from Django settings (if specified there) or Constance configuration (otherwise).
Source code in nautobot/core/utils/config.py
nautobot.apps.utils.get_table_for_model(model)
¶
Return the Table
class associated with a given model
.
The Table
class is expected to be in the tables
module within the application
associated with the model and its name is expected to be {ModelName}Table
.
If a matching Table
is not found, this will return None
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model |
BaseModel
|
A model class |
required |
Returns:
Type | Description |
---|---|
Union[Table, None]
|
Either the |
Source code in nautobot/core/utils/lookup.py
nautobot.apps.utils.get_worker_count(request=None, queue=None)
¶
Return a count of the active Celery workers in a specified queue. Defaults to the CELERY_TASK_DEFAULT_QUEUE
setting.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.hex_to_rgb(hex_str)
¶
nautobot.apps.utils.image_upload(instance, filename)
¶
Return a path for uploading image attachments.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.is_url(value)
¶
Validate whether a value is a URL.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value |
str
|
String to validate. |
required |
Returns:
Type | Description |
---|---|
bool
|
True if the value is a valid URL, False otherwise. |
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.lighten_color(r, g, b, factor)
¶
Make a given RGB color lighter (closer to white).
nautobot.apps.utils.merge_dicts_without_collision(d1, d2)
¶
Merge two dicts into a new dict, but raise a ValueError if any key exists with differing values across both dicts.
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.migrate_role_data(model_to_migrate, *, from_role_field_name, from_role_model=None, from_role_choiceset=None, to_role_field_name, to_role_model=None, to_role_choiceset=None, is_m2m_field=False)
¶
Update all model_to_migrate
with a value for to_role_field
based on from_role_field
values.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
model_to_migrate |
Model
|
Model with role fields to alter |
required |
from_role_field_name |
str
|
Name of the field on |
required |
from_role_model |
Model
|
If |
None
|
from_role_choiceset |
ChoiceSet
|
If |
None
|
to_role_field_name |
str
|
Name of the field on |
required |
to_role_model |
Model
|
If |
None
|
to_role_choiceset |
ChoiceSet
|
If |
None
|
is_m2m_field |
bool
|
True if the role fields are both ManyToManyFields, else False |
False
|
Source code in nautobot/extras/utils.py
505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 |
|
nautobot.apps.utils.normalize_querydict(querydict, form_class=None)
¶
Convert a QueryDict to a normal, mutable dictionary, preserving list values. For example,
QueryDict('foo=1&bar=2&bar=3&baz=')
becomes
{'foo': '1', 'bar': ['2', '3'], 'baz': ''}
This function is necessary because QueryDict does not provide any built-in mechanism which preserves multiple values.
A form_class
can be provided as a way to hint which query parameters should be treated as lists.
Source code in nautobot/core/utils/requests.py
nautobot.apps.utils.permission_is_exempt(name)
¶
Determine whether a specified permission is exempt from evaluation.
:param name: Permission name in the format
Source code in nautobot/core/utils/permissions.py
nautobot.apps.utils.populate_model_features_registry(refresh=False)
¶
Populate the registry model features with new apps.
This function updates the registry model features.
Behavior:
- Defines a list of dictionaries called lookup_confs. Each dictionary contains:
- 'feature_name': The name of the feature to be updated in the registry.
- 'field_names': A list of names of fields that must be present in order for the model to be considered
a valid model_feature.
- 'field_attributes': Optional dictionary of attributes to filter the fields by. Only model which fields match
all the attributes specified in the dictionary will be considered. This parameter can be
useful to narrow down the search for fields that match certain criteria. For example, if
field_attributes
is set to {"related_model": RelationshipAssociation}, only fields with
a related model of RelationshipAssociation will be considered.
- Looks up all the models in the installed apps.
- For each dictionary in lookup_confs, calls lookup_by_field() function to look for all models that have fields with the names given in the dictionary.
- Groups the results by app and updates the registry model features for each app.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.refresh_job_model_from_job_class(job_model_class, job_class)
¶
Create or update a job_model record based on the metadata of the provided job_class.
Note that job_model_class is a parameter (rather than doing a "from nautobot.extras.models import Job") because this function may be called from various initialization processes (such as the "nautobot_database_ready" signal) and in that case we need to not import models ourselves.
Source code in nautobot/extras/utils.py
332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 |
|
nautobot.apps.utils.remove_prefix_from_cf_key(field_name)
¶
nautobot.apps.utils.render_jinja2(template_code, context)
¶
Render a Jinja2 template with the provided context. Return the rendered content.
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.resolve_permission(name)
¶
Given a permission name, return the app_label, action, and model_name components. For example, "dcim.view_location" returns ("dcim", "view", "location").
:param name: Permission name in the format
Source code in nautobot/core/utils/permissions.py
nautobot.apps.utils.resolve_permission_ct(name)
¶
Given a permission name, return the relevant ContentType and action. For example, "dcim.view_location" returns (Location, "view").
:param name: Permission name in the format
Source code in nautobot/core/utils/permissions.py
nautobot.apps.utils.rgb_to_hex(r, g, b)
¶
nautobot.apps.utils.sanitize(string, replacement='(redacted)')
¶
Make an attempt at stripping potentially-sensitive information from the given string.
Obviously this will never be 100% foolproof but we can at least try.
Uses settings.SANITIZER_PATTERNS as the list of (regexp, repl) tuples to apply.
Source code in nautobot/core/utils/logging.py
nautobot.apps.utils.shallow_compare_dict(source_dict, destination_dict, exclude=None)
¶
Return a new dictionary of the different keys. The values of destination_dict
are returned. Only the equality of
the first layer of keys/values is checked. exclude
is a list or tuple of keys to be ignored.
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.swap_status_initials(data)
¶
nautobot.apps.utils.task_queues_as_choices(task_queues)
¶
Returns a list of 2-tuples for use in the form field choices
argument. Appends
worker count to the description.
Source code in nautobot/extras/utils.py
nautobot.apps.utils.to_meters(length, unit)
¶
Convert the given length to meters.
Source code in nautobot/core/utils/data.py
nautobot.apps.utils.wrap_model_clean_methods()
¶
Helper function that wraps plugin model validator registered clean methods for all applicable models