iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

restify PEP 349 (#148)

This commit is contained in:
Mariatta 2016-12-03 16:03:37 -08:00 committed by Brett Cannon
parent 26b4086667
commit 4e21b23c38
1 changed files with 102 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
pep-0349.txt
View File

@ -5,140 +5,148 @@ Last-Modified: $Date$
Author: Neil Schemenauer <nas@arctrix.com> Author: Neil Schemenauer <nas@arctrix.com>
Status: Deferred Status: Deferred
Type: Standards Track Type: Standards Track
Content-Type: text/plain Content-Type: text/x-rst
Created: 02-Aug-2005 Created: 02-Aug-2005
Python-Version: 2.5 Python-Version: 2.5
Post-History: 06-Aug-2005 Post-History: 06-Aug-2005
Abstract Abstract
========
This PEP proposes to change the str() built-in function so that it This PEP proposes to change the ``str()`` built-in function so that it
can return unicode strings. This change would make it easier to can return unicode strings. This change would make it easier to
write code that works with either string type and would also make write code that works with either string type and would also make
some existing code handle unicode strings. The C function some existing code handle unicode strings. The C function
PyObject_Str() would remain unchanged and the function ``PyObject_Str()`` would remain unchanged and the function
PyString_New() would be added instead. ``PyString_New()`` would be added instead.
Rationale Rationale
=========
Python has had a Unicode string type for some time now but use of Python has had a Unicode string type for some time now but use of
it is not yet widespread. There is a large amount of Python code it is not yet widespread. There is a large amount of Python code
that assumes that string data is represented as str instances. that assumes that string data is represented as str instances.
The long term plan for Python is to phase out the str type and use The long term plan for Python is to phase out the str type and use
unicode for all string data. Clearly, a smooth migration path unicode for all string data. Clearly, a smooth migration path
must be provided. must be provided.
We need to upgrade existing libraries, written for str instances, We need to upgrade existing libraries, written for str instances,
to be made capable of operating in an all-unicode string world. to be made capable of operating in an all-unicode string world.
We can't change to an all-unicode world until all essential We can't change to an all-unicode world until all essential
libraries are made capable for it. Upgrading the libraries in one libraries are made capable for it. Upgrading the libraries in one
shot does not seem feasible. A more realistic strategy is to shot does not seem feasible. A more realistic strategy is to
individually make the libraries capable of operating on unicode individually make the libraries capable of operating on unicode
strings while preserving their current all-str environment strings while preserving their current all-str environment
behaviour. behaviour.
First, we need to be able to write code that can accept unicode First, we need to be able to write code that can accept unicode
instances without attempting to coerce them to str instances. Let instances without attempting to coerce them to str instances. Let
us label such code as Unicode-safe. Unicode-safe libraries can be us label such code as Unicode-safe. Unicode-safe libraries can be
used in an all-unicode world. used in an all-unicode world.
Second, we need to be able to write code that, when provided only Second, we need to be able to write code that, when provided only
str instances, will not create unicode results. Let us label such str instances, will not create unicode results. Let us label such
code as str-stable. Libraries that are str-stable can be used by code as str-stable. Libraries that are str-stable can be used by
libraries and applications that are not yet Unicode-safe. libraries and applications that are not yet Unicode-safe.
Sometimes it is simple to write code that is both str-stable and Sometimes it is simple to write code that is both str-stable and
Unicode-safe. For example, the following function just works: Unicode-safe. For example, the following function just works::
def appendx(s): def appendx(s):
return s + 'x' return s + 'x'
That's not too surprising since the unicode type is designed to That's not too surprising since the unicode type is designed to
make the task easier. The principle is that when str and unicode make the task easier. The principle is that when str and unicode
instances meet, the result is a unicode instance. One notable instances meet, the result is a unicode instance. One notable
difficulty arises when code requires a string representation of an difficulty arises when code requires a string representation of an
object; an operation traditionally accomplished by using the str() object; an operation traditionally accomplished by using the ``str()``
built-in function. built-in function.
Using the current str() function makes the code not Unicode-safe. Using the current ``str()`` function makes the code not Unicode-safe.
Replacing a str() call with a unicode() call makes the code not Replacing a ``str()`` call with a ``unicode()`` call makes the code not
str-stable. Changing str() so that it could return unicode str-stable. Changing ``str()`` so that it could return unicode
instances would solve this problem. As a further benefit, some code instances would solve this problem. As a further benefit, some code
that is currently not Unicode-safe because it uses str() would that is currently not Unicode-safe because it uses ``str()`` would
become Unicode-safe. become Unicode-safe.
Specification Specification
=============
A Python implementation of the str() built-in follows: A Python implementation of the ``str()`` built-in follows::
def str(s): def str(s):
"""Return a nice string representation of the object. The """Return a nice string representation of the object. The
return value is a str or unicode instance. return value is a str or unicode instance.
""" """
if type(s) is str or type(s) is unicode: if type(s) is str or type(s) is unicode:
return s return s
r = s.__str__() r = s.__str__()
if not isinstance(r, (str, unicode)): if not isinstance(r, (str, unicode)):
raise TypeError('__str__ returned non-string') raise TypeError('__str__ returned non-string')
return r return r
The following function would be added to the C API and would be the The following function would be added to the C API and would be the
equivalent to the str() built-in (ideally it be called PyObject_Str, equivalent to the ``str()`` built-in (ideally it be called ``PyObject_Str``,
but changing that function could cause a massive number of but changing that function could cause a massive number of
compatibility problems): compatibility problems)::
PyObject *PyString_New(PyObject *); PyObject *PyString_New(PyObject *);
A reference implementation is available on Sourceforge [1] as a A reference implementation is available on Sourceforge [1]_ as a
patch. patch.
Backwards Compatibility Backwards Compatibility
=======================
Some code may require that str() returns a str instance. In the Some code may require that ``str()`` returns a str instance. In the
standard library, only one such case has been found so far. The standard library, only one such case has been found so far. The
function email.header_decode() requires a str instance and the function ``email.header_decode()`` requires a str instance and the
email.Header.decode_header() function tries to ensure this by ``email.Header.decode_header()`` function tries to ensure this by
calling str() on its argument. The code was fixed by changing calling ``str()`` on its argument. The code was fixed by changing
the line "header = str(header)" to: the line "header = str(header)" to::
if isinstance(header, unicode): if isinstance(header, unicode):
header = header.encode('ascii') header = header.encode('ascii')
Whether this is truly a bug is questionable since decode_header() Whether this is truly a bug is questionable since ``decode_header()``
really operates on byte strings, not character strings. Code that really operates on byte strings, not character strings. Code that
passes it a unicode instance could itself be considered buggy. passes it a unicode instance could itself be considered buggy.
Alternative Solutions Alternative Solutions
=====================
A new built-in function could be added instead of changing str(). A new built-in function could be added instead of changing ``str()``.
Doing so would introduce virtually no backwards compatibility Doing so would introduce virtually no backwards compatibility
problems. However, since the compatibility problems are expected to problems. However, since the compatibility problems are expected to
rare, changing str() seems preferable to adding a new built-in. rare, changing ``str()`` seems preferable to adding a new built-in.
The basestring type could be changed to have the proposed behaviour, The basestring type could be changed to have the proposed behaviour,
rather than changing str(). However, that would be confusing rather than changing ``str()``. However, that would be confusing
behaviour for an abstract base type. behaviour for an abstract base type.
References References
==========
[1] http://www.python.org/sf/1266570 .. [1] http://www.python.org/sf/1266570
Copyright Copyright
=========
This document has been placed in the public domain. This document has been placed in the public domain.
Local Variables: ..
mode: indented-text Local Variables:
indent-tabs-mode: nil mode: indented-text
sentence-end-double-space: t indent-tabs-mode: nil
fill-column: 70 sentence-end-double-space: t
End: fill-column: 70
End: