From b93d52b04fa9249c2bfe83c3eb16086b9a286b1c Mon Sep 17 00:00:00 2001 From: Madison Swain-Bowden Date: Mon, 6 May 2024 16:57:02 -0700 Subject: [PATCH] Address feedback, make docstrings less imperative --- api/api/migrations/0060_fill_out_help_text.py | 4 +-- api/api/models/audio.py | 12 +++---- api/api/models/image.py | 10 +++--- api/api/models/media.py | 14 +++----- documentation/meta/media_properties/api.md | 33 ++++++++----------- 5 files changed, 32 insertions(+), 41 deletions(-) diff --git a/api/api/migrations/0060_fill_out_help_text.py b/api/api/migrations/0060_fill_out_help_text.py index 1840752c09d..b6e95943384 100644 --- a/api/api/migrations/0060_fill_out_help_text.py +++ b/api/api/migrations/0060_fill_out_help_text.py @@ -28,7 +28,7 @@ class Migration(migrations.Migration): migrations.AlterField( model_name='audio', name='removed_from_source', - field=models.BooleanField(default=False, help_text='Whether or not the media has been removed from the upstream source.'), + field=models.BooleanField(default=False, help_text='Whether the media has been removed from the upstream source.'), ), migrations.AlterField( model_name='audio', @@ -58,7 +58,7 @@ class Migration(migrations.Migration): migrations.AlterField( model_name='image', name='removed_from_source', - field=models.BooleanField(default=False, help_text='Whether or not the media has been removed from the upstream source.'), + field=models.BooleanField(default=False, help_text='Whether the media has been removed from the upstream source.'), ), migrations.AlterField( model_name='image', diff --git a/api/api/models/audio.py b/api/api/models/audio.py index 4f2b29862bd..1c41e5633d5 100644 --- a/api/api/models/audio.py +++ b/api/api/models/audio.py @@ -141,7 +141,7 @@ class AudioAddOn(OpenLedgerModel): class Audio(AudioFileMixin, AbstractMedia): """ - Represents one audio media instance. + One audio media instance. Inherited fields ================ @@ -254,7 +254,7 @@ class Meta(AbstractMedia.Meta): class DeletedAudio(AbstractDeletedMedia): """ - Represents audio tracks deleted from the upstream source. + Audio tracks deleted from the upstream source. Do not create instances of this model manually. Create an ``AudioReport`` instance instead. @@ -280,7 +280,7 @@ class Meta: class SensitiveAudio(AbstractSensitiveMedia): """ - Represents audio tracks with verified sensitivity reports. + Audio tracks with verified sensitivity reports. Do not create instances of this model manually. Create an ``AudioReport`` instance instead. @@ -307,7 +307,7 @@ class Meta: class AudioReport(AbstractMediaReport): """ - Represents user-submitted reports of audio tracks. + User-submitted reports of audio tracks. ``AudioDecision`` is populated only if moderators have made a decision for this report. @@ -337,7 +337,7 @@ class Meta: class AudioDecision(AbstractMediaDecision): - """Represents moderation decisions taken for audio tracks.""" + """Moderation decisions taken for audio tracks.""" media_class = Audio @@ -349,7 +349,7 @@ class AudioDecision(AbstractMediaDecision): class AudioList(AbstractMediaList): - """Represents a list of audio files. Currently unused.""" + """A list of audio files. Currently unused.""" audios = models.ManyToManyField( Audio, diff --git a/api/api/models/image.py b/api/api/models/image.py index d0d0b67ef6d..4faef17d0dd 100644 --- a/api/api/models/image.py +++ b/api/api/models/image.py @@ -43,7 +43,7 @@ class Meta: class Image(ImageFileMixin, AbstractMedia): """ - Represents one image media instance. + One image media instance. Inherited fields ================ @@ -60,7 +60,7 @@ def sensitive(self) -> bool: class DeletedImage(AbstractDeletedMedia): """ - Represents images deleted from the upstream source. + Images deleted from the upstream source. Do not create instances of this model manually. Create an ``ImageReport`` instance instead. @@ -83,7 +83,7 @@ class DeletedImage(AbstractDeletedMedia): class SensitiveImage(AbstractSensitiveMedia): """ - Represents images with verified sensitivity reports. + Images with verified sensitivity reports. Do not create instances of this model manually. Create an ``ImageReport`` instance instead. @@ -139,7 +139,7 @@ class Meta: class ImageDecision(AbstractMediaDecision): - """Represents moderation decisions taken for images.""" + """Moderation decisions taken for images.""" media_class = Image @@ -151,7 +151,7 @@ class ImageDecision(AbstractMediaDecision): class ImageList(AbstractMediaList): - """Represents a list of images. Currently unused.""" + """A list of images. Currently unused.""" images = models.ManyToManyField( Image, diff --git a/api/api/models/media.py b/api/api/models/media.py index 3f6151d6de3..8c58d6223e6 100644 --- a/api/api/models/media.py +++ b/api/api/models/media.py @@ -1,6 +1,6 @@ import logging import mimetypes -from textwrap import dedent as d +from textwrap import dedent from django.conf import settings from django.core.exceptions import ValidationError @@ -87,8 +87,7 @@ class AbstractMedia( tags = models.JSONField( blank=True, null=True, - help_text=d( - """ + help_text=dedent(""" JSON array of objects containing tags for the media. Each tag object is expected to have: @@ -98,8 +97,7 @@ class AbstractMedia( for that label expressed as a value between 0 and 1. Note that only `name` and `accuracy` are presently surfaced in API results. - """ - ), + """), ) category = models.CharField( @@ -113,14 +111,12 @@ class AbstractMedia( meta_data = models.JSONField( blank=True, null=True, - help_text=d( - """ + help_text=dedent(""" JSON object containing extra data about the media item. No fields are expected, but if the `license_url` field is available, it will be used for determining the license URL for the media item. The `description` field, if available, is also indexed into Elasticsearch and as a search field on queries. - """ - ), + """), ) @property diff --git a/documentation/meta/media_properties/api.md b/documentation/meta/media_properties/api.md index 5e55205535b..d829a25015c 100644 --- a/documentation/meta/media_properties/api.md +++ b/documentation/meta/media_properties/api.md @@ -86,10 +86,10 @@ Each object is expected to contain: #### `audio_report` -**Model docstring:** Represents audio tracks that have been reported by users. +**Model docstring:** User-submitted reports of audio tracks. -This contains an `AudioDecision` as well, if moderators have made a decision for -this report. +`AudioDecision` is populated only if moderators have made a decision for this +report. (Audio-audio_set_foreign_identifier-notes)= @@ -107,7 +107,7 @@ this report. #### `audiodecision` -**Model docstring:** Represents moderation decisions taken for audio tracks. +**Model docstring:** Moderation decisions taken for audio tracks. (Audio-audioset-notes)= @@ -152,8 +152,7 @@ The FileMixin inherited by this model refers not to audio but album art. #### `deleted_audio` -**Model docstring:** Represents audio tracks that have been deleted from the -source. +**Model docstring:** Audio tracks deleted from the upstream source. Do not create instances of this model manually. Create an `AudioReport` instance instead. @@ -230,7 +229,7 @@ explicitly. #### `lists` -**Model docstring:** Represents a list of audio files. Currently unused. +**Model docstring:** A list of audio files. Currently unused. (Audio-meta_data-notes)= @@ -251,8 +250,7 @@ available, is also indexed into Elasticsearch and as a search field on queries. #### `removed_from_source` -**Help text:** Whether or not the media has been removed from the upstream -source. +**Help text:** Whether the media has been removed from the upstream source. (Audio-sample_rate-notes)= @@ -264,8 +262,7 @@ source. #### `sensitive_audio` -**Model docstring:** Represents audio tracks that have been flagged and verified -as 'mature'. +**Model docstring:** Audio tracks with verified sensitivity reports. Do not create instances of this model manually. Create an `AudioReport` instance instead. @@ -389,7 +386,7 @@ Note that only `name` and `accuracy` are presently surfaced in API results. #### `deleted_image` -**Model docstring:** Represents images that have been deleted from the source. +**Model docstring:** Images deleted from the upstream source. Do not create instances of this model manually. Create an `ImageReport` instance instead. @@ -441,7 +438,7 @@ explicitly. #### `image_report` -**Model docstring:** Represents images that have been reported by users. +**Model docstring:** User-submitted report of an image. This contains an `ImageDecision` as well, if moderators have made a decision for this report. @@ -450,7 +447,7 @@ this report. #### `imagedecision` -**Model docstring:** Represents moderation decisions taken for images. +**Model docstring:** Moderation decisions taken for images. (Image-last_synced_with_source-notes)= @@ -474,7 +471,7 @@ this report. #### `lists` -**Model docstring:** Represents a list of images. Currently unused. +**Model docstring:** A list of images. Currently unused. (Image-meta_data-notes)= @@ -495,15 +492,13 @@ available, is also indexed into Elasticsearch and as a search field on queries. #### `removed_from_source` -**Help text:** Whether or not the media has been removed from the upstream -source. +**Help text:** Whether the media has been removed from the upstream source. (Image-sensitive_image-notes)= #### `sensitive_image` -**Model docstring:** Represents images that have been flagged and verified as -'mature'. +**Model docstring:** Images with verified sensitivity reports. Do not create instances of this model manually. Create an `ImageReport` instance instead.