Standardize docstring

keystone_api/apps/admin_utils/management/commands/clean.py

@@ -24,10 +24,10 @@ class Command(BaseCommand):
     help = __doc__
 
     def add_arguments(self, parser: ArgumentParser) -> None:
-        """Define command-line arguments
+        """Define command-line arguments.
 
         Args:
-          parser: The parser instance to add arguments under
+          parser: The parser instance to add arguments under.
         """
 
         group = parser.add_argument_group('clean options')
@@ -37,7 +37,7 @@ def add_arguments(self, parser: ArgumentParser) -> None:
         group.add_argument('--all', action='store_true', help='Shorthand for deleting all targets')
 
     def handle(self, *args, **options) -> None:
-        """Handle the command execution
+        """Handle the command execution.
 
         Args:
           *args: Additional positional arguments.

keystone_api/apps/admin_utils/management/commands/enable_autocomplete.py

@@ -12,11 +12,11 @@ class Command(BaseCommand):
     help = __doc__
 
     def handle(self, *args, **options) -> None:
-        """Handle the command execution
+        """Handle the command execution.
 
         Args:
-          *args: Additional positional arguments
-          **options: Additional keyword arguments
+          *args: Additional positional arguments.
+          **options: Additional keyword arguments.
         """
 
         try:
@@ -27,7 +27,7 @@ def handle(self, *args, **options) -> None:
             exit(1)
 
     def _handle(self) -> None:
-        """Execute the application logic"""
+        """Execute the application logic."""
 
         if not self.prompt_for_confirmation():
             return
@@ -49,10 +49,10 @@ def _handle(self) -> None:
 
     @staticmethod
     def prompt_for_confirmation() -> bool:
-        """Prompt the user to confirm executing of the parent command
+        """Prompt the user to confirm executing of the parent command.
 
         Args:
-            A boolean indicating whether the user confirmed execution
+            A boolean indicating whether the user confirmed execution.
         """
 
         print(
@@ -73,12 +73,12 @@ def prompt_for_confirmation() -> bool:
 
     @staticmethod
     def get_profile_path() -> Path | None:
-        """Search the user's home directory .bash_profile or .bashrc file
+        """Search the user's home directory .bash_profile or .bashrc file.
 
         The .bash_profile file is given preference over .bashrc.
 
-        Return:
-            The file path object if a file is found, otherwise None
+        Returns:
+            The file path object if a file is found, otherwise `None`.
         """
 
         bash_profile_path = Path.home() / '.bash_profile'

keystone_api/apps/admin_utils/management/commands/quickstart.py

@@ -30,10 +30,10 @@ class Command(BaseCommand):
     help = __doc__
 
     def add_arguments(self, parser: ArgumentParser) -> None:
-        """Add command-line arguments to the parser
+        """Add command-line arguments to the parser.
 
         Args:
-          parser: The argument parser instance
+          parser: The argument parser instance.
         """
 
         group = parser.add_argument_group('quickstart options')
@@ -45,11 +45,11 @@ def add_arguments(self, parser: ArgumentParser) -> None:
         group.add_argument('--all', action='store_true', help='Launch all available services.')
 
     def handle(self, *args, **options) -> None:
-        """Handle the command execution
+        """Handle the command execution.
 
         Args:
-          *args: Additional positional arguments
-          **options: Additional keyword arguments
+          *args: Additional positional arguments.
+          **options: Additional keyword arguments.
         """
 
         # Note: `no_input=False` indicates the user should not be prompted for input
@@ -75,7 +75,7 @@ def handle(self, *args, **options) -> None:
             self.run_gunicorn()
 
     def create_admin(self) -> None:
-        """Create an `admin` user account if no other accounts already exist"""
+        """Create an `admin` user account if no other accounts already exist."""
 
         user = get_user_model()
         if user.objects.exists():
@@ -86,7 +86,7 @@ def create_admin(self) -> None:
 
     @staticmethod
     def run_celery() -> None:
-        """Start a Celery worker"""
+        """Start a Celery worker."""
 
         subprocess.Popen(['redis-server'])
         subprocess.Popen(['celery', '-A', 'keystone_api.apps.scheduler', 'worker'])
