Adding missing help_text and check

.github/workflows/sanity.yml

@@ -0,0 +1,37 @@
+---
+name: Sanity
+env:
+  LC_ALL: "C.UTF-8" # prevent ERROR: Ansible could not initialize the preferred locale: unsupported locale setting
+on:
+  pull_request:
+  push:
+jobs:
+  help_text:
+    name: Help Test Check
+    runs-on: ubuntu-latest
+    permissions:
+      packages: read
+      contents: read
+    strategy:
+      fail-fast: false
+    steps:
+      - name: Install make
+        run: sudo apt install make
+
+      - uses: actions/checkout@v4
+        with:
+          show-progress: false
+
+      - name: Install build requirements
+        run: sudo apt-get update && sudo apt-get install -y libsasl2-dev libldap2-dev libssl-dev libxmlsec1-dev
+
+      - name: Install python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install requirements
+        run: pip3.11 install -r requirements/requirements_all.txt -r requirements/requirements_dev.txt
+
+      - name: Run help text check
+        run: ./manage.py help_text_check --applications=dab --ignore-file=./.help_text_check.ignore

.help_text_check.ignore

@@ -0,0 +1,23 @@
+dab_authentication.AuthenticatorUser.created  # Inherited from social auth
+dab_authentication.AuthenticatorUser.extra_data  # Inherited from social auth
+dab_authentication.AuthenticatorUser.modified  # Inherited from social auth
+dab_authentication.AuthenticatorUser.uid  # Inherited from social auth
+
+dab_oauth2_provider.OAuth2AccessToken.expires  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2AccessToken.id_token  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2AccessToken.source_refresh_token  # Inherited from django-oauth-toolkit
+
+dab_oauth2_provider.OAuth2Application.algorithm  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2Application.client_id  # Inherited from django-oauth-toolkit
+
+dab_oauth2_provider.OAuth2IDToken.application  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2IDToken.expires  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2IDToken.jti  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2IDToken.scope  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2IDToken.user  # Inherited from django-oauth-toolkit
+
+dab_oauth2_provider.OAuth2RefreshToken.access_token  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2RefreshToken.application  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2RefreshToken.revoked  # Inherited from django-oauth-toolkit
+dab_oauth2_provider.OAuth2RefreshToken.user  # Inherited from django-oauth-toolkit
+

ansible_base/activitystream/migrations/0005_alter_entry_changes_alter_entry_content_type_and_more.py

@@ -0,0 +1,50 @@
+# Generated by Django 4.2.16 on 2024-11-22 21:25
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('contenttypes', '0002_remove_content_type_name'),
+        ('dab_activitystream', '0004_alter_entry_created_alter_entry_created_by'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='entry',
+            name='changes',
+            field=models.JSONField(blank=True, help_text='The changes to the system recorded by this entry.', null=True),
+        ),
+        migrations.AlterField(
+            model_name='entry',
+            name='content_type',
+            field=models.ForeignKey(help_text='The content type which was changed in this entry.', on_delete=django.db.models.deletion.DO_NOTHING, to='contenttypes.contenttype'),
+        ),
+        migrations.AlterField(
+            model_name='entry',
+            name='object_id',
+            field=models.TextField(blank=True, help_text='The object id which was modified in this entry.', null=True),
+        ),
+        migrations.AlterField(
+            model_name='entry',
+            name='operation',
+            field=models.CharField(choices=[('create', 'Entity created'), ('update', 'Entity updated'), ('delete', 'Entity deleted'), ('associate', 'Entity was associated with another entity'), ('disassociate', 'Entity was disassociated with another entity')], help_text='The type of change recorded by the entry (i.e. create/update/delete/etc).', max_length=12),
+        ),
+        migrations.AlterField(
+            model_name='entry',
+            name='related_content_type',
+            field=models.ForeignKey(blank=True, help_text='The content type if this entry is recording an many to many (M2M) change.', null=True, on_delete=django.db.models.deletion.DO_NOTHING, related_name='related_content_type', to='contenttypes.contenttype'),
+        ),
+        migrations.AlterField(
+            model_name='entry',
+            name='related_field_name',
+            field=models.CharField(blank=True, help_text='The related field name if this entry is for an many to many (M2M) relationship.', max_length=64, null=True),
+        ),
+        migrations.AlterField(
+            model_name='entry',
+            name='related_object_id',
+            field=models.TextField(blank=True, help_text='The object id of the related model if this entry is for an many to many (M2M) change.', null=True),
+        ),
+    ]

ansible_base/activitystream/models/entry.py

@@ -32,17 +32,35 @@ class Meta:
         ('disassociate', _("Entity was disassociated with another entity")),
     ]
 
