`duck.utils.email.collection`¶

Module Contents¶

Classes¶

EmailCollector

Email collection utility.

Functions¶

`async_collect_email`	Shortcut to collect an email asynchronously.
`collect_email`	Shortcut to collect an email synchronously.

API¶

class duck.utils.email.collection.EmailCollector¶

Email collection utility.

Provides an interface for registering callbacks that handle email collection, supporting both synchronous and asynchronous usages, plus email storage and retrieval.

_async_callback: Optional[Callable[[str, Optional[str]], Awaitable[None]]]¶: None

_emails: List[Tuple[str, Optional[str]]]¶: []

_sync_callback: Optional[Callable[[str, Optional[str]], None]]¶: None

async classmethod async_collect_email(email: str, category: Optional[str] = None)¶

Collect an email using the registered asynchronous callback.

Parameters:

email – The email address to collect.
category – The category of the email collection.

Raises:

TypeError – If an asynchronous callback is not registered.

classmethod collect_email(email: str, category: Optional[str] = None)¶

Collect an email using the registered synchronous callback.

Parameters:

email – The email address to collect.
category – The category of the email collection.

Raises:

TypeError – If a synchronous callback is not registered.

classmethod get_collected_emails() → List[Tuple[str, Optional[str]]]¶

Get a list of all collected emails with their categories.

Returns:: A list of tuples (email, category).
Return type:: List[Tuple[str, Optional[str]]]

… admonition:: Notes

This only returns collected emails within current session. This doesn’t persist between application life cycle. To get persistent emails, implement custom logic for retrieving emails e.g. retrieving from Database.

classmethod register(callback: Union[Callable[[str, Optional[str]], None], Callable[[str, Optional[str]], Awaitable[None]]])¶

Register a callback for email collection.

Parameters:: callback – A synchronous or asynchronous callable to call on email collection.
Raises:: AssertionError – If callback is not callable.

async duck.utils.email.collection.async_collect_email(email: str, category: Optional[str] = None)¶: Shortcut to collect an email asynchronously.

duck.utils.email.collection.collect_email(email: str, category: Optional[str] = None)¶: Shortcut to collect an email synchronously.

Email collection utility.¶

Provides an interface for registering callbacks that handle email collection, supporting both synchronous and asynchronous usages.

Example:¶

# urls.py / some entry module
from duck.utils.email.collection import EmailCollector

def collect(email, category = None):
    # Do your logic for saving email e.g. saving to a Database
    pass

async def async_collect(email, category = None):
    # Do your async logic for saving email e.g. saving to a Database
    pass

# Register callbacks for saving emails.
EmailCollector.register(collect) # Register sync callback
EmailCollector.register(async_collect) # Register async callback

# some module
from duck.utils.email.collection import async_collect_email, collect_email

# From some callback, collect email
def process_request(request):
    # Do some request processing
    email = request.POST.get("email")
    collect_email(email, category="Newsletter")


async def async_process_request(request):
    # Do some request processing
    email = request.POST.get("email")
    await async_collect_email(email, category="Newsletter")

Obligations When Collecting Emails¶

When collecting email addresses from users, you have important legal and ethical obligations, including:

Transparency: Clearly inform users why their email is being collected and how it will be used.
Consent: Obtain explicit consent from users before collecting or using their emails, especially for marketing or newsletters.
Data Minimization: Only collect email addresses (and related data) that are strictly necessary for your stated purpose.
Security: Store collected emails securely and protect them from unauthorized access or breaches.
Privacy Compliance: Follow relevant data protection laws (such as GDPR, CCPA, etc.), including providing users with access to, and the ability to delete, their data upon request.
No Unsolicited Communication: Do not send unsolicited emails or share user emails with third parties without explicit permission.

Respecting user privacy builds trust and helps you stay compliant with global regulations.

duck.utils.email.collection¶