@@ -95,11 +95,11 @@ def run_celery() -> None:
 
     @staticmethod
     def run_gunicorn(host: str = '0.0.0.0', port: int = 8000) -> None:
-        """Start a Gunicorn server
+        """Start a Gunicorn server.
 
         Args:
-          host: The host to bind to
-          port: The port to bind to
+          host: The host to bind to.
+          port: The port to bind to.
         """
 
         command = ['gunicorn', '--bind', f'{host}:{port}', 'keystone_api.main.wsgi:application']

keystone_api/apps/allocations/admin.py

@@ -23,15 +23,15 @@
 
 
 class AllocationInline(admin.TabularInline):
-    """Inline admin interface for the `Allocation` model"""
+    """Inline admin interface for the `Allocation` model."""
 
     model = Allocation
     show_change_link = True
     extra = 1
 
 
 class AllocationRequestReviewInline(admin.StackedInline):
-    """Inline admin interface for the `AllocationRequestReview` model"""
+    """Inline admin interface for the `AllocationRequestReview` model."""
 
     model = AllocationRequestReview
     verbose_name = 'Review'
@@ -41,7 +41,7 @@ class AllocationRequestReviewInline(admin.StackedInline):
 
 
 class AttachmentInline(admin.TabularInline):
-    """Inline interface for the `Attachment` model"""
+    """Inline interface for the `Attachment` model."""
 
     model = Attachment
     show_change_link = True
@@ -50,33 +50,33 @@ class AttachmentInline(admin.TabularInline):
 
 @admin.register(Allocation)
 class AllocationAdmin(admin.ModelAdmin):
-    """Admin interface for the `Allocation` model"""
+    """Admin interface for the `Allocation` model."""
 
     @staticmethod
     @admin.display
     def group(obj: Allocation) -> str:
-        """Return the name of the group the allocation is assigned to"""
+        """Return the name of the group the allocation is assigned to."""
 
         return obj.request.group.name
 
     @staticmethod
     @admin.display
     def request(obj: Allocation) -> str:
-        """Return the title of the allocation's corresponding request"""
+        """Return the title of the allocation's corresponding request."""
 
         return obj.request.title
 
     @staticmethod
     @admin.display
     def cluster(obj: Allocation) -> str:
-        """Return the name of the cluster the allocation is assigned to"""
+        """Return the name of the cluster the allocation is assigned to."""
 
         return obj.cluster.name
 
     @staticmethod
     @admin.display
     def status(obj: Allocation) -> str:
-        """Return the status of the corresponding allocation request"""
+        """Return the status of the corresponding allocation request."""
 
         return obj.request.StatusChoices(obj.request.status).label
 
@@ -96,19 +96,19 @@ def status(obj: Allocation) -> str:
 
 @admin.register(AllocationRequest)
 class AllocationRequestAdmin(admin.ModelAdmin):
-    """Admin interface for the `AllocationRequest` model"""
+    """Admin interface for the `AllocationRequest` model."""
 
     @staticmethod
     @admin.display
     def group(obj: Allocation) -> str:
-        """Return the name of the group the allocation is assigned to"""
+        """Return the name of the group the allocation is assigned to."""
 
         return obj.group.name
 
     @staticmethod
     @admin.display
     def reviews(obj: AllocationRequest) -> int:
-        """Return the total number of submitted reviews"""
+        """Return the total number of submitted reviews."""
 
         return sum(1 for _ in obj.allocationrequestreview_set.all())
 
@@ -129,17 +129,17 @@ def reviews(obj: AllocationRequest) -> int:
 
 @admin.register(Cluster)
 class ClusterAdmin(admin.ModelAdmin):
-    """Admin interface for the `Cluster` model"""
+    """Admin interface for the `Cluster` model."""
 
     @admin.action
     def enable_selected_clusters(self, request, queryset) -> None:
-        """Mark selected clusters as enabled"""
+        """Mark selected clusters as enabled."""
 
         queryset.update(enabled=True)
 
     @admin.action
     def disable_selected_clusters(self, request, queryset) -> None:
-        """Mark selected clusters as disabled"""
+        """Mark selected clusters as disabled."""
 
         queryset.update(enabled=False)
 

keystone_api/apps/allocations/models.py

