diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 6571cc244b3..b6a0e17b39c 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -810,7 +810,7 @@ on the entrance and exit from the block. Some language have a construct that looks like this:: with obj: - a = 1 # equivalent to obj.a = 1 + a = 1 # equivalent to obj.a = 1 total = total + 1 # obj.total = obj.total + 1 In Python, such a construct would be ambiguous. diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index d9eb00c277f..20a6245dc65 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -122,7 +122,8 @@ and off individually. They are described here in more detail. .. 2to3fixer:: callable - Converts ``callable(x)`` to ``hasattr(x, "__call_")``. + Converts ``callable(x)`` to ``isinstance(x, collections.Callable)``, adding + an import to :mod:`collections` if needed. .. 2to3fixer:: dict diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 4f632f29919..652a2f4d324 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1005,7 +1005,7 @@ Here is what we get on Windows:: >>> It is funny to see that on linux the sort function seems to work much more -efficient, it is doing less comparisons:: +efficiently, it is doing less comparisons:: >>> qsort(ia, len(ia), sizeof(c_int), cmp_func) # doctest: +LINUX py_cmp_func 5 1 diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index b05282b502d..a5768387bdc 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -1659,6 +1659,8 @@ file-like object (or, more precisely, any object which supports :meth:`write` and :meth:`flush` methods). +.. currentmodule:: logging + .. class:: StreamHandler(stream=None) Returns a new instance of the :class:`StreamHandler` class. If *stream* is diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index 2b311809bcb..d9688332513 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -144,6 +144,4 @@ Other Functions .. function:: heapmin() Force the :cfunc:`malloc` heap to clean itself up and return unused blocks to - the operating system. This only works on Windows NT. On failure, this raises - :exc:`IOError`. - + the operating system. On failure, this raises :exc:`IOError`. diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 523079f9a86..9527d356805 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -153,9 +153,7 @@ required option an option that must be supplied on the command-line; note that the phrase "required option" is self-contradictory in English. :mod:`optparse` doesn't prevent you from implementing required options, but doesn't give you much - help at it either. See ``examples/required_1.py`` and - ``examples/required_2.py`` in the :mod:`optparse` source distribution for two - ways to implement required options with :mod:`optparse`. + help at it either. For example, consider this hypothetical command-line:: diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 7c96bfe2340..96d21841ec2 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -13,26 +13,34 @@ module. For creating temporary files and directories see the :mod:`tempfile` module, and for high-level file and directory handling see the :mod:`shutil` module. -The design of all built-in operating system dependent modules of Python is such -that as long as the same functionality is available, it uses the same interface; -for example, the function ``os.stat(path)`` returns stat information about -*path* in the same format (which happens to have originated with the POSIX -interface). +Notes on the availability of these functions: -Extensions peculiar to a particular operating system are also available through -the :mod:`os` module, but using them is of course a threat to portability! +* The design of all built-in operating system dependent modules of Python is + such that as long as the same functionality is available, it uses the same + interface; for example, the function ``os.stat(path)`` returns stat + information about *path* in the same format (which happens to have originated + with the POSIX interface). -.. note:: +* Extensions peculiar to a particular operating system are also available + through the :mod:`os` module, but using them is of course a threat to + portability. - All functions accepting path or file names accept both bytes and string - objects, and result in an object of the same type, if a path or file name is - returned. +* All functions accepting path or file names accept both bytes and string + objects, and result in an object of the same type, if a path or file name is + returned. .. note:: If not separately noted, all functions that claim "Availability: Unix" are supported on Mac OS X, which builds on a Unix core. +* An "Availability: Unix" note means that this function is commonly found on + Unix systems. It does not make any claims about its existence on a specific + operating system. + +* If not separately noted, all functions that claim "Availability: Unix" are + supported on Mac OS X, which builds on a Unix core. + .. note:: All functions in this module raise :exc:`OSError` in the case of invalid or @@ -46,9 +54,9 @@ the :mod:`os` module, but using them is of course a threat to portability! .. data:: name - The name of the operating system dependent module imported. The following names - have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, ``'os2'``, - ``'ce'``, ``'java'``. + The name of the operating system dependent module imported. The following + names have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, + ``'os2'``, ``'ce'``, ``'java'``. .. _os-filenames: diff --git a/Doc/library/select.rst b/Doc/library/select.rst index ae5ffa534ad..60a894f0b91 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -45,7 +45,7 @@ The module defines the following: :ref:`kqueue-objects` below for the methods supported by kqueue objects. -.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0) +.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0) (Only supported on BSD.) Returns a kernel event object object; see section :ref:`kevent-objects` below for the methods supported by kqueue objects. diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index eaa413b0d2e..469ecddb222 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2458,8 +2458,7 @@ types, where they are relevant. Some of these are not reported by the .. attribute:: class.__bases__ - The tuple of base classes of a class object. If there are no base classes, this - will be an empty tuple. + The tuple of base classes of a class object. .. attribute:: class.__name__ diff --git a/Doc/library/string.rst b/Doc/library/string.rst index 0766894d7c0..d181841be3f 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -86,6 +86,7 @@ substitutions and value formatting via the :func:`format` method described in you to create and customize your own string formatting behaviors using the same implementation as the built-in :meth:`format` method. + .. class:: Formatter The :class:`Formatter` class has the following public methods: @@ -470,6 +471,8 @@ The available presentation types for floating point and decimal values are: Template strings ---------------- +.. versionadded:: 2.4 + Templates provide simpler string substitutions as described in :pep:`292`. Instead of the normal ``%``\ -based substitutions, Templates support ``$``\ -based substitutions, using the following rules: diff --git a/Lib/test/regrtest.py b/Lib/test/regrtest.py index 06648560552..eab22d66ca0 100755 --- a/Lib/test/regrtest.py +++ b/Lib/test/regrtest.py @@ -121,8 +121,6 @@ resources to test. Currently only the following are defined: curses - Tests that use curses and will modify the terminal's state and output modes. - lib2to3 - Run the tests for 2to3 (They take a while.) - largefile - It is okay to run some test that may create huge files. These tests can take a long time and may consume >2GB of disk space temporarily. diff --git a/Lib/test/test_posix.py b/Lib/test/test_posix.py index 3a404833327..701d1ea5811 100644 --- a/Lib/test/test_posix.py +++ b/Lib/test/test_posix.py @@ -195,32 +195,54 @@ class PosixTester(unittest.TestCase): if hasattr(posix, 'stat'): self.assertTrue(posix.stat(support.TESTFN)) - if hasattr(posix, 'chown'): - def test_chown(self): - # raise an OSError if the file does not exist - os.unlink(support.TESTFN) - self.assertRaises(OSError, posix.chown, support.TESTFN, -1, -1) + def _test_all_chown_common(self, chown_func, first_param): + """Common code for chown, fchown and lchown tests.""" + if os.getuid() == 0: + try: + # Many linux distros have a nfsnobody user as MAX_UID-2 + # that makes a good test case for signedness issues. + # http://bugs.python.org/issue1747858 + # This part of the test only runs when run as root. + # Only scary people run their tests as root. + ent = pwd.getpwnam('nfsnobody') + chown_func(first_param, ent.pw_uid, ent.pw_gid) + except KeyError: + pass + else: + # non-root cannot chown to root, raises OSError + self.assertRaises(OSError, chown_func, + first_param, 0, 0) + # test a successful chown call + chown_func(first_param, os.getuid(), os.getgid()) - # re-create the file - open(support.TESTFN, 'w').close() - if os.getuid() == 0: - try: - # Many linux distros have a nfsnobody user as MAX_UID-2 - # that makes a good test case for signedness issues. - # http://bugs.python.org/issue1747858 - # This part of the test only runs when run as root. - # Only scary people run their tests as root. - ent = pwd.getpwnam('nfsnobody') - posix.chown(support.TESTFN, ent.pw_uid, ent.pw_gid) - except KeyError: - pass - else: - # non-root cannot chown to root, raises OSError - self.assertRaises(OSError, posix.chown, - support.TESTFN, 0, 0) + @unittest.skipUnless(hasattr(posix, 'chown'), "test needs os.chown()") + def test_chown(self): + # raise an OSError if the file does not exist + os.unlink(support.TESTFN) + self.assertRaises(OSError, posix.chown, support.TESTFN, -1, -1) - # test a successful chown call - posix.chown(support.TESTFN, os.getuid(), os.getgid()) + # re-create the file + open(support.TESTFN, 'w').close() + self._test_all_chown_common(posix.chown, support.TESTFN) + + @unittest.skipUnless(hasattr(posix, 'fchown'), "test needs os.fchown()") + def test_fchown(self): + os.unlink(support.TESTFN) + + # re-create the file + test_file = open(support.TESTFN, 'w') + try: + fd = test_file.fileno() + self._test_all_chown_common(posix.fchown, fd) + finally: + test_file.close() + + @unittest.skipUnless(hasattr(posix, 'lchown'), "test needs os.lchown()") + def test_lchown(self): + os.unlink(support.TESTFN) + # create a symlink + os.symlink('/tmp/dummy-symlink-target', support.TESTFN) + self._test_all_chown_common(posix.lchown, support.TESTFN) def test_chdir(self): if hasattr(posix, 'chdir'): diff --git a/Modules/gcmodule.c b/Modules/gcmodule.c index d4a0900fcb2..1b5cf89ba62 100644 --- a/Modules/gcmodule.c +++ b/Modules/gcmodule.c @@ -927,7 +927,7 @@ collect(int generation) */ (void)handle_finalizers(&finalizers, old); - /* Clear free list only during the collection of the higest + /* Clear free list only during the collection of the highest * generation */ if (generation == NUM_GENERATIONS-1) { clear_freelists(); @@ -948,7 +948,7 @@ collect_generations(void) int i; Py_ssize_t n = 0; - /* Find the oldest generation (higest numbered) where the count + /* Find the oldest generation (highest numbered) where the count * exceeds the threshold. Objects in the that generation and * generations younger than it will be collected. */ for (i = NUM_GENERATIONS-1; i >= 0; i--) { diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c index 3ed8d5f71f0..4a63f3d31dd 100644 --- a/Modules/posixmodule.c +++ b/Modules/posixmodule.c @@ -1988,9 +1988,10 @@ fd to the numeric uid and gid."); static PyObject * posix_fchown(PyObject *self, PyObject *args) { - int fd, uid, gid; + int fd; + long uid, gid; int res; - if (!PyArg_ParseTuple(args, "iii:chown", &fd, &uid, &gid)) + if (!PyArg_ParseTuple(args, "ill:chown", &fd, &uid, &gid)) return NULL; Py_BEGIN_ALLOW_THREADS res = fchown(fd, (uid_t) uid, (gid_t) gid); @@ -2012,9 +2013,9 @@ posix_lchown(PyObject *self, PyObject *args) { PyObject *opath; char *path; - int uid, gid; + long uid, gid; int res; - if (!PyArg_ParseTuple(args, "O&ii:lchown", + if (!PyArg_ParseTuple(args, "O&ll:lchown", PyUnicode_FSConverter, &opath, &uid, &gid)) return NULL; diff --git a/Modules/selectmodule.c b/Modules/selectmodule.c index 3820bbbe735..9f1b96825e8 100644 --- a/Modules/selectmodule.c +++ b/Modules/selectmodule.c @@ -1166,7 +1166,7 @@ static PyTypeObject pyEpoll_Type = { #endif PyDoc_STRVAR(kqueue_event_doc, -"kevent(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0)\n\ +"kevent(ident, filter=KQ_FILTER_READ, flags=KQ_EV_ADD, fflags=0, data=0, udata=0)\n\ \n\ This object is the equivalent of the struct kevent for the C API.\n\ \n\ diff --git a/PC/msvcrtmodule.c b/PC/msvcrtmodule.c index 3ef1b7cf86e..48e739f2b76 100755 --- a/PC/msvcrtmodule.c +++ b/PC/msvcrtmodule.c @@ -45,6 +45,12 @@ msvcrt_heapmin(PyObject *self, PyObject *args) return Py_None; } +PyDoc_STRVAR(heapmin_doc, +"heapmin() -> None\n\ +\n\ +Force the malloc() heap to clean itself up and return unused blocks\n\ +to the operating system. On failure, this raises IOError."); + // Perform locking operations on a C runtime file descriptor. static PyObject * msvcrt_locking(PyObject *self, PyObject *args) @@ -67,6 +73,17 @@ msvcrt_locking(PyObject *self, PyObject *args) return Py_None; } +PyDoc_STRVAR(locking_doc, +"locking(fd, mode, nbytes) -> None\n\ +\n\ +Lock part of a file based on file descriptor fd from the C runtime.\n\ +Raises IOError on failure. The locked region of the file extends from\n\ +the current file position for nbytes bytes, and may continue beyond\n\ +the end of the file. mode must be one of the LK_* constants listed\n\ +below. Multiple regions in a file may be locked at the same time, but\n\ +may not overlap. Adjacent regions are not merged; they must be unlocked\n\ +individually."); + // Set the file translation mode for a C runtime file descriptor. static PyObject * msvcrt_setmode(PyObject *self, PyObject *args) @@ -83,6 +100,13 @@ msvcrt_setmode(PyObject *self, PyObject *args) return PyLong_FromLong(flags); } +PyDoc_STRVAR(setmode_doc, +"setmode(fd, mode) -> Previous mode\n\ +\n\ +Set the line-end translation mode for the file descriptor fd. To set\n\ +it to text mode, flags should be os.O_TEXT; for binary, it should be\n\ +os.O_BINARY."); + // Convert an OS file handle to a C runtime file descriptor. static PyObject * msvcrt_open_osfhandle(PyObject *self, PyObject *args) @@ -101,6 +125,14 @@ msvcrt_open_osfhandle(PyObject *self, PyObject *args) return PyLong_FromLong(fd); } +PyDoc_STRVAR(open_osfhandle_doc, +"open_osfhandle(handle, flags) -> file descriptor\n\ +\n\ +Create a C runtime file descriptor from the file handle handle. The\n\ +flags parameter should be a bitwise OR of os.O_APPEND, os.O_RDONLY,\n\ +and os.O_TEXT. The returned file descriptor may be used as a parameter\n\ +to os.fdopen() to create a file object."); + // Convert a C runtime file descriptor to an OS file handle. static PyObject * msvcrt_get_osfhandle(PyObject *self, PyObject *args) @@ -121,6 +153,12 @@ msvcrt_get_osfhandle(PyObject *self, PyObject *args) return PyLong_FromVoidPtr((void*)handle); } +PyDoc_STRVAR(get_osfhandle_doc, +"get_osfhandle(fd) -> file handle\n\ +\n\ +Return the file handle for the file descriptor fd. Raises IOError\n\ +if fd is not recognized."); + /* Console I/O */ static PyObject * @@ -135,6 +173,11 @@ msvcrt_kbhit(PyObject *self, PyObject *args) return PyLong_FromLong(ok); } +PyDoc_STRVAR(kbhit_doc, +"kbhit() -> bool\n\ +\n\ +Return true if a keypress is waiting to be read."); + static PyObject * msvcrt_getch(PyObject *self, PyObject *args) { @@ -151,6 +194,16 @@ msvcrt_getch(PyObject *self, PyObject *args) return PyBytes_FromStringAndSize(s, 1); } +PyDoc_STRVAR(getch_doc, +"getch() -> key character\n\ +\n\ +Read a keypress and return the resulting character. Nothing is echoed to\n\ +the console. This call will block if a keypress is not already\n\ +available, but will not wait for Enter to be pressed. If the pressed key\n\ +was a special function key, this will return '\\000' or '\\xe0'; the next\n\ +call will return the keycode. The Control-C keypress cannot be read with\n\ +this function."); + #ifdef _WCONIO_DEFINED static PyObject * msvcrt_getwch(PyObject *self, PyObject *args) @@ -167,6 +220,11 @@ msvcrt_getwch(PyObject *self, PyObject *args) u[0] = ch; return PyUnicode_FromUnicode(u, 1); } + +PyDoc_STRVAR(getwch_doc, +"getwch() -> Unicode key character\n\ +\n\ +Wide char variant of getch(), returning a Unicode value."); #endif static PyObject * @@ -185,6 +243,12 @@ msvcrt_getche(PyObject *self, PyObject *args) return PyBytes_FromStringAndSize(s, 1); } +PyDoc_STRVAR(getche_doc, +"getche() -> key character\n\ +\n\ +Similar to getch(), but the keypress will be echoed if it represents\n\ +a printable character."); + #ifdef _WCONIO_DEFINED static PyObject * msvcrt_getwche(PyObject *self, PyObject *args) @@ -201,6 +265,11 @@ msvcrt_getwche(PyObject *self, PyObject *args) s[0] = ch; return PyUnicode_FromUnicode(s, 1); } + +PyDoc_STRVAR(getwche_doc, +"getwche() -> Unicode key character\n\ +\n\ +Wide char variant of getche(), returning a Unicode value."); #endif static PyObject * @@ -216,6 +285,11 @@ msvcrt_putch(PyObject *self, PyObject *args) return Py_None; } +PyDoc_STRVAR(putch_doc, +"putch(char) -> None\n\ +\n\ +Print the character char to the console without buffering."); + #ifdef _WCONIO_DEFINED static PyObject * msvcrt_putwch(PyObject *self, PyObject *args) @@ -229,6 +303,11 @@ msvcrt_putwch(PyObject *self, PyObject *args) Py_RETURN_NONE; } + +PyDoc_STRVAR(putwch_doc, +"putwch(unicode_char) -> None\n\ +\n\ +Wide char variant of putch(), accepting a Unicode value."); #endif static PyObject * @@ -245,6 +324,12 @@ msvcrt_ungetch(PyObject *self, PyObject *args) return Py_None; } +PyDoc_STRVAR(ungetch_doc, +"ungetch(char) -> None\n\ +\n\ +Cause the character char to be \"pushed back\" into the console buffer;\n\ +it will be the next character read by getch() or getche()."); + #ifdef _WCONIO_DEFINED static PyObject * msvcrt_ungetwch(PyObject *self, PyObject *args) @@ -259,6 +344,11 @@ msvcrt_ungetwch(PyObject *self, PyObject *args) Py_INCREF(Py_None); return Py_None; } + +PyDoc_STRVAR(ungetwch_doc, +"ungetwch(unicode_char) -> None\n\ +\n\ +Wide char variant of ungetch(), accepting a Unicode value."); #endif static void @@ -332,16 +422,16 @@ seterrormode(PyObject *self, PyObject *args) /* List of functions exported by this module */ static struct PyMethodDef msvcrt_functions[] = { - {"heapmin", msvcrt_heapmin, METH_VARARGS}, - {"locking", msvcrt_locking, METH_VARARGS}, - {"setmode", msvcrt_setmode, METH_VARARGS}, - {"open_osfhandle", msvcrt_open_osfhandle, METH_VARARGS}, - {"get_osfhandle", msvcrt_get_osfhandle, METH_VARARGS}, - {"kbhit", msvcrt_kbhit, METH_VARARGS}, - {"getch", msvcrt_getch, METH_VARARGS}, - {"getche", msvcrt_getche, METH_VARARGS}, - {"putch", msvcrt_putch, METH_VARARGS}, - {"ungetch", msvcrt_ungetch, METH_VARARGS}, + {"heapmin", msvcrt_heapmin, METH_VARARGS, heapmin_doc}, + {"locking", msvcrt_locking, METH_VARARGS, locking_doc}, + {"setmode", msvcrt_setmode, METH_VARARGS, setmode_doc}, + {"open_osfhandle", msvcrt_open_osfhandle, METH_VARARGS, open_osfhandle_doc}, + {"get_osfhandle", msvcrt_get_osfhandle, METH_VARARGS, get_osfhandle_doc}, + {"kbhit", msvcrt_kbhit, METH_VARARGS, kbhit_doc}, + {"getch", msvcrt_getch, METH_VARARGS, getch_doc}, + {"getche", msvcrt_getche, METH_VARARGS, getche_doc}, + {"putch", msvcrt_putch, METH_VARARGS, putch_doc}, + {"ungetch", msvcrt_ungetch, METH_VARARGS, ungetch_doc}, {"SetErrorMode", seterrormode, METH_VARARGS}, #ifdef _DEBUG {"CrtSetReportFile", msvcrt_setreportfile, METH_VARARGS}, @@ -349,10 +439,10 @@ static struct PyMethodDef msvcrt_functions[] = { {"set_error_mode", msvcrt_seterrormode, METH_VARARGS}, #endif #ifdef _WCONIO_DEFINED - {"getwch", msvcrt_getwch, METH_VARARGS}, - {"getwche", msvcrt_getwche, METH_VARARGS}, - {"putwch", msvcrt_putwch, METH_VARARGS}, - {"ungetwch", msvcrt_ungetwch, METH_VARARGS}, + {"getwch", msvcrt_getwch, METH_VARARGS, getwch_doc}, + {"getwche", msvcrt_getwche, METH_VARARGS, getwche_doc}, + {"putwch", msvcrt_putwch, METH_VARARGS, putwch_doc}, + {"ungetwch", msvcrt_ungetwch, METH_VARARGS, ungetwch_doc}, #endif {NULL, NULL} };