django-ctct 0.0.1.dev2__tar.gz → 0.0.1.dev4__tar.gz

{django_ctct-0.0.1.dev2 → django_ctct-0.0.1.dev4}/PKG-INFO

@@ -1,20 +1,19 @@
 Metadata-Version: 2.3
 Name: django-ctct
-Version: 0.0.1.dev2
+Version: 0.0.1.dev4
 Summary: A Django interface for the Constant Contact API
 License: MIT
 Author: Geoffrey Eisenbarth
 Author-email: geoffrey.eisenbarth@gmail.com
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: django (>=3.2.0,<6.0.0)
-Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
+Requires-Dist: pyjwt[crypto] (>=2.10.1,<3.0.0)
 Requires-Dist: ratelimit (>=2.2.1,<3.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Requires-Dist: tqdm (>=4.67.1,<5.0.0)

{django_ctct-0.0.1.dev2 → django_ctct-0.0.1.dev4}/django_ctct/admin.py

@@ -1,23 +1,24 @@
 import functools
-from typing import List, Optional
-
+from typing import TypeVar, ParamSpec, Generic, Optional, Callable, Iterable
 from requests.exceptions import HTTPError
 
 from django import forms
 from django.conf import settings
 from django.contrib import admin, messages
+from django.contrib.auth import get_user_model
 from django.db.models import signals
-from django.db.models import Model, QuerySet
-from django.forms import ModelForm
+from django.db.models import Model, QuerySet, When, Case, F, FloatField
+from django.db.models.functions import Cast
+from django.forms import ModelForm, BaseFormSet
 from django.forms.models import BaseInlineFormSet
 from django.http import HttpRequest
+from django.urls import reverse
 from django.utils.html import format_html
 from django.utils.formats import date_format
-from django.utils.safestring import mark_safe
-from django.utils.translation import gettext_lazy as _
+from django.utils.translation import gettext as _
 
 from django_ctct.models import (
-  Token, CTCTRemoteModel, ContactList, CustomField,
+  CTCTEndpointModel, ContactList, CustomField,
   Contact,
   ContactCustomField, ContactStreetAddress, ContactPhoneNumber, ContactNote,
   EmailCampaign, CampaignActivity, CampaignSummary,
@@ -26,46 +27,81 @@ from django_ctct.signals import remote_save, remote_delete
 from django_ctct.vendor import mute_signals
 
 
-def catch_api_errors(func):
-  """Decorator to catch HTTP errors from CTCT API."""
+P = ParamSpec('P')
+M = TypeVar('M', bound=Model)
+E = TypeVar('E', bound=CTCTEndpointModel)
+
+
+def catch_api_errors(func: Callable[P, None]) -> Callable[P, None]:
+  """Decorator to catch HTTP errors from CTCT API.
+
+  Notes
+  -----
+  If the wrapped functioms (e.g., `save_related()` didn't return `None`, then
+  we would need to adjust the types above to `Callable[P, R]`, where R is
+  defined as TypeVar('R').
+
+  """
 
   @functools.wraps(func)
-  def wrapper(self, request, *args, **kwargs):
+  def wrapper(*args: P.args, **kwargs: P.kwargs) -> None:
     try:
-      return func(self, request, *args, **kwargs)
+      return func(*args, **kwargs)
     except HTTPError as e:
       if getattr(settings, 'CTCT_RAISE_FOR_API', False):
         raise e
       else:
-        message = format_html(_(f"ConstantContact: {e}"))
-        self.message_user(request, message, level=messages.ERROR)
+        self, request, *_ = args
+        assert isinstance(self, admin.ModelAdmin)
+        assert isinstance(request, HttpRequest)
+        self.message_user(
+          request=request,
+          message=format_html(_(f"ConstantContact: {e}")),
+          level=messages.ERROR,
+        )
 
   return wrapper
 
 
 class RemoteSyncMixin:
-  def is_synced(self, obj: CTCTRemoteModel) -> bool:
+  @admin.display(
+    boolean=True,
+    description=_('Synced'),
+    ordering='api_id',
+  )
+  def is_synced(self, obj: CTCTEndpointModel) -> bool:
     return (obj.api_id is not None)
-  is_synced.boolean = True
-  is_synced.admin_order_field = 'api_id'
-  is_synced.short_description = _('Synced')
 
 
-class ViewModelAdmin(admin.ModelAdmin):
+class ViewModelAdmin(admin.ModelAdmin[Model]):
   """Remove CRUD permissions."""
 
-  def has_add_permission(self, request: HttpRequest, obj=None):
+  actions = None
+
+  def has_add_permission(
+    self,
+    request: HttpRequest,
+    obj: Optional[Model] = None,
+  ) -> bool:
     """Prevent creation in the Django admin."""
     return False
 
-  def has_change_permission(self, request: HttpRequest, obj=None):
+  def has_change_permission(
+    self,
+    request: HttpRequest,
+    obj: Optional[Model] = None,
+  ) -> bool:
     """Prevent updates in the Django admin."""
     return False
 
-  def get_readonly_fields(self, request: HttpRequest, obj=None):
+  def get_readonly_fields(
+    self,
+    request: HttpRequest,
+    obj: Optional[Model] = None,
+  ) -> tuple[str, ...]:
     """Prevent updates in the Django admin."""
     if obj is not None:
-      readonly_fields = (
+      readonly_fields = tuple(
         field.name
         for field in obj._meta.fields
         if field.name != 'active'
@@ -74,44 +110,18 @@ class ViewModelAdmin(admin.ModelAdmin):
       readonly_fields = tuple()
     return readonly_fields
 
-  def has_delete_permission(self, request: HttpRequest, obj=None):
-    """Prevent deletion in the Django admin."""
-    return False
-
-
-class TokenAdmin(ViewModelAdmin):
-  """Admin functionality for CTCT Tokens."""
-
-  # ListView
-  list_display_links = None
-  list_display = (
-    'scope',
-    'created_at',
-    'expires_at',
-    'copy_access_token',
-    'copy_refresh_token',
-  )
-
-  def copy_access_token(self, obj: Token) -> str:
-    html = format_html(
-      '<button class="button" onclick="{function}">{copy_icon}</button>',
-      function=f"navigator.clipboard.writeText('{obj.access_token}')",
-      copy_icon=mark_safe('&#128203;'),
-    )
-    return html
-  copy_access_token.short_description = _('Access Token')
-
-  def copy_refresh_token(self, obj: Token) -> str:
-    html = format_html(
-      '<button class="button" onclick="{function}">{copy_icon}</button>',
-      function=f"navigator.clipboard.writeText('{obj.refresh_token}')",
-      copy_icon=mark_safe('&#128203;'),
-    )
-    return html
-  copy_refresh_token.short_description = _('Refresh Token')
+  def has_delete_permission(
+    self,
+    request: HttpRequest,
+    obj: Optional[Model] = None,
+  ) -> bool:
+    """Allow superusers to delete objects."""
+    return request.user.is_superuser
 
 
-class RemoteModelAdmin(RemoteSyncMixin, admin.ModelAdmin):
+class RemoteModelAdmin(
+  RemoteSyncMixin, admin.ModelAdmin[E], Generic[E]
+):
   """Facilitate remote saving and deleting."""
 
   # ChangeView
@@ -122,20 +132,30 @@ class RemoteModelAdmin(RemoteSyncMixin, admin.ModelAdmin):
     return sync_admin and not sync_signals
 
   @catch_api_errors
-  def delete_model(self, request: HttpRequest, obj: Model):
+  def delete_model(self, request: HttpRequest, obj: Model) -> None:
     obj.delete()
     if self.remote_sync:
       remote_delete(sender=self.model, instance=obj)
 
   @catch_api_errors
-  def delete_queryset(self, request: HttpRequest, queryset: QuerySet):
+  def delete_queryset(
+    self,
+    request: HttpRequest,
+    queryset: QuerySet[CTCTEndpointModel],
+  ) -> None:
     if self.remote_sync:
       queryset.model.remote.bulk_delete(queryset)
     with mute_signals(signals.pre_delete):
       queryset.delete()
 
   @catch_api_errors
-  def save_related(self, request: HttpRequest, form, formsets, change):
+  def save_related(
+    self,
+    request: HttpRequest,
+    form: ModelForm[CTCTEndpointModel],
+    formsets: list[BaseFormSet[ModelForm[Model]]],
+    change: bool,
+  ) -> None:
     """Default implementation with an added line for saving remotely.
 
     Notes
@@ -144,13 +164,21 @@ class RemoteModelAdmin(RemoteSyncMixin, admin.ModelAdmin):
     for saving objects remotely.
 
     """
-    form.save_m2m()
+    with mute_signals(signals.m2m_changed):
+      # ManyToMany information is sent to CTCT in PUT call
+      form.save_m2m()
     for formset in formsets:
       self.save_formset(request, form, formset, change=change)
     self.save_remotely(request, form, formsets, change)
 
   @catch_api_errors
-  def save_remotely(self, request, form, formsets, change):
+  def save_remotely(
+    self,
+    request: HttpRequest,
+    form: ModelForm[CTCTEndpointModel],
+    formsets: list[BaseFormSet[ModelForm[Model]]],
+    change: bool,
+  ) -> None:
     if self.remote_sync:
       # Remote save the primary object after related objects have been saved
       remote_save(
@@ -160,7 +188,7 @@ class RemoteModelAdmin(RemoteSyncMixin, admin.ModelAdmin):
       )
 
 
-class ContactListForm(forms.ModelForm):
+class ContactListForm(forms.ModelForm[ContactList]):
   """Custom widget choices for ContactList admin."""
 
   class Meta:
@@ -171,7 +199,7 @@ class ContactListForm(forms.ModelForm):
     fields = '__all__'
 
 
-class ContactListAdmin(RemoteModelAdmin):
+class ContactListAdmin(RemoteModelAdmin[ContactList]):
   """Admin functionality for CTCT ContactLists."""
 
   # ListView
@@ -185,13 +213,13 @@ class ContactListAdmin(RemoteModelAdmin):
     'is_synced',
   )
 
+  @admin.display(description=_('Membership'))
   def membership(self, obj: ContactList) -> int:
     return obj.members.all().count()
-  membership.short_description = _('Membership')
 
+  @admin.display(description=_('Opt Outs'))
   def optouts(self, obj: ContactList) -> int:
     return obj.members.exclude(opt_out_source='').count()
-  optouts.short_description = _('Opt Outs')
 
   # ChangeView
   form = ContactListForm
@@ -205,7 +233,7 @@ class ContactListAdmin(RemoteModelAdmin):
   )
 
 
-class CustomFieldAdmin(RemoteModelAdmin):
+class CustomFieldAdmin(RemoteModelAdmin[CustomField]):
   """Admin functionality for CTCT CustomFields."""
 
   # ListView
@@ -213,6 +241,7 @@ class CustomFieldAdmin(RemoteModelAdmin):
     'label',
     'type',
     'created_at',
+    'updated_at',
     'is_synced',
   )
 
@@ -220,54 +249,58 @@ class CustomFieldAdmin(RemoteModelAdmin):
   exclude = ('api_id', )
 
 
-class ContactStreetAddressInline(admin.StackedInline):
+class ContactStreetAddressInline(
+  admin.StackedInline[ContactStreetAddress, Contact]
+):
   """Inline for adding ContactStreetAddresses to a Contact."""
 
   model = ContactStreetAddress
   exclude = ('api_id', )
 
   extra = 0
-  max_num = Contact.remote.API_MAX_STREET_ADDRESSES
+  max_num = Contact.API_MAX_NUM['street_addresses']
 
 
-class ContactPhoneNumberInline(admin.TabularInline):
+class ContactPhoneNumberInline(
+  admin.TabularInline[ContactPhoneNumber, Contact]
+):
   """Inline for adding ContactPhoneNumbers to a Contact."""
 
   model = ContactPhoneNumber
   exclude = ('api_id', )
 
   extra = 0
-  max_num = Contact.remote.API_MAX_PHONE_NUMBERS
+  max_num = Contact.API_MAX_NUM['phone_numbers']
 
 
-class ContactNoteInline(admin.TabularInline):
+class ContactNoteInline(admin.TabularInline[ContactNote, Contact]):
   """Inline for adding ContactNotes to a Contact."""
 
   model = ContactNote
-  exclude = ('api_id', )
+  fields = ('content', )
 
-  extra = 1
-  max_num = Contact.remote.API_MAX_NOTES
-
-  readonly_fields = ('author', 'created_at')
+  extra = 0
+  max_num = Contact.API_MAX_NUM['notes']
 
   def has_change_permission(
     self,
     request: HttpRequest,
-    obj: Optional[ContactNote] = None,
+    obj: Optional[Contact] = None,  # type: ignore[override]
   ) -> bool:
     return False
 
 
-class ContactCustomFieldInline(admin.TabularInline):
+class ContactCustomFieldInline(
+  admin.TabularInline[ContactCustomField, Contact]
+):
 
   model = ContactCustomField
   excldue = ('api_id', )
 
-  extra = 1
+  extra = 0
 
 
-class ContactAdmin(RemoteModelAdmin):
+class ContactAdmin(RemoteModelAdmin[Contact]):
   """Admin functionality for CTCT Contacts."""
 
   # ListView
@@ -294,11 +327,13 @@ class ContactAdmin(RemoteModelAdmin):
   )
   empty_value_display = '(None)'
 
