improve docs

anchor/forms/fields.py

@@ -1,7 +1,7 @@
 from django import forms
 
-from .widgets import ClearableBlobInput
+from .widgets import SingleAttachmentInput
 
 
-class BlobField(forms.FileField):
-    widget = ClearableBlobInput
+class SingleAttachmentField(forms.FileField):
+    widget = SingleAttachmentInput

anchor/forms/widgets.py

@@ -1,10 +1,10 @@
 from django.forms.widgets import ClearableFileInput
 
 
-class ClearableBlobInput(ClearableFileInput):
+class SingleAttachmentInput(ClearableFileInput):
     # make this widget work with the Django admin
     choices = []
 
 
-class AdminBlobInput(ClearableBlobInput):
+class AdminSingleAttachmentInput(SingleAttachmentInput):
     template_name = "anchor/widgets/admin_blob_input.html"

anchor/management/commands/anchor_purge_unattached.py

@@ -5,6 +5,8 @@
 
 
 class Command(BaseCommand):
+    help = "Purge and delete blobs not used by any attachment"
+
     def add_arguments(self, parser):
         parser.add_argument(
             "--dry-run", action="store_true", help="Dry run the command"

anchor/models/attachment.py

@@ -1,17 +1,18 @@
 from typing import Any
 
 from django.contrib.contenttypes.fields import GenericForeignKey
-from django.contrib.contenttypes.models import ContentType
 from django.db import models
 
 from anchor.models.base import BaseModel
 
 
-class AttachmentManager(models.Manager):
-    pass
+class Attachment(BaseModel):
+    """
+    An attachment relates your own models to Blobs.
 
+    Most properties are proxies to the Blob.
+    """
 
-class Attachment(BaseModel):
     class Meta:
         constraints = (
             models.constraints.UniqueConstraint(
@@ -26,8 +27,6 @@ class Meta:
             ),
         )
 
-    objects = AttachmentManager()
-
     blob = models.ForeignKey(
         "anchor.Blob",
         on_delete=models.PROTECT,
@@ -36,37 +35,77 @@ class Meta:
         blank=True,
         verbose_name="blob",
     )
+    """
+    A reference to the Blob which stores the file for this attachment.
+    """
 
     content_type = models.ForeignKey(
-        ContentType,
+        "contenttypes.ContentType",
         on_delete=models.CASCADE,
         verbose_name="content type",
         db_index=False,
         related_name="+",
     )
+    """
+    Content Type (as in Django content types) of the object this attachment
+    points to.
+    """
+
     object_id = models.CharField(max_length=64, verbose_name="object id")
+    """
+    ID of the object this attachment points to.
+    """
+
     content_object = GenericForeignKey("content_type", "object_id")
+    """
+    The actual object this attachment points to.
+    """
 
     order = models.IntegerField(default=0, verbose_name="order")
+    """
+    The order of this attachment in the list of attachments.
+    """
+
     name = models.CharField(max_length=256, default="attachments", verbose_name="name")
+    """
+    The name of this attachment.
+    """
 
     def __str__(self) -> str:
         return str(self.blob)
 
     def url(self, **kwargs):
+        """
+        Returns a URL to the file's location in the storage backend.
+        """
         return self.blob.url(**kwargs)
 
     @property
     def signed_id(self):
+        """
+        Returns a signed ID for this attachment.
+        """
         return self.blob.signed_id
 
     @property
     def filename(self):
+        """
+        The filename of the file stored in the storage backend.
+        """
         return self.blob.filename
 
     @property
     def is_image(self) -> bool:
+        """
+        Whether the file is an image.
+        """
         return self.blob.is_image
 
     def representation(self, transformations: dict[str, Any]):
+        """
+        Returns a representation of the file. See :py:class:`the docs on
+        representations
+        <anchor.models.blob.representations.RepresentationsMixin>` for full
+        details.
+        """
         return self.blob.representation(transformations)

anchor/models/base.py

@@ -2,7 +2,6 @@
 
 from django.db import models
 from django.utils import timezone
-from django.utils.translation import gettext_lazy as _
 
 from anchor.support import base58
 
@@ -11,6 +10,11 @@
 
 
 def generate_pk():
+    """
+    Generates a primary key with the same entropy as a UUID but encoded in
+    base58, which works much nicer with URLs than the default hex-based UUID
+    encoding.
+    """
     return (
         base58.b58encode(uuid.uuid4().bytes, alphabet=SHORT_UUID_ALPHABET)
         .decode("ascii")
@@ -26,9 +30,7 @@ class BaseModel(models.Model):
         editable=False,
         default=generate_pk,
     )
-    created_at = models.DateTimeField(
-        default=timezone.now, verbose_name=_("created at")
-    )
+    created_at = models.DateTimeField(default=timezone.now, verbose_name="created at")
 
     class Meta:
         abstract = True