Rename example_plugins to example_apps

.github/PULL_REQUEST_TEMPLATE.md

@@ -29,5 +29,5 @@
 - [ ] Attached Screenshots, Payload Example
 - [ ] Unit, Integration Tests
 - [ ] Documentation Updates (when adding/changing features)
-- [ ] Example Plugin Updates (when adding/changing features)
+- [ ] Example App Updates (when adding/changing features)
 - [ ] Outline Remaining Work, Constraints from Design

.gitignore

@@ -28,6 +28,6 @@ uwsgi.ini
 jobs/*
 htmlcov/*
 /nautobot/project-static/docs/
-/examples/example_plugin/example_plugin/static/example_plugin/docs/
+/examples/example_*/**/static/example_*/docs/
 development/factory_dump.json
 node_modules

changes/5179.documentation

@@ -0,0 +1,2 @@
+Updated all documentation referencing the `example_plugin` to refer to the (renamed) `example_app`.
+Replaced some "plugin" references in the documentation with "App" or "Nautobot App" as appropriate.

changes/5179.housekeeping

@@ -0,0 +1,4 @@
+Renamed `example_plugin` to `example_app`.
+Renamed `example_plugin_with_view_override` to `example_app_with_view_override`.
+Replaced all "plugin" terminology within the `examples` directory with "App", except in cases where the terminology is embedded in core code (`settings.PLUGINS`, `plugins:` and `plugins-api` named URLs, etc.)
+Replaced some "plugin" terminology in docstrings, comments, and test code with "app" as appropriate.

development/nautobot_config.py

@@ -42,7 +42,7 @@
 #
 
 PLUGINS = [
-    "example_plugin",
+    "example_app",
 ]
 
 CORS_ALLOWED_ORIGINS = ["http://localhost:3000"]

docker/Dockerfile

@@ -135,7 +135,7 @@ COPY --from=poetry ${POETRY_HOME} ${POETRY_HOME}
 COPY --from=poetry /root/.config/pypoetry /root/.config/pypoetry
 ENV PATH="${POETRY_HOME}/bin:${PATH}"
 
-# The example_plugin is only a dev dependency, but Poetry fails to install non-dev dependencies if its source is missing
+# The example_app is only a dev dependency, but Poetry fails to install non-dev dependencies if its source is missing
 COPY --chown=nautobot:nautobot pyproject.toml poetry.lock README.md /source/
 COPY --chown=nautobot:nautobot examples /source/examples
 
