innov
/
django1
1
0
Fork 0
Code Issues Pull Requests 1 Projects Releases Wiki Activity

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

This commit is contained in:
Anton Samarchyan 2017-01-24 15:32:33 -05:00 committed by Tim Graham
parent 98bcc5d81b
commit 9718fa2e8a
30 changed files with 255 additions and 329 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
django/utils/_os.py
View File

@ -24,11 +24,11 @@ def npath(path):
def safe_join(base, *paths):
"""
Joins one or more path components to the base path component intelligently.
Returns a normalized, absolute version of the final path.
Join one or more path components to the base path component intelligently.
Return a normalized, absolute version of the final path.
The final path must be located inside of the base path component (otherwise
a ValueError is raised).
Raise ValueError if the final path isn't located inside of the base path
component.
"""
base = force_text(base)
paths = [force_text(p) for p in paths]
@ -52,9 +52,9 @@ def safe_join(base, *paths):
def symlinks_supported():
"""
A function to check if creating symlinks are supported in the
host platform and/or if they are allowed to be created (e.g.
on Windows it requires admin permissions).
Return whether or not creating symlinks are supported in the host platform
and/or if they are allowed to be created (e.g. on Windows it requires admin
permissions).
"""
with tempfile.TemporaryDirectory() as temp_dir:
original_path = os.path.join(temp_dir, 'original')

4
django/utils/archive.py
View File

@ -119,8 +119,8 @@ class BaseArchive:
def has_leading_dir(self, paths):
"""
Returns true if all the paths have the same leading path name
(i.e., everything is in one subdirectory in an archive)
Return True if all the paths have the same leading path name
(i.e., everything is in one subdirectory in an archive).
"""
common_prefix = None
for path in paths:

5
django/utils/autoreload.py
View File

@ -81,8 +81,7 @@ _cached_filenames = []
def gen_filenames(only_new=False):
"""
Returns a list of filenames referenced in sys.modules and translation
files.
Return a list of filenames referenced in sys.modules and translation files.
"""
# N.B. ``list(...)`` is needed, because this runs in parallel with
# application code which might be mutating ``sys.modules``, and this will
@ -152,7 +151,7 @@ def reset_translations():
def inotify_code_changed():
"""
Checks for changed code using inotify. After being called
Check for changed code using inotify. After being called
it blocks until a change event has been fired.
"""
class EventHandler(pyinotify.ProcessEvent):

30
django/utils/cache.py
View File

