[Python-checkins] r72247 - in python/branches/pep-0383/Doc/library: codecs.rst os.rst

Sun May 3 22:29:02 CEST 2009

Author: martin.v.loewis
Date: Sun May 3 22:29:02 2009
New Revision: 72247
Log:
Document PEP 383.
Modified:
 python/branches/pep-0383/Doc/library/codecs.rst
 python/branches/pep-0383/Doc/library/os.rst
Modified: python/branches/pep-0383/Doc/library/codecs.rst
==============================================================================

--- python/branches/pep-0383/Doc/library/codecs.rst	(original)
+++ python/branches/pep-0383/Doc/library/codecs.rst	Sun May 3 22:29:02 2009
@@ -322,6 +322,8 @@
 | ``'backslashreplace'`` | Replace with backslashed escape sequences |
 | | (only for encoding). |
 +-------------------------+-----------------------------------------------+
+| ``'utf8b'`` | Replace byte with surrogate U+DCxx. |
++-------------------------+-----------------------------------------------+
 
 In addition, the following error handlers are specific to a single codec:
 
Modified: python/branches/pep-0383/Doc/library/os.rst
==============================================================================
--- python/branches/pep-0383/Doc/library/os.rst	(original)
+++ python/branches/pep-0383/Doc/library/os.rst	Sun May 3 22:29:02 2009
@@ -50,6 +50,26 @@
 have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``,
 ``'ce'``, ``'java'``.
 
+.. _os-filenames:
+
+File Names, Command Line Arguments, and Environment Variables
+-------------------------------------------------------------
+
+In Python, file names, command line arguments, and environment
+variables are represented using the string type. On some systems,
+decoding these strings to and from bytes is necessary before passing
+them to the operating system. Python uses the file system encoding to
+perform this conversion (see :func:`sys.getfilesystemencoding`).
+
+.. versionchanged:: 3.1
+ On some systems, conversion using the file system encoding may
+ fail. In this case, Python uses the ``utf8b`` encoding error
+ handler.
+
+
+The file system encoding must guarantee to successfully decode all
+bytes below 128. If the file system encoding fails to provide this
+guarantee, API functions may raise UnicodeErrors.
 
 .. _os-procinfo:
 
@@ -688,12 +708,7 @@
 
 .. function:: getcwd()
 
- Return a string representing the current working directory. On Unix
- platforms, this function may raise :exc:`UnicodeDecodeError` if the name of
- the current directory is not decodable in the file system encoding. Use
- :func:`getcwdb` if you need the call to never fail. Availability: Unix,
- Windows.
-
+ Return a string representing the current working directory.
 
 .. function:: getcwdb()
 
@@ -800,10 +815,8 @@
 entries ``'.'`` and ``'..'`` even if they are present in the directory.
 Availability: Unix, Windows.
 
- This function can be called with a bytes or string argument. In the bytes
- case, all filenames will be listed as returned by the underlying API. In the
- string case, filenames will be decoded using the file system encoding, and
- skipped if a decoding error occurs.
+ This function can be called with a bytes or string argument, and return
+ filenames of the same datatype.
 
 
 .. function:: lstat(path)
