From 5a6f70b4281817656db2f36c5919036d38fcce7f Mon Sep 17 00:00:00 2001 From: Anton Samarchyan Date: Wed, 25 Jan 2017 14:02:33 -0500 Subject: [PATCH] Refs #27656 -- Updated django.core docstring verbs according to PEP 257. --- django/core/cache/__init__.py | 2 +- django/core/cache/backends/base.py | 54 ++++++++++--------- django/core/cache/backends/filebased.py | 5 +- django/core/cache/backends/memcached.py | 2 +- django/core/files/base.py | 16 ++---- django/core/files/images.py | 2 +- django/core/files/move.py | 11 ++-- django/core/files/storage.py | 22 ++++---- django/core/files/uploadedfile.py | 7 +-- django/core/files/uploadhandler.py | 11 ++-- django/core/handlers/wsgi.py | 13 ++--- django/core/mail/__init__.py | 22 ++++---- django/core/mail/backends/base.py | 9 ++-- django/core/mail/backends/locmem.py | 3 +- django/core/mail/backends/smtp.py | 4 +- django/core/mail/message.py | 37 ++++++------- django/core/management/__init__.py | 38 ++++++------- django/core/management/base.py | 8 +-- django/core/management/color.py | 6 +-- .../core/management/commands/diffsettings.py | 2 +- django/core/management/commands/loaddata.py | 10 ++-- .../core/management/commands/makemessages.py | 21 ++++---- .../management/commands/makemigrations.py | 2 +- django/core/management/commands/runserver.py | 8 +-- .../management/commands/showmigrations.py | 4 +- django/core/management/sql.py | 6 +-- django/core/management/templates.py | 16 +++--- django/core/management/utils.py | 4 +- django/core/paginator.py | 24 +++------ django/core/serializers/__init__.py | 2 +- django/core/serializers/json.py | 11 ++-- django/core/serializers/python.py | 6 +-- django/core/serializers/pyyaml.py | 8 +-- django/core/serializers/xml_serializer.py | 38 +++++-------- django/core/servers/basehttp.py | 4 +- django/core/signing.py | 18 +++---- django/core/validators.py | 8 ++- django/core/wsgi.py | 7 ++- 38 files changed, 200 insertions(+), 271 deletions(-) diff --git a/django/core/cache/__init__.py b/django/core/cache/__init__.py index d51c1cb38e..7aaa057229 100644 --- a/django/core/cache/__init__.py +++ b/django/core/cache/__init__.py @@ -59,7 +59,7 @@ class CacheHandler: """ A Cache Handler to manage access to Cache instances. - Ensures only one instance of each alias exists per thread. + Ensure only one instance of each alias exists per thread. """ def __init__(self): self._caches = local() diff --git a/django/core/cache/backends/base.py b/django/core/cache/backends/base.py index 2d5b0634a1..b5661891d6 100644 --- a/django/core/cache/backends/base.py +++ b/django/core/cache/backends/base.py @@ -26,7 +26,7 @@ def default_key_func(key, key_prefix, version): """ Default function to generate keys. - Constructs the key used by all other methods. By default it prepends + Construct the key used by all other methods. By default, prepend the `key_prefix'. KEY_FUNCTION can be used to specify an alternate function with custom key making behavior. """ @@ -37,7 +37,7 @@ def get_key_func(key_func): """ Function to decide which key function to use. - Defaults to ``default_key_func``. + Default to ``default_key_func``. """ if key_func is not None: if callable(key_func): @@ -76,7 +76,7 @@ class BaseCache: def get_backend_timeout(self, timeout=DEFAULT_TIMEOUT): """ - Returns the timeout value usable by this backend based upon the provided + Return the timeout value usable by this backend based upon the provided timeout. """ if timeout == DEFAULT_TIMEOUT: @@ -87,12 +87,12 @@ class BaseCache: return None if timeout is None else time.time() + timeout def make_key(self, key, version=None): - """Constructs the key used by all other methods. By default it - uses the key_func to generate a key (which, by default, - prepends the `key_prefix' and 'version'). A different key - function can be provided at the time of cache construction; - alternatively, you can subclass the cache backend to provide - custom key making behavior. + """ + Construct the key used by all other methods. By default, use the + key_func to generate a key (which, by default, prepends the + `key_prefix' and 'version'). A different key function can be provided + at the time of cache construction; alternatively, you can subclass the + cache backend to provide custom key making behavior. """ if version is None: version = self.version @@ -103,10 +103,10 @@ class BaseCache: def add(self, key, value, timeout=DEFAULT_TIMEOUT, version=None): """ Set a value in the cache if the key does not already exist. If - timeout is given, that timeout will be used for the key; otherwise - the default cache timeout will be used. + timeout is given, use that timeout for the key; otherwise use the + default cache timeout. - Returns True if the value was stored, False otherwise. + Return True if the value was stored, False otherwise. """ raise NotImplementedError('subclasses of BaseCache must provide an add() method') @@ -119,8 +119,8 @@ class BaseCache: def set(self, key, value, timeout=DEFAULT_TIMEOUT, version=None): """ - Set a value in the cache. If timeout is given, that timeout will be - used for the key; otherwise the default cache timeout will be used. + Set a value in the cache. If timeout is given, use that timeout for the + key; otherwise use the default cache timeout. """ raise NotImplementedError('subclasses of BaseCache must provide a set() method') @@ -135,7 +135,7 @@ class BaseCache: Fetch a bunch of keys from the cache. For certain backends (memcached, pgsql) this can be *much* faster when fetching multiple values. - Returns a dict mapping each key in keys to its value. If the given + Return a dict mapping each key in keys to its value. If the given key is missing, it will be missing from the response dict. """ d = {} @@ -148,9 +148,9 @@ class BaseCache: def get_or_set(self, key, default, timeout=DEFAULT_TIMEOUT, version=None): """ Fetch a given key from the cache. If the key does not exist, - the key is added and set to the default value. The default value can - also be any callable. If timeout is given, that timeout will be used - for the key; otherwise the default cache timeout will be used. + add the key and set it to the default value. The default value can + also be any callable. If timeout is given, use that timeout for the + key; otherwise use the default cache timeout. Return the value of the key stored or retrieved. """ @@ -166,7 +166,7 @@ class BaseCache: def has_key(self, key, version=None): """ - Returns True if the key is in the cache and has not expired. + Return True if the key is in the cache and has not expired. """ return self.get(key, version=version) is not None @@ -191,7 +191,7 @@ class BaseCache: def __contains__(self, key): """ - Returns True if the key is in the cache and has not expired. + Return True if the key is in the cache and has not expired. """ # This is a separate method, rather than just a copy of has_key(), # so that it always has the same functionality as has_key(), even @@ -204,8 +204,8 @@ class BaseCache: pairs. For certain backends (memcached), this is much more efficient than calling set() multiple times. - If timeout is given, that timeout will be used for the key; otherwise - the default cache timeout will be used. + If timeout is given, use that timeout for the key; otherwise use the + default cache timeout. """ for key, value in data.items(): self.set(key, value, timeout=timeout, version=version) @@ -243,8 +243,9 @@ class BaseCache: break def incr_version(self, key, delta=1, version=None): - """Adds delta to the cache version for the supplied key. Returns the - new version. + """ + Add delta to the cache version for the supplied key. Return the new + version. """ if version is None: version = self.version @@ -258,8 +259,9 @@ class BaseCache: return version + delta def decr_version(self, key, delta=1, version=None): - """Subtracts delta from the cache version for the supplied key. Returns - the new version. + """ + Subtract delta from the cache version for the supplied key. Return the + new version. """ return self.incr_version(key, -delta, version) diff --git a/django/core/cache/backends/filebased.py b/django/core/cache/backends/filebased.py index a381ebc265..56d2cf5b6d 100644 --- a/django/core/cache/backends/filebased.py +++ b/django/core/cache/backends/filebased.py @@ -75,7 +75,7 @@ class FileBasedCache(BaseCache): def _cull(self): """ - Removes random cache entries if max_entries is reached at a ratio + Remove random cache entries if max_entries is reached at a ratio of num_entries / cull_frequency. A value of 0 for CULL_FREQUENCY means that the entire cache will be purged. """ @@ -119,8 +119,7 @@ class FileBasedCache(BaseCache): def _is_expired(self, f): """ - Takes an open cache file and determines if it has expired, - deletes the file if it is has passed its expiry time. + Take an open cache file `f` and delete it if it's expired. """ exp = pickle.load(f) if exp is not None and exp < time.time(): diff --git a/django/core/cache/backends/memcached.py b/django/core/cache/backends/memcached.py index 8f87f487bf..6e8211bdff 100644 --- a/django/core/cache/backends/memcached.py +++ b/django/core/cache/backends/memcached.py @@ -30,7 +30,7 @@ class BaseMemcachedCache(BaseCache): @property def _cache(self): """ - Implements transparent thread-safe access to a memcached client. + Implement transparent thread-safe access to a memcached client. """ if getattr(self, '_client', None) is None: self._client = self._lib.Client(self._servers, **self._options) diff --git a/django/core/files/base.py b/django/core/files/base.py index 9030ed9155..90b75b18cb 100644 --- a/django/core/files/base.py +++ b/django/core/files/base.py @@ -76,7 +76,7 @@ class File(FileProxyMixin): def multiple_chunks(self, chunk_size=None): """ - Returns ``True`` if you can expect multiple chunks. + Return ``True`` if you can expect multiple chunks. NB: If a particular file representation is in memory, subclasses should always return ``False`` -- there's no good reason to read from memory in @@ -133,7 +133,7 @@ class File(FileProxyMixin): class ContentFile(File): """ - A File-like object that takes just raw content, rather than an actual file. + A File-like object that take just raw content, rather than an actual file. """ def __init__(self, content, name=None): stream_class = StringIO if isinstance(content, str) else BytesIO @@ -154,21 +154,15 @@ class ContentFile(File): def endswith_cr(line): - """ - Return True if line (a text or byte string) ends with '\r'. - """ + """Return True if line (a text or byte string) ends with '\r'.""" return line.endswith('\r' if isinstance(line, str) else b'\r') def endswith_lf(line): - """ - Return True if line (a text or byte string) ends with '\n'. - """ + """Return True if line (a text or byte string) ends with '\n'.""" return line.endswith('\n' if isinstance(line, str) else b'\n') def equals_lf(line): - """ - Return True if line (a text or byte string) equals '\n'. - """ + """Return True if line (a text or byte string) equals '\n'.""" return line == ('\n' if isinstance(line, str) else b'\n') diff --git a/django/core/files/images.py b/django/core/files/images.py index 5bd0f638fe..cdb89de2cc 100644 --- a/django/core/files/images.py +++ b/django/core/files/images.py @@ -32,7 +32,7 @@ class ImageFile(File): def get_image_dimensions(file_or_path, close=False): """ - Returns the (width, height) of an image, given an open file or a path. Set + Return the (width, height) of an image, given an open file or a path. Set 'close' to True to close the file at the end if it is initially in an open state. """ diff --git a/django/core/files/move.py b/django/core/files/move.py index 9e6cfe7684..23491d6573 100644 --- a/django/core/files/move.py +++ b/django/core/files/move.py @@ -28,15 +28,14 @@ def _samefile(src, dst): def file_move_safe(old_file_name, new_file_name, chunk_size=1024 * 64, allow_overwrite=False): """ - Moves a file from one location to another in the safest way possible. + Move a file from one location to another in the safest way possible. - First, tries ``os.rename``, which is simple but will break across filesystems. - If that fails, streams manually from one file to another in pure Python. + First, try ``os.rename``, which is simple but will break across filesystems. + If that fails, stream manually from one file to another in pure Python. - If the destination file exists and ``allow_overwrite`` is ``False``, this - function will throw an ``IOError``. + If the destination file exists and ``allow_overwrite`` is ``False``, raise + ``IOError``. """ - # There's no reason to move if we don't have to. if _samefile(old_file_name, new_file_name): return diff --git a/django/core/files/storage.py b/django/core/files/storage.py index df4db9f2e8..1ee9533eb2 100644 --- a/django/core/files/storage.py +++ b/django/core/files/storage.py @@ -29,14 +29,12 @@ class Storage: # These shouldn't be overridden by subclasses unless absolutely necessary. def open(self, name, mode='rb'): - """ - Retrieves the specified file from storage. - """ + """Retrieve the specified file from storage.""" return self._open(name, mode) def save(self, name, content, max_length=None): """ - Saves new content to the file specified by name. The content should be + Save new content to the file specified by name. The content should be a proper File object or any python file-like object, ready to be read from the beginning. """ @@ -54,14 +52,14 @@ class Storage: def get_valid_name(self, name): """ - Returns a filename, based on the provided filename, that's suitable for + Return a filename, based on the provided filename, that's suitable for use in the target storage system. """ return get_valid_filename(name) def get_available_name(self, name, max_length=None): """ - Returns a filename that's free on the target storage system, and + Return a filename that's free on the target storage system and available for new content to be written to. """ dir_name, file_name = os.path.split(name) @@ -101,7 +99,7 @@ class Storage: def path(self, name): """ - Returns a local filesystem path where the file can be retrieved using + Return a local filesystem path where the file can be retrieved using Python's built-in open() function. Storage systems that can't be accessed using open() should *not* implement this method. """ @@ -112,33 +110,33 @@ class Storage: def delete(self, name): """ - Deletes the specified file from the storage system. + Delete the specified file from the storage system. """ raise NotImplementedError('subclasses of Storage must provide a delete() method') def exists(self, name): """ - Returns True if a file referenced by the given name already exists in the + Return True if a file referenced by the given name already exists in the storage system, or False if the name is available for a new file. """ raise NotImplementedError('subclasses of Storage must provide an exists() method') def listdir(self, path): """ - Lists the contents of the specified path, returning a 2-tuple of lists; + List the contents of the specified path. Return a 2-tuple of lists: the first item being directories, the second item being files. """ raise NotImplementedError('subclasses of Storage must provide a listdir() method') def size(self, name): """ - Returns the total size, in bytes, of the file specified by name. + Return the total size, in bytes, of the file specified by name. """ raise NotImplementedError('subclasses of Storage must provide a size() method') def url(self, name): """ - Returns an absolute URL where the file's contents can be accessed + Return an absolute URL where the file's contents can be accessed directly by a Web browser. """ raise NotImplementedError('subclasses of Storage must provide a url() method') diff --git a/django/core/files/uploadedfile.py b/django/core/files/uploadedfile.py index 9f1efde419..485bfbfd6f 100644 --- a/django/core/files/uploadedfile.py +++ b/django/core/files/uploadedfile.py @@ -62,9 +62,7 @@ class TemporaryUploadedFile(UploadedFile): super().__init__(file, name, content_type, size, charset, content_type_extra) def temporary_file_path(self): - """ - Returns the full path of this file. - """ + """Return the full path of this file.""" return self.file.name def close(self): @@ -108,8 +106,7 @@ class SimpleUploadedFile(InMemoryUploadedFile): @classmethod def from_dict(cls, file_dict): """ - Creates a SimpleUploadedFile object from - a dictionary object with the following keys: + Create a SimpleUploadedFile object from a dictionary with keys: - filename - content-type - content diff --git a/django/core/files/uploadhandler.py b/django/core/files/uploadhandler.py index a6832491c1..5e993d13e2 100644 --- a/django/core/files/uploadhandler.py +++ b/django/core/files/uploadhandler.py @@ -158,7 +158,8 @@ class MemoryFileUploadHandler(FileUploadHandler): def handle_raw_input(self, input_data, META, content_length, boundary, encoding=None): """ - Use the content_length to signal whether or not this handler should be in use. + Use the content_length to signal whether or not this handler should be + used. """ # Check the content-length header to see if we should # If the post is too large, we cannot use the Memory handler. @@ -174,18 +175,14 @@ class MemoryFileUploadHandler(FileUploadHandler): raise StopFutureHandlers() def receive_data_chunk(self, raw_data, start): - """ - Add the data to the BytesIO file. - """ + """Add the data to the BytesIO file.""" if self.activated: self.file.write(raw_data) else: return raw_data def file_complete(self, file_size): - """ - Return a file object if we're activated. - """ + """Return a file object if this handler is activated.""" if not self.activated: return diff --git a/django/core/handlers/wsgi.py b/django/core/handlers/wsgi.py index a041dd11d4..6c0c5ae57f 100644 --- a/django/core/handlers/wsgi.py +++ b/django/core/handlers/wsgi.py @@ -15,10 +15,7 @@ _slashes_re = re.compile(br'/+') class LimitedStream: - ''' - LimitedStream wraps another stream in order to not allow reading from it - past specified amount of bytes. - ''' + """Wrap another stream to disallow reading it past a number of bytes.""" def __init__(self, stream, limit, buf_size=64 * 1024 * 1024): self.stream = stream self.remaining = limit @@ -161,9 +158,7 @@ class WSGIHandler(base.BaseHandler): def get_path_info(environ): - """ - Return the HTTP request's PATH_INFO as a string. - """ + """Return the HTTP request's PATH_INFO as a string.""" path_info = get_bytes_from_wsgi(environ, 'PATH_INFO', '/') return repercent_broken_unicode(path_info).decode() @@ -171,8 +166,8 @@ def get_path_info(environ): def get_script_name(environ): """ - Returns the equivalent of the HTTP request's SCRIPT_NAME environment - variable. If Apache mod_rewrite has been used, returns what would have been + Return the equivalent of the HTTP request's SCRIPT_NAME environment + variable. If Apache mod_rewrite is used, return what would have been the script name prior to any rewriting (so it's the script name as seen from the client's perspective), unless the FORCE_SCRIPT_NAME setting is set (to anything). diff --git a/django/core/mail/__init__.py b/django/core/mail/__init__.py index 23beae0cce..05c8c6a1b1 100644 --- a/django/core/mail/__init__.py +++ b/django/core/mail/__init__.py @@ -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( diff --git a/django/core/mail/backends/base.py b/django/core/mail/backends/base.py index e0d2e3626b..d687703332 100644 --- a/django/core/mail/backends/base.py +++ b/django/core/mail/backends/base.py @@ -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') diff --git a/django/core/mail/backends/locmem.py b/django/core/mail/backends/locmem.py index f022236dd7..84732e997b 100644 --- a/django/core/mail/backends/locmem.py +++ b/django/core/mail/backends/locmem.py @@ -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. diff --git a/django/core/mail/backends/smtp.py b/django/core/mail/backends/smtp.py index 97b5df97e8..d061fb5750 100644 --- a/django/core/mail/backends/smtp.py +++ b/django/core/mail/backends/smtp.py @@ -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: diff --git a/django/core/mail/message.py b/django/core/mail/message.py index 790cbdf31a..7ab5414482 100644 --- a/django/core/mail/message.py +++ b/django/core/mail/message.py @@ -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) diff --git a/django/core/management/__init__.py b/django/core/management/__init__.py index d5295680ab..b4782172d2 100644 --- a/django/core/management/__init__.py +++ b/django/core/management/__init__.py @@ -19,10 +19,8 @@ from django.utils.encoding import force_text def find_commands(management_dir): """ - Given a path to a management directory, returns a list of all the command + Given a path to a management directory, return a list of all the command names that are available. - - Returns an empty list if no commands are defined. """ command_dir = os.path.join(management_dir, 'commands') return [name for _, name, is_pkg in pkgutil.iter_modules([command_dir]) @@ -31,9 +29,9 @@ def find_commands(management_dir): def load_command_class(app_name, name): """ - Given a command name and an application name, returns the Command - class instance. All errors raised by the import process - (ImportError, AttributeError) are allowed to propagate. + Given a command name and an application name, return the Command + class instance. Allow all errors raised by the import process + (ImportError, AttributeError) to propagate. """ module = import_module('%s.management.commands.%s' % (app_name, name)) return module.Command() @@ -42,14 +40,14 @@ def load_command_class(app_name, name): @functools.lru_cache(maxsize=None) def get_commands(): """ - Returns a dictionary mapping command names to their callback applications. + Return a dictionary mapping command names to their callback applications. - This works by looking for a management.commands package in django.core, and - in each installed application -- if a commands package exists, all commands - in that package are registered. + Look for a management.commands package in django.core, and in each + installed application -- if a commands package exists, register all + commands in that package. Core commands are always included. If a settings module has been - specified, user-defined commands will also be included. + specified, also include user-defined commands. The dictionary is in the format {command_name: app_name}. Key-value pairs from this dictionary can then be used in calls to @@ -76,7 +74,7 @@ def get_commands(): def call_command(command_name, *args, **options): """ - Calls the given command, with the given options and args/kwargs. + Call the given command, with the given options and args/kwargs. This is the primary API you should use for calling specific commands. @@ -130,7 +128,7 @@ def call_command(command_name, *args, **options): class ManagementUtility: """ - Encapsulates the logic of the django-admin and manage.py utilities. + Encapsulate the logic of the django-admin and manage.py utilities. """ def __init__(self, argv=None): self.argv = argv or sys.argv[:] @@ -138,9 +136,7 @@ class ManagementUtility: self.settings_exception = None def main_help_text(self, commands_only=False): - """ - Returns the script's main help text, as a string. - """ + """Return the script's main help text, as a string.""" if commands_only: usage = sorted(get_commands().keys()) else: @@ -174,7 +170,7 @@ class ManagementUtility: def fetch_command(self, subcommand): """ - Tries to fetch the given subcommand, printing a message with the + Try to fetch the given subcommand, printing a message with the appropriate command called from the command line (usually "django-admin" or "manage.py") if it can't be found. """ @@ -280,8 +276,8 @@ class ManagementUtility: def execute(self): """ - Given the command-line arguments, this figures out which subcommand is - being run, creates a parser appropriate to that command, and runs it. + Given the command-line arguments, figure out which subcommand is being + run, create a parser appropriate to that command, and run it. """ try: subcommand = self.argv[1] @@ -354,8 +350,6 @@ class ManagementUtility: def execute_from_command_line(argv=None): - """ - A simple method that runs a ManagementUtility. - """ + """Run a ManagementUtility.""" utility = ManagementUtility(argv) utility.execute() diff --git a/django/core/management/base.py b/django/core/management/base.py index b0f454381a..6300b0c0bf 100644 --- a/django/core/management/base.py +++ b/django/core/management/base.py @@ -345,10 +345,10 @@ class BaseCommand: def check(self, app_configs=None, tags=None, display_num_errors=False, include_deployment_checks=False, fail_level=checks.ERROR): """ - Uses the system check framework to validate entire Django project. - Raises CommandError for any serious message (error or critical errors). - If there are only light messages (like warnings), they are printed to - stderr and no exception is raised. + Use the system check framework to validate entire Django project. + Raise CommandError for any serious message (error or critical errors). + If there are only light messages (like warnings), print them to stderr + and don't raise an exception. """ all_issues = self._run_checks( app_configs=app_configs, diff --git a/django/core/management/color.py b/django/core/management/color.py index 4519d29025..e04c94fed1 100644 --- a/django/core/management/color.py +++ b/django/core/management/color.py @@ -11,7 +11,7 @@ from django.utils import termcolors def supports_color(): """ - Returns True if the running system's terminal supports color, + Return True if the running system's terminal supports color, and False otherwise. """ plat = sys.platform @@ -61,14 +61,14 @@ def make_style(config_string=''): @functools.lru_cache(maxsize=None) def no_style(): """ - Returns a Style object with no color scheme. + Return a Style object with no color scheme. """ return make_style('nocolor') def color_style(): """ - Returns a Style object from the Django color scheme. + Return a Style object from the Django color scheme. """ if not supports_color(): return no_style() diff --git a/django/core/management/commands/diffsettings.py b/django/core/management/commands/diffsettings.py index 3a5ebcf845..c8bb7cb352 100644 --- a/django/core/management/commands/diffsettings.py +++ b/django/core/management/commands/diffsettings.py @@ -2,7 +2,7 @@ from django.core.management.base import BaseCommand def module_to_dict(module, omittable=lambda k: k.startswith('_')): - """Converts a module namespace to a Python dictionary.""" + """Convert a module namespace to a Python dictionary.""" return {k: repr(v) for k, v in module.__dict__.items() if not omittable(k)} diff --git a/django/core/management/commands/loaddata.py b/django/core/management/commands/loaddata.py index 4556d9b9d8..1b685e8767 100644 --- a/django/core/management/commands/loaddata.py +++ b/django/core/management/commands/loaddata.py @@ -137,9 +137,7 @@ class Command(BaseCommand): ) def load_label(self, fixture_label): - """ - Loads fixtures files for a given label. - """ + """Load fixtures files for a given label.""" show_progress = self.verbosity >= 3 for fixture_file, fixture_dir, fixture_name in self.find_fixtures(fixture_label): _, ser_fmt, cmp_fmt = self.parse_name(os.path.basename(fixture_file)) @@ -203,9 +201,7 @@ class Command(BaseCommand): @functools.lru_cache(maxsize=None) def find_fixtures(self, fixture_label): - """ - Finds fixture files for a given label. - """ + """Find fixture files for a given label.""" fixture_name, ser_fmt, cmp_fmt = self.parse_name(fixture_label) databases = [self.using, None] cmp_fmts = list(self.compression_formats.keys()) if cmp_fmt is None else [cmp_fmt] @@ -291,7 +287,7 @@ class Command(BaseCommand): def parse_name(self, fixture_name): """ - Splits fixture name in name, serialization format, compression format. + Split fixture name in name, serialization format, compression format. """ parts = fixture_name.rsplit('.', 2) diff --git a/django/core/management/commands/makemessages.py b/django/core/management/commands/makemessages.py index fd2cb7eaa6..17b1f05d5a 100644 --- a/django/core/management/commands/makemessages.py +++ b/django/core/management/commands/makemessages.py @@ -60,7 +60,7 @@ class TranslatableFile: class BuildFile: """ - Represents the state of a translatable file during the build process. + Represent the state of a translatable file during the build process. """ def __init__(self, command, domain, translatable): self.command = command @@ -170,8 +170,8 @@ def normalize_eols(raw_contents): def write_pot_file(potfile, msgs): """ - Write the :param potfile: POT file with the :param msgs: contents, - previously making sure its format is valid. + Write the `potfile` with the `msgs` contents, making sure its format is + valid. """ pot_lines = msgs.splitlines() if os.path.exists(potfile): @@ -423,10 +423,9 @@ class Command(BaseCommand): def find_files(self, root): """ - Helper method to get all files in the given root. Also check that there - is a matching locale dir for each file. + Get all files in the given root. Also check that there is a matching + locale dir for each file. """ - def is_ignored(path, ignore_patterns): """ Check if the given path should be ignored or not. @@ -499,7 +498,7 @@ class Command(BaseCommand): Extract translatable literals from the specified files, creating or updating the POT file for a given locale directory. - Uses the xgettext GNU gettext utility. + Use the xgettext GNU gettext utility. """ build_files = [] for translatable in files: @@ -591,10 +590,10 @@ class Command(BaseCommand): def write_po_file(self, potfile, locale): """ - Creates or updates the PO file for self.domain and :param locale:. - Uses contents of the existing :param potfile:. + Create or update the PO file for self.domain and `locale`. + Use contents of the existing `potfile`. - Uses msgmerge, and msgattrib GNU gettext utilities. + Use msgmerge and msgattrib GNU gettext utilities. """ basedir = os.path.join(os.path.dirname(potfile), locale, 'LC_MESSAGES') if not os.path.isdir(basedir): @@ -633,7 +632,7 @@ class Command(BaseCommand): def copy_plural_forms(self, msgs, locale): """ - Copies plural forms header contents from a Django catalog of locale to + Copy plural forms header contents from a Django catalog of locale to the msgs string, inserting it at the right place. msgs should be the contents of a newly created .po file. """ diff --git a/django/core/management/commands/makemigrations.py b/django/core/management/commands/makemigrations.py index 8572bbeb95..baa335c984 100644 --- a/django/core/management/commands/makemigrations.py +++ b/django/core/management/commands/makemigrations.py @@ -176,7 +176,7 @@ class Command(BaseCommand): def write_migration_files(self, changes): """ - Takes a changes dict and writes them out as migration files. + Take a changes dict and write them out as migration files. """ directory_created = {} for app_label, app_migrations in changes.items(): diff --git a/django/core/management/commands/runserver.py b/django/core/management/commands/runserver.py index cc47b14ca2..0ef6b5c4ac 100644 --- a/django/core/management/commands/runserver.py +++ b/django/core/management/commands/runserver.py @@ -62,9 +62,7 @@ class Command(BaseCommand): super().execute(*args, **options) def get_handler(self, *args, **options): - """ - Returns the default WSGI handler for the runner. - """ + """Return the default WSGI handler for the runner.""" return get_internal_wsgi_application() def handle(self, *args, **options): @@ -101,9 +99,7 @@ class Command(BaseCommand): self.run(**options) def run(self, **options): - """ - Runs the server, using the autoreloader if needed - """ + """Run the server, using the autoreloader if needed.""" use_reloader = options['use_reloader'] if use_reloader: diff --git a/django/core/management/commands/showmigrations.py b/django/core/management/commands/showmigrations.py index 1e20ec1745..4130d44389 100644 --- a/django/core/management/commands/showmigrations.py +++ b/django/core/management/commands/showmigrations.py @@ -54,7 +54,7 @@ class Command(BaseCommand): def show_list(self, connection, app_names=None): """ - Shows a list of all migrations on the system, or only those of + Show a list of all migrations on the system, or only those of some named apps. """ # Load migrations from disk/DB @@ -90,7 +90,7 @@ class Command(BaseCommand): def show_plan(self, connection, app_names=None): """ - Shows all known migrations (or only those of the specified app_names) + Show all known migrations (or only those of the specified app_names) in the order they will be applied. """ # Load migrations from disk/DB diff --git a/django/core/management/sql.py b/django/core/management/sql.py index 3783025900..44b57b386a 100644 --- a/django/core/management/sql.py +++ b/django/core/management/sql.py @@ -4,10 +4,10 @@ from django.db import models def sql_flush(style, connection, only_django=False, reset_sequences=True, allow_cascade=False): """ - Returns a list of the SQL statements used to flush the database. + Return a list of the SQL statements used to flush the database. - If only_django is True, then only table names that have associated Django - models and are in INSTALLED_APPS will be included. + If only_django is True, only include the table names that have associated + Django models and are in INSTALLED_APPS . """ if only_django: tables = connection.introspection.django_table_names(only_existing=True, include_views=False) diff --git a/django/core/management/templates.py b/django/core/management/templates.py index 772f20b93f..3aecd10a42 100644 --- a/django/core/management/templates.py +++ b/django/core/management/templates.py @@ -24,7 +24,7 @@ _url_drive_re = re.compile('^([a-z])[:|]', re.I) class TemplateCommand(BaseCommand): """ - Copies either a Django application layout template or a Django project + Copy either a Django application layout template or a Django project layout template into the specified directory. :param style: A color style object (see django.core.management.color). @@ -185,9 +185,9 @@ class TemplateCommand(BaseCommand): def handle_template(self, template, subdir): """ - Determines where the app or project templates are. - Use django.__path__[0] as the default because we don't - know into which directory Django has been installed. + Determine where the app or project templates are. + Use django.__path__[0] as the default because the Django install + directory isn't known. """ if template is None: return path.join(django.__path__[0], 'conf', subdir) @@ -222,7 +222,7 @@ class TemplateCommand(BaseCommand): def download(self, url): """ - Downloads the given URL and returns the file name. + Download the given URL and return the file name. """ def cleanup_url(url): tmp = url.rstrip('/') @@ -286,7 +286,7 @@ class TemplateCommand(BaseCommand): def extract(self, filename): """ - Extracts the given file to a temporarily and returns + Extract the given file to a temporarily and return the path of the directory with the extracted content. """ prefix = 'django_%s_template_' % self.app_or_project @@ -302,9 +302,7 @@ class TemplateCommand(BaseCommand): (filename, tempdir, e)) def is_url(self, template): - """ - Returns True if the name looks like a URL - """ + """Return True if the name looks like a URL.""" if ':' not in template: return False scheme = template.split(':', 1)[0].lower() diff --git a/django/core/management/utils.py b/django/core/management/utils.py index 5903e53341..a4ac6fad58 100644 --- a/django/core/management/utils.py +++ b/django/core/management/utils.py @@ -12,7 +12,7 @@ def popen_wrapper(args, os_err_exc_type=CommandError, stdout_encoding='utf-8'): """ Friendly wrapper around Popen. - Returns stdout output, stderr output and OS status code. + Return stdout output, stderr output, and OS status code. """ try: p = Popen(args, shell=False, stdout=PIPE, stderr=PIPE, close_fds=os.name != 'nt') @@ -28,7 +28,7 @@ def popen_wrapper(args, os_err_exc_type=CommandError, stdout_encoding='utf-8'): def handle_extensions(extensions): """ - Organizes multiple extensions that are separated with commas or passed by + Organize multiple extensions that are separated with commas or passed by using --extension/-e multiple times. For example: running 'django-admin makemessages -e js,txt -e xhtml -a' diff --git a/django/core/paginator.py b/django/core/paginator.py index e0e78bf020..85d88eb180 100644 --- a/django/core/paginator.py +++ b/django/core/paginator.py @@ -33,9 +33,7 @@ class Paginator: self.allow_empty_first_page = allow_empty_first_page def validate_number(self, number): - """ - Validates the given 1-based page number. - """ + """Validate the given 1-based page number.""" try: number = int(number) except (TypeError, ValueError): @@ -50,9 +48,7 @@ class Paginator: return number def page(self, number): - """ - Returns a Page object for the given 1-based page number. - """ + """Return a Page object for the given 1-based page number.""" number = self.validate_number(number) bottom = (number - 1) * self.per_page top = bottom + self.per_page @@ -62,7 +58,7 @@ class Paginator: def _get_page(self, *args, **kwargs): """ - Returns an instance of a single page. + Return an instance of a single page. This hook can be used by subclasses to use an alternative to the standard :cls:`Page` object. @@ -71,9 +67,7 @@ class Paginator: @cached_property def count(self): - """ - Returns the total number of objects, across all pages. - """ + """Return the total number of objects, across all pages.""" try: return self.object_list.count() except (AttributeError, TypeError): @@ -84,9 +78,7 @@ class Paginator: @cached_property def num_pages(self): - """ - Returns the total number of pages. - """ + """Return the total number of pages.""" if self.count == 0 and not self.allow_empty_first_page: return 0 hits = max(1, self.count - self.orphans) @@ -95,7 +87,7 @@ class Paginator: @property def page_range(self): """ - Returns a 1-based range of pages for iterating through within + Return a 1-based range of pages for iterating through within a template for loop. """ return range(1, self.num_pages + 1) @@ -154,7 +146,7 @@ class Page(collections.Sequence): def start_index(self): """ - Returns the 1-based index of the first object on this page, + Return the 1-based index of the first object on this page, relative to total objects in the paginator. """ # Special case, return zero if no items. @@ -164,7 +156,7 @@ class Page(collections.Sequence): def end_index(self): """ - Returns the 1-based index of the last object on this page, + Return the 1-based index of the last object on this page, relative to total objects found (hits). """ # Special case for the last page because there can be orphans. diff --git a/django/core/serializers/__init__.py b/django/core/serializers/__init__.py index 3d0ed9a13f..666d1bb297 100644 --- a/django/core/serializers/__init__.py +++ b/django/core/serializers/__init__.py @@ -131,7 +131,7 @@ def serialize(format, queryset, **options): def deserialize(format, stream_or_string, **options): """ - Deserialize a stream or a string. Returns an iterator that yields ``(obj, + Deserialize a stream or a string. Return an iterator that yields ``(obj, m2m_relation_dict)``, where ``obj`` is an instantiated -- but *unsaved* -- object, and ``m2m_relation_dict`` is a dictionary of ``{m2m_field_name : list_of_related_objects}``. diff --git a/django/core/serializers/json.py b/django/core/serializers/json.py index a948d87856..31f065a831 100644 --- a/django/core/serializers/json.py +++ b/django/core/serializers/json.py @@ -17,9 +17,7 @@ from django.utils.timezone import is_aware class Serializer(PythonSerializer): - """ - Convert a queryset to JSON. - """ + """Convert a queryset to JSON.""" internal_use_only = False def _init_options(self): @@ -64,9 +62,7 @@ class Serializer(PythonSerializer): def Deserializer(stream_or_string, **options): - """ - Deserialize a stream or string of JSON data. - """ + """Deserialize a stream or string of JSON data.""" if not isinstance(stream_or_string, (bytes, str)): stream_or_string = stream_or_string.read() if isinstance(stream_or_string, bytes): @@ -83,7 +79,8 @@ def Deserializer(stream_or_string, **options): class DjangoJSONEncoder(json.JSONEncoder): """ - JSONEncoder subclass that knows how to encode date/time, decimal types and UUIDs. + JSONEncoder subclass that knows how to encode date/time, decimal types, and + UUIDs. """ def default(self, o): # See "Date Time String Format" in the ECMA-262 specification. diff --git a/django/core/serializers/python.py b/django/core/serializers/python.py index a299ed62c8..80c8bfe1d2 100644 --- a/django/core/serializers/python.py +++ b/django/core/serializers/python.py @@ -14,7 +14,7 @@ from django.utils.encoding import force_text, is_protected_type class Serializer(base.Serializer): """ - Serializes a QuerySet to basic Python objects. + Serialize a QuerySet to basic Python objects. """ internal_use_only = True @@ -180,9 +180,7 @@ def Deserializer(object_list, *, using=DEFAULT_DB_ALIAS, ignorenonexistent=False def _get_model(model_identifier): - """ - Helper to look up a model from an "app_label.model_name" string. - """ + """Look up a model from an "app_label.model_name" string.""" try: return apps.get_model(model_identifier) except (LookupError, TypeError): diff --git a/django/core/serializers/pyyaml.py b/django/core/serializers/pyyaml.py index 991ffa4f1e..b65c9ec3a8 100644 --- a/django/core/serializers/pyyaml.py +++ b/django/core/serializers/pyyaml.py @@ -37,9 +37,7 @@ DjangoSafeDumper.add_representer(collections.OrderedDict, DjangoSafeDumper.repre class Serializer(PythonSerializer): - """ - Convert a queryset to YAML. - """ + """Convert a queryset to YAML.""" internal_use_only = False @@ -64,9 +62,7 @@ class Serializer(PythonSerializer): def Deserializer(stream_or_string, **options): - """ - Deserialize a stream or string of YAML data. - """ + """Deserialize a stream or string of YAML data.""" if isinstance(stream_or_string, bytes): stream_or_string = stream_or_string.decode() if isinstance(stream_or_string, str): diff --git a/django/core/serializers/xml_serializer.py b/django/core/serializers/xml_serializer.py index 7e64952074..cf860d1d24 100644 --- a/django/core/serializers/xml_serializer.py +++ b/django/core/serializers/xml_serializer.py @@ -18,9 +18,7 @@ from django.utils.xmlutils import ( class Serializer(base.Serializer): - """ - Serializes a QuerySet to XML. - """ + """Serialize a QuerySet to XML.""" def indent(self, level): if self.options.get('indent') is not None: @@ -67,8 +65,8 @@ class Serializer(base.Serializer): def handle_field(self, obj, field): """ - Called to handle each field on an object (except for ForeignKeys and - ManyToManyFields) + Handle each field on an object (except for ForeignKeys and + ManyToManyFields). """ self.indent(2) self.xml.startElement("field", OrderedDict([ @@ -90,7 +88,7 @@ class Serializer(base.Serializer): def handle_fk_field(self, obj, field): """ - Called to handle a ForeignKey (we need to treat them slightly + Handle a ForeignKey (they need to be treated slightly differently from regular fields). """ self._start_relational_field(field) @@ -113,9 +111,9 @@ class Serializer(base.Serializer): def handle_m2m_field(self, obj, field): """ - Called to handle a ManyToManyField. Related objects are only - serialized as references to the object's PK (i.e. the related *data* - is not dumped, just the relation). + Handle a ManyToManyField. Related objects are only serialized as + references to the object's PK (i.e. the related *data* is not dumped, + just the relation). """ if field.remote_field.through._meta.auto_created: self._start_relational_field(field) @@ -141,9 +139,7 @@ class Serializer(base.Serializer): self.xml.endElement("field") def _start_relational_field(self, field): - """ - Helper to output the element for relational fields - """ + """Output the element for relational fields.""" self.indent(2) self.xml.startElement("field", OrderedDict([ ("name", field.name), @@ -153,9 +149,7 @@ class Serializer(base.Serializer): class Deserializer(base.Deserializer): - """ - Deserialize XML. - """ + """Deserialize XML.""" def __init__(self, stream_or_string, *, using=DEFAULT_DB_ALIAS, ignorenonexistent=False, **options): super().__init__(stream_or_string, **options) @@ -175,9 +169,7 @@ class Deserializer(base.Deserializer): raise StopIteration def _handle_object(self, node): - """ - Convert an node to a DeserializedObject. - """ + """Convert an node to a DeserializedObject.""" # Look up the model using the model loading mechanism. If this fails, # bail. Model = self._get_model_from_node(node, "model") @@ -278,8 +270,8 @@ class Deserializer(base.Deserializer): def _get_model_from_node(self, node, attr): """ - Helper to look up a model from a or a node. + Look up a model from a or a + node. """ model_identifier = node.getAttribute(attr) if not model_identifier: @@ -295,9 +287,7 @@ class Deserializer(base.Deserializer): def getInnerText(node): - """ - Get all the inner text of a DOM node (recursively). - """ + """Get all the inner text of a DOM node (recursively).""" # inspired by http://mail.python.org/pipermail/xml-sig/2005-March/011022.html inner_text = [] for child in node.childNodes: @@ -317,7 +307,7 @@ class DefusedExpatParser(_ExpatParser): """ An expat parser hardened against XML bomb attacks. - Forbids DTDs, external entity references + Forbid DTDs, external entity references """ def __init__(self, *args, **kwargs): _ExpatParser.__init__(self, *args, **kwargs) diff --git a/django/core/servers/basehttp.py b/django/core/servers/basehttp.py index 111b5818cd..8ef39e98fc 100644 --- a/django/core/servers/basehttp.py +++ b/django/core/servers/basehttp.py @@ -24,7 +24,7 @@ logger = logging.getLogger('django.server') def get_internal_wsgi_application(): """ - Loads and returns the WSGI application as configured by the user in + Load and return the WSGI application as configured by the user in ``settings.WSGI_APPLICATION``. With the default ``startproject`` layout, this will be the ``application`` object in ``projectname/wsgi.py``. @@ -32,7 +32,7 @@ def get_internal_wsgi_application(): for Django's internal server (runserver); external WSGI servers should just be configured to point to the correct application object directly. - If settings.WSGI_APPLICATION is not set (is ``None``), we just return + If settings.WSGI_APPLICATION is not set (is ``None``), return whatever ``django.core.wsgi.get_wsgi_application`` returns. """ from django.conf import settings diff --git a/django/core/signing.py b/django/core/signing.py index 2ab3ae89cf..f9ee60dae8 100644 --- a/django/core/signing.py +++ b/django/core/signing.py @@ -50,16 +50,12 @@ _SEP_UNSAFE = re.compile(r'^[A-z0-9-_=]*$') class BadSignature(Exception): - """ - Signature does not match - """ + """Signature does not match.""" pass class SignatureExpired(BadSignature): - """ - Signature timestamp is older than required max_age - """ + """Signature timestamp is older than required max_age.""" pass @@ -96,11 +92,11 @@ class JSONSerializer: def dumps(obj, key=None, salt='django.core.signing', serializer=JSONSerializer, compress=False): """ - Returns URL-safe, sha1 signed base64 compressed JSON string. If key is - None, settings.SECRET_KEY is used instead. + Return URL-safe, sha1 signed base64 compressed JSON string. If key is + None, use settings.SECRET_KEY instead. - If compress is True (not the default) checks if compressing using zlib can - save some space. Prepends a '.' to signify compression. This is included + If compress is True (not the default), check if compressing using zlib can + save some space. Prepend a '.' to signify compression. This is included in the signature, to protect against zip bombs. Salt can be used to namespace the hash, so that a signed string is @@ -129,7 +125,7 @@ def dumps(obj, key=None, salt='django.core.signing', serializer=JSONSerializer, def loads(s, key=None, salt='django.core.signing', serializer=JSONSerializer, max_age=None): """ - Reverse of dumps(), raises BadSignature if signature fails. + Reverse of dumps(), raise BadSignature if signature fails. The serializer is expected to accept a bytestring. """ diff --git a/django/core/validators.py b/django/core/validators.py index 44db6c00f0..f55918c8ba 100644 --- a/django/core/validators.py +++ b/django/core/validators.py @@ -52,8 +52,8 @@ class RegexValidator: def __call__(self, value): """ - Validates that the input matches the regular expression - if inverse_match is False, otherwise raises ValidationError. + Validate that the input matches the regular expression + if inverse_match is False, otherwise raise ValidationError. """ if not (self.inverse_match is not bool(self.regex.search( force_text(value)))): @@ -280,10 +280,8 @@ ip_address_validator_map = { def ip_address_validators(protocol, unpack_ipv4): """ - Depending on the given parameters returns the appropriate validators for + Depending on the given parameters, return the appropriate validators for the GenericIPAddressField. - - This code is here, because it is exactly the same for the model and the form field. """ if protocol != 'both' and unpack_ipv4: raise ValueError( diff --git a/django/core/wsgi.py b/django/core/wsgi.py index e0ded3db54..35e0fa8e80 100644 --- a/django/core/wsgi.py +++ b/django/core/wsgi.py @@ -4,11 +4,10 @@ from django.core.handlers.wsgi import WSGIHandler def get_wsgi_application(): """ - The public interface to Django's WSGI support. Should return a WSGI - callable. + The public interface to Django's WSGI support. Return a WSGI callable. - Allows us to avoid making django.core.handlers.WSGIHandler public API, in - case the internal WSGI implementation changes or moves in the future. + Avoids making django.core.handlers.WSGIHandler a public API, in case the + internal WSGI implementation changes or moves in the future. """ django.setup(set_prefix=False) return WSGIHandler()