@ -40,8 +40,8 @@ logger = logging.getLogger('django.request')
def patch_cache_control(response, **kwargs):
"""
This function patches the Cache-Control header by adding all
keyword arguments to it. The transformation is as follows:
Patch the Cache-Control header by adding all keyword arguments to it.
The transformation is as follows:
* All keyword parameter names are turned to lowercase, and underscores
are converted to hyphens.
@ -89,8 +89,8 @@ def patch_cache_control(response, **kwargs):
def get_max_age(response):
"""
Returns the max-age from the response Cache-Control header as an integer
(or ``None`` if it wasn't found or wasn't an integer.
Return the max-age from the response Cache-Control header as an integer,
or None if it wasn't found or wasn't an integer.
"""
if not response.has_header('Cache-Control'):
return
@ -267,7 +267,7 @@ def patch_response_headers(response, cache_timeout=None):
def add_never_cache_headers(response):
"""
Adds headers to a response to indicate that a page should never be cached.
Add headers to a response to indicate that a page should never be cached.
"""
patch_response_headers(response, cache_timeout=-1)
patch_cache_control(response, no_cache=True, no_store=True, must_revalidate=True)
@ -275,7 +275,7 @@ def add_never_cache_headers(response):
def patch_vary_headers(response, newheaders):
"""
Adds (or updates) the "Vary" header in the given HttpResponse object.
Add (or update) the "Vary" header in the given HttpResponse object.
newheaders is a list of header names that should be in "Vary". Existing
headers in "Vary" aren't removed.
"""
@ -295,7 +295,7 @@ def patch_vary_headers(response, newheaders):
def has_vary_header(response, header_query):
"""
Checks to see if the response has a given header name in its Vary header.
Check to see if the response has a given header name in its Vary header.
"""
if not response.has_header('Vary'):
return False
@ -305,7 +305,7 @@ def has_vary_header(response, header_query):
def _i18n_cache_key_suffix(request, cache_key):
"""If necessary, adds the current locale or time zone to the cache key."""
"""If necessary, add the current locale or time zone to the cache key."""
if settings.USE_I18N or settings.USE_L10N:
# first check if LocaleMiddleware or another middleware added
# LANGUAGE_CODE to request, then fall back to the active language
@ -322,7 +322,7 @@ def _i18n_cache_key_suffix(request, cache_key):
def _generate_cache_key(request, method, headerlist, key_prefix):
"""Returns a cache key from the headers given in the header list."""
"""Return a cache key from the headers given in the header list."""
ctx = hashlib.md5()
for header in headerlist:
value = request.META.get(header)
@ -335,7 +335,7 @@ def _generate_cache_key(request, method, headerlist, key_prefix):
def _generate_cache_header_key(key_prefix, request):
"""Returns a cache key for the header cache."""
"""Return a cache key for the header cache."""
url = hashlib.md5(force_bytes(iri_to_uri(request.build_absolute_uri())))
cache_key = 'views.decorators.cache.cache_header.%s.%s' % (
key_prefix, url.hexdigest())
@ -344,13 +344,13 @@ def _generate_cache_header_key(key_prefix, request):
def get_cache_key(request, key_prefix=None, method='GET', cache=None):
"""
Returns a cache key based on the request URL and query. It can be used
Return a cache key based on the request URL and query. It can be used
in the request phase because it pulls the list of headers to take into
account from the global URL registry and uses those to build a cache key
to check against.
If there is no headerlist stored, the page needs to be rebuilt, so this
function returns None.
If there isn't a headerlist stored, return None, indicating that the page
needs to be rebuilt.
"""
if key_prefix is None:
key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
@ -366,8 +366,8 @@ def get_cache_key(request, key_prefix=None, method='GET', cache=None):
def learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None):
"""
Learns what headers to take into account for some request URL from the
response object. It stores those headers in a global URL registry so that
Learn what headers to take into account for some request URL from the
response object. Store those headers in a global URL registry so that
later access to that URL will know what headers to take into account
without building the response object itself. The headers are named in the
Vary header of the response, but we want to prevent response generation.

4
django/utils/crypto.py
View File

@ -22,7 +22,7 @@ except NotImplementedError:
def salted_hmac(key_salt, value, secret=None):
"""
Returns the HMAC-SHA1 of 'value', using a key generated from key_salt and a
Return the HMAC-SHA1 of 'value', using a key generated from key_salt and a
secret (which defaults to settings.SECRET_KEY).
A different key_salt should be passed in for every application of HMAC.
@ -49,7 +49,7 @@ def get_random_string(length=12,
allowed_chars='abcdefghijklmnopqrstuvwxyz'
'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'):
"""
Returns a securely generated random string.
Return a securely generated random string.
The default length of 12 with the a-z, A-Z, 0-9 character set returns
a 71-bit value. log_2((26+26+10)^12) =~ 71 bits

29
django/utils/datastructures.py
View File

@ -70,8 +70,8 @@ class MultiValueDict(dict):
def __getitem__(self, key):
"""
Returns the last data value for this key, or [] if it's an empty list;
raises KeyError if not found.
Return the last data value for this key, or [] if it's an empty list;
raise KeyError if not found.
"""
try:
list_ = super().__getitem__(key)
@ -114,8 +114,8 @@ class MultiValueDict(dict):
def get(self, key, default=None):
"""
Returns the last data value for the passed key. If key doesn't exist
or value is an empty list, then default is returned.
Return the last data value for the passed key. If key doesn't exist
or value is an empty list, return `default`.
"""
try:
val = self[key]
@ -170,19 +170,19 @@ class MultiValueDict(dict):
return self._getlist(key)
def appendlist(self, key, value):
"""Appends an item to the internal list associated with key."""
"""Append an item to the internal list associated with key."""
self.setlistdefault(key).append(value)
def items(self):
"""
Yields (key, value) pairs, where value is the last item in the list
Yield (key, value) pairs, where value is the last item in the list
associated with the key.
"""
for key in self:
yield key, self[key]
def lists(self):
"""Yields (key, list) pairs."""
"""Yield (key, list) pairs."""
return iter(super().items())
def values(self):
@ -191,14 +191,11 @@ class MultiValueDict(dict):
yield self[key]
def copy(self):
"""Returns a shallow copy of this object."""
"""Return a shallow copy of this object."""
return copy.copy(self)
def update(self, *args, **kwargs):
"""
update() extends rather than replaces existing key lists.
Also accepts keyword args.
"""
"""Extend rather than replace existing key lists."""
if len(args) > 1:
raise TypeError("update expected at most 1 arguments, got %d" % len(args))
if args:
@ -216,9 +213,7 @@ class MultiValueDict(dict):
self.setlistdefault(key).append(value)
def dict(self):
"""
Returns current object as a dict with singular values.
"""
"""Return current object as a dict with singular values."""
return {key: self[key] for key in self}
@ -264,7 +259,7 @@ class ImmutableList(tuple):
class DictWrapper(dict):
"""
Wraps accesses to a dictionary so that certain values (those starting with
Wrap accesses to a dictionary so that certain values (those starting with
the specified prefix) are passed through a function before being returned.
The prefix is removed before looking up the real value.
@ -278,7 +273,7 @@ class DictWrapper(dict):
def __getitem__(self, key):
"""
Retrieves the real value after stripping the prefix string (if
Retrieve the real value after stripping the prefix string (if
present). If the prefix is present, pass the value through self.func
before returning, otherwise return the raw value.
"""

12
django/utils/dateformat.py
View File

@ -77,8 +77,7 @@ class TimeFormat(Formatter):
"""
Timezone name.
If timezone information is not available, this method returns
an empty string.
If timezone information is not available, return an empty string.
"""
if not self.timezone:
return ""
@ -129,8 +128,7 @@ class TimeFormat(Formatter):
"""
Difference to Greenwich time in hours; e.g. '+0200', '-0430'.
If timezone information is not available, this method returns
an empty string.
If timezone information is not available, return an empty string.
"""
if not self.timezone:
return ""
@ -163,8 +161,7 @@ class TimeFormat(Formatter):
"""
Time zone of this machine; e.g. 'EST' or 'MDT'.
If timezone information is not available, this method returns
an empty string.
If timezone information is not available, return an empty string.
"""
if not self.timezone:
return ""
@ -191,8 +188,7 @@ class TimeFormat(Formatter):
timezones west of UTC is always negative, and for those east of UTC is
always positive.
If timezone information is not available, this method returns
an empty string.
If timezone information is not available, return an empty string.
"""
if not self.timezone:
return ""

20
django/utils/dateparse.py
View File

@ -52,10 +52,10 @@ iso8601_duration_re = re.compile(
def parse_date(value):
"""Parses a string and return a datetime.date.
"""Parse a string and return a datetime.date.
Raises ValueError if the input is well formatted but not a valid date.
Returns None if the input isn't well formatted.
Raise ValueError if the input is well formatted but not a valid date.
Return None if the input isn't well formatted.
"""
match = date_re.match(value)
if match:
@ -64,12 +64,12 @@ def parse_date(value):
def parse_time(value):
"""Parses a string and return a datetime.time.
"""Parse a string and return a datetime.time.
This function doesn't support time zone offsets.
Raises ValueError if the input is well formatted but not a valid time.
Returns None if the input isn't well formatted, in particular if it
Raise ValueError if the input is well formatted but not a valid time.
Return None if the input isn't well formatted, in particular if it
contains an offset.
"""
match = time_re.match(value)
@ -82,13 +82,13 @@ def parse_time(value):
def parse_datetime(value):
"""Parses a string and return a datetime.datetime.
"""Parse a string and return a datetime.datetime.
This function supports time zone offsets. When the input contains one,
the output uses a timezone with a fixed offset from UTC.
Raises ValueError if the input is well formatted but not a valid datetime.
Returns None if the input isn't well formatted.
Raise ValueError if the input is well formatted but not a valid datetime.
Return None if the input isn't well formatted.
"""
match = datetime_re.match(value)
if match:
@ -110,7 +110,7 @@ def parse_datetime(value):
def parse_duration(value):
"""Parses a duration string and returns a datetime.timedelta.
"""Parse a duration string and return a datetime.timedelta.
The preferred format for durations in Django is '%d %H:%M:%S.%f'.

6
django/utils/deconstruct.py
View File

@ -5,10 +5,10 @@ from django.utils.version import get_docs_version
def deconstructible(*args, path=None):
"""
Class decorator that allow the decorated class to be serialized
Class decorator that allows the decorated class to be serialized
by the migrations subsystem.
Accepts an optional kwarg `path` to specify the import path.
The `path` kwarg specifies the import path.
"""
def decorator(klass):
def __new__(cls, *args, **kwargs):
@ -19,7 +19,7 @@ def deconstructible(*args, path=None):
def deconstruct(obj):
"""
Returns a 3-tuple of class import path, positional arguments,
Return a 3-tuple of class import path, positional arguments,
and keyword arguments.
"""
# Fallback version

6
django/utils/decorators.py
View File

@ -14,7 +14,7 @@ class classonlymethod(classmethod):
def method_decorator(decorator, name=''):
"""
Converts a function decorator into a method decorator
Convert a function decorator into a method decorator
"""
# 'obj' can be a class or a function. If 'obj' is a function at the time it
# is passed to _dec, it will eventually be a method of the class it is
@ -90,7 +90,7 @@ def method_decorator(decorator, name=''):
def decorator_from_middleware_with_args(middleware_class):
"""
Like decorator_from_middleware, but returns a function
Like decorator_from_middleware, but return a function
that accepts the arguments to be passed to the middleware_class.
Use like::
@ -106,7 +106,7 @@ def decorator_from_middleware_with_args(middleware_class):
def decorator_from_middleware(middleware_class):
"""
Given a middleware class (not an instance), returns a view decorator. This
Given a middleware class (not an instance), return a view decorator. This
lets you use middleware functionality on a per-view basis. The middleware
is created with no params passed.
"""

25
django/utils/encoding.py
View File

@ -72,7 +72,7 @@ def force_text(s, encoding='utf-8', strings_only=False, errors='strict'):
def smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict'):
"""
Returns a bytestring version of 's', encoded as specified in 'encoding'.
Return a bytestring version of 's', encoded as specified in 'encoding'.
If strings_only is True, don't convert (some) non-string-like objects.
"""
@ -171,12 +171,12 @@ _hextobyte.update({
def uri_to_iri(uri):
"""
Converts a Uniform Resource Identifier(URI) into an Internationalized
Convert a Uniform Resource Identifier(URI) into an Internationalized
Resource Identifier(IRI).
This is the algorithm from section 3.2 of RFC 3987, excluding step 4.
Takes an URI in ASCII bytes (e.g. '/I%20%E2%99%A5%20Django/') and returns
Take an URI in ASCII bytes (e.g. '/I%20%E2%99%A5%20Django/') and return
a string containing the encoded result (e.g. '/I%20♥%20Django/').
"""
if uri is None:
@ -225,8 +225,8 @@ def escape_uri_path(path):
def repercent_broken_unicode(path):
"""
As per section 3.2 of RFC 3987, step three of converting a URI into an IRI,
we need to re-percent-encode any octet produced that is not part of a
strictly legal UTF-8 octet sequence.
repercent-encode any octet produced that is not part of a strictly legal
UTF-8 octet sequence.
"""
try:
path.decode()
@ -241,12 +241,9 @@ def filepath_to_uri(path):
"""Convert a file system path to a URI portion that is suitable for
inclusion in a URL.
This method will encode certain chars that would normally be recognized as
special chars for URIs. Note that this method does not encode the '
character, as it is a valid character within URIs. See
encodeURIComponent() JavaScript function for more details.
Return a string containing the result.
Encode certain chars that would normally be recognized as special chars
for URIs. Do not encode the ' character, as it is a valid character
within URIs. See the encodeURIComponent() JavaScript function for details.
"""
if path is None:
return path
@ -257,9 +254,9 @@ def filepath_to_uri(path):
def get_system_encoding():
"""
The encoding of the default system locale but falls back to the given
fallback encoding if the encoding is unsupported by python or could
not be determined. See tickets #10335 and #5846
The encoding of the default system locale. Fallback to 'ascii' if the
#encoding is unsupported by Python or could not be determined. See tickets
#10335 and #5846.
"""
try:
encoding = locale.getdefaultlocale()[1] or 'ascii'

12
django/utils/feedgenerator.py
View File

@ -68,7 +68,7 @@ def rfc3339_date(date):
def get_tag_uri(url, date):
"""
Creates a TagURI.
Create a TagURI.
See http://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
"""
@ -176,14 +176,14 @@ class SyndicationFeed:
def write(self, outfile, encoding):
"""
Outputs the feed in the given encoding to outfile, which is a file-like
Output the feed in the given encoding to outfile, which is a file-like
object. Subclasses should override this.
"""
raise NotImplementedError('subclasses of SyndicationFeed must provide a write() method')
def writeString(self, encoding):
"""
Returns the feed in the given encoding as a string.
Return the feed in the given encoding as a string.
"""
s = StringIO()
self.write(s, encoding)
@ -191,8 +191,8 @@ class SyndicationFeed:
def latest_post_date(self):
"""
Returns the latest item's pubdate or updateddate. If no items
have either of these attributes this returns the current UTC date/time.
Return the latest item's pubdate or updateddate. If no items
have either of these attributes this return the current UTC date/time.
"""
latest_date = None
date_keys = ('updateddate', 'pubdate')
@ -209,7 +209,7 @@ class SyndicationFeed:
class Enclosure:
"Represents an RSS enclosure"
"""An RSS enclosure"""
def __init__(self, url, length, mime_type):
"All args are expected to be strings"
self.length, self.mime_type = length, mime_type

36
django/utils/formats.py
View File

@ -59,9 +59,7 @@ def reset_format_cache():
def iter_format_modules(lang, format_module_path=None):
"""
Does the heavy lifting of finding format modules.
"""
"""Find format modules."""
if not check_for_language(lang):
return
@ -88,9 +86,7 @@ def iter_format_modules(lang, format_module_path=None):
def get_format_modules(lang=None, reverse=False):
"""
Returns a list of the format modules found
"""
"""Return a list of the format modules found."""
if lang is None:
lang = get_language()
if lang not in _format_modules_cache:
@ -103,11 +99,11 @@ def get_format_modules(lang=None, reverse=False):
def get_format(format_type, lang=None, use_l10n=None):
"""
For a specific format type, returns the format for the current
language (locale), defaults to the format in the settings.
format_type is the name of the format, e.g. 'DATE_FORMAT'
For a specific format type, return the format for the current
language (locale). Default to the format in the settings.
format_type is the name of the format, e.g. 'DATE_FORMAT'.
If use_l10n is provided and is not None, that will force the value to
If use_l10n is provided and is not None, it forces the value to
be localized (or not), overriding the value of settings.USE_L10N.
"""
use_l10n = use_l10n or (use_l10n is None and settings.USE_L10N)
@ -151,8 +147,8 @@ get_format_lazy = lazy(get_format, str, list, tuple)
def date_format(value, format=None, use_l10n=None):
"""
Formats a datetime.date or datetime.datetime object using a
localizable format
Format a datetime.date or datetime.datetime object using a
localizable format.
If use_l10n is provided and is not None, that will force the value to
be localized (or not), overriding the value of settings.USE_L10N.
@ -162,9 +158,9 @@ def date_format(value, format=None, use_l10n=None):
def time_format(value, format=None, use_l10n=None):
"""
Formats a datetime.time object using a localizable format
Format a datetime.time object using a localizable format.
If use_l10n is provided and is not None, that will force the value to
If use_l10n is provided and is not None, it forces the value to
be localized (or not), overriding the value of settings.USE_L10N.
"""
return dateformat.time_format(value, get_format(format or 'TIME_FORMAT', use_l10n=use_l10n))
@ -172,9 +168,9 @@ def time_format(value, format=None, use_l10n=None):
def number_format(value, decimal_pos=None, use_l10n=None, force_grouping=False):
"""
Formats a numeric value using localization settings
Format a numeric value using localization settings.
If use_l10n is provided and is not None, that will force the value to
If use_l10n is provided and is not None, it forces the value to
be localized (or not), overriding the value of settings.USE_L10N.
"""
if use_l10n or (use_l10n is None and settings.USE_L10N):
@ -193,10 +189,10 @@ def number_format(value, decimal_pos=None, use_l10n=None, force_grouping=False):
def localize(value, use_l10n=None):
"""
Checks if value is a localizable type (date, number...) and returns it
Check if value is a localizable type (date, number...) and return it
formatted as a string using current locale format.
If use_l10n is provided and is not None, that will force the value to
If use_l10n is provided and is not None, it forces the value to
be localized (or not), overriding the value of settings.USE_L10N.
"""
if isinstance(value, str): # Handle strings first for performance reasons.
@ -216,7 +212,7 @@ def localize(value, use_l10n=None):
def localize_input(value, default=None):
"""
Checks if an input value is a localizable type and returns it
Check if an input value is a localizable type and return it
formatted with the appropriate formatting string of the current locale.
"""
if isinstance(value, str): # Handle strings first for performance reasons.
@ -241,7 +237,7 @@ def localize_input(value, default=None):
def sanitize_separators(value):
"""
Sanitizes a value according to the current decimal and
Sanitize a value according to the current decimal and
thousand separator setting. Used with form field input.
"""
if settings.USE_L10N and isinstance(value, str):

11
django/utils/functional.py
View File

@ -34,17 +34,16 @@ class cached_property:
class Promise:
"""
This is just a base class for the proxy class created in
the closure of the lazy function. It can be used to recognize
promises in code.
Base class for the proxy class created in the closure of the lazy function.
It's used to recognize promises in code.
"""
pass
def lazy(func, *resultclasses):
"""
Turns any callable into a lazy evaluated callable. You need to give result
classes or types -- at least one is needed so that the automatic forcing of
Turn any callable into a lazy evaluated callable. result classes or types
is required -- at least one is needed so that the automatic forcing of
the lazy evaluation code is triggered. Results are not memoized; the
function is evaluated on every access.
"""
@ -383,7 +382,7 @@ class SimpleLazyObject(LazyObject):
def partition(predicate, values):
"""
Splits the values into two sets, based on the return value of the function
Split the values into two sets, based on the return value of the function
(True/False). e.g.:
>>> partition(lambda x: x > 3, range(5))

37
django/utils/html.py
View File

@ -35,12 +35,12 @@ simple_email_re = re.compile(r'^\S+@\S+\.\S+$')
@keep_lazy(str, SafeText)
def escape(text):
"""
Returns the given text with ampersands, quotes and angle brackets encoded
Return the given text with ampersands, quotes and angle brackets encoded
for use in HTML.
This function always escapes its input, even if it's already escaped and
marked as such. This may result in double-escaping. If this is a concern,
use conditional_escape() instead.
Always escape input, even if it's already escaped and marked as such.
This may result in double-escaping. If this is a concern, use
conditional_escape() instead.
"""
return mark_safe(
force_text(text).replace('&', '&amp;').replace('<', '&lt;')
@ -68,7 +68,7 @@ _js_escapes.update((ord('%c' % z), '\\u%04X' % z) for z in range(32))
@keep_lazy(str, SafeText)
def escapejs(value):
"""Hex encodes characters for use in JavaScript strings."""
"""Hex encode characters for use in JavaScript strings."""
return mark_safe(force_text(value).translate(_js_escapes))
@ -89,8 +89,8 @@ def conditional_escape(text):
def format_html(format_string, *args, **kwargs):
"""
Similar to str.format, but passes all arguments through conditional_escape,
and calls 'mark_safe' on the result. This function should be used instead
Similar to str.format, but pass all arguments through conditional_escape(),
and call mark_safe() on the result. This function should be used instead
of str.format or % interpolation to build up small HTML fragments.
"""
args_safe = map(conditional_escape, args)
@ -119,7 +119,7 @@ def format_html_join(sep, format_string, args_generator):
@keep_lazy_text
def linebreaks(value, autoescape=False):
"""Converts newlines into <p> and <br />s."""
"""Convert newlines into <p> and <br />s."""
value = normalize_newlines(force_text(value))
paras = re.split('\n{2,}', value)
if autoescape:
@ -167,7 +167,7 @@ def _strip_once(value):
@keep_lazy_text
def strip_tags(value):
"""Returns the given HTML with all tags stripped."""
"""Return the given HTML with all tags stripped."""
# Note: in typical case this loop executes _strip_once once. Loop condition
# is redundant, but helps to reduce number of executions of _strip_once.
value = force_text(value)
@ -182,12 +182,12 @@ def strip_tags(value):
@keep_lazy_text
def strip_spaces_between_tags(value):
"""Returns the given HTML with spaces between tags removed."""
"""Return the given HTML with spaces between tags removed."""
return re.sub(r'>\s+<', '><', force_text(value))
def smart_urlquote(url):
"Quotes a URL if it isn't already quoted."
"""Quote a URL if it isn't already quoted."""
def unquote_quote(segment):
segment = unquote(segment)
# Tilde is part of RFC3986 Unreserved Characters
@ -225,20 +225,19 @@ def smart_urlquote(url):
@keep_lazy_text
def urlize(text, trim_url_limit=None, nofollow=False, autoescape=False):
"""
Converts any URLs in text into clickable links.
Convert any URLs in text into clickable links.
Works on http://, https://, www. links, and also on links ending in one of
the original seven gTLDs (.com, .edu, .gov, .int, .mil, .net, and .org).
Links can have trailing punctuation (periods, commas, close-parens) and
leading punctuation (opening parens) and it'll still do the right thing.
If trim_url_limit is not None, the URLs in the link text longer than this
limit will be truncated to trim_url_limit-3 characters and appended with
an ellipsis.
If trim_url_limit is not None, truncate the URLs in the link text longer
than this limit to trim_url_limit-3 characters and append an ellipsis.
If nofollow is True, the links will get a rel="nofollow" attribute.
If nofollow is True, give the links a rel="nofollow" attribute.
If autoescape is True, the link text and URLs will be autoescaped.
If autoescape is True, autoescape the link text and URLs.
"""
safe_input = isinstance(text, SafeData)
@ -249,8 +248,8 @@ def urlize(text, trim_url_limit=None, nofollow=False, autoescape=False):
def unescape(text, trail):
"""
If input URL is HTML-escaped, unescape it so as we can safely feed it to
smart_urlquote. For example:
If input URL is HTML-escaped, unescape it so that it can be safely fed
to smart_urlquote. For example:
http://example.com?x=1&amp;y=&lt;2&gt; => http://example.com?x=1&y=<2>
"""
unescaped = (text + trail).replace(

42
django/utils/http.py
View File

@ -98,13 +98,13 @@ def urlencode(query, doseq=False):
def cookie_date(epoch_seconds=None):
"""
Formats the time to ensure compatibility with Netscape's cookie standard.
Format the time to ensure compatibility with Netscape's cookie standard.
Accepts a floating point number expressed in seconds since the epoch, in
UTC - such as that outputted by time.time(). If set to None, defaults to
the current time.
`epoch_seconds` is a floating point number expressed in seconds since the
epoch, in UTC - such as that outputted by time.time(). If set to None, it
defaults to the current time.
Outputs a string in the format 'Wdy, DD-Mon-YYYY HH:MM:SS GMT'.
Output a string in the format 'Wdy, DD-Mon-YYYY HH:MM:SS GMT'.
"""
rfcdate = formatdate(epoch_seconds)
return '%s-%s-%s GMT' % (rfcdate[:7], rfcdate[8:11], rfcdate[12:25])
@ -112,26 +112,26 @@ def cookie_date(epoch_seconds=None):
def http_date(epoch_seconds=None):
"""
Formats the time to match the RFC1123 date format as specified by HTTP
Format the time to match the RFC1123 date format as specified by HTTP
RFC7231 section 7.1.1.1.
Accepts a floating point number expressed in seconds since the epoch, in
UTC - such as that outputted by time.time(). If set to None, defaults to
the current time.
`epoch_seconds` is a floating point number expressed in seconds since the
epoch, in UTC - such as that outputted by time.time(). If set to None, it
defaults to the current time.
Outputs a string in the format 'Wdy, DD Mon YYYY HH:MM:SS GMT'.
Output a string in the format 'Wdy, DD Mon YYYY HH:MM:SS GMT'.
"""
return formatdate(epoch_seconds, usegmt=True)
def parse_http_date(date):
"""
Parses a date format as specified by HTTP RFC7231 section 7.1.1.1.
Parse a date format as specified by HTTP RFC7231 section 7.1.1.1.
The three formats allowed by the RFC are accepted, even if only the first
one is still in widespread use.
Returns an integer expressed in seconds since the epoch, in UTC.
Return an integer expressed in seconds since the epoch, in UTC.
"""
# emails.Util.parsedate does the job for RFC1123 dates; unfortunately
# RFC7231 makes it mandatory to support RFC850 dates too. So we roll
@ -162,7 +162,7 @@ def parse_http_date(date):
def parse_http_date_safe(date):
"""
Same as parse_http_date, but returns None if the input is invalid.
Same as parse_http_date, but return None if the input is invalid.
"""
try:
return parse_http_date(date)
@ -174,8 +174,8 @@ def parse_http_date_safe(date):
def base36_to_int(s):
"""
Converts a base 36 string to an ``int``. Raises ``ValueError` if the
input won't fit into an int.
Convert a base 36 string to an int. Raise ValueError if the input won't fit
into an int.
"""
# To prevent overconsumption of server resources, reject any
# base36 string that is longer than 13 base36 digits (13 digits
@ -186,9 +186,7 @@ def base36_to_int(s):
def int_to_base36(i):
"""
Converts an integer to a base36 string
"""
"""Convert an integer to a base36 string."""
char_set = '0123456789abcdefghijklmnopqrstuvwxyz'
if i < 0:
raise ValueError("Negative base36 conversion input.")
@ -203,15 +201,15 @@ def int_to_base36(i):
def urlsafe_base64_encode(s):
"""
Encodes a bytestring in base64 for use in URLs, stripping any trailing
equal signs.
Encode a bytestring in base64 for use in URLs. Strip any trailing equal
signs.
"""
return base64.urlsafe_b64encode(s).rstrip(b'\n=')
def urlsafe_base64_decode(s):
"""
Decodes a base64 encoded string, adding back any trailing equal signs that
Decode a base64 encoded string. Add back any trailing equal signs that
might have been stripped.
"""
s = force_bytes(s)
@ -270,7 +268,7 @@ def is_safe_url(url, host=None, allowed_hosts=None, require_https=False):
Return ``True`` if the url is a safe redirection (i.e. it doesn't point to
a different host and uses a safe scheme).
Always returns ``False`` on an empty url.
Always return ``False`` on an empty url.
If ``require_https`` is ``True``, only 'https' will be considered a valid
scheme, as opposed to 'http' and 'https' with the default, ``False``.

8
django/utils/ipv6.py
View File

@ -37,13 +37,7 @@ def clean_ipv6_address(ip_str, unpack_ipv4=False,
def is_valid_ipv6_address(ip_str):
"""
Ensure we have a valid IPv6 address.
Args:
ip_str: A string, the IPv6 address.
Returns:
A boolean, True if this is a valid IPv6 address.
Return whether or not the `ip_str` string is a valid IPv6 address.
"""
try:
ipaddress.IPv6Address(ip_str)

9
django/utils/itercompat.py
View File

@ -1,12 +1,5 @@
"""
Providing iterator functions that are not in all version of Python we support.
Where possible, we try to use the system-native version and only fall back to
these implementations if necessary.
"""
def is_iterable(x):
"A implementation independent way of checking for iterables"
"An implementation independent way of checking for iterables"
try:
iter(x)
except TypeError:

2
django/utils/jslex.py
View File

@ -50,7 +50,7 @@ class Lexer:
"""
Lexically analyze `text`.
Yields pairs (`name`, `tokentext`).
Yield pairs (`name`, `tokentext`).
"""
end = len(text)
state = self.state

8
django/utils/lorem_ipsum.py
View File

@ -55,7 +55,7 @@ COMMON_WORDS = (
def sentence():
"""
Returns a randomly generated sentence of lorem ipsum text.
Return a randomly generated sentence of lorem ipsum text.
The first word is capitalized, and the sentence ends in either a period or
question mark. Commas are added at random.
@ -70,7 +70,7 @@ def sentence():
def paragraph():
"""
Returns a randomly generated paragraph of lorem ipsum text.
Return a randomly generated paragraph of lorem ipsum text.
The paragraph consists of between 1 and 4 sentences, inclusive.
"""
@ -79,7 +79,7 @@ def paragraph():
def paragraphs(count, common=True):
"""
Returns a list of paragraphs as returned by paragraph().
Return a list of paragraphs as returned by paragraph().
If `common` is True, then the first paragraph will be the standard
'lorem ipsum' paragraph. Otherwise, the first paragraph will be random
@ -96,7 +96,7 @@ def paragraphs(count, common=True):
def words(count, common=True):
"""
Returns a string of `count` lorem ipsum words separated by a single space.
Return a string of `count` lorem ipsum words separated by a single space.
If `common` is True, then the first 19 words will be the standard
'lorem ipsum' words. Otherwise, all words will be selected randomly.

2
django/utils/numberformat.py
View File

@ -7,7 +7,7 @@ from django.utils.safestring import mark_safe
def format(number, decimal_sep, decimal_pos=None, grouping=0, thousand_sep='',
force_grouping=False):
"""
Gets a number (as a number or string), and returns it as a string,
Get a number (as a number or string), and return it as a string,
using formats defined as arguments:
* decimal_sep: Decimal separator symbol (for example ".")

30
django/utils/regex_helper.py
View File

@ -27,28 +27,20 @@ ESCAPE_MAPPINGS = {
class Choice(list):
"""
Used to represent multiple possibilities at this point in a pattern string.
We use a distinguished type, rather than a list, so that the usage in the
code is clear.
"""
"""Represent multiple possibilities at this point in a pattern string."""
class Group(list):
"""
Used to represent a capturing group in the pattern string.
"""
"""Represent a capturing group in the pattern string."""
class NonCapture(list):
"""
Used to represent a non-capturing group in the pattern string.
"""
"""Represent a non-capturing group in the pattern string."""
def normalize(pattern):
r"""
Given a reg-exp pattern, normalizes it to an iterable of forms that
Given a reg-exp pattern, normalize it to an iterable of forms that
suffice for reverse matching. This does the following:
(1) For any repeating sections, keeps the minimum number of occurrences
@ -212,7 +204,7 @@ def next_char(input_iter):
its class (e.g. \w -> "x"). If the escaped character is one that is
skipped, it is not returned (the next character is returned instead).
Yields the next character, along with a boolean indicating whether it is a
Yield the next character, along with a boolean indicating whether it is a
raw (unescaped) character or not.
"""
for ch in input_iter:
@ -228,8 +220,8 @@ def next_char(input_iter):
def walk_to_end(ch, input_iter):
"""
The iterator is currently inside a capturing group. We want to walk to the
close of this group, skipping over any nested groups and handling escaped
The iterator is currently inside a capturing group. Walk to the close of
this group, skipping over any nested groups and handling escaped
parentheses correctly.
"""
if ch == '(':
@ -252,7 +244,7 @@ def get_quantifier(ch, input_iter):
Parse a quantifier from the input, where "ch" is the first character in the
quantifier.
Returns the minimum number of occurrences permitted by the quantifier and
Return the minimum number of occurrences permitted by the quantifier and
either None or the next character from the input_iter if the next character
is not part of the quantifier.
"""
@ -286,7 +278,7 @@ def get_quantifier(ch, input_iter):
def contains(source, inst):
"""
Returns True if the "source" contains an instance of "inst". False,
Return True if the "source" contains an instance of "inst". False,
otherwise.
"""
if isinstance(source, inst):
@ -300,8 +292,8 @@ def contains(source, inst):
def flatten_result(source):
"""
Turns the given source sequence into a list of reg-exp possibilities and
their arguments. Returns a list of strings and a list of argument lists.
Turn the given source sequence into a list of reg-exp possibilities and
their arguments. Return a list of strings and a list of argument lists.
Each of the two lists will be of the same length.
"""
if source is None:

2
django/utils/safestring.py
View File

@ -11,7 +11,7 @@ from django.utils.functional import Promise, wraps
class SafeData:
def __html__(self):
"""
Returns the html representation of a string for interoperability.
Return the html representation of a string for interoperability.
This allows other template engines to understand Django's SafeData.
"""

6
django/utils/termcolors.py
View File

@ -12,12 +12,12 @@ opt_dict = {'bold': '1', 'underscore': '4', 'blink': '5', 'reverse': '7', 'conce
def colorize(text='', opts=(), **kwargs):
"""
Returns your text, enclosed in ANSI graphics codes.
Return your text, enclosed in ANSI graphics codes.
Depends on the keyword arguments 'fg' and 'bg', and the contents of
the opts tuple/list.
Returns the RESET code if no parameters are given.
Return the RESET code if no parameters are given.
Valid colors:
'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
@ -57,7 +57,7 @@ def colorize(text='', opts=(), **kwargs):
def make_style(opts=(), **kwargs):
"""
Returns a function with default parameters for colorize()
Return a function with default parameters for colorize()
Example:
bold_red = make_style(opts=('bold',), fg='red')

47
django/utils/text.py
View File

@ -32,10 +32,10 @@ def wrap(text, width):
A word-wrap function that preserves existing line breaks. Expects that
existing line breaks are posix newlines.
All white space is preserved except added line breaks consume the space on
Preserve all white space except added line breaks consume the space on
which they break the line.
Long words are not wrapped, so the output text may have lines longer than
Don't wrap long words, thus the output text may have lines longer than
``width``.
"""
text = force_text(text)
@ -84,12 +84,12 @@ class Truncator(SimpleLazyObject):
def chars(self, num, truncate=None, html=False):
"""
Returns the text truncated to be no longer than the specified number
Return the text truncated to be no longer than the specified number
of characters.
Takes an optional argument of what should be used to notify that the
string has been truncated, defaulting to a translatable string of an
ellipsis (...).
`truncate` specifies what should be used to notify that the string has
been truncated, defaulting to a translatable string of an ellipsis
(...).
"""
self._setup()
length = int(num)
@ -107,9 +107,7 @@ class Truncator(SimpleLazyObject):
return self._text_chars(length, truncate, text, truncate_len)
def _text_chars(self, length, truncate, text, truncate_len):
"""
Truncates a string after a certain number of chars.
"""
"""Truncate a string after a certain number of chars."""
s_len = 0
end_index = None
for i, char in enumerate(text):
@ -130,9 +128,9 @@ class Truncator(SimpleLazyObject):
def words(self, num, truncate=None, html=False):
"""
Truncates a string after a certain number of words. Takes an optional
argument of what should be used to notify that the string has been
truncated, defaulting to ellipsis (...).
Truncate a string after a certain number of words. `truncate` specifies
what should be used to notify that the string has been truncated,
defaulting to ellipsis (...).
"""
self._setup()
length = int(num)
@ -142,9 +140,9 @@ class Truncator(SimpleLazyObject):
def _text_words(self, length, truncate):
"""
Truncates a string after a certain number of words.
Truncate a string after a certain number of words.
Newlines in the string will be stripped.
Strip newlines in the string.
"""
words = self._wrapped.split()
if len(words) > length:
@ -154,11 +152,11 @@ class Truncator(SimpleLazyObject):
def _truncate_html(self, length, truncate, text, truncate_len, words):
"""
Truncates HTML to a certain number of chars (not counting tags and
Truncate HTML to a certain number of chars (not counting tags and
comments), or, if words is True, then to a certain number of words.
Closes opened tags if they were correctly closed in the given HTML.
Close opened tags if they were correctly closed in the given HTML.
Newlines in the HTML are preserved.
Preserve newlines in the HTML.
"""
if words and length <= 0:
return ''
@ -228,10 +226,10 @@ class Truncator(SimpleLazyObject):
@keep_lazy_text
def get_valid_filename(s):
"""
Returns the given string converted to a string that can be used for a clean
filename. Specifically, leading and trailing spaces are removed; other
spaces are converted to underscores; and anything that is not an
alphanumeric, dash, underscore, or dot, is removed.
Return the given string converted to a string that can be used for a clean
filename. Remove leading and trailing spaces; convert other spaces to
underscores; and remove anything that is not an alphanumeric, dash,
underscore, or dot.
>>> get_valid_filename("john's portrait in 2004.jpg")
'johns_portrait_in_2004.jpg'
"""
@ -265,14 +263,14 @@ def get_text_list(list_, last_word=gettext_lazy('or')):
@keep_lazy_text
def normalize_newlines(text):
"""Normalizes CRLF and CR newlines to just LF."""
"""Normalize CRLF and CR newlines to just LF."""
text = force_text(text)
return re_newlines.sub('\n', text)
@keep_lazy_text
def phone2numeric(phone):
"""Converts a phone number with letters into its numeric equivalent."""
"""Convert a phone number with letters into its numeric equivalent."""
char2number = {
'a': '2', 'b': '2', 'c': '2', 'd': '3', 'e': '3', 'f': '3', 'g': '4',
'h': '4', 'i': '4', 'j': '5', 'k': '5', 'l': '5', 'm': '6', 'n': '6',
@ -426,8 +424,7 @@ def slugify(value, allow_unicode=False):
def camel_case_to_spaces(value):
"""
Splits CamelCase and converts to lower case. Also strips leading and
trailing whitespace.
Split CamelCase and convert to lower case. Strip surrounding whitespace.
"""
return re_camel_case.sub(r' \1', value).strip().lower()

9
django/utils/timesince.py
View File

@ -17,9 +17,9 @@ TIMESINCE_CHUNKS = (
def timesince(d, now=None, reversed=False):
"""
Takes two datetime objects and returns the time between d and now
as a nicely formatted string, e.g. "10 minutes". If d occurs after now,
then "0 minutes" is returned.
Take two datetime objects and return the time between d and now as a nicely
formatted string, e.g. "10 minutes". If d occurs after now, return
"0 minutes".
Units used are years, months, weeks, days, hours, and minutes.
Seconds and microseconds are ignored. Up to two adjacent units will be
@ -72,7 +72,6 @@ def timesince(d, now=None, reversed=False):
def timeuntil(d, now=None):
"""
Like timesince, but returns a string measuring the time until
the given time.
Like timesince, but return a string measuring the time until the given time.
"""
return timesince(d, now, reversed=True)

50
django/utils/timezone.py
View File

@ -51,14 +51,12 @@ class FixedOffset(tzinfo):
return ZERO
# UTC time zone as a tzinfo instance.
utc = pytz.utc
"""UTC time zone as a tzinfo instance."""
def get_fixed_timezone(offset):
"""
Returns a tzinfo instance with a fixed offset from UTC.
"""
"""Return a tzinfo instance with a fixed offset from UTC."""
if isinstance(offset, timedelta):
offset = offset.seconds // 60
sign = '-' if offset < 0 else '+'
@ -72,7 +70,7 @@ def get_fixed_timezone(offset):
@functools.lru_cache()
def get_default_timezone():
"""
Returns the default time zone as a tzinfo instance.
Return the default time zone as a tzinfo instance.
This is the time zone defined by settings.TIME_ZONE.
"""
@ -81,9 +79,7 @@ def get_default_timezone():
# This function exists for consistency with get_current_timezone_name
def get_default_timezone_name():
"""
Returns the name of the default time zone.
"""
"""Return the name of the default time zone."""
return _get_timezone_name(get_default_timezone())
@ -91,23 +87,17 @@ _active = local()
def get_current_timezone():
"""
Returns the currently active time zone as a tzinfo instance.
"""
"""Return the currently active time zone as a tzinfo instance."""
return getattr(_active, "value", get_default_timezone())
def get_current_timezone_name():
"""
Returns the name of the currently active time zone.
"""
"""Return the name of the currently active time zone."""
return _get_timezone_name(get_current_timezone())
def _get_timezone_name(timezone):
"""
Returns the name of ``timezone``.
"""
"""Return the name of ``timezone``."""
try:
# for pytz timezones
return timezone.zone
@ -123,7 +113,7 @@ def _get_timezone_name(timezone):
def activate(timezone):
"""
Sets the time zone for the current thread.
Set the time zone for the current thread.
The ``timezone`` argument must be an instance of a tzinfo subclass or a
time zone name.
@ -138,7 +128,7 @@ def activate(timezone):
def deactivate():
"""
Unsets the time zone for the current thread.
Unset the time zone for the current thread.
Django will then use the time zone defined by settings.TIME_ZONE.
"""
@ -150,8 +140,8 @@ class override(ContextDecorator):
"""
Temporarily set the time zone for the current thread.
This is a context manager that uses ``~django.utils.timezone.activate()``
to set the timezone on entry, and restores the previously active timezone
This is a context manager that uses django.utils.timezone.activate()
to set the timezone on entry and restores the previously active timezone
on exit.
The ``timezone`` argument must be an instance of a ``tzinfo`` subclass, a
@ -179,7 +169,7 @@ class override(ContextDecorator):
def template_localtime(value, use_tz=None):
"""
Checks if value is a datetime and converts it to local time if necessary.
Check if value is a datetime and converts it to local time if necessary.
If use_tz is provided and is not None, that will force the value to
be converted (or not), overriding the value of settings.USE_TZ.
@ -199,7 +189,7 @@ def template_localtime(value, use_tz=None):
def localtime(value=None, timezone=None):
"""
Converts an aware datetime.datetime to local time.
Convert an aware datetime.datetime to local time.
Only aware datetimes are allowed. When value is omitted, it defaults to
now().
@ -236,7 +226,7 @@ def localdate(value=None, timezone=None):
def now():
"""
Returns an aware or naive datetime.datetime, depending on settings.USE_TZ.
Return an aware or naive datetime.datetime, depending on settings.USE_TZ.
"""
if settings.USE_TZ:
# timeit shows that datetime.now(tz=utc) is 24% slower
@ -250,7 +240,7 @@ def now():
def is_aware(value):
"""
Determines if a given datetime.datetime is aware.
Determine if a given datetime.datetime is aware.
The concept is defined in Python's docs:
http://docs.python.org/library/datetime.html#datetime.tzinfo
@ -263,7 +253,7 @@ def is_aware(value):
def is_naive(value):
"""
Determines if a given datetime.datetime is naive.
Determine if a given datetime.datetime is naive.
The concept is defined in Python's docs:
http://docs.python.org/library/datetime.html#datetime.tzinfo
@ -275,9 +265,7 @@ def is_naive(value):
def make_aware(value, timezone=None, is_dst=None):
"""
Makes a naive datetime.datetime in a given time zone aware.
"""
"""Make a naive datetime.datetime in a given time zone aware."""
if timezone is None:
timezone = get_current_timezone()
if hasattr(timezone, 'localize'):
@ -293,9 +281,7 @@ def make_aware(value, timezone=None, is_dst=None):
def make_naive(value, timezone=None):
"""
Makes an aware datetime.datetime naive in a given time zone.
"""
"""Make an aware datetime.datetime naive in a given time zone."""
if timezone is None:
timezone = get_current_timezone()
# Emulate the behavior of astimezone() on Python < 3.6.

63
django/utils/translation/trans_real.py
View File

@ -59,7 +59,7 @@ def reset_cache(**kwargs):
def to_locale(language, to_lower=False):
"""
Turns a language name (en-us) into a locale name (en_US). If 'to_lower' is
Turn a language name (en-us) into a locale name (en_US). If 'to_lower' is
True, the last component is lower-cased (en_us).
"""
p = language.find('-')
@ -76,7 +76,7 @@ def to_locale(language, to_lower=False):
def to_language(locale):
"""Turns a locale name (en_US) into a language name (en-us)."""
"""Turn a locale name (en_US) into a language name (en-us)."""
p = locale.find('_')
if p >= 0:
return locale[:p].lower() + '-' + locale[p + 1:].lower()
@ -86,8 +86,7 @@ def to_language(locale):
class DjangoTranslation(gettext_module.GNUTranslations):
"""
This class sets up the GNUTranslations context with regard to output
charset.
Set up the GNUTranslations context with regard to output charset.
This translation object will be constructed out of multiple GNUTranslations
objects by merging their catalogs. It will construct an object for the
@ -138,7 +137,7 @@ class DjangoTranslation(gettext_module.GNUTranslations):
def _new_gnu_trans(self, localedir, use_null_fallback=True):
"""
Returns a mergeable gettext.GNUTranslations instance.
Return a mergeable gettext.GNUTranslations instance.
A convenience wrapper. By default gettext uses 'fallback=False'.
Using param `use_null_fallback` to avoid confusion with any other
@ -152,14 +151,14 @@ class DjangoTranslation(gettext_module.GNUTranslations):
fallback=use_null_fallback)
def _init_translation_catalog(self):
"""Creates a base catalog using global django translations."""
"""Create a base catalog using global django translations."""
settingsfile = sys.modules[settings.__module__].__file__
localedir = os.path.join(os.path.dirname(settingsfile), 'locale')
translation = self._new_gnu_trans(localedir)
self.merge(translation)
def _add_installed_apps_translations(self):
"""Merges translations from each installed app."""
"""Merge translations from each installed app."""
try:
app_configs = reversed(list(apps.get_app_configs()))
except AppRegistryNotReady:
@ -174,13 +173,13 @@ class DjangoTranslation(gettext_module.GNUTranslations):
self.merge(translation)
def _add_local_translations(self):
"""Merges translations defined in LOCALE_PATHS."""
"""Merge translations defined in LOCALE_PATHS."""
for localedir in reversed(settings.LOCALE_PATHS):
translation = self._new_gnu_trans(localedir)
self.merge(translation)
def _add_fallback(self, localedirs=None):
"""Sets the GNUTranslations() fallback with the default language."""
"""Set the GNUTranslations() fallback with the default language."""
# Don't set a fallback for the default language or any English variant
# (as it's empty, so it'll ALWAYS fall back to the default language)
if self.__language == settings.LANGUAGE_CODE or self.__language.startswith('en'):
@ -207,17 +206,17 @@ class DjangoTranslation(gettext_module.GNUTranslations):
self._catalog.update(other._catalog)
def language(self):
"""Returns the translation language."""
"""Return the translation language."""
return self.__language
def to_language(self):
"""Returns the translation language name."""
"""Return the translation language name."""
return self.__to_language
def translation(language):
"""
Returns a translation object in the default 'django' domain.
Return a translation object in the default 'django' domain.
"""
global _translations
if language not in _translations:
@ -227,7 +226,7 @@ def translation(language):
def activate(language):
"""
Fetches the translation object for a given language and installs it as the
Fetch the translation object for a given language and install it as the
current translation object for the current thread.
"""
if not language:
@ -237,8 +236,8 @@ def activate(language):
def deactivate():
"""
Deinstalls the currently active translation object so that further _ calls
will resolve against the default translation object, again.
Uninstall the active translation object so that further _() calls resolve
to the default translation object.
"""
if hasattr(_active, "value"):
del _active.value
@ -246,7 +245,7 @@ def deactivate():
def deactivate_all():
"""
Makes the active translation object a NullTranslations() instance. This is
Make the active translation object a NullTranslations() instance. This is
useful when we want delayed translations to appear as the original string
for some reason.
"""
@ -255,7 +254,7 @@ def deactivate_all():
def get_language():
"""Returns the currently selected language."""
"""Return the currently selected language."""
t = getattr(_active, "value", None)
if t is not None:
try:
@ -268,7 +267,7 @@ def get_language():
def get_language_bidi():
"""
Returns selected language's BiDi layout.
Return selected language's BiDi layout.
* False = left-to-right layout
* True = right-to-left layout
@ -283,7 +282,7 @@ def get_language_bidi():
def catalog():
"""
Returns the current active catalog for further processing.
Return the current active catalog for further processing.
This can be used if you need to modify the catalog or want to access the
whole message catalog instead of just translating one string.
"""
@ -308,7 +307,7 @@ def gettext(message):
eol_message = message.replace('\r\n', '\n').replace('\r', '\n')
if len(eol_message) == 0:
# Returns an empty value of the corresponding type if an empty message
# Return an empty value of the corresponding type if an empty message
# is given, instead of metadata, which is the default gettext behavior.
result = type(message)("")
else:
@ -335,7 +334,7 @@ def pgettext(context, message):
def gettext_noop(message):
"""
Marks strings for translation but doesn't translate them now. This can be
Mark strings for translation but don't translate them now. This can be
used to store strings in global variables that should stay in the base
language (because they might be used externally) and will be translated
later.
@ -356,7 +355,7 @@ def do_ntranslate(singular, plural, number, translation_function):
def ngettext(singular, plural, number):
"""
Returns a string of the translation of either the singular or plural,
Return a string of the translation of either the singular or plural,
based on the number.
"""
return do_ntranslate(singular, plural, number, 'ngettext')
@ -375,7 +374,7 @@ def npgettext(context, singular, plural, number):
def all_locale_paths():
"""
Returns a list of paths to user-provides languages files.
Return a list of paths to user-provides languages files.
"""
globalpath = os.path.join(
os.path.dirname(sys.modules[settings.__module__].__file__), 'locale')
@ -385,7 +384,7 @@ def all_locale_paths():
@functools.lru_cache(maxsize=1000)
def check_for_language(lang_code):
"""
Checks whether there is a global language file for the given language
Check whether there is a global language file for the given language
code. This is used to decide whether a user-provided language is
available.
@ -413,10 +412,10 @@ def get_languages():
@functools.lru_cache(maxsize=1000)
def get_supported_language_variant(lang_code, strict=False):
"""
Returns the language-code that's listed in supported languages, possibly
selecting a more generic variant. Raises LookupError if nothing found.
Return the language-code that's listed in supported languages, possibly
selecting a more generic variant. Raise LookupError if nothing is found.
If `strict` is False (the default), the function will look for an alternative
If `strict` is False (the default), look for an alternative
country-specific variant when the currently checked is not found.
lru_cache should have a maxsize to prevent from memory exhaustion attacks,
@ -447,7 +446,7 @@ def get_supported_language_variant(lang_code, strict=False):
def get_language_from_path(path, strict=False):
"""
Returns the language-code if there is a valid language-code
Return the language-code if there is a valid language-code
found in the `path`.
If `strict` is False (the default), the function will look for an alternative
@ -465,7 +464,7 @@ def get_language_from_path(path, strict=False):
def get_language_from_request(request, check_path=False):
"""
Analyzes the request to find what language the user wants the system to
Analyze the request to find what language the user wants the system to
show. Only languages listed in settings.LANGUAGES are taken into account.
If the user requests a sublanguage where we have a main language, we send
out the main language.
@ -513,10 +512,10 @@ def get_language_from_request(request, check_path=False):
def parse_accept_lang_header(lang_string):
"""
Parses the lang_string, which is the body of an HTTP Accept-Language
header, and returns a list of (lang, q-value), ordered by 'q' values.
Parse the lang_string, which is the body of an HTTP Accept-Language
header, and return a list of (lang, q-value), ordered by 'q' values.
Any format errors in lang_string results in an empty list being returned.
Return an empty list if there are any format errors in lang_string.
"""
result = []
pieces = accept_language_re.split(lang_string.lower())

44
django/utils/tree.py
View File

@ -17,25 +17,22 @@ class Node:
default = 'DEFAULT'
def __init__(self, children=None, connector=None, negated=False):
"""
Constructs a new Node. If no connector is given, the default will be
used.
"""
"""Construct a new Node. If no connector is given, use the default."""
self.children = children[:] if children else []
self.connector = connector or self.default
self.negated = negated
# We need this because of django.db.models.query_utils.Q. Q. __init__() is
# Required because django.db.models.query_utils.Q. Q. __init__() is
# problematic, but it is a natural Node subclass in all other respects.
@classmethod
def _new_instance(cls, children=None, connector=None, negated=False):
"""
This is called to create a new instance of this class when we need new
Nodes (or subclasses) in the internal code in this class. Normally, it
just shadows __init__(). However, subclasses with an __init__ signature
that is not an extension of Node.__init__ might need to implement this
method to allow a Node to create a new instance of them (if they have
any extra setting up to do).
Create a new instance of this class when new Nodes (or subclasses) are
needed in the internal code in this class. Normally, it just shadows
__init__(). However, subclasses with an __init__ signature that aren't
an extension of Node.__init__ might need to implement this method to
allow a Node to create a new instance of them (if they have any extra
setting up to do).
"""
obj = Node(children, connector, negated)
obj.__class__ = cls
@ -49,43 +46,34 @@ class Node:
return "<%s: %s>" % (self.__class__.__name__, self)
def __deepcopy__(self, memodict):
"""
Utility method used by copy.deepcopy().
"""
obj = Node(connector=self.connector, negated=self.negated)
obj.__class__ = self.__class__
obj.children = copy.deepcopy(self.children, memodict)
return obj
def __len__(self):
"""
The size of a node if the number of children it has.
"""
"""Return the the number of children this node has."""
return len(self.children)
def __bool__(self):
"""
For truth value testing.
"""
"""Return whether or not this node has children."""
return bool(self.children)
def __contains__(self, other):
"""
Returns True is 'other' is a direct child of this instance.
"""
"""Return True if 'other' is a direct child of this instance."""
return other in self.children
def add(self, data, conn_type, squash=True):
"""
Combines this tree and the data represented by data using the
Combine this tree and the data represented by data using the
connector conn_type. The combine is done by squashing the node other
away if possible.
This tree (self) will never be pushed to a child node of the
combined tree, nor will the connector or negated properties change.
The function returns a node which can be used in place of data
regardless if the node other got squashed or not.
Return a node which can be used in place of data regardless if the
node other got squashed or not.
If `squash` is False the data is prepared and added as a child to
this tree without further logic.
@ -120,7 +108,5 @@ class Node:
return data
def negate(self):
"""
Negate the sense of the root connector.
"""
"""Negate the sense of the root connector."""
self.negated = not self.negated

11
django/utils/version.py
View File

@ -5,7 +5,7 @@ import subprocess
def get_version(version=None):
"Returns a PEP 440-compliant version number from VERSION."
"""Return a PEP 440-compliant version number from VERSION."""
version = get_complete_version(version)
# Now build the two parts of the version number:
@ -29,15 +29,16 @@ def get_version(version=None):
def get_main_version(version=None):
"Returns main version (X.Y[.Z]) from VERSION."
"""Return main version (X.Y[.Z]) from VERSION."""
version = get_complete_version(version)
parts = 2 if version[2] == 0 else 3
return '.'.join(str(x) for x in version[:parts])
def get_complete_version(version=None):
"""Returns a tuple of the django version. If version argument is non-empty,
then checks for correctness of the tuple provided.
"""
Return a tuple of the django version. If version argument is non-empty,
check for correctness of the tuple provided.
"""
if version is None:
from django import VERSION as version
@ -58,7 +59,7 @@ def get_docs_version(version=None):
@functools.lru_cache()
def get_git_changeset():
"""Returns a numeric identifier of the latest git changeset.
"""Return a numeric identifier of the latest git changeset.
The result is the UTC timestamp of the changeset in YYYYMMDDHHMMSS format.
This value isn't guaranteed to be unique, but collisions are very unlikely,