@@ -200,7 +200,7 @@ COPY --from=build-nautobot --chown=nautobot:nautobot /source/dist /source/dist
 # hadolint ignore=DL3042
 RUN --mount=type=cache,target="/root/.cache",sharing=locked \
     pip install --no-deps /source/dist/*.whl && \
-    pip uninstall -y example-plugin example-plugin-with-view-override && \
+    pip uninstall -y example-app example-app-with-view-override && \
     rm -rf /source/*
 
 USER nautobot

examples/README.md

@@ -1,3 +1,3 @@
 # Nautobot Examples
 
-This directory contains examples of extending Nautobot using plugins or other exciting features!
+This directory contains examples of extending Nautobot using Apps or other exciting features!

examples/azure_ad/README.md

@@ -2,7 +2,7 @@
 
 This example shows how to extend the Social Auth Pipeline to read groups from a groups claim in AzureAD and sync those with Nautobot.  
 
-Create a python module with the provided `group_sync.py` file in it. This could be done as part of a plugin or as a standalone python module.
+Create a python module with the provided `group_sync.py` file in it. This could be done as part of a Nautobot App, or as a standalone python module.
 
 In the `nautobot_config.py` set the following values with the settings from Azure:
 

examples/example_app/README.md

@@ -0,0 +1,19 @@
+# Example App
+
+This is a sample Nautobot App with all the bells and whistles that is used for unit testing App features. It is also provided here as an example for those interested in developing their own Apps.
+
+## Installation
+
+To install this example App from this directory run this command:
+
+```no-highlight
+pip install .
+```
+
+And then add it to your `PLUGINS` setting in your `nautobot_config.py`:
+
+```python
+PLUGINS = [
+    "example_app",
+]
+```

examples/example_app/docs/index.md

@@ -0,0 +1 @@
+# Example App

examples/example_plugin/example_plugin/__init__.py → examples/example_app/example_app/__init__.py

@@ -5,21 +5,21 @@
 
 from nautobot.apps import ConstanceConfigItem, nautobot_database_ready, NautobotAppConfig
 
-from example_plugin.signals import nautobot_database_ready_callback
+from example_app.signals import nautobot_database_ready_callback
 
 
-class ExamplePluginConfig(NautobotAppConfig):
-    name = "example_plugin"
+class ExampleAppConfig(NautobotAppConfig):
+    name = "example_app"
     verbose_name = "Example Nautobot App"
     author = "Nautobot development team"
     author_email = "nautobot@example.com"
     version = __version__
     description = "For testing purposes only"
-    base_url = "example-plugin"
+    base_url = "example-app"
     min_version = "0.9"
     max_version = "9.0"
-    middleware = ["example_plugin.middleware.ExampleMiddleware"]
-    installed_apps = ["nautobot.extras.tests.example_plugin_dependency"]
+    middleware = ["example_app.middleware.ExampleMiddleware"]
+    installed_apps = ["nautobot.extras.tests.example_app_dependency"]
     default_settings = {
         "ANOTHER_SAMPLE_VARIABLE": "example_default_value",
     }
@@ -34,17 +34,17 @@ class ExamplePluginConfig(NautobotAppConfig):
     searchable_models = ["examplemodel"]
 
     # URL reverse lookup names
-    home_view_name = "plugins:example_plugin:home"
-    config_view_name = "plugins:example_plugin:config"
-    docs_view_name = "plugins:example_plugin:docs"
+    home_view_name = "plugins:example_app:home"
+    config_view_name = "plugins:example_app:config"
+    docs_view_name = "plugins:example_app:docs"
 
     def ready(self):
         """Callback when this app is loaded."""
         super().ready()
         # Connect the nautobot_database_ready_callback() function to the nautobot_database_ready signal.
-        # This is by no means a requirement for all plugins, but is a useful way for a plugin to perform
+        # This is by no means a requirement for all Apps, but is a useful way for an App to perform
         # database operations such as defining CustomFields, Relationships, etc. at the appropriate time.
         nautobot_database_ready.connect(nautobot_database_ready_callback, sender=self)
 
 
-config = ExamplePluginConfig
+config = ExampleAppConfig

examples/example_plugin/example_plugin/admin.py → examples/example_app/example_app/admin.py

@@ -2,7 +2,7 @@
 
 from nautobot.apps.admin import NautobotModelAdmin
 
-from example_plugin.models import ExampleModel
+from example_app.models import ExampleModel
 
 
 @admin.register(ExampleModel)

examples/example_plugin/example_plugin/api/serializers.py → examples/example_app/example_app/api/serializers.py

@@ -2,13 +2,13 @@
 
 from nautobot.apps.api import NautobotModelSerializer
 
-from example_plugin.models import AnotherExampleModel, ExampleModel
+from example_app.models import AnotherExampleModel, ExampleModel
 
 
 class AnotherExampleModelSerializer(NautobotModelSerializer):
     """Used for normal CRUD operations."""
 
-    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:example_plugin-api:anotherexamplemodel-detail")
+    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:example_app-api:anotherexamplemodel-detail")
 
     class Meta:
         model = AnotherExampleModel
@@ -18,7 +18,7 @@ class Meta:
 class ExampleModelSerializer(NautobotModelSerializer):
     """Used for normal CRUD operations."""
 
-    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:example_plugin-api:examplemodel-detail")
+    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:example_app-api:examplemodel-detail")
 
     class Meta:
         model = ExampleModel

examples/example_plugin/example_plugin/api/urls.py → examples/example_app/example_app/api/urls.py

@@ -2,15 +2,13 @@
 
 from nautobot.apps.api import OrderedDefaultRouter
 
-from example_plugin.api.views import AnotherExampleModelViewSet, ExampleModelViewSet, ExampleModelWebhook
+from example_app.api.views import AnotherExampleModelViewSet, ExampleModelViewSet, ExampleModelWebhook
 
 router = OrderedDefaultRouter()
 router.register("models", ExampleModelViewSet)
 router.register("other-models", AnotherExampleModelViewSet)
 
 urlpatterns = [
-    path(
-        "webhook/", ExampleModelWebhook.as_view(), name="examplemodel_webhook"
-    ),  # URL path for testing plugin webhooks
+    path("webhook/", ExampleModelWebhook.as_view(), name="examplemodel_webhook"),  # URL path for testing App webhooks
     path("", include(router.urls)),
 ]

examples/example_plugin/example_plugin/api/views.py → examples/example_app/example_app/api/views.py

@@ -9,9 +9,9 @@
 
 from nautobot.apps.api import NautobotModelViewSet
 
-from example_plugin.api.serializers import AnotherExampleModelSerializer, ExampleModelSerializer
-from example_plugin.filters import AnotherExampleModelFilterSet, ExampleModelFilterSet
-from example_plugin.models import AnotherExampleModel, ExampleModel
+from example_app.api.serializers import AnotherExampleModelSerializer, ExampleModelSerializer
+from example_app.filters import AnotherExampleModelFilterSet, ExampleModelFilterSet
+from example_app.models import AnotherExampleModel, ExampleModel
 
 
 class AnotherExampleModelViewSet(NautobotModelViewSet):
@@ -34,7 +34,7 @@ class ExampleModelViewSet(NautobotModelViewSet):
 @extend_schema(exclude=True)
 class ExampleModelWebhook(APIView):
     """
-    Example view used in testing webhooks for plugins.
+    Example view used in testing webhooks for Apps.
     """
 
     permission_classes = [AllowAny]

examples/example_plugin/example_plugin/banner.py → examples/example_app/example_app/banner.py

@@ -1,4 +1,4 @@
-"""Example of using a plugin to inject a custom banner across various pages."""
+"""Example of using an App to inject a custom banner across various pages."""
 
 from typing import Optional
 
@@ -23,7 +23,7 @@ def banner(context, *args, **kwargs) -> Optional[Banner]:
 
     # Banner content greeting the user
     content = format_html(
-        "<div>Example Plugin says “Hello, <strong>{}</strong>!” 👋</div>",
+        "<div>Example App says “Hello, <strong>{}</strong>!” 👋</div>",
         context.request.user,
     )
 
@@ -49,10 +49,10 @@ def banner(context, *args, **kwargs) -> Optional[Banner]:
         return Banner(content=content, banner_class=BannerClassChoices.CLASS_SUCCESS)
 
     content += format_html(
-        "<div>SAMPLE_VARIABLE is {}</div>", get_app_settings_or_config("example_plugin", "SAMPLE_VARIABLE")
+        "<div>SAMPLE_VARIABLE is {}</div>", get_app_settings_or_config("example_app", "SAMPLE_VARIABLE")
     )
     content += format_html(
-        "<div>lowercase_example is {}</div>", get_app_settings_or_config("example_plugin", "lowercase_example")
+        "<div>lowercase_example is {}</div>", get_app_settings_or_config("example_app", "lowercase_example")
     )
 
     # Default banner rendering

examples/example_plugin/example_plugin/datasources.py → examples/example_app/example_app/datasources.py

@@ -2,7 +2,7 @@
 
 
 def refresh_git_text_files(repository, job_result, delete=False):
-    if "example_plugin.textfile" in repository.provided_contents:
+    if "example_app.textfile" in repository.provided_contents:
         job_result.log(message="Refreshed text files")
 
 
@@ -11,7 +11,7 @@ def refresh_git_text_files(repository, job_result, delete=False):
         "extras.gitrepository",
         DatasourceContent(
             name="text files",
-            content_identifier="example_plugin.textfile",
+            content_identifier="example_app.textfile",
             icon="mdi-note-text",
             callback=refresh_git_text_files,
         ),

examples/example_plugin/example_plugin/filter_extensions.py → examples/example_app/example_app/filter_extensions.py

@@ -15,20 +15,20 @@ class TenantFilterExtension(FilterExtension):
     model = "tenancy.tenant"
 
     filterset_fields = {
-        "example_plugin_description": MultiValueCharFilter(field_name="description", label="Description"),
-        "example_plugin_sdescrip": MultiValueCharFilter(
+        "example_app_description": MultiValueCharFilter(field_name="description", label="Description"),
+        "example_app_sdescrip": MultiValueCharFilter(
             field_name="description", label="Description", method=suffix_search
         ),
-        "example_plugin_dtype": MultiValueCharFilter(
+        "example_app_dtype": MultiValueCharFilter(
             field_name="locations__devices__device_type__model", label="Device Type (model)"
         ),
     }
 
     filterform_fields = {
-        "example_plugin_description": forms.CharField(required=False, label="Description"),
-        "example_plugin_dtype": forms.CharField(required=False, label="Device Type"),
+        "example_app_description": forms.CharField(required=False, label="Description"),
+        "example_app_dtype": forms.CharField(required=False, label="Device Type"),
         "name__ic": forms.CharField(required=False, label="Name Contains"),
-        "example_plugin_sdescrip": forms.CharField(required=False, label="Suffix Description"),
+        "example_app_sdescrip": forms.CharField(required=False, label="Suffix Description"),
     }
 
 
@@ -44,7 +44,7 @@ class PrefixFilterExtension(FilterExtension):
     model = "ipam.prefix"
 
     filterset_fields = {
-        "example_plugin_prefix_tenant_name": NaturalKeyOrPKMultipleChoiceFilter(
+        "example_app_prefix_tenant_name": NaturalKeyOrPKMultipleChoiceFilter(
             field_name="tenant",
             queryset=Tenant.objects.all(),
             to_field_name="name",
@@ -53,7 +53,7 @@ class PrefixFilterExtension(FilterExtension):
     }
 
     filterform_fields = {
-        "example_plugin_prefix_tenant_name": DynamicModelMultipleChoiceField(
+        "example_app_prefix_tenant_name": DynamicModelMultipleChoiceField(
             queryset=Tenant.objects.all(),
             to_field_name="name",
             required=False,

examples/example_plugin/example_plugin/filters.py → examples/example_app/example_app/filters.py

@@ -1,6 +1,6 @@
 from nautobot.apps.filters import BaseFilterSet, SearchFilter
 
-from example_plugin.models import AnotherExampleModel, ExampleModel
+from example_app.models import AnotherExampleModel, ExampleModel
 
 
 class ExampleModelFilterSet(BaseFilterSet):

examples/example_plugin/example_plugin/forms.py → examples/example_app/example_app/forms.py

@@ -2,11 +2,11 @@
 
 from nautobot.apps.forms import BootstrapMixin, BulkEditForm, NautobotModelForm
 
-from example_plugin.models import AnotherExampleModel, ExampleModel
+from example_app.models import AnotherExampleModel, ExampleModel
 
 
-class ExamplePluginConfigForm(BootstrapMixin, forms.Form):
-    """Example of what a plugin-specific configuration form might look like."""
+class ExampleAppConfigForm(BootstrapMixin, forms.Form):
+    """Example of what an App-specific configuration form might look like."""
 
     magic_word = forms.CharField()
     maximum_velocity = forms.IntegerField(help_text="Meters per second")

examples/example_plugin/example_plugin/graphql/types.py → examples/example_app/example_app/graphql/types.py

@@ -1,6 +1,6 @@
 from nautobot.apps.graphql import OptimizedNautobotObjectType
 
-from example_plugin.models import AnotherExampleModel
+from example_app.models import AnotherExampleModel
 
 
 class AnotherExampleModelType(OptimizedNautobotObjectType):

examples/example_plugin/example_plugin/homepage.py → examples/example_app/example_app/homepage.py

@@ -22,30 +22,30 @@ def get_example_data(request):
                 name="Example Models",
                 model=ExampleModel,
                 weight=150,
-                link="plugins:example_plugin:examplemodel_list",
-                description="List example plugin models.",
-                permissions=["example_plugin.view_examplemodel"],
+                link="plugins:example_app:examplemodel_list",
+                description="List Example App models.",
+                permissions=["example_app.view_examplemodel"],
             ),
         ),
     ),
     HomePagePanel(
-        name="Example Plugin",
+        name="Example App Standard Panel",
         weight=250,
         items=(
             HomePageItem(
-                name="Custom Example Plugin",
+                name="Example App Custom Item",
                 custom_template="item_example.html",
                 custom_data={"example_data": get_example_data},
-                permissions=["example_plugin.view_examplemodel"],
+                permissions=["example_app.view_examplemodel"],
                 weight=100,
             ),
         ),
     ),
     HomePagePanel(
-        name="Custom Example Plugin",
+        name="Example App Custom Panel",
         custom_template="panel_example.html",
         custom_data={"example_data": get_example_data},
-        permissions=["example_plugin.view_examplemodel"],
+        permissions=["example_app.view_examplemodel"],
         weight=350,
     ),
 )

examples/example_plugin/example_plugin/jobs.py → examples/example_app/example_app/jobs.py

@@ -17,7 +17,7 @@
 from nautobot.dcim.models import Device, Location
 from nautobot.extras.choices import ObjectChangeActionChoices
 
-name = "ExamplePlugin jobs"
+name = "Example App jobs"
 
 
 class ExampleDryRunJob(Job):
@@ -49,7 +49,7 @@ class ExampleJob(Job):
     some_json_data = JSONVar(label="JSON", description="Example JSONVar for a job.", default={})
 
     # specify template_name to override the default job scheduling template
-    template_name = "example_plugin/example_with_custom_template.html"
+    template_name = "example_app/example_with_custom_template.html"
 
     class Meta:
         name = "Example job, does nothing"