+  @admin.display(
+    boolean=True,
+    description=_('Opted Out'),
+    ordering='opt_out_date',
+  )
   def opted_out(self, obj: Contact) -> bool:
     return bool(obj.opt_out_source)
-  opted_out.boolean = True
-  opted_out.admin_order_field = 'opt_out_date'
-  opted_out.short_description = _('Opted Out')
 
   # ChangeView
   fieldsets = (
@@ -336,8 +371,8 @@ class ContactAdmin(RemoteModelAdmin):
     self,
     request: HttpRequest,
     obj: Optional[Contact] = None,
-  ) -> List[str]:
-    readonly_fields = Contact.remote.API_READONLY_FIELDS
+  ) -> list[str]:
+    readonly_fields = list(Contact.API_READONLY_FIELDS)
     if obj and obj.opt_out_source and not request.user.is_superuser:
       readonly_fields.append('list_memberships')
     return readonly_fields
@@ -345,8 +380,8 @@ class ContactAdmin(RemoteModelAdmin):
   def save_formset(
     self,
     request: HttpRequest,
-    form: ModelForm,
-    formset: BaseInlineFormSet,
+    form: ModelForm[Contact],
+    formset: BaseInlineFormSet[M, Contact, ModelForm[M]],
     change: bool,
   ) -> None:
     """Set the current user as ContactNote author.
@@ -365,7 +400,35 @@ class ContactAdmin(RemoteModelAdmin):
       if isinstance(instance, ContactNote) and instance.pk is None:
         instance.author = request.user
       instance.save()
-    formset.save_m2m()
+
+    with mute_signals(signals.m2m_changed):
+      # ManyToMany information is sent to CTCT in PUT call
+      formset.save_m2m()
+
+
+class ContactNoteAuthorFilter(admin.SimpleListFilter):
+  """Only display Users that have authored a ContactNote."""
+
+  title = _('Author')
+  parameter_name = 'author'
+
+  def lookups(
+    self,
+    request: HttpRequest,
+    model_admin: admin.ModelAdmin[Model],
+  ) -> Optional[Iterable[tuple[str, str]]]:
+    authors = get_user_model().objects.exclude(notes__isnull=True)
+    return [(str(obj.id), str(obj)) for obj in authors]
+
+  def queryset(
+    self,
+    request: HttpRequest,
+    queryset: QuerySet[ContactNote],
+  ) -> QuerySet[ContactNote]:
+    author_id = self.value()
+    if author_id is not None and author_id.isdigit():
+      queryset = queryset.filter(author_id=int(author_id))
+    return queryset
 
 
 class ContactNoteAdmin(RemoteSyncMixin, ViewModelAdmin):
@@ -384,23 +447,39 @@ class ContactNoteAdmin(RemoteSyncMixin, ViewModelAdmin):
 
   list_display_links = None
   list_display = (
-    'contact',
+    'contact_link',
     'content',
-    'created_at',
     'author',
+    'created_at',
     'is_synced',
   )
   list_filter = (
     'created_at',
-    'author',
+    ContactNoteAuthorFilter,
   )
 
-  def has_delete_permission(self, request: HttpRequest, obj=None):
+  @admin.display(
+    description=_('Contact'),
+    ordering='contact__email',
+  )
+  def contact_link(self, obj: ContactNote) -> str:
+    url = reverse(
+      'admin:django_ctct_contact_change',
+      args=[obj.contact.pk],
+    )
+    html = format_html('<a href="{}">{}</a>', url, obj.contact)
+    return html
+
+  def has_delete_permission(
+    self,
+    request: HttpRequest,
+    obj: Optional[Model] = None,
+  ) -> bool:
     """Allow superusers to delete Notes."""
     return request.user.is_superuser
 
 
-class CampaignActivityInlineForm(forms.ModelForm):
+class CampaignActivityInlineForm(forms.ModelForm[CampaignActivity]):
   """Custom widget choices for ContactList admin."""
 
   html_content = forms.CharField(
@@ -413,7 +492,9 @@ class CampaignActivityInlineForm(forms.ModelForm):
     fields = '__all__'
 
 
-class CampaignActivityInline(admin.StackedInline):
+class CampaignActivityInline(
+  admin.StackedInline[CampaignActivity, EmailCampaign]
+):
   """Inline for adding CampaignActivity to a EmailCampaign."""
 
   model = CampaignActivity
@@ -432,23 +513,36 @@ class CampaignActivityInline(admin.StackedInline):
   extra = 1
   max_num = 1
 
-  def get_readonly_fields(self, request: HttpRequest, obj=None):
-    readonly_fields = CampaignActivity.remote.API_READONLY_FIELDS
+  def get_readonly_fields(
+    self,
+    request: HttpRequest,
+    obj: Optional[CampaignActivity] = None,
+  ) -> list[str]:
+    readonly_fields = list(CampaignActivity.API_READONLY_FIELDS)
     if obj and obj.current_status == 'DONE':
-      readonly_fields += CampaignActivity.remote.API_EDITABLE_FIELDS
+      readonly_fields += list(CampaignActivity.API_EDITABLE_FIELDS)
     return readonly_fields
 
 
-class EmailCampaignAdmin(RemoteModelAdmin):
-  """Admin functionality for CTCT EmailCampaigns."""
+class EmailCampaignAdmin(RemoteModelAdmin[EmailCampaign]):
+  """Admin functionality for CTCT EmailCampaigns.
+
+  Notes
+  -----
+  CTCT does not provide an endpoint for bulk deleting EmailCampaigns, so we set
+  `actions` to None.
+
+  """
 
   # ListView
+  actions = None
   search_fields = ('name', )
   list_display = (
     'name',
-    'updated_at',
     'current_status',
     'scheduled_datetime',
+    'created_at',
+    'updated_at',
     'is_synced',
   )
 
@@ -462,14 +556,24 @@ class EmailCampaignAdmin(RemoteModelAdmin):
   )
   inlines = (CampaignActivityInline, )
 
-  def get_readonly_fields(self, request: HttpRequest, obj=None):
-    readonly_fields = EmailCampaign.remote.API_READONLY_FIELDS
+  def get_readonly_fields(
+    self,
+    request: HttpRequest,
+    obj: Optional[EmailCampaign] = None,
+  ) -> list[str]:
+    readonly_fields = list(EmailCampaign.API_READONLY_FIELDS)
     if obj and obj.current_status == 'DONE':
-      readonly_fields += ('scheduled_datetime', )
+      readonly_fields.append('scheduled_datetime')
     return readonly_fields
 
   @catch_api_errors
-  def save_remotely(self, request, form, formsets, change) -> None:
+  def save_remotely(
+    self,
+    request: HttpRequest,
+    form: ModelForm[EmailCampaign],  # type: ignore[override]
+    formsets: list[BaseFormSet[ModelForm[Model]]],
+    change: bool,
+  ) -> None:
     if self.remote_sync:
 
       campaign = form.instance
@@ -502,7 +606,13 @@ class EmailCampaignAdmin(RemoteModelAdmin):
         # Inform the user
         self.ctct_message_user(request, form, formsets, change)
 
-  def ctct_message_user(self, request, form, formsets, change) -> None:
+  def ctct_message_user(
+    self,
+    request: HttpRequest,
+    form: ModelForm[EmailCampaign],
+    formsets: list[BaseFormSet[ModelForm[Model]]],
+    change: bool,
+  ) -> None:
     """Inform the user of API actions."""
 
     campaign = form.instance
@@ -543,21 +653,33 @@ class CampaignSummaryAdmin(ViewModelAdmin):
     'campaign',
     'open_rate',
     'sends',
+    'opens',
     'bounces',
     'clicks',
     'optouts',
     'abuse',
   )
 
+  def get_queryset(self, request: HttpRequest) -> QuerySet[Model]:
+    qs = super().get_queryset(request)
+    qs = qs.annotate(
+      open_rate=Case(
+        When(sends=0, then=0.0),
+        default=Cast(
+          F('opens') * 1.0 / F('sends'),  # Avoid int division
+          output_field=FloatField(),
+        ),
+      ),
+    )
+    return qs
+
+  @admin.display(
+    description=_('Open Rate'),
+    ordering='open_rate',
+  )
   def open_rate(self, obj: EmailCampaign) -> str:
-    if obj.current_status == 'DONE':
-      r = (obj.opens / obj.sends) if obj.sends else 0
-      s = f'{r:0.2%}'
-    else:
-      s = '-'
-    return s
-  open_rate.admin_order_field = 'open_rate'
-  open_rate.short_description = _('Open Rate')
+    assert hasattr(obj, 'open_rate')
+    return f'{obj.open_rate:0.0%}'
 
   # ChangeView
   fieldsets = (
@@ -576,7 +698,6 @@ class CampaignSummaryAdmin(ViewModelAdmin):
 
 
 if getattr(settings, 'CTCT_USE_ADMIN', False):
-  admin.site.register(Token, TokenAdmin)
   admin.site.register(ContactList, ContactListAdmin)
   admin.site.register(CustomField, CustomFieldAdmin)
   admin.site.register(Contact, ContactAdmin)

{django_ctct-0.0.1.dev2 → django_ctct-0.0.1.dev4}/django_ctct/apps.py

@@ -16,7 +16,7 @@ class CTCTConfig(AppConfig):
     'CTCT_FROM_EMAIL',
   ]
 
-  def ready(self):
+  def ready(self) -> None:
     # Validate that necessary settings have been defined
     for value in self.ctct_settings:
       if not hasattr(settings, value):