diff --git a/modules/mailpit/testcontainers/mailpit/__init__.py b/modules/mailpit/testcontainers/mailpit/__init__.py index c18a679a..5628e525 100644 --- a/modules/mailpit/testcontainers/mailpit/__init__.py +++ b/modules/mailpit/testcontainers/mailpit/__init__.py @@ -33,7 +33,35 @@ class MailpitUser(NamedTuple): - """Mailpit user for authentication""" + """Mailpit user for authentication + + Helper class to define a user for Mailpit authentication. + + Is just a named tuple with username and password. + + + Example: + + .. doctest:: + + >>> from testcontainers.mailpit import MailpitUser + + >>> users = [ + ... MailpitUser("jane", "secret"), + ... MailpitUser("ron", "pass2"), + ... ] + + >>> for user in users: + ... print(user.username, user.password) + ... + jane secret + ron pass2 + + >>> username, password = users[0] + + >>> print(username, password) + jane secret + """ username: str password: str @@ -47,11 +75,12 @@ class MailpitContainer(DockerContainer): user/password. Options: - - ``require_tls = True`` forces the use of SSL - - ``users = [MailpitUser("jane", "secret"), MailpitUser("ron", "pass2")]`` + + * ``require_tls = True`` forces the use of SSL + * ``users = [MailpitUser("jane", "secret"), MailpitUser("ron", "pass2")]`` \ only allows login with ``jane:secret`` or ``ron:pass2`` - Example: + Simple example: .. doctest:: @@ -69,6 +98,27 @@ class MailpitContainer(DockerContainer): ... code, _ = server.login("any", "auth") ... assert code == 235 # authentication successful ... # use server.sendmail(...) to send emails + + Example with auth and forced TLS: + + .. doctest:: + + >>> import smtplib + + >>> from testcontainers.mailpit import MailpitContainer, MailpitUser + + >>> users = [MailpitUser("jane", "secret"), MailpitUser("ron", "pass2")] + + >>> with MailpitContainer(users=users, require_tls=True) as mailpit_container: + ... host_ip = mailpit_container.get_container_host_ip() + ... host_port = mailpit_container.get_exposed_smtp_port() + ... server = smtplib.SMTP_SSL( + ... mailpit_container.get_container_host_ip(), + ... mailpit_container.get_exposed_smtp_port(), + ... ) + ... code, _ = server.login("jane", "secret") + ... assert code == 235 # authentication successful + ... # use server.sendmail(...) to send emails """ def __init__(