diff options
| author | Vytis Banaitis <vytis.banaitis@gmail.com> | 2017-01-20 23:04:05 +0200 |
|---|---|---|
| committer | Tim Graham <timograham@gmail.com> | 2017-01-26 08:19:27 -0500 |
| commit | d1bab24e0144d14513a1411503c95ececb425188 (patch) | |
| tree | 187452bf7b66a9600abc47570ccae22e6d539ede /docs/ref | |
| parent | 888c1e9bfe49135d049cbdcbbb0f2e97a1a0a1f5 (diff) | |
Refs #23919, #27778 -- Removed obsolete mentions of unicode.
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/contrib/gis/geos.txt | 12 | ||||
| -rw-r--r-- | docs/ref/contrib/syndication.txt | 12 | ||||
| -rw-r--r-- | docs/ref/files/uploads.txt | 2 | ||||
| -rw-r--r-- | docs/ref/forms/api.txt | 8 | ||||
| -rw-r--r-- | docs/ref/forms/fields.txt | 26 | ||||
| -rw-r--r-- | docs/ref/models/querysets.txt | 22 | ||||
| -rw-r--r-- | docs/ref/request-response.txt | 5 | ||||
| -rw-r--r-- | docs/ref/templates/builtins.txt | 3 | ||||
| -rw-r--r-- | docs/ref/unicode.txt | 48 | ||||
| -rw-r--r-- | docs/ref/utils.txt | 27 | ||||
| -rw-r--r-- | docs/ref/views.txt | 2 |
11 files changed, 79 insertions, 88 deletions
diff --git a/docs/ref/contrib/gis/geos.txt b/docs/ref/contrib/gis/geos.txt index 6df0daf514..815d4268cb 100644 --- a/docs/ref/contrib/gis/geos.txt +++ b/docs/ref/contrib/gis/geos.txt @@ -197,14 +197,14 @@ given ``geo_input`` argument, and then assumes the proper geometry subclass The following input formats, along with their corresponding Python types, are accepted: -======================= ====================== +======================= ========== Format Input Type -======================= ====================== -WKT / EWKT ``str`` or ``unicode`` -HEX / HEXEWKB ``str`` or ``unicode`` +======================= ========== +WKT / EWKT ``str`` +HEX / HEXEWKB ``str`` WKB / EWKB ``buffer`` -GeoJSON ``str`` or ``unicode`` -======================= ====================== +GeoJSON ``str`` +======================= ========== .. classmethod:: GEOSGeometry.from_gml(gml_string) diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index 8c32cef191..d8e59edc85 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -114,7 +114,7 @@ into those elements. calling the methods ``item_title()`` and ``item_description()`` on the :class:`~django.contrib.syndication.views.Feed` class. They are passed a single parameter, ``item``, which is the object itself. These are - optional; by default, the unicode representation of the object is used for + optional; by default, the string representation of the object is used for both. If you want to do any special formatting for either the title or @@ -615,7 +615,7 @@ This example illustrates all possible attributes and methods for a # ITEM TITLE AND DESCRIPTION -- If title_template or # description_template are not defined, these are used instead. Both are - # optional, by default they will use the unicode representation of the + # optional, by default they will use the string representation of the # item. def item_title(self, item): @@ -940,8 +940,8 @@ They share this interface: Any extra keyword arguments you pass to ``__init__`` will be stored in ``self.feed`` for use with `custom feed generators`_. - All parameters should be Unicode objects, except ``categories``, which - should be a sequence of Unicode objects. Beware that some control characters + All parameters should be strings, except ``categories``, which should be a + sequence of strings. Beware that some control characters are `not allowed <http://www.w3.org/International/questions/qa-controls>`_ in XML documents. If your content has some of them, you might encounter a :exc:`ValueError` when producing the feed. @@ -971,13 +971,13 @@ They share this interface: Extra keyword arguments will be stored for `custom feed generators`_. - All parameters, if given, should be Unicode objects, except: + All parameters, if given, should be strings, except: * ``pubdate`` should be a Python :class:`~datetime.datetime` object. * ``updateddate`` should be a Python :class:`~datetime.datetime` object. * ``enclosures`` should be a list of :class:`django.utils.feedgenerator.Enclosure` instances. - * ``categories`` should be a sequence of Unicode objects. + * ``categories`` should be a sequence of strings. :meth:`.SyndicationFeed.write` Outputs the feed in the given encoding to outfile, which is a file-like object. diff --git a/docs/ref/files/uploads.txt b/docs/ref/files/uploads.txt index 9bc508781f..4e843732a1 100644 --- a/docs/ref/files/uploads.txt +++ b/docs/ref/files/uploads.txt @@ -196,7 +196,7 @@ attributes: ``field_name`` is a string name of the file ``<input>`` field. - ``file_name`` is the unicode filename that was provided by the browser. + ``file_name`` is the filename provided by the browser. ``content_type`` is the MIME type provided by the browser -- E.g. ``'image/jpeg'``. diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index e64e25d241..fda7472105 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -112,7 +112,7 @@ messages:: {'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']} In this dictionary, the keys are the field names, and the values are lists of -Unicode strings representing the error messages. The error messages are stored +strings representing the error messages. The error messages are stored in lists because a field can have multiple error messages. You can access :attr:`~Form.errors` without having to call @@ -357,8 +357,8 @@ it, you can access the clean data via its ``cleaned_data`` attribute:: {'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'} Note that any text-based field -- such as ``CharField`` or ``EmailField`` -- -always cleans the input into a Unicode string. We'll cover the encoding -implications later in this document. +always cleans the input into a string. We'll cover the encoding implications +later in this document. If your data does *not* validate, the ``cleaned_data`` dictionary contains only the valid fields:: @@ -490,7 +490,7 @@ Notice the following: Although ``<table>`` output is the default output style when you ``print`` a form, other output styles are available. Each style is available as a method on -a form object, and each rendering method returns a Unicode object. +a form object, and each rendering method returns a string. ``as_p()`` ---------- diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 2949ad0a9b..341d142c4b 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -88,9 +88,8 @@ To specify that a field is *not* required, pass ``required=False`` to the If a ``Field`` has ``required=False`` and you pass ``clean()`` an empty value, then ``clean()`` will return a *normalized* empty value rather than raising -``ValidationError``. For ``CharField``, this will be a Unicode empty string. -For other ``Field`` classes, it might be ``None``. (This varies from field to -field.) +``ValidationError``. For ``CharField``, this will be an empty string. For other +``Field`` classes, it might be ``None``. (This varies from field to field.) Widgets of required form fields have the ``required`` HTML attribute. Set the :attr:`Form.use_required_attribute` attribute to ``False`` to disable it. The @@ -371,7 +370,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: Whatever you've given as :attr:`empty_value`. - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates ``max_length`` or ``min_length``, if they are provided. Otherwise, all inputs are valid. * Error message keys: ``required``, ``max_length``, ``min_length`` @@ -402,7 +401,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`Select` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates that the given value exists in the list of choices. * Error message keys: ``required``, ``invalid_choice`` @@ -585,7 +584,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`EmailInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates that the given value is a valid email address, using a moderately complex regular expression. * Error message keys: ``required``, ``invalid`` @@ -629,7 +628,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`Select` * Empty value: ``None`` - * Normalizes to: A unicode object + * Normalizes to: A string. * Validates that the selected choice exists in the list of choices. * Error message keys: ``required``, ``invalid_choice`` @@ -747,8 +746,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. IPv6 addresses are - normalized as described below. + * Normalizes to: A string. IPv6 addresses are normalized as described below. * Validates that the given value is a valid IP address. * Error message keys: ``required``, ``invalid`` @@ -780,7 +778,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`SelectMultiple` * Empty value: ``[]`` (an empty list) - * Normalizes to: A list of Unicode objects. + * Normalizes to: A list of strings. * Validates that every value in the given list of values exists in the list of choices. * Error message keys: ``required``, ``invalid_choice``, ``invalid_list`` @@ -829,7 +827,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates that the given value matches against a certain regular expression. * Error message keys: ``required``, ``invalid`` @@ -856,7 +854,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates that the given value contains only letters, numbers, underscores, and hyphens. * Error messages: ``required``, ``invalid`` @@ -902,7 +900,7 @@ For each field, we describe the default widget used if you don't specify * Default widget: :class:`URLInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates that the given value is a valid URL. * Error message keys: ``required``, ``invalid`` @@ -936,7 +934,7 @@ Slightly complex built-in ``Field`` classes * Default widget: :class:`TextInput` * Empty value: ``''`` (an empty string) - * Normalizes to: A Unicode object. + * Normalizes to: A string. * Validates the given value against each of the fields specified as an argument to the ``ComboField``. * Error message keys: ``required``, ``invalid`` diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 2893c91b8e..844c9e1d11 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -2391,10 +2391,9 @@ Note the first query will match ``'Beatles Blog'``, ``'beatles blog'``, .. admonition:: SQLite users - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. SQLite does not do case-insensitive matching for Unicode - strings. + When using the SQLite backend and non-ASCII strings, bear in mind the + :ref:`database note <sqlite-string-matching>` about string comparisons. + SQLite does not do case-insensitive matching for non-ASCII strings. .. fieldlookup:: contains @@ -2438,9 +2437,8 @@ SQL equivalent:: .. admonition:: SQLite users - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. + When using the SQLite backend and non-ASCII strings, bear in mind the + :ref:`database note <sqlite-string-matching>` about string comparisons. .. fieldlookup:: in @@ -2572,9 +2570,8 @@ SQL equivalent:: .. admonition:: SQLite users - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. + When using the SQLite backend and non-ASCII strings, bear in mind the + :ref:`database note <sqlite-string-matching>` about string comparisons. .. fieldlookup:: endswith @@ -2614,9 +2611,8 @@ SQL equivalent:: .. admonition:: SQLite users - When using the SQLite backend and Unicode (non-ASCII) strings, bear in - mind the :ref:`database note <sqlite-string-matching>` about string - comparisons. + When using the SQLite backend and non-ASCII strings, bear in mind the + :ref:`database note <sqlite-string-matching>` about string comparisons. .. fieldlookup:: range diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index a6f80feb2e..2d564d1954 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -416,7 +416,7 @@ a subclass of dictionary. Exceptions are outlined here: ``mutable=True`` to its ``__init__()``. Strings for setting both keys and values will be converted from ``encoding`` - to unicode. If encoding is not set, it defaults to :setting:`DEFAULT_CHARSET`. + to ``str``. If encoding is not set, it defaults to :setting:`DEFAULT_CHARSET`. .. classmethod:: QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None) @@ -654,8 +654,7 @@ Attributes .. attribute:: HttpResponse.content - A bytestring representing the content, encoded from a Unicode - object if necessary. + A bytestring representing the content, encoded from a string if necessary. .. attribute:: HttpResponse.charset diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index b4fe7f9665..5b453a0cba 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -1934,8 +1934,7 @@ If ``value`` is ``Totally LOVING this Album!``, the output will be ------------- Returns the value turned into a list. For a string, it's a list of characters. -For an integer, the argument is cast into an unicode string before creating a -list. +For an integer, the argument is cast to a string before creating a list. For example:: diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index d493ce56ad..eb71b63682 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -3,8 +3,8 @@ Unicode data ============ Django natively supports Unicode data everywhere. Providing your database can -somehow store the data, you can safely pass around Unicode strings to -templates, models and the database. +somehow store the data, you can safely pass around strings to templates, +models, and the database. This document tells you what you need to know if you're writing applications that use data or templates that are encoded in something other than ASCII. @@ -35,11 +35,10 @@ able to store certain characters in the database, and information will be lost. .. _section 2: https://docs.oracle.com/database/121/NLSPG/ch2charset.htm#NLSPG002 .. _section 11: https://docs.oracle.com/database/121/NLSPG/ch11charsetmig.htm#NLSPG011 -All of Django's database backends automatically convert Unicode strings into +All of Django's database backends automatically convert strings into the appropriate encoding for talking to the database. They also automatically -convert strings retrieved from the database into Python Unicode strings. You -don't even need to tell Django what encoding your database uses: that is -handled transparently. +convert strings retrieved from the database into strings. You don't even need +to tell Django what encoding your database uses: that is handled transparently. For more, see the section "The database API" below. @@ -48,7 +47,7 @@ General string handling Whenever you use strings with Django -- e.g., in database lookups, template rendering or anywhere else -- you have two choices for encoding those strings. -You can use normal Unicode strings or bytestrings (starting with a 'b'). +You can use normal strings or bytestrings (starting with a 'b'). .. warning:: @@ -74,13 +73,13 @@ using your application -- and if that person chooses a different setting, your code must still continue to work. Ergo, it cannot rely on that setting. In most cases when Django is dealing with strings, it will convert them to -Unicode strings before doing anything else. So, as a general rule, if you pass -in a bytestring, be prepared to receive a Unicode string back in the result. +strings before doing anything else. So, as a general rule, if you pass +in a bytestring, be prepared to receive a string back in the result. Translated strings ------------------ -Aside from Unicode strings and bytestrings, there's a third type of string-like +Aside from strings and bytestrings, there's a third type of string-like object you may encounter when using Django. The framework's internationalization features introduce the concept of a "lazy translation" -- a string that has been marked as translated but whose actual translation result @@ -93,7 +92,7 @@ Normally, you won't have to worry about lazy translations. Just be aware that if you examine an object and it claims to be a ``django.utils.functional.__proxy__`` object, it is a lazy translation. Calling ``str()`` with the lazy translation as the argument will generate a -Unicode string in the current locale. +string in the current locale. For more details about lazy translation objects, refer to the :doc:`internationalization </topics/i18n/index>` documentation. @@ -102,17 +101,17 @@ Useful utility functions ------------------------ Because some string operations come up again and again, Django ships with a few -useful functions that should make working with Unicode and bytestring objects +useful functions that should make working with string and bytestring objects a bit easier. Conversion functions ~~~~~~~~~~~~~~~~~~~~ The ``django.utils.encoding`` module contains a few functions that are handy -for converting back and forth between Unicode and bytestrings. +for converting back and forth between strings and bytestrings. * ``smart_text(s, encoding='utf-8', strings_only=False, errors='strict')`` - converts its input to a Unicode string. The ``encoding`` parameter + converts its input to a string. The ``encoding`` parameter specifies the input encoding. (For example, Django uses this internally when processing form input data, which might not be UTF-8 encoded.) The ``strings_only`` parameter, if set to True, will result in Python @@ -126,7 +125,7 @@ for converting back and forth between Unicode and bytestrings. cases. The difference is when the first argument is a :ref:`lazy translation <lazy-translations>` instance. While ``smart_text()`` preserves lazy translations, ``force_text()`` forces those objects to a - Unicode string (causing the translation to occur). Normally, you'll want + string (causing the translation to occur). Normally, you'll want to use ``smart_text()``. However, ``force_text()`` is useful in template tags and filters that absolutely *must* have a string to work with, not just something that can be converted to a string. @@ -139,8 +138,8 @@ for converting back and forth between Unicode and bytestrings. but the difference is needed in a few places within Django's internals. Normally, you'll only need to use ``force_text()``. Call it as early as -possible on any input data that might be either Unicode or a bytestring, and -from then on, you can treat the result as always being Unicode. +possible on any input data that might be either a string or a bytestring, and +from then on, you can treat the result as always being a string. .. _uri-and-iri-handling: @@ -225,13 +224,13 @@ double-quoting problems. Models ====== -Because all strings are returned from the database as Unicode strings, model +Because all strings are returned from the database as ``str`` objects, model fields that are character based (CharField, TextField, URLField, etc.) will contain Unicode values when Django retrieves data from the database. This is *always* the case, even if the data could fit into an ASCII bytestring. You can pass in bytestrings when creating a model or populating a field, and -Django will convert it to Unicode when it needs to. +Django will convert it to strings when it needs to. Taking care in ``get_absolute_url()`` ------------------------------------- @@ -263,7 +262,7 @@ non-ASCII characters would have been removed in quoting in the first line.) The database API ================ -You can pass either Unicode strings or UTF-8 bytestrings as arguments to +You can pass either strings or UTF-8 bytestrings as arguments to ``filter()`` methods and the like in the database API. The following two querysets are identical:: @@ -273,11 +272,12 @@ querysets are identical:: Templates ========= -You can use either Unicode or bytestrings when creating templates manually:: +You can use either strings or UTF-8 bytestrings when creating templates +manually:: from django.template import Template t1 = Template(b'This is a bytestring template.') - t2 = Template('This is a Unicode template.') + t2 = Template('This is a string template.') But the common case is to read templates from the filesystem, and this creates a slight complication: not all filesystems store their data encoded as UTF-8. @@ -294,13 +294,13 @@ Template tags and filters A couple of tips to remember when writing your own template tags and filters: -* Always return Unicode strings from a template tag's ``render()`` method +* Always return strings from a template tag's ``render()`` method and from template filters. * Use ``force_text()`` in preference to ``smart_text()`` in these places. Tag rendering and filter calls occur as the template is being rendered, so there is no advantage to postponing the conversion of lazy - translation objects into strings. It's easier to work solely with Unicode + translation objects into strings. It's easier to work solely with strings at that point. .. _unicode-files: diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 056f228bdf..cc6cf74478 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -276,13 +276,13 @@ The functions defined in this module share the following properties: This is an algorithm from section 3.2 of :rfc:`3987#section-3.2`. - Takes a URI in ASCII bytes and returns a unicode string containing the - encoded result. + Takes a URI in ASCII bytes and returns a string containing the encoded + result. .. function:: filepath_to_uri(path) Convert a file system path to a URI portion that is suitable for inclusion - in a URL. The path is assumed to be either UTF-8 or unicode. + in a URL. The path is assumed to be either UTF-8 bytes or string. This method will encode certain characters that would normally be recognized as special characters for URIs. Note that this method does not @@ -346,13 +346,13 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 Any extra keyword arguments you pass to ``__init__`` will be stored in ``self.feed``. - All parameters should be Unicode objects, except ``categories``, which - should be a sequence of Unicode objects. + All parameters should be strings, except ``categories``, which should + be a sequence of strings. .. method:: add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs) - Adds an item to the feed. All args are expected to be Python ``unicode`` - objects except ``pubdate`` and ``updateddate``, which are ``datetime.datetime`` + Adds an item to the feed. All args are expected to be strings except + ``pubdate`` and ``updateddate``, which are ``datetime.datetime`` objects, and ``enclosures``, which is a list of ``Enclosure`` instances. .. method:: num_items() @@ -802,7 +802,7 @@ appropriate entities. .. function:: mark_safe(s) Explicitly mark a string as safe for (HTML) output purposes. The returned - object can be used everywhere a string or unicode object is appropriate. + object can be used everywhere a string is appropriate. Can be called multiple times on a single string. @@ -1030,16 +1030,15 @@ For a complete discussion on the usage of the following see the .. function:: gettext(message) - Translates ``message`` and returns it in a UTF-8 bytestring + Translates ``message`` and returns it in a UTF-8 bytestring. .. function:: ugettext(message) - Translates ``message`` and returns it in a unicode string + Translates ``message`` and returns it as a string. .. function:: pgettext(context, message) - Translates ``message`` given the ``context`` and returns - it in a unicode string. + Translates ``message`` given the ``context`` and returns it as a string. For more information, see :ref:`contextual-markers`. @@ -1067,12 +1066,12 @@ For a complete discussion on the usage of the following see the .. function:: ungettext(singular, plural, number) Translates ``singular`` and ``plural`` and returns the appropriate string - based on ``number`` in a unicode string. + based on ``number`` as a string. .. function:: npgettext(context, singular, plural, number) Translates ``singular`` and ``plural`` and returns the appropriate string - based on ``number`` and the ``context`` in a unicode string. + based on ``number`` and the ``context`` as a string. .. function:: ngettext_lazy(singular, plural, number) .. function:: ungettext_lazy(singular, plural, number) diff --git a/docs/ref/views.txt b/docs/ref/views.txt index 93303527bc..dd1897c915 100644 --- a/docs/ref/views.txt +++ b/docs/ref/views.txt @@ -121,7 +121,7 @@ default, call the view ``django.views.defaults.permission_denied``. This view loads and renders the template ``403.html`` in your root template directory, or if this file does not exist, instead serves the text "403 Forbidden", as per :rfc:`7231#section-6.5.3` (the HTTP 1.1 Specification). -The template context contains ``exception``, which is the unicode +The template context contains ``exception``, which is the string representation of the exception that triggered the view. ``django.views.defaults.permission_denied`` is triggered by a |
