diff options
| author | Tim Graham <timograham@gmail.com> | 2017-01-18 11:51:29 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2017-01-18 11:51:29 -0500 |
| commit | f6acd1d271122d66de8061e75ae26137ddf02658 (patch) | |
| tree | 26392839b0cf03b48696240d7ce6d835ec1011dc /docs/ref | |
| parent | c716fe87821df00f9f03ecc761c914d1682591a2 (diff) | |
Refs #23919 -- Removed Python 2 notes in docs.
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/applications.txt | 11 | ||||
| -rw-r--r-- | docs/ref/checks.txt | 6 | ||||
| -rw-r--r-- | docs/ref/contrib/admin/actions.txt | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/admin/index.txt | 16 | ||||
| -rw-r--r-- | docs/ref/contrib/auth.txt | 11 | ||||
| -rw-r--r-- | docs/ref/contrib/contenttypes.txt | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/gis/commands.txt | 4 | ||||
| -rw-r--r-- | docs/ref/contrib/gis/layermapping.txt | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/gis/tutorial.txt | 2 | ||||
| -rw-r--r-- | docs/ref/contrib/postgres/fields.txt | 8 | ||||
| -rw-r--r-- | docs/ref/databases.txt | 53 | ||||
| -rw-r--r-- | docs/ref/exceptions.txt | 6 | ||||
| -rw-r--r-- | docs/ref/files/file.txt | 3 | ||||
| -rw-r--r-- | docs/ref/forms/api.txt | 8 | ||||
| -rw-r--r-- | docs/ref/forms/fields.txt | 11 | ||||
| -rw-r--r-- | docs/ref/models/querysets.txt | 2 | ||||
| -rw-r--r-- | docs/ref/request-response.txt | 21 | ||||
| -rw-r--r-- | docs/ref/templates/language.txt | 6 | ||||
| -rw-r--r-- | docs/ref/unicode.txt | 35 | ||||
| -rw-r--r-- | docs/ref/urlresolvers.txt | 2 | ||||
| -rw-r--r-- | docs/ref/utils.txt | 69 |
21 files changed, 80 insertions, 200 deletions
diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index 8663e65222..1cff9aafa4 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -295,13 +295,12 @@ Methods .. _namespace package: -Namespace packages as apps (Python 3.3+) ----------------------------------------- +Namespace packages as apps +-------------------------- -Python versions 3.3 and later support Python packages without an -``__init__.py`` file. These packages are known as "namespace packages" and may -be spread across multiple directories at different locations on ``sys.path`` -(see :pep:`420`). +Python packages without an ``__init__.py`` file are known as "namespace +packages" and may be spread across multiple directories at different locations +on ``sys.path`` (see :pep:`420`). Django applications require a single base filesystem path where Django (depending on configuration) will search for templates, static assets, diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index 13ef44053e..518ed507af 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -45,9 +45,9 @@ Constructor arguments are: ``obj`` Optional. An object providing context for the message (for example, the model where the problem was discovered). The object should be a model, - field, or manager or any other object that defines ``__str__`` method (on - Python 2 you need to define ``__unicode__`` method). The method is used - while reporting all messages and its result precedes the message. + field, or manager or any other object that defines a ``__str__()`` method. + The method is used while reporting all messages and its result precedes the + message. ``id`` Optional string. A unique identifier for the issue. Identifiers should diff --git a/docs/ref/contrib/admin/actions.txt b/docs/ref/contrib/admin/actions.txt index e98d8d2aef..039d8d37d6 100644 --- a/docs/ref/contrib/admin/actions.txt +++ b/docs/ref/contrib/admin/actions.txt @@ -57,7 +57,7 @@ simple news application with an ``Article`` model:: body = models.TextField() status = models.CharField(max_length=1, choices=STATUS_CHOICES) - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.title A common task we might perform with a model like this is to update an diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 1fa3843c73..74faef6a75 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -137,10 +137,8 @@ The ``register`` decorator You can't use this decorator if you have to reference your model admin class in its ``__init__()`` method, e.g. - ``super(PersonAdmin, self).__init__(*args, **kwargs)``. If you are using - Python 3 and don't have to worry about supporting Python 2, you can - use ``super().__init__(*args, **kwargs)`` . Otherwise, you'll have to use - ``admin.site.register()`` instead of this decorator. + ``super(PersonAdmin, self).__init__(*args, **kwargs)``. You can use + ``super().__init__(*args, **kwargs)``. Discovery of admin files ------------------------ @@ -543,8 +541,7 @@ subclass:: list_display = ('first_name', 'last_name') If you don't set ``list_display``, the admin site will display a single - column that displays the ``__str__()`` (``__unicode__()`` on Python 2) - representation of each object. + column that displays the ``__str__()`` representation of each object. You have four possible values that can be used in ``list_display``: @@ -594,7 +591,7 @@ subclass:: A few special cases to note about ``list_display``: * If the field is a ``ForeignKey``, Django will display the - ``__str__()`` (``__unicode__()`` on Python 2) of the related object. + ``__str__()`` of the related object. * ``ManyToManyField`` fields aren't supported, because that would entail executing a separate SQL statement for each row in the table. @@ -681,9 +678,8 @@ subclass:: class PersonAdmin(admin.ModelAdmin): list_display = ('name', 'born_in_fifties') - * The ``__str__()`` (``__unicode__()`` on Python 2) method is just - as valid in ``list_display`` as any other model method, so it's - perfectly OK to do this:: + * The ``__str__()`` method is just as valid in ``list_display`` as any + other model method, so it's perfectly OK to do this:: list_display = ('__str__', 'some_other_field') diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt index c049deb439..a269230643 100644 --- a/docs/ref/contrib/auth.txt +++ b/docs/ref/contrib/auth.txt @@ -137,12 +137,11 @@ Attributes .. attribute:: username_validator Points to a validator instance used to validate usernames. Defaults to - :class:`validators.UnicodeUsernameValidator` on Python 3 and - :class:`validators.ASCIIUsernameValidator` on Python 2. + :class:`validators.UnicodeUsernameValidator`. To change the default username validator, you can subclass the ``User`` model and set this attribute to a different validator instance. For - example, to use ASCII usernames on Python 3:: + example, to use ASCII usernames:: from django.contrib.auth.models import User from django.contrib.auth.validators import ASCIIUsernameValidator @@ -390,14 +389,12 @@ Validators .. class:: validators.ASCIIUsernameValidator A field validator allowing only ASCII letters, in addition to ``@``, ``.``, - ``+``, ``-``, and ``_``. The default validator for ``User.username`` on - Python 2. + ``+``, ``-``, and ``_``. .. class:: validators.UnicodeUsernameValidator A field validator allowing Unicode letters, in addition to ``@``, ``.``, - ``+``, ``-``, and ``_``. The default validator for ``User.username`` on - Python 3. + ``+``, ``-``, and ``_``. The default validator for ``User.username``. .. _topics-auth-signals: diff --git a/docs/ref/contrib/contenttypes.txt b/docs/ref/contrib/contenttypes.txt index 33e690d97c..e5635ef59e 100644 --- a/docs/ref/contrib/contenttypes.txt +++ b/docs/ref/contrib/contenttypes.txt @@ -251,7 +251,7 @@ A simple example is a tagging system, which might look like this:: object_id = models.PositiveIntegerField() content_object = GenericForeignKey('content_type', 'object_id') - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.tag A normal :class:`~django.db.models.ForeignKey` can only "point diff --git a/docs/ref/contrib/gis/commands.txt b/docs/ref/contrib/gis/commands.txt index 77fa915396..eeb6ca0513 100644 --- a/docs/ref/contrib/gis/commands.txt +++ b/docs/ref/contrib/gis/commands.txt @@ -63,8 +63,8 @@ of using ``ogrinspect`` :ref:`in the tutorial <ogrinspect-intro>`. .. django-admin-option:: --name-field NAME_FIELD - Generates a ``__str__`` routine (``__unicode__`` on Python 2) on the model - that will return the given field name. + Generates a ``__str__()`` method on the model that returns the given field + name. .. django-admin-option:: --no-imports diff --git a/docs/ref/contrib/gis/layermapping.txt b/docs/ref/contrib/gis/layermapping.txt index 06cded679b..f273fa9c20 100644 --- a/docs/ref/contrib/gis/layermapping.txt +++ b/docs/ref/contrib/gis/layermapping.txt @@ -58,7 +58,7 @@ Example name = models.CharField(max_length=25) # corresponds to the 'str' field poly = models.PolygonField(srid=4269) # we want our model in a different SRID - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return 'Name: %s' % self.name 3. Use :class:`LayerMapping` to extract all the features and place them in the diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index cc518a999c..22e3b075ad 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -216,7 +216,7 @@ model to represent this data:: mpoly = models.MultiPolygonField() # Returns the string representation of the model. - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.name Note that the ``models`` module is imported from ``django.contrib.gis.db``. diff --git a/docs/ref/contrib/postgres/fields.txt b/docs/ref/contrib/postgres/fields.txt index 5a79d8879d..f0f320b725 100644 --- a/docs/ref/contrib/postgres/fields.txt +++ b/docs/ref/contrib/postgres/fields.txt @@ -104,7 +104,7 @@ We will use the following example model:: name = models.CharField(max_length=200) tags = ArrayField(models.CharField(max_length=200), blank=True) - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.name .. fieldlookup:: arrayfield.contains @@ -313,7 +313,7 @@ We will use the following example model:: name = models.CharField(max_length=200) data = HStoreField() - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.name .. fieldlookup:: hstorefield.key @@ -521,7 +521,7 @@ We will use the following example model:: name = models.CharField(max_length=200) data = JSONField() - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.name .. fieldlookup:: jsonfield.key @@ -680,7 +680,7 @@ model:: ages = IntegerRangeField() start = models.DateTimeField() - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return self.name We will also use the following example objects:: diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 03fed7db24..5ba10664d4 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -273,24 +273,18 @@ running ``migrate``:: MySQL DB API Drivers -------------------- -The Python Database API is described in :pep:`249`. MySQL has three prominent -drivers that implement this API: +MySQL has a couple drivers that implement the Python Database API described in +:pep:`249`: -- `MySQLdb`_ is a native driver that has been developed and supported for over - a decade by Andy Dustman. -- `mysqlclient`_ is a fork of ``MySQLdb`` which notably supports Python 3 and - can be used as a drop-in replacement for MySQLdb. At the time of this writing, - this is **the recommended choice** for using MySQL with Django. +- `mysqlclient`_ is a native driver. It's **the recommended choice**. - `MySQL Connector/Python`_ is a pure Python driver from Oracle that does not require the MySQL client library or any Python modules outside the standard library. -.. _MySQLdb: https://pypi.python.org/pypi/MySQL-python/1.2.4 .. _mysqlclient: https://pypi.python.org/pypi/mysqlclient .. _MySQL Connector/Python: https://dev.mysql.com/downloads/connector/python -All these drivers are thread-safe and provide connection pooling. ``MySQLdb`` -is the only one not supporting Python 3 currently. +All these drivers are thread-safe and provide connection pooling. In addition to a DB API driver, Django needs an adapter to access the database drivers from its ORM. Django provides an adapter for MySQLdb/mysqlclient while @@ -298,30 +292,10 @@ MySQL Connector/Python includes `its own`_. .. _its own: https://dev.mysql.com/doc/connector-python/en/connector-python-django-backend.html -MySQLdb -~~~~~~~ - -Django requires MySQLdb version 1.2.1p2 or later. - -At the time of writing, the latest release of MySQLdb (1.2.5) doesn't support -Python 3. In order to use MySQLdb under Python 3, you'll have to install -``mysqlclient`` instead. - -.. note:: - There are known issues with the way MySQLdb converts date strings into - datetime objects. Specifically, date strings with value ``0000-00-00`` are - valid for MySQL but will be converted into ``None`` by MySQLdb. - - This means you should be careful while using :djadmin:`loaddata` and - :djadmin:`dumpdata` with rows that may have ``0000-00-00`` values, as they - will be converted to ``None``. - mysqlclient ~~~~~~~~~~~ -Django requires `mysqlclient`_ 1.3.3 or later. Note that Python 3.2 is not -supported. Except for the Python 3.3+ support, mysqlclient should mostly behave -the same as MySQLDB. +Django requires `mysqlclient`_ 1.3.3 or later. MySQL Connector/Python ~~~~~~~~~~~~~~~~~~~~~~ @@ -689,23 +663,6 @@ substring filtering. .. _documented at sqlite.org: https://www.sqlite.org/faq.html#q18 -Old SQLite and ``CASE`` expressions ------------------------------------ - -SQLite 3.6.23.1 and older contains a bug when `handling query parameters`_ in -a ``CASE`` expression that contains an ``ELSE`` and arithmetic. - -SQLite 3.6.23.1 was released in March 2010, and most current binary -distributions for different platforms include a newer version of SQLite, with -the notable exception of the Python 2.7 installers for Windows. - -As of this writing, the latest release for Windows - Python 2.7.10 - includes -SQLite 3.6.21. You can install ``pysqlite2`` or replace ``sqlite3.dll`` (by -default installed in ``C:\Python27\DLLs``) with a newer version from -https://www.sqlite.org/ to remedy this issue. - -.. _handling query parameters: https://code.djangoproject.com/ticket/24148 - .. _using-newer-versions-of-pysqlite: Using newer versions of the SQLite DB-API 2.0 driver diff --git a/docs/ref/exceptions.txt b/docs/ref/exceptions.txt index 79afe702a1..7057b90804 100644 --- a/docs/ref/exceptions.txt +++ b/docs/ref/exceptions.txt @@ -217,11 +217,7 @@ Specification v2.0, for further information. As per :pep:`3134`, a ``__cause__`` attribute is set with the original (underlying) database exception, allowing access to any additional -information provided. (Note that this attribute is available under -both Python 2 and Python 3, although :pep:`3134` normally only applies -to Python 3. To avoid unexpected differences with Python 3, Django will also -ensure that the exception made available via ``__cause__`` has a usable -``__traceback__`` attribute.) +information provided. .. exception:: models.ProtectedError diff --git a/docs/ref/files/file.txt b/docs/ref/files/file.txt index 4169b74b88..803f060c29 100644 --- a/docs/ref/files/file.txt +++ b/docs/ref/files/file.txt @@ -97,8 +97,7 @@ The ``File`` class .. versionchanged:: 1.11 - The ``readable()`` and ``writable()`` methods were added and the - ``seekable()`` method was made available on Python 2. + The ``readable()`` and ``writable()`` methods were added. .. currentmodule:: django.core.files.base diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 1c4185156d..e64e25d241 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -810,12 +810,11 @@ Customizing the error list format By default, forms use ``django.forms.utils.ErrorList`` to format validation errors. If you'd like to use an alternate class for displaying errors, you can -pass that in at construction time (replace ``__str__`` by ``__unicode__`` on -Python 2):: +pass that in at construction time:: >>> from django.forms.utils import ErrorList >>> class DivErrorList(ErrorList): - ... def __str__(self): # __unicode__ on Python 2 + ... def __str__(self): ... return self.as_divs() ... def as_divs(self): ... if not self: return '' @@ -840,8 +839,7 @@ they're not the only way a form object can be displayed. Used to display HTML or access attributes for a single field of a :class:`Form` instance. - The ``__str__()`` (``__unicode__`` on Python 2) method of this - object displays the HTML for this field. + The ``__str__()`` method of this object displays the HTML for this field. To retrieve a single ``BoundField``, use dictionary lookup syntax on your form using the field's name as the key:: diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt index 8dfe26aa79..2008e65b95 100644 --- a/docs/ref/forms/fields.txt +++ b/docs/ref/forms/fields.txt @@ -1183,12 +1183,11 @@ method:: ... </select> - The ``__str__`` (``__unicode__`` on Python 2) method of the model will be - called to generate string representations of the objects for use in the - field's choices; to provide customized representations, subclass - ``ModelChoiceField`` and override ``label_from_instance``. This method will - receive a model object, and should return a string suitable for representing - it. For example:: + The ``__str__()`` method of the model will be called to generate string + representations of the objects for use in the field's choices. To provide + customized representations, subclass ``ModelChoiceField`` and override + ``label_from_instance``. This method will receive a model object and should + return a string suitable for representing it. For example:: from django.forms import ModelChoiceField diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index ddacf25769..18e81a7da8 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1002,7 +1002,7 @@ For example, suppose you have these models:: name = models.CharField(max_length=50) toppings = models.ManyToManyField(Topping) - def __str__(self): # __unicode__ on Python 2 + def __str__(self): return "%s (%s)" % ( self.name, ", ".join(topping.name for topping in self.toppings.all()), diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index 40ba20738e..a6f80feb2e 100644 --- a/docs/ref/request-response.txt +++ b/docs/ref/request-response.txt @@ -480,21 +480,6 @@ a subclass of dictionary. Exceptions are outlined here: >>> q.items() [('a', '3')] -.. method:: QueryDict.iteritems() - - Just like the standard dictionary ``iteritems()`` method. Like - :meth:`QueryDict.items()` this uses the same last-value logic as - :meth:`QueryDict.__getitem__()`. - - Available only on Python 2. - -.. method:: QueryDict.iterlists() - - Like :meth:`QueryDict.iteritems()` except it includes all values, as a list, - for each member of the dictionary. - - Available only on Python 2. - .. method:: QueryDict.values() Just like the standard dictionary ``values()`` method, except this uses the @@ -504,12 +489,6 @@ a subclass of dictionary. Exceptions are outlined here: >>> q.values() ['3'] -.. method:: QueryDict.itervalues() - - Just like :meth:`QueryDict.values()`, except an iterator. - - Available only on Python 2. - In addition, ``QueryDict`` has the following methods: .. method:: QueryDict.copy() diff --git a/docs/ref/templates/language.txt b/docs/ref/templates/language.txt index d6f13a637f..430ada3a2f 100644 --- a/docs/ref/templates/language.txt +++ b/docs/ref/templates/language.txt @@ -105,13 +105,13 @@ Use a dot (``.``) to access attributes of a variable. override dictionary lookup. For example, consider the following code snippet that attempts to loop over a ``collections.defaultdict``:: - {% for k, v in defaultdict.iteritems %} + {% for k, v in defaultdict.items %} Do something with k and v here... {% endfor %} Because dictionary lookup happens first, that behavior kicks in and provides - a default value instead of using the intended ``.iteritems()`` - method. In this case, consider converting to a dictionary first. + a default value instead of using the intended ``.items()`` method. In this + case, consider converting to a dictionary first. In the above example, ``{{ section.title }}`` will be replaced with the ``title`` attribute of the ``section`` object. diff --git a/docs/ref/unicode.txt b/docs/ref/unicode.txt index c167fd55b3..d493ce56ad 100644 --- a/docs/ref/unicode.txt +++ b/docs/ref/unicode.txt @@ -48,29 +48,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 Unicode strings, or you can use normal strings (sometimes called -"bytestrings") that are encoded using UTF-8. - -In Python 3, the logic is reversed, that is normal strings are Unicode, and -when you want to specifically create a bytestring, you have to prefix the -string with a 'b'. As we are doing in Django code from version 1.5, -we recommend that you import ``unicode_literals`` from the __future__ library -in your code. Then, when you specifically want to create a bytestring literal, -prefix the string with 'b'. - -Python 2 legacy:: - - my_string = "This is a bytestring" - my_unicode = u"This is an Unicode string" - -Python 2 with unicode literals or Python 3:: - - from __future__ import unicode_literals - - my_string = b"This is a bytestring" - my_unicode = "This is an Unicode string" - -See also :doc:`Python 3 compatibility </topics/python3>`. +You can use normal Unicode strings or bytestrings (starting with a 'b'). .. warning:: @@ -114,7 +92,7 @@ imported. 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 ``unicode()`` with the lazy translation as the argument will generate a +Calling ``str()`` with the lazy translation as the argument will generate a Unicode string in the current locale. For more details about lazy translation objects, refer to the @@ -140,12 +118,9 @@ for converting back and forth between Unicode and bytestrings. ``strings_only`` parameter, if set to True, will result in Python numbers, booleans and ``None`` not being converted to a string (they keep their original types). The ``errors`` parameter takes any of the values - that are accepted by Python's ``unicode()`` function for its error + that are accepted by Python's ``str()`` function for its error handling. - If you pass ``smart_text()`` an object that has a ``__unicode__`` - method, it will use that method to do the conversion. - * ``force_text(s, encoding='utf-8', strings_only=False, errors='strict')`` is identical to ``smart_text()`` in almost all cases. The difference is when the first argument is a :ref:`lazy @@ -292,8 +267,6 @@ You can pass either Unicode strings or UTF-8 bytestrings as arguments to ``filter()`` methods and the like in the database API. The following two querysets are identical:: - from __future__ import unicode_literals - qs = People.objects.filter(name__contains='Å') qs = People.objects.filter(name__contains=b'\xc3\x85') # UTF-8 encoding of Å @@ -302,7 +275,6 @@ Templates You can use either Unicode or bytestrings when creating templates manually:: - from __future__ import unicode_literals from django.template import Template t1 = Template(b'This is a bytestring template.') t2 = Template('This is a Unicode template.') @@ -373,7 +345,6 @@ characters. The following code example demonstrates that everything except email addresses can be non-ASCII:: - from __future__ import unicode_literals from django.core.mail import EmailMessage subject = 'My visit to Sør-Trøndelag' diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt index 6e3ec595b1..9d462637ef 100644 --- a/docs/ref/urlresolvers.txt +++ b/docs/ref/urlresolvers.txt @@ -175,9 +175,9 @@ A :class:`ResolverMatch` object can also be assigned to a triple:: One possible use of :func:`~django.urls.resolve` would be to test whether a view would raise a ``Http404`` error before redirecting to it:: + from urllib.parse import urlparse from django.urls import resolve from django.http import HttpResponseRedirect, Http404 - from django.utils.six.moves.urllib.parse import urlparse def myview(request): next = request.META.get('HTTP_REFERER', None) or '/' diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 79787227e2..550facd142 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -203,16 +203,12 @@ The functions defined in this module share the following properties: .. function:: smart_text(s, encoding='utf-8', strings_only=False, errors='strict') - Returns a text object representing ``s`` -- ``unicode`` on Python 2 and - ``str`` on Python 3. Treats bytestrings using the ``encoding`` codec. + Returns a ``str`` object representing ``s``. Treats bytestrings using the + ``encoding`` codec. If ``strings_only`` is ``True``, don't convert (some) non-string-like objects. -.. function:: smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict') - - Historical name of :func:`smart_text`. Only available under Python 2. - .. function:: is_protected_type(obj) Determine if the object instance is of a protected type. @@ -228,10 +224,6 @@ The functions defined in this module share the following properties: If ``strings_only`` is ``True``, don't convert (some) non-string-like objects. -.. function:: force_unicode(s, encoding='utf-8', strings_only=False, errors='strict') - - Historical name of :func:`force_text`. Only available under Python 2. - .. function:: smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict') Returns a bytestring version of ``s``, encoded as specified in @@ -250,16 +242,20 @@ The functions defined in this module share the following properties: .. function:: smart_str(s, encoding='utf-8', strings_only=False, errors='strict') - Alias of :func:`smart_bytes` on Python 2 and :func:`smart_text` on Python - 3. This function returns a ``str`` or a lazy string. + Alias of :func:`smart_text`. This function returns a ``str`` or a lazy + string. + + For instance, this is suitable for writing to :data:`sys.stdout`. - For instance, this is suitable for writing to :data:`sys.stdout` on - Python 2 and 3. + Alias of :func:`smart_bytes` on Python 2 (in older versions of Django that + support it). .. function:: force_str(s, encoding='utf-8', strings_only=False, errors='strict') - Alias of :func:`force_bytes` on Python 2 and :func:`force_text` on Python - 3. This function always returns a ``str``. + Alias of :func:`force_text`. This function always returns a ``str``. + + Alias of :func:`force_bytes` on Python 2 (in older versions of Django that + support it). .. function:: iri_to_uri(iri) @@ -538,23 +534,22 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 For example:: - from django.utils import six from django.utils.functional import keep_lazy, keep_lazy_text def fancy_utility_function(s, ...): # Do some conversion on string 's' ... - fancy_utility_function = keep_lazy(six.text_type)(fancy_utility_function) + fancy_utility_function = keep_lazy(str)(fancy_utility_function) # Or more succinctly: - @keep_lazy(six.text_type) + @keep_lazy(str) def fancy_utility_function(s, ...): ... The ``keep_lazy()`` decorator takes a number of extra arguments (``*args``) specifying the type(s) that the original function can return. A common use case is to have functions that return text. For these, you can just - pass the ``six.text_type`` type to ``keep_lazy`` (or even simpler, use the + pass the ``str`` type to ``keep_lazy`` (or even simpler, use the :func:`keep_lazy_text` decorator described in the next section). Using this decorator means you can write your function and assume that the @@ -563,16 +558,15 @@ https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004 .. function:: keep_lazy_text(func) - A shortcut for ``keep_lazy(six.text_type)(func)``. + A shortcut for ``keep_lazy(str)(func)``. If you have a function that returns text and you want to be able to take lazy arguments while delaying their evaluation, simply use this decorator:: - from django.utils import six from django.utils.functional import keep_lazy, keep_lazy_text # Our previous example was: - @keep_lazy(six.text_type) + @keep_lazy(str) def fancy_utility_function(s, ...): ... @@ -680,11 +674,9 @@ escaping HTML. classes whose output doesn't require HTML escaping. This decorator defines the ``__html__()`` method on the decorated class - by wrapping the ``__unicode__()`` (Python 2) or ``__str__()`` (Python 3) - in :meth:`~django.utils.safestring.mark_safe`. Ensure the ``__unicode__()`` - or ``__str__()`` method does indeed return text that doesn't require HTML - escaping. - + by wrapping ``__str__()`` in :meth:`~django.utils.safestring.mark_safe`. + Ensure the ``__str__()`` method does indeed return text that doesn't + require HTML escaping. ``django.utils.http`` ===================== @@ -737,13 +729,11 @@ escaping HTML. .. function:: base36_to_int(s) - Converts a base 36 string to an integer. On Python 2 the output is - guaranteed to be an ``int`` and not a ``long``. + Converts a base 36 string to an integer. .. function:: int_to_base36(i) - Converts a positive integer to a base 36 string. On Python 2 ``i`` must be - smaller than `sys.maxint`_. + Converts a positive integer to a base 36 string. .. _sys.maxint: https://docs.python.org/2/library/sys.html#sys.maxint @@ -798,17 +788,16 @@ appropriate entities. .. class:: SafeString A ``str`` subclass that has been specifically marked as "safe" - (requires no further escaping) for HTML output purposes. This is - :class:`SafeBytes` on Python 2 and :class:`SafeText` on Python 3. + (requires no further escaping) for HTML output purposes. Alias of + :class:`SafeText`. -.. class:: SafeText + Alias of :class:`SafeBytes` on Python 2 (in older versions of Django that + support it). - A ``str`` (in Python 3) or ``unicode`` (in Python 2) subclass - that has been specifically marked as "safe" for HTML output purposes. - -.. class:: SafeUnicode +.. class:: SafeText - Historical name of :class:`SafeText`. Only available under Python 2. + A ``str`` subclass that has been specifically marked as "safe" for HTML + output purposes. .. function:: mark_safe(s) |
