This document covers all stable modules in django.utils. Most of the\nmodules in django.utils are designed for internal use and only the\nfollowing parts can be considered stable and thus backwards compatible as per\nthe internal release deprecation policy.
django.utils.cacheLink to this heading#This module contains helper functions for controlling HTTP caching. It does so\nby managing the Vary header of responses. It includes functions to patch\nthe header of response objects directly and decorators that change functions to\ndo that header-patching themselves.
For information on the Vary header, see RFC 7231 Section 7.1.4.
Essentially, the Vary HTTP header defines which headers a cache should take\ninto account when building its cache key. Requests with the same path but\ndifferent header content for headers named in Vary need to get different\ncache keys to prevent delivery of wrong content.
For example, internationalization middleware would\nneed to distinguish caches by the Accept-language header.
This function patches the Cache-Control header by adding all keyword\narguments to it. The transformation is as follows:
All keyword parameter names are turned to lowercase, and underscores\nare converted to hyphens.
If the value of a parameter is True (exactly True, not just a\ntrue value), only the parameter name is added to the header.
All other parameters are added with their value, after applying\nstr() to it.
Returns the max-age from the response Cache-Control header as an integer\n(or None if it wasn’t found or wasn’t an integer).
Adds some useful headers to the given HttpResponse object:
Expires
Cache-Control
Each header is only added if it isn’t already set.
\ncache_timeout is in seconds. The CACHE_MIDDLEWARE_SECONDS\nsetting is used by default.
Adds a Cache-Control: max-age=0, no-cache, no-store, must-revalidate\nheader to a response to indicate that a page should never be cached.
Adds (or updates) the Vary header in the given HttpResponse object.\nnewheaders is a list of header names that should be in Vary.\nExisting headers in Vary aren’t removed.
Returns a cache key based on the request path. It can be used in the\nrequest phase because it pulls the list of headers to take into account\nfrom the global path registry and uses those to build a cache key to\ncheck against.
\nIf there is no headerlist stored, the page needs to be rebuilt, so this\nfunction returns None.
Learns what headers to take into account for some request path from the\nresponse object. It stores those headers in a global path registry so that\nlater access to that path will know what headers to take into account\nwithout building the response object itself. The headers are named in\nthe Vary header of the response, but we want to prevent response\ngeneration.
The list of headers to use for cache key generation is stored in the same\ncache as the pages themselves. If the cache ages some data out of the\ncache, this just means that we have to build the response once to get at\nthe Vary header and so at the list of headers to use for the cache key.
\ndjango.utils.dateparseLink to this heading#The functions defined in this module share the following properties:
\nThey accept strings in ISO 8601 date/time formats (or some close\nalternatives) and return objects from the corresponding classes in Python’s\ndatetime module.
They raise ValueError if their input is well formatted but isn’t a\nvalid date or time.
They return None if it isn’t well formatted at all.
They accept up to picosecond resolution in input, but they truncate it to\nmicroseconds, since that’s what Python supports.
Parses a string and returns a datetime.date.
Parses a string and returns a datetime.time.
UTC offsets aren’t supported; if value describes one, the result is\nNone.
Parses a string and returns a datetime.datetime.
UTC offsets are supported; if value describes one, the result’s\ntzinfo attribute is a FixedOffset\ninstance.
Parses a string and returns a datetime.timedelta.
Expects data in the format "DD HH:MM:SS.uuuuuu" or as specified by ISO\n8601 (e.g. P4DT1H15M20S which is equivalent to 4 1:15:20) or\nPostgreSQL’s day-time interval format (e.g. 3 days 04:05:06).
django.utils.decoratorsLink to this heading#Converts a function decorator into a method decorator. It can be used to\ndecorate methods or classes; in the latter case, name is the name\nof the method to be decorated and is required.
decorator may also be a list or tuple of functions. They are wrapped\nin reverse order so that the call order is the order in which the functions\nappear in the list/tuple.
See decorating class based views for\nexample usage.
\nGiven a middleware class, returns a view decorator. This lets you use\nmiddleware functionality on a per-view basis. The middleware is created\nwith no params passed.
\nIt assumes middleware that’s compatible with the old style of Django 1.9\nand earlier (having methods like process_request(),\nprocess_exception(), and process_response()).
Like decorator_from_middleware, but returns a function\nthat accepts the arguments to be passed to the middleware_class.\nFor example, the cache_page()\ndecorator is created from the CacheMiddleware like this:
cache_page = decorator_from_middleware_with_args(CacheMiddleware)\n\n@cache_page(3600)\ndef my_view(request):\n pass\ndjango.utils.encodingLink to this heading#A decorator that defines __unicode__ and __str__ methods under\nPython 2. Under Python 3 it does nothing.
To support Python 2 and 3 with a single code base, define a __str__\nmethod returning text (use six.text_type() if you’re doing some\ncasting) and apply this decorator to the class.
Returns a str object representing arbitrary object s. Treats\nbytestrings using the encoding codec.
If strings_only is True, don’t convert (some) non-string-like\nobjects.
Determine if the object instance is of a protected type.
\nObjects of protected types are preserved as-is when passed to\nforce_text(strings_only=True).
Similar to smart_text, except that lazy instances are resolved to\nstrings, rather than kept as lazy objects.
If strings_only is True, don’t convert (some) non-string-like\nobjects.
Returns a bytestring version of arbitrary object s, encoded as\nspecified in encoding.
If strings_only is True, don’t convert (some) non-string-like\nobjects.
Similar to smart_bytes, except that lazy instances are resolved to\nbytestrings, rather than kept as lazy objects.
If strings_only is True, don’t convert (some) non-string-like\nobjects.
Alias of smart_text(). This function returns a str or a lazy\nstring.
For instance, this is suitable for writing to sys.stdout.
Alias of smart_bytes() on Python 2 (in older versions of Django that\nsupport it).
Alias of force_text(). This function always returns a str.
Alias of force_bytes() on Python 2 (in older versions of Django that\nsupport it).
Convert an Internationalized Resource Identifier (IRI) portion to a URI\nportion that is suitable for inclusion in a URL.
\nThis is the algorithm from section 3.1 of RFC 3987 Section 3.1, slightly\nsimplified since the input is assumed to be a string rather than an\narbitrary byte stream.
\nTakes an IRI (string or UTF-8 bytes) and returns a string containing the\nencoded result.
\nConverts a Uniform Resource Identifier into an Internationalized Resource\nIdentifier.
\nThis is an algorithm from section 3.2 of RFC 3987 Section 3.2.
\nTakes a URI in ASCII bytes and returns a string containing the encoded\nresult.
\nConvert a file system path to a URI portion that is suitable for inclusion\nin a URL. The path is assumed to be either UTF-8 bytes or string.
\nThis method will encode certain characters that would normally be\nrecognized as special characters for URIs. Note that this method does not\nencode the ‘ character, as it is a valid character within URIs. See\nencodeURIComponent() JavaScript function for more details.
Returns an ASCII string containing the encoded result.
\nEscapes the unsafe characters from the path portion of a Uniform Resource\nIdentifier (URI).
\ndjango.utils.feedgeneratorLink to this heading#Sample usage:
\n>>> from django.utils import feedgenerator\n>>> feed = feedgenerator.Rss201rev2Feed(\n... title="Poynter E-Media Tidbits",\n... link="http://www.poynter.org/column.asp?id=31",\n... description="A group Weblog by the sharpest minds in online media/journalism/publishing.",\n... language="en",\n... )\n>>> feed.add_item(\n... title="Hello",\n... link="http://www.holovaty.com/test/",\n... description="Testing.",\n... )\n>>> with open('test.rss', 'w') as fp:\n... feed.write(fp, 'utf-8')\nFor simplifying the selection of a generator use feedgenerator.DefaultFeed\nwhich is currently Rss201rev2Feed
For definitions of the different versions of RSS, see:\nhttps://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss
\nCreates a TagURI.
\nSee https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
\nEnclosureLink to this heading#Represents an RSS enclosure
\nRssFeedLink to this heading#Rss201rev2FeedLink to this heading#RssUserland091FeedLink to this heading#Atom1FeedLink to this heading#django.utils.functionalLink to this heading#The @cached_property decorator caches the result of a method with a\nsingle self argument as a property. The cached result will persist\nas long as the instance does, so if the instance is passed around and the\nfunction subsequently invoked, the cached result will be returned.
Consider a typical case, where a view might need to call a model’s method\nto perform some computation, before placing the model instance into the\ncontext, where the template might invoke the method once more:
\n# the model\nclass Person(models.Model):\n\n def friends(self):\n # expensive computation\n ...\n return friends\n\n# in the view:\nif person.friends():\n ...\nAnd in the template you would have:
\n{% for friend in person.friends %}\nHere, friends() will be called twice. Since the instance person in\nthe view and the template are the same, decorating the friends() method\nwith @cached_property can avoid that:
from django.utils.functional import cached_property\n\nclass Person(models.Model):\n\n @cached_property\n def friends(self):\n ...\nNote that as the method is now a property, in Python code it will need to\nbe accessed appropriately:
\n# in the view:\nif person.friends:\n ...\nThe cached value can be treated like an ordinary attribute of the instance:
\n# clear it, requiring re-computation next time it's called\ndel person.friends # or delattr(person, "friends")\n\n# set a value manually, that will persist on the instance until cleared\nperson.friends = ["Huckleberry Finn", "Tom Sawyer"]\nAs well as offering potential performance advantages, @cached_property\ncan ensure that an attribute’s value does not change unexpectedly over the\nlife of an instance. This could occur with a method whose computation is\nbased on datetime.now(), or simply if a change were saved to the\ndatabase by some other process in the brief interval between subsequent\ninvocations of a method on the same instance.
You can use the name argument to make cached properties of other\nmethods. For example, if you had an expensive get_friends() method and\nwanted to allow calling it without retrieving the cached value, you could\nwrite:
friends = cached_property(get_friends, name='friends')\nWhile person.get_friends() will recompute the friends on each call, the\nvalue of the cached property will persist until you delete it as described\nabove:
x = person.friends # calls first time\ny = person.get_friends() # calls again\nz = person.friends # does not call\nx is z # is True\nDjango offers many utility functions (particularly in django.utils)\nthat take a string as their first argument and do something to that string.\nThese functions are used by template filters as well as directly in other\ncode.
If you write your own similar functions and deal with translations, you’ll\nface the problem of what to do when the first argument is a lazy\ntranslation object. You don’t want to convert it to a string immediately,\nbecause you might be using this function outside of a view (and hence the\ncurrent thread’s locale setting will not be correct).
\nFor cases like this, use the django.utils.functional.keep_lazy()\ndecorator. It modifies the function so that if it’s called with a lazy\ntranslation as one of its arguments, the function evaluation is delayed\nuntil it needs to be converted to a string.
For example:
\nfrom django.utils.functional import keep_lazy, keep_lazy_text\n\ndef fancy_utility_function(s, ...):\n # Do some conversion on string 's'\n ...\nfancy_utility_function = keep_lazy(str)(fancy_utility_function)\n\n# Or more succinctly:\n@keep_lazy(str)\ndef fancy_utility_function(s, ...):\n ...\nThe keep_lazy() decorator takes a number of extra arguments (*args)\nspecifying the type(s) that the original function can return. A common\nuse case is to have functions that return text. For these, you can just\npass the str type to keep_lazy (or even simpler, use the\nkeep_lazy_text() decorator described in the next section).
Using this decorator means you can write your function and assume that the\ninput is a proper string, then add support for lazy translation objects at\nthe end.
\nA shortcut for keep_lazy(str)(func).
If you have a function that returns text and you want to be able to take\nlazy arguments while delaying their evaluation, simply use this decorator:
\nfrom django.utils.functional import keep_lazy, keep_lazy_text\n\n# Our previous example was:\n@keep_lazy(str)\ndef fancy_utility_function(s, ...):\n ...\n\n# Which can be rewritten as:\n@keep_lazy_text\ndef fancy_utility_function(s, ...):\n ...\ndjango.utils.htmlLink to this heading#Usually you should build up HTML using Django’s templates to make use of its\nautoescape mechanism, using the utilities in django.utils.safestring\nwhere appropriate. This module provides some additional low level utilities for\nescaping HTML.
Returns the given text with ampersands, quotes and angle brackets encoded\nfor use in HTML. The input is first coerced to a string and the output has\nmark_safe() applied.
Similar to escape(), except that it doesn’t operate on pre-escaped\nstrings, so it will not double escape.
This is similar to str.format(), except that it is appropriate for\nbuilding up HTML fragments. All args and kwargs are passed through\nconditional_escape() before being passed to str.format().
For the case of building up small HTML fragments, this function is to be\npreferred over string interpolation using % or str.format()\ndirectly, because it applies escaping to all arguments - just like the\ntemplate system applies escaping by default.
So, instead of writing:
\nmark_safe("%s <b>%s</b> %s" % (\n some_html,\n escape(some_text),\n escape(some_other_text),\n))\nYou should instead use:
\nformat_html("{} <b>{}</b> {}",\n mark_safe(some_html),\n some_text,\n some_other_text,\n)\nThis has the advantage that you don’t need to apply escape() to each\nargument and risk a bug and an XSS vulnerability if you forget one.
Note that although this function uses str.format() to do the\ninterpolation, some of the formatting options provided by str.format()\n(e.g. number formatting) will not work, since all arguments are passed\nthrough conditional_escape() which (ultimately) calls\nforce_text() on the values.
A wrapper of format_html(), for the common case of a group of\narguments that need to be formatted using the same format string, and then\njoined using sep. sep is also passed through\nconditional_escape().
args_generator should be an iterator that returns the sequence of\nargs that will be passed to format_html(). For example:
format_html_join(\n '\\n', "<li>{} {}</li>",\n ((u.first_name, u.last_name) for u in users)\n)\nTries to remove anything that looks like an HTML tag from the string, that\nis anything contained within <>.
Absolutely NO guarantee is provided about the resulting string being\nHTML safe. So NEVER mark safe the result of a strip_tag call without\nescaping it first, for example with escape().
For example:
\nstrip_tags(value)\nIf value is "<b>Joel</b> <button>is</button> a <span>slug</span>"\nthe return value will be "Joel is a slug".
If you are looking for a more robust solution, take a look at the bleach Python library.
\nThe __html__() method on a class helps non-Django templates detect\nclasses whose output doesn’t require HTML escaping.
This decorator defines the __html__() method on the decorated class\nby wrapping __str__() in mark_safe().\nEnsure the __str__() method does indeed return text that doesn’t\nrequire HTML escaping.
django.utils.httpLink to this heading#A version of Python’s urllib.parse.urlencode() function that can\noperate on MultiValueDict and non-string values.
Formats the time to ensure compatibility with Netscape’s cookie standard.
\nAccepts a floating point number expressed in seconds since the epoch in\nUTC–such as that outputted by time.time(). If set to None,\ndefaults to the current time.
Outputs a string in the format Wdy, DD-Mon-YYYY HH:MM:SS GMT.
Formats the time to match the RFC 1123 date format as specified by HTTP\nRFC 7231 Section 7.1.1.1.
\nAccepts a floating point number expressed in seconds since the epoch in\nUTC–such as that outputted by time.time(). If set to None,\ndefaults to the current time.
Outputs a string in the format Wdy, DD Mon YYYY HH:MM:SS GMT.
Converts a base 36 string to an integer.
\nConverts a positive integer to a base 36 string.
\nEncodes a bytestring in base64 for use in URLs, stripping any trailing\nequal signs.
\nDecodes a base64 encoded string, adding back any trailing equal signs that\nmight have been stripped.
\ndjango.utils.module_loadingLink to this heading#Functions for working with Python modules.
\nImports a dotted module path and returns the attribute/class designated by\nthe last name in the path. Raises ImportError if the import failed. For\nexample:
from django.utils.module_loading import import_string\nValidationError = import_string('django.core.exceptions.ValidationError')\nis equivalent to:
\nfrom django.core.exceptions import ValidationError\ndjango.utils.safestringLink to this heading#Functions and classes for working with “safe strings”: strings that can be\ndisplayed safely without further escaping in HTML. Marking something as a “safe\nstring” means that the producer of the string has already turned characters\nthat should not be interpreted by the HTML engine (e.g. ‘<’) into the\nappropriate entities.
\nA str subclass that has been specifically marked as “safe”\n(requires no further escaping) for HTML output purposes. Alias of\nSafeText.
A str subclass that has been specifically marked as “safe” for HTML\noutput purposes.
Explicitly mark a string as safe for (HTML) output purposes. The returned\nobject can be used everywhere a string is appropriate.
\nCan be called multiple times on a single string.
\nCan also be used as a decorator.
\nFor building up fragments of HTML, you should normally be using\ndjango.utils.html.format_html() instead.
String marked safe will become unsafe again if modified. For example:
\n>>> mystr = '<b>Hello World</b> '\n>>> mystr = mark_safe(mystr)\n>>> type(mystr)\n<class 'django.utils.safestring.SafeText'>\n\n>>> mystr = mystr.strip() # removing whitespace\n>>> type(mystr)\n<type 'str'>\ndjango.utils.textLink to this heading#A version of str.format() for when format_string, args,\nand/or kwargs contain lazy objects. The first argument is the string to\nbe formatted. For example:
from django.utils.text import format_lazy\nfrom django.utils.translation import pgettext_lazy\n\nurlpatterns = [\n path(format_lazy('{person}/<int:pk>/', person=pgettext_lazy('URL', 'person')),\n PersonDetailView.as_view()),\n]\nThis example allows translators to translate part of the URL. If “person”\nis translated to “persona”, the regular expression will match\npersona/(?P<pk>\\d+)/$, e.g. persona/5/.
Converts a string to a URL slug by:
\nConverting to ASCII if allow_unicode is False (the default).
Removing characters that aren’t alphanumerics, underscores, hyphens, or\nwhitespace.
Removing leading and trailing whitespace.
Converting to lowercase.
Replacing any whitespace or repeated dashes with single dashes.
For example:
\n>>> slugify(' Joel is a slug ')\n'joel-is-a-slug'\nIf you want to allow Unicode characters, pass allow_unicode=True. For\nexample:
>>> slugify('你好 World', allow_unicode=True)\n'你好-world'\ndjango.utils.timezoneLink to this heading#tzinfo instance that represents UTC.
A tzinfo subclass modeling a fixed offset from UTC.\noffset is an integer number of minutes east of UTC.
Returns a tzinfo instance that represents a time zone\nwith a fixed offset from UTC.
offset is a datetime.timedelta or an integer number of\nminutes. Use positive values for time zones east of UTC and negative\nvalues for west of UTC.
Returns a tzinfo instance that represents the\ndefault time zone.
Returns the name of the default time zone.
\nReturns a tzinfo instance that represents the\ncurrent time zone.
Returns the name of the current time zone.
\nSets the current time zone. The\ntimezone argument must be an instance of a tzinfo\nsubclass or a time zone name.
Unsets the current time zone.
\nThis is a Python context manager that sets the current time zone on entry with activate(), and restores\nthe previously active time zone on exit. If the timezone argument is\nNone, the current time zone is unset\non entry with deactivate() instead.
override is also usable as a function decorator.
Converts an aware datetime to a different time zone,\nby default the current time zone.
When value is omitted, it defaults to now().
This function doesn’t work on naive datetimes; use make_aware()\ninstead.
Uses localtime() to convert an aware datetime to a\ndate() in a different time zone, by default the\ncurrent time zone.
When value is omitted, it defaults to now().
This function doesn’t work on naive datetimes.
\nReturns a datetime that represents the\ncurrent point in time. Exactly what’s returned depends on the value of\nUSE_TZ:
If USE_TZ is False, this will be a\nnaive datetime (i.e. a datetime\nwithout an associated timezone) that represents the current time\nin the system’s local timezone.
If USE_TZ is True, this will be an\naware datetime representing the\ncurrent time in UTC. Note that now() will always return\ntimes in UTC regardless of the value of TIME_ZONE;\nyou can use localtime() to get the time in the current time zone.
Returns True if value is aware, False if it is naive. This\nfunction assumes that value is a datetime.
Returns True if value is naive, False if it is aware. This\nfunction assumes that value is a datetime.
Returns an aware datetime that represents the same\npoint in time as value in timezone, value being a naive\ndatetime. If timezone is set to None, it\ndefaults to the current time zone.
The pytz.AmbiguousTimeError exception is raised if you try to make\nvalue aware during a DST transition where the same time occurs twice\n(when reverting from DST). Setting is_dst to True or False will\navoid the exception by choosing if the time is pre-transition or\npost-transition respectively.
The pytz.NonExistentTimeError exception is raised if you try to make\nvalue aware during a DST transition such that the time never occurred\n(when entering into DST). Setting is_dst to True or False will\navoid the exception by moving the hour backwards or forwards by 1\nrespectively. For example, is_dst=True would change a nonexistent\ntime of 2:30 to 1:30 and is_dst=False would change the time to 3:30.
Returns a naive datetime that represents in\ntimezone the same point in time as value, value being an\naware datetime. If timezone is set to None, it\ndefaults to the current time zone.
django.utils.translationLink to this heading#For a complete discussion on the usage of the following see the\ntranslation documentation.
\nThe u prefix on the functions below comes from a difference in Python 2\nbetween unicode and bytestrings. If your code doesn’t support Python 2, use the\nfunctions without the u.
Translates message and returns it as a string.
Translates message given the context and returns it as a string.
For more information, see Contextual markers.
\nSame as the non-lazy versions above, but using lazy execution.
\n\nMarks strings for translation but doesn’t translate them now. This can be\nused to store strings in global variables that should stay in the base\nlanguage (because they might be used externally) and will be translated\nlater.
\nTranslates singular and plural and returns the appropriate string\nbased on number.
Translates singular and plural and returns the appropriate string\nbased on number and the context.
Same as the non-lazy versions above, but using lazy execution.
\n\nFetches the translation object for a given language and activates it as\nthe current translation object for the current thread.
\nDeactivates the currently active translation object so that further _ calls\nwill resolve against the default translation object, again.
\nMakes the active translation object a NullTranslations() instance.\nThis is useful when we want delayed translations to appear as the original\nstring for some reason.
A Python context manager that uses\ndjango.utils.translation.activate() to fetch the translation object\nfor a given language, activates it as the translation object for the\ncurrent thread and reactivates the previous active language on exit.\nOptionally, it can simply deactivate the temporary translation on exit with\ndjango.utils.translation.deactivate() if the deactivate argument\nis True. If you pass None as the language argument, a\nNullTranslations() instance is activated within the context.
override is also usable as a function decorator.
Checks whether there is a global language file for the given language\ncode (e.g. ‘fr’, ‘pt_BR’). This is used to decide whether a user-provided\nlanguage is available.
\nReturns the currently selected language code. Returns None if\ntranslations are temporarily deactivated (by deactivate_all() or\nwhen None is passed to override()).
Returns selected language’s BiDi layout:
\nFalse = left-to-right layout
True = right-to-left layout
Analyzes the request to find what language the user wants the system to\nshow. Only languages listed in settings.LANGUAGES are taken into account.\nIf the user requests a sublanguage where we have a main language, we send\nout the main language.
\nIf check_path is True, the function first checks the requested URL\nfor whether its path begins with a language code listed in the\nLANGUAGES setting.
Returns lang_code if it’s in the LANGUAGES setting, possibly\nselecting a more generic variant. For example, 'es' is returned if\nlang_code is 'es-ar' and 'es' is in LANGUAGES but\n'es-ar' isn’t.
If strict is False (the default), a country-specific variant may\nbe returned when neither the language code nor its generic variant is found.\nFor example, if only 'es-co' is in LANGUAGES, that’s\nreturned for lang_codes like 'es' and 'es-ar'. Those matches\naren’t returned if strict=True.
Raises LookupError if nothing is found.
Turns a language name (en-us) into a locale name (en_US).
\nTurns a Django template into something that is understood by xgettext.\nIt does so by translating the Django translation tags into standard\ngettext function invocations.
Session key under which the active language for the current session is\nstored.
\n