@@ -27,15 +27,15 @@
 
 
 class RGModelInterface:
-    """Interface class for database models affiliated with a research group"""
+    """Interface class for database models affiliated with a research group."""
 
     @abc.abstractmethod
     def get_research_group(self) -> ResearchGroup:
-        """Return the research group tied to the current record"""
+        """Return the research group tied to the current record."""
 
 
 class Allocation(RGModelInterface, models.Model):
-    """User service unit allocation"""
+    """User service unit allocation."""
 
     requested = models.PositiveIntegerField()
     awarded = models.PositiveIntegerField(null=True, blank=True)
@@ -45,21 +45,21 @@ class Allocation(RGModelInterface, models.Model):
     request: AllocationRequest = models.ForeignKey('AllocationRequest', on_delete=models.CASCADE)
 
     def get_research_group(self) -> ResearchGroup:
-        """Return the research group tied to the current record"""
+        """Return the research group tied to the current record."""
 
         return self.request.group
 
     def __str__(self) -> str:  # pragma: nocover
-        """Return a human-readable summary of the allocation"""
+        """Return a human-readable summary of the allocation."""
 
         return f'{self.cluster} allocation for {self.request.group}'
 
 
 class AllocationRequest(RGModelInterface, models.Model):
-    """User request for additional service units on one or more clusters"""
+    """User request for additional service units on one or more clusters."""
 
     class StatusChoices(models.TextChoices):
-        """Enumerated choices for the `status` field"""
+        """Enumerated choices for the `status` field."""
 
         PENDING = 'PD', 'Pending'
         APPROVED = 'AP', 'Approved'
@@ -77,31 +77,31 @@ class StatusChoices(models.TextChoices):
     assignees: User = models.ManyToManyField(User, blank=True)
 
     def clean(self) -> None:
-        """Validate the model instance
+        """Validate the model instance.
 
         Raises:
-            ValidationError: When the model instance data is not valid
+            ValidationError: When the model instance data is not valid.
         """
 
         if self.active and self.expire and self.active >= self.expire:
             raise ValidationError('The expiration date must come after the activation date.')
 
     def get_research_group(self) -> ResearchGroup:
-        """Return the research group tied to the current record"""
+        """Return the research group tied to the current record."""
 
         return self.group
 
     def __str__(self) -> str:  # pragma: nocover
-        """Return the request title as a string"""
+        """Return the request title as a string."""
 
         return truncatechars(self.title, 100)
 
 
 class AllocationRequestReview(RGModelInterface, models.Model):
-    """Reviewer feedback for an allocation request"""
+    """Reviewer feedback for an allocation request."""
 
     class StatusChoices(models.TextChoices):
-        """Enumerated choices for the `status` field"""
+        """Enumerated choices for the `status` field."""
 
         APPROVED = 'AP', 'Approved'
         DECLINED = 'DC', 'Declined'
@@ -116,18 +116,18 @@ class StatusChoices(models.TextChoices):
     reviewer: User = models.ForeignKey(User, on_delete=models.CASCADE)
 
     def get_research_group(self) -> ResearchGroup:
-        """Return the research group tied to the current record"""
+        """Return the research group tied to the current record."""
 
         return self.request.group
 
     def __str__(self) -> str:  # pragma: nocover
-        """Return a human-readable identifier for the allocation request"""
+        """Return a human-readable identifier for the allocation request."""
 
         return f'{self.reviewer} review for \"{self.request.title}\"'
 
 
 class Attachment(models.Model):
-    """File data uploaded by users"""
+    """File data uploaded by users."""
 
     file_data = models.FileField()
     uploaded = models.DateTimeField(auto_now=True)
@@ -136,13 +136,13 @@ class Attachment(models.Model):
 
 
 class Cluster(models.Model):
-    """A slurm cluster and it's associated management settings"""
+    """A slurm cluster and it's associated management settings."""
 
     name = models.CharField(max_length=50)
     description = models.TextField(max_length=150, null=True, blank=True)
     enabled = models.BooleanField(default=True)
 
     def __str__(self) -> str:  # pragma: nocover
-        """Return the cluster name as a string"""
+        """Return the cluster name as a string."""
 
         return str(self.name)