mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-24 22:26:08 +00:00
Code Issues 32 Releases Wiki Activity

Refs #27656 -- Updated django.core docstring verbs according to PEP 257.

Browse Source
This commit is contained in:
Anton Samarchyan
2017-01-25 14:02:33 -05:00
committed by Tim Graham
parent 3eb679a869
commit 5a6f70b428
38 changed files with 200 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
django/core/mail/__init__.py
View File

@@ -26,7 +26,7 @@ __all__ = [
def get_connection(backend=None, fail_silently=False, **kwds):
"""Load an email backend and return an instance of it.
If backend is None (default) settings.EMAIL_BACKEND is used.
If backend is None (default), use settings.EMAIL_BACKEND.
Both fail_silently and other keyword arguments are used in the
constructor of the backend.
@@ -42,8 +42,8 @@ def send_mail(subject, message, from_email, recipient_list,
Easy wrapper for sending a single message to a recipient list. All members
of the recipient list will see the other recipients in the 'To' field.
If auth_user is None, the EMAIL_HOST_USER setting is used.
If auth_password is None, the EMAIL_HOST_PASSWORD setting is used.
If auth_user is None, use the EMAIL_HOST_USER setting.
If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
Note: The API for this method is frozen. New code wanting to extend the
functionality should use the EmailMessage class directly.
@@ -63,13 +63,13 @@ def send_mail(subject, message, from_email, recipient_list,
def send_mass_mail(datatuple, fail_silently=False, auth_user=None,
auth_password=None, connection=None):
"""
Given a datatuple of (subject, message, from_email, recipient_list), sends
each message to each recipient list. Returns the number of emails sent.
Given a datatuple of (subject, message, from_email, recipient_list), send
each message to each recipient list. Return the number of emails sent.
If from_email is None, the DEFAULT_FROM_EMAIL setting is used.
If auth_user and auth_password are set, they're used to log in.
If auth_user is None, the EMAIL_HOST_USER setting is used.
If auth_password is None, the EMAIL_HOST_PASSWORD setting is used.
If from_email is None, use the DEFAULT_FROM_EMAIL setting.
If auth_user and auth_password are set, use them to log in.
If auth_user is None, use the EMAIL_HOST_USER setting.
If auth_password is None, use the EMAIL_HOST_PASSWORD setting.
Note: The API for this method is frozen. New code wanting to extend the
functionality should use the EmailMessage class directly.
@@ -88,7 +88,7 @@ def send_mass_mail(datatuple, fail_silently=False, auth_user=None,
def mail_admins(subject, message, fail_silently=False, connection=None,
html_message=None):
"""Sends a message to the admins, as defined by the ADMINS setting."""
"""Send a message to the admins, as defined by the ADMINS setting."""
if not settings.ADMINS:
return
mail = EmailMultiAlternatives(
@@ -103,7 +103,7 @@ def mail_admins(subject, message, fail_silently=False, connection=None,
def mail_managers(subject, message, fail_silently=False, connection=None,
html_message=None):
"""Sends a message to the managers, as defined by the MANAGERS setting."""
"""Send a message to the managers, as defined by the MANAGERS setting."""
if not settings.MANAGERS:
return
mail = EmailMultiAlternatives(

9
django/core/mail/backends/base.py
View File

@@ -7,8 +7,8 @@ class BaseEmailBackend:
Subclasses must at least overwrite send_messages().
open() and close() can be called indirectly by using a backend object as a
context manager:
open() and close() can be called indirectly by using a backend object as a
context manager:
with backend as connection:
# do something with connection
@@ -18,7 +18,8 @@ class BaseEmailBackend:
self.fail_silently = fail_silently
def open(self):
"""Open a network connection.
"""
Open a network connection.
This method can be overwritten by backend implementations to
open a network connection.
@@ -52,7 +53,7 @@ class BaseEmailBackend:
def send_messages(self, email_messages):
"""
Sends one or more EmailMessage objects and returns the number of email
Send one or more EmailMessage objects and return the number of email
messages sent.
"""
raise NotImplementedError('subclasses of BaseEmailBackend must override send_messages() method')

3
django/core/mail/backends/locmem.py
View File

@@ -7,7 +7,8 @@ from django.core.mail.backends.base import BaseEmailBackend
class EmailBackend(BaseEmailBackend):
"""A email backend for use during test sessions.
"""
An email backend for use during test sessions.
The test connection stores email messages in a dummy outbox,
rather than sending them out on the wire.

4
django/core/mail/backends/smtp.py
View File

@@ -74,7 +74,7 @@ class EmailBackend(BaseEmailBackend):
raise
def close(self):
"""Closes the connection to the email server."""
"""Close the connection to the email server."""
if self.connection is None:
return
try:
@@ -94,7 +94,7 @@ class EmailBackend(BaseEmailBackend):
def send_messages(self, email_messages):
"""
Sends one or more EmailMessage objects and returns the number of email
Send one or more EmailMessage objects and return the number of email
messages sent.
"""
if not email_messages:

37
django/core/mail/message.py
View File

@@ -53,7 +53,7 @@ ADDRESS_HEADERS = {
def forbid_multi_line_headers(name, val, encoding):
"""Forbids multi-line headers, to prevent header injection."""
"""Forbid multi-line headers to prevent header injection."""
encoding = encoding or settings.DEFAULT_CHARSET
val = force_text(val)
if '\n' in val or '\r' in val:
@@ -73,7 +73,7 @@ def forbid_multi_line_headers(name, val, encoding):
def split_addr(addr, encoding):
"""
Split the address into local part and domain, properly encoded.
Split the address into local part and domain and encode them.
When non-ascii characters are present in the local part, it must be
MIME-word encoded. The domain name must be idna-encoded if it contains
@@ -193,9 +193,7 @@ class SafeMIMEMultipart(MIMEMixin, MIMEMultipart):
class EmailMessage:
"""
A container for email information.
"""
"""A container for email information."""
content_subtype = 'plain'
mixed_subtype = 'mixed'
encoding = None # None => use settings default
@@ -280,13 +278,13 @@ class EmailMessage:
def recipients(self):
"""
Returns a list of all recipients of the email (includes direct
Return a list of all recipients of the email (includes direct
addressees as well as Cc and Bcc entries).
"""
return [email for email in (self.to + self.cc + self.bcc) if email]
def send(self, fail_silently=False):
"""Sends the email message."""
"""Send the email message."""
if not self.recipients():
# Don't bother creating the network connection if there's nobody to
# send to.
@@ -295,16 +293,15 @@ class EmailMessage:
def attach(self, filename=None, content=None, mimetype=None):
"""
Attaches a file with the given filename and content. The filename can
Attach a file with the given filename and content. The filename can
be omitted and the mimetype is guessed, if not provided.
If the first parameter is a MIMEBase subclass it is inserted directly
If the first parameter is a MIMEBase subclass, insert it directly
into the resulting message attachments.
For a text/* mimetype (guessed or specified), when a bytes object is
specified as content, it will be decoded as UTF-8. If that fails,
the mimetype will be set to DEFAULT_ATTACHMENT_MIME_TYPE and the
content is not decoded.
specified as content, decode it as UTF-8. If that fails, set the
mimetype to DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
"""
if isinstance(filename, MIMEBase):
assert content is None
@@ -332,14 +329,14 @@ class EmailMessage:
def attach_file(self, path, mimetype=None):
"""
Attaches a file from the filesystem.
Attach a file from the filesystem.
The mimetype will be set to the DEFAULT_ATTACHMENT_MIME_TYPE if it is
not specified and cannot be guessed.
Set the mimetype to DEFAULT_ATTACHMENT_MIME_TYPE if it isn't specified
and cannot be guessed.
For a text/* mimetype (guessed or specified), the file's content
will be decoded as UTF-8. If that fails, the mimetype will be set to
DEFAULT_ATTACHMENT_MIME_TYPE and the content is not decoded.
For a text/* mimetype (guessed or specified), decode the file's content
as UTF-8. If that fails, set the mimetype to
DEFAULT_ATTACHMENT_MIME_TYPE and don't decode the content.
"""
filename = os.path.basename(path)
@@ -366,7 +363,7 @@ class EmailMessage:
def _create_mime_attachment(self, content, mimetype):
"""
Converts the content, mimetype pair into a MIME attachment object.
Convert the content, mimetype pair into a MIME attachment object.
If the mimetype is message/rfc822, content may be an
email.Message or EmailMessage object, as well as a str.
@@ -396,7 +393,7 @@ class EmailMessage:
def _create_attachment(self, filename, content, mimetype=None):
"""
Converts the filename, content, mimetype triple into a MIME attachment
Convert the filename, content, mimetype triple into a MIME attachment
object.
"""
attachment = self._create_mime_attachment(content, mimetype)