-    content_type = models.ForeignKey(ContentType, on_delete=models.DO_NOTHING)
-    object_id = models.TextField(null=True, blank=True)
+    content_type = models.ForeignKey(ContentType, on_delete=models.DO_NOTHING, help_text=_("The content type which was changed in this entry."))
+    object_id = models.TextField(null=True, blank=True, help_text=_("The object id which was modified in this entry."))
     content_object = GenericForeignKey('content_type', 'object_id')
-    operation = models.CharField(max_length=12, choices=OPERATION_CHOICES)
-    changes = models.JSONField(null=True, blank=True)
+    operation = models.CharField(
+        max_length=12, choices=OPERATION_CHOICES, help_text=_("The type of change recorded by the entry (i.e. create/update/delete/etc).")
+    )
+    changes = models.JSONField(null=True, blank=True, help_text=_("The changes to the system recorded by this entry."))
 
     # This is used for m2m (dis)associations
-    related_content_type = models.ForeignKey(ContentType, on_delete=models.DO_NOTHING, null=True, blank=True, related_name='related_content_type')
-    related_object_id = models.TextField(null=True, blank=True)
+    related_content_type = models.ForeignKey(
+        ContentType,
+        on_delete=models.DO_NOTHING,
+        null=True,
+        blank=True,
+        related_name='related_content_type',
+        help_text=_("The content type if this entry is recording an many to many (M2M) change."),
+    )
+    related_object_id = models.TextField(
+        null=True,
+        blank=True,
+        help_text=_("The object id of the related model if this entry is for an many to many (M2M) change."),
+    )
     related_content_object = GenericForeignKey('related_content_type', 'related_object_id')
-    related_field_name = models.CharField(max_length=64, null=True, blank=True)
+    related_field_name = models.CharField(
+        max_length=64,
+        null=True,
+        blank=True,
+        help_text=_("The related field name if this entry is for an many to many (M2M) relationship."),
+    )
 
     def __str__(self):
         return f'[{self.created}] {self.get_operation_display()} by {self.created_by}: {self.content_type} {self.object_id}'

ansible_base/authentication/migrations/0016_alter_authenticatoruser_access_allowed_and_more.py

@@ -0,0 +1,41 @@
+# Generated by Django 4.2.16 on 2024-11-22 21:25
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('dab_authentication', '0015_alter_authenticator_category_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='authenticatoruser',
+            name='access_allowed',
+            field=models.BooleanField(default=None, help_text='Tracks if this user was allowed access to the system from the authenticator maps.', null=True),
+        ),
+        migrations.AlterField(
+            model_name='authenticatoruser',
+            name='claims',
+            field=models.JSONField(blank=True, default=dict, help_text='The claims for the user as generated by the authenticator maps on their last login.'),
+        ),
+        migrations.AlterField(
+            model_name='authenticatoruser',
+            name='last_login_map_results',
+            field=models.JSONField(blank=True, default=list, help_text='A data structure indicating how the authenticator maps were evaluated for the last login attempt.'),
+        ),
+        migrations.AlterField(
+            model_name='authenticatoruser',
+            name='provider',
+            field=models.ForeignKey(help_text='The provider this user authenticated from.', on_delete=django.db.models.deletion.PROTECT, related_name='authenticator_providers', to='dab_authentication.authenticator', to_field='slug'),
+        ),
+        migrations.AlterField(
+            model_name='authenticatoruser',
+            name='user',
+            field=models.ForeignKey(help_text='The local DB user related to this authenticator user.', on_delete=django.db.models.deletion.CASCADE, related_name='authenticator_users', to=settings.AUTH_USER_MODEL),
+        ),
+    ]

ansible_base/authentication/models/authenticator_user.py

@@ -3,6 +3,7 @@
 
 from django.conf import settings
 from django.db import models
+from django.utils.translation import gettext_lazy as _
 from social_django.models import AbstractUserSocialAuth
 
 from ansible_base.authentication.models import Authenticator
@@ -28,14 +29,31 @@ class AuthenticatorUser(AbstractUserSocialAuth, AbstractCommonModel):
     the authenticators and links the user to the authenticator that they used to login.
     """
 
-    provider = models.ForeignKey(Authenticator, to_field='slug', on_delete=models.PROTECT, related_name="authenticator_providers")
-    user = models.ForeignKey(settings.AUTH_USER_MODEL, related_name="authenticator_users", on_delete=models.CASCADE)
+    provider = models.ForeignKey(
+        Authenticator,
+        to_field='slug',
+        on_delete=models.PROTECT,
+        related_name="authenticator_providers",
+        help_text=_("The provider this user authenticated from."),
+    )
+    user = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        related_name="authenticator_users",
+        on_delete=models.CASCADE,
+        help_text=_("The local DB user related to this authenticator user."),
+    )
     # TODO: set self.authenticated based on the provider that is passed to this method.
     # the provider should be the name of the Authenticator model instance
-    claims = models.JSONField(default=dict, null=False, blank=True)
-    last_login_map_results = models.JSONField(default=list, null=False, blank=True)
+    claims = models.JSONField(
+        default=dict, null=False, blank=True, help_text=_("The claims for the user as generated by the authenticator maps on their last login.")
+    )
+    last_login_map_results = models.JSONField(
+        default=list, null=False, blank=True, help_text=_("A data structure indicating how the authenticator maps were evaluated for the last login attempt.")
+    )
     # This field tracks if a user passed or failed an allow map
-    access_allowed = models.BooleanField(default=None, null=True)
+    access_allowed = models.BooleanField(
+        default=None, null=True, help_text=_("Tracks if this user was allowed access to the system from the authenticator maps.")
+    )
 
     encrypted_fields = ["extra_data"]
 

ansible_base/oauth2_provider/migrations/0007_alter_oauth2accesstoken_application_and_more.py

@@ -0,0 +1,51 @@
+# Generated by Django 4.2.16 on 2024-11-22 21:25
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ('dab_oauth2_provider', '0006_alter_oauth2accesstoken_created_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='oauth2accesstoken',
+            name='application',
+            field=models.ForeignKey(blank=True, help_text='The related application. If None, this is a user token instead of an application token.', null=True, on_delete=django.db.models.deletion.CASCADE, related_name='access_tokens', to=settings.OAUTH2_PROVIDER_APPLICATION_MODEL),
+        ),
+        migrations.AlterField(
+            model_name='oauth2accesstoken',
+            name='description',
+            field=models.TextField(blank=True, default='', help_text='A description for this token.'),
+        ),
+        migrations.AlterField(
+            model_name='oauth2accesstoken',
+            name='last_used',
+            field=models.DateTimeField(default=None, editable=False, help_text='A timestamp of when this token was last used.', null=True),
+        ),
+        migrations.AlterField(
+            model_name='oauth2accesstoken',
+            name='token',
+            field=models.CharField(help_text='The generated token value.', max_length=255, unique=True),
+        ),
+        migrations.AlterField(
+            model_name='oauth2application',
+            name='description',
+            field=models.TextField(blank=True, default='', help_text='A description of this application.'),
+        ),
+        migrations.AlterField(
+            model_name='oauth2application',
+            name='user',
+            field=models.ForeignKey(blank=True, help_text='The user who created the application.', null=True, on_delete=django.db.models.deletion.CASCADE, related_name='applications', to=settings.AUTH_USER_MODEL),
+        ),
+        migrations.AlterField(
+            model_name='oauth2refreshtoken',
+            name='token',
+            field=models.CharField(help_text='The refresh token value.', max_length=255),
+        ),
+    ]

ansible_base/oauth2_provider/models/access_token.py

@@ -58,28 +58,17 @@ class Meta(oauth2_models.AbstractAccessToken.Meta):
         blank=True,
         null=True,
         related_name='access_tokens',
+        help_text=_('The related application. If None, this is a user token instead of an application token.'),
     )
-    description = models.TextField(
-        default='',
-        blank=True,
-    )
-    last_used = models.DateTimeField(
-        null=True,
-        default=None,
-        editable=False,
-    )
+    description = models.TextField(default='', blank=True, help_text=_('A description for this token.'))
+    last_used = models.DateTimeField(null=True, default=None, editable=False, help_text=_('A timestamp of when this token was last used.'))
     scope = models.CharField(
         default='write',
         max_length=32,
         help_text=_("Allowed scopes, further restricts user permissions. Must be a simple space-separated string with allowed scopes ['read', 'write']."),
         validators=[validate_scope],
     )
-    token = prevent_search(
-        models.CharField(
-            max_length=255,
-            unique=True,
-        )
-    )
+    token = prevent_search(models.CharField(max_length=255, unique=True, help_text=_("The generated token value.")))
     updated = None  # Tracked in CommonModel with 'modified', no need for this
 
     def is_valid(self, scopes=None):

ansible_base/oauth2_provider/models/application.py

@@ -43,11 +43,13 @@ class Meta(oauth2_models.AbstractAccessToken.Meta):
         null=True,
         blank=True,
         on_delete=models.CASCADE,
+        help_text=_("The user who created the application."),
     )
 
     description = models.TextField(
         default='',
         blank=True,
+        help_text=_("A description of this application."),
     )
     organization = models.ForeignKey(
         getattr(settings, 'ANSIBLE_BASE_ORGANIZATION_MODEL'),

ansible_base/oauth2_provider/models/refresh_token.py

@@ -22,7 +22,7 @@ class Meta(oauth2_models.AbstractRefreshToken.Meta):
         ordering = ('id',)
         swappable = "OAUTH2_PROVIDER_REFRESH_TOKEN_MODEL"
 
-    token = prevent_search(models.CharField(max_length=255))
+    token = prevent_search(models.CharField(max_length=255, help_text=_("The refresh token value.")))
     updated = None  # Tracked in CommonModel with 'modified', no need for this
 
     def save(self, *args, **kwargs):