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.
.. 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
>>>
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
and :meth:`flush` methods).
+.. currentmodule:: logging
+
.. class:: StreamHandler(stream=None)
Returns a new instance of the :class:`StreamHandler` class. If *stream* is
.. 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`.
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::
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
.. 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:
: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.
.. 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__
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:
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:
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.
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)
-
- # 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)
-
- # test a successful chown call
- posix.chown(support.TESTFN, os.getuid(), os.getgid())
+ 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())
+
+ @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)
+
+ # 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'):
*/
(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();
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--) {
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);
{
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;
#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\
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)
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)
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)
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)
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 *
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)
{
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)
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 *
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)
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 *
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)
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 *
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)
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
/* 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},
{"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}
};
projects / python / commitdiff