diff --git a/django/utils/_os.py b/django/utils/_os.py index 937ba82fbc..f6a96b221b 100644 --- a/django/utils/_os.py +++ b/django/utils/_os.py @@ -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') diff --git a/django/utils/archive.py b/django/utils/archive.py index 1dd3f9d660..879f3c49f7 100644 --- a/django/utils/archive.py +++ b/django/utils/archive.py @@ -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: diff --git a/django/utils/autoreload.py b/django/utils/autoreload.py index 3fe47200ee..2784a89aeb 100644 --- a/django/utils/autoreload.py +++ b/django/utils/autoreload.py @@ -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): diff --git a/django/utils/cache.py b/django/utils/cache.py index fabdb363b9..7e7428f112 100644 --- a/django/utils/cache.py +++ b/django/utils/cache.py @@ -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. diff --git a/django/utils/crypto.py b/django/utils/crypto.py index db941615be..f6f44856d0 100644 --- a/django/utils/crypto.py +++ b/django/utils/crypto.py @@ -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 diff --git a/django/utils/datastructures.py b/django/utils/datastructures.py index c15cb5eb49..dd405e1337 100644 --- a/django/utils/datastructures.py +++ b/django/utils/datastructures.py @@ -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. """ diff --git a/django/utils/dateformat.py b/django/utils/dateformat.py index 1deee1c377..6c8cab61f5 100644 --- a/django/utils/dateformat.py +++ b/django/utils/dateformat.py @@ -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 "" diff --git a/django/utils/dateparse.py b/django/utils/dateparse.py index d091100a0d..48d15d4c1e 100644 --- a/django/utils/dateparse.py +++ b/django/utils/dateparse.py @@ -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'. diff --git a/django/utils/deconstruct.py b/django/utils/deconstruct.py index c546fc1dea..aa952f6b73 100644 --- a/django/utils/deconstruct.py +++ b/django/utils/deconstruct.py @@ -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 diff --git a/django/utils/decorators.py b/django/utils/decorators.py index 87a20cf23b..a43c168e57 100644 --- a/django/utils/decorators.py +++ b/django/utils/decorators.py @@ -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. """ diff --git a/django/utils/encoding.py b/django/utils/encoding.py index 63f915b139..1ac14a66d7 100644 --- a/django/utils/encoding.py +++ b/django/utils/encoding.py @@ -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' diff --git a/django/utils/feedgenerator.py b/django/utils/feedgenerator.py index 814d767671..9dec126941 100644 --- a/django/utils/feedgenerator.py +++ b/django/utils/feedgenerator.py @@ -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 diff --git a/django/utils/formats.py b/django/utils/formats.py index 74af39eade..3cb0c0420c 100644 --- a/django/utils/formats.py +++ b/django/utils/formats.py @@ -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): diff --git a/django/utils/functional.py b/django/utils/functional.py index 9dc321ebd8..055e511912 100644 --- a/django/utils/functional.py +++ b/django/utils/functional.py @@ -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)) diff --git a/django/utils/html.py b/django/utils/html.py index cb5a6258ac..18c650fb06 100644 --- a/django/utils/html.py +++ b/django/utils/html.py @@ -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('&', '&').replace('<', '<') @@ -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

and
s.""" + """Convert newlines into

and
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&y=<2> => http://example.com?x=1&y=<2> """ unescaped = (text + trail).replace( diff --git a/django/utils/http.py b/django/utils/http.py index 7e7b7ab321..bd2daad4b2 100644 --- a/django/utils/http.py +++ b/django/utils/http.py @@ -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``. diff --git a/django/utils/ipv6.py b/django/utils/ipv6.py index 81733e1613..ddb8c8091d 100644 --- a/django/utils/ipv6.py +++ b/django/utils/ipv6.py @@ -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) diff --git a/django/utils/itercompat.py b/django/utils/itercompat.py index 096f808671..9895e3f816 100644 --- a/django/utils/itercompat.py +++ b/django/utils/itercompat.py @@ -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: diff --git a/django/utils/jslex.py b/django/utils/jslex.py index 7738ce468a..b2ff689f33 100644 --- a/django/utils/jslex.py +++ b/django/utils/jslex.py @@ -50,7 +50,7 @@ class Lexer: """ Lexically analyze `text`. - Yields pairs (`name`, `tokentext`). + Yield pairs (`name`, `tokentext`). """ end = len(text) state = self.state diff --git a/django/utils/lorem_ipsum.py b/django/utils/lorem_ipsum.py index 87988d2050..cfa675d70a 100644 --- a/django/utils/lorem_ipsum.py +++ b/django/utils/lorem_ipsum.py @@ -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. diff --git a/django/utils/numberformat.py b/django/utils/numberformat.py index 1931015e7b..e910be9206 100644 --- a/django/utils/numberformat.py +++ b/django/utils/numberformat.py @@ -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 ".") diff --git a/django/utils/regex_helper.py b/django/utils/regex_helper.py index f5cfc57156..9e57ff8f15 100644 --- a/django/utils/regex_helper.py +++ b/django/utils/regex_helper.py @@ -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: diff --git a/django/utils/safestring.py b/django/utils/safestring.py index 5baaca2e08..2da467a079 100644 --- a/django/utils/safestring.py +++ b/django/utils/safestring.py @@ -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. """ diff --git a/django/utils/termcolors.py b/django/utils/termcolors.py index f75e068187..089c9f93c9 100644 --- a/django/utils/termcolors.py +++ b/django/utils/termcolors.py @@ -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') diff --git a/django/utils/text.py b/django/utils/text.py index 2898160287..97cd42e7a2 100644 --- a/django/utils/text.py +++ b/django/utils/text.py @@ -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() diff --git a/django/utils/timesince.py b/django/utils/timesince.py index 4dcafa521d..8acfb6a484 100644 --- a/django/utils/timesince.py +++ b/django/utils/timesince.py @@ -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) diff --git a/django/utils/timezone.py b/django/utils/timezone.py index bc6d60e228..36b39f30d4 100644 --- a/django/utils/timezone.py +++ b/django/utils/timezone.py @@ -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. diff --git a/django/utils/translation/trans_real.py b/django/utils/translation/trans_real.py index 73494320a0..ef92359c04 100644 --- a/django/utils/translation/trans_real.py +++ b/django/utils/translation/trans_real.py @@ -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()) diff --git a/django/utils/tree.py b/django/utils/tree.py index d4a2930e42..15f3c58205 100644 --- a/django/utils/tree.py +++ b/django/utils/tree.py @@ -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 diff --git a/django/utils/version.py b/django/utils/version.py index b80d445d0c..790a68c19c 100644 --- a/django/utils/version.py +++ b/django/utils/version.py @@ -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,