diff --git a/Misc/NEWS b/Misc/NEWS index 26b33b2bd16..46c8765b64c 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -12,6 +12,8 @@ What's New in Python 2.7 alpha 2? Core and Builtins ----------------- +- Issue #7579: the msvcrt module now has docstrings for all its functions. + - Issue #7413: Passing '\0' as the separator to datetime.datetime.isoformat() used to drop the time part of the result. diff --git a/PC/msvcrtmodule.c b/PC/msvcrtmodule.c index cad22b19e0a..24e0cd52124 100755 --- a/PC/msvcrtmodule.c +++ b/PC/msvcrtmodule.c @@ -43,6 +43,13 @@ 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. This only works on Windows NT. On failure,\n\ +this raises IOError."); + // Perform locking operations on a C runtime file descriptor. static PyObject * msvcrt_locking(PyObject *self, PyObject *args) @@ -65,6 +72,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) @@ -81,6 +99,13 @@ msvcrt_setmode(PyObject *self, PyObject *args) return PyInt_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) @@ -99,6 +124,14 @@ msvcrt_open_osfhandle(PyObject *self, PyObject *args) return PyInt_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) @@ -119,6 +152,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 * @@ -133,6 +172,11 @@ msvcrt_kbhit(PyObject *self, PyObject *args) return PyInt_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) { @@ -149,6 +193,16 @@ msvcrt_getch(PyObject *self, PyObject *args) return PyString_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) @@ -165,6 +219,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 * @@ -183,6 +242,12 @@ msvcrt_getche(PyObject *self, PyObject *args) return PyString_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) @@ -199,6 +264,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 * @@ -214,6 +284,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) @@ -233,6 +308,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 * @@ -249,6 +329,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) @@ -263,6 +349,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 @@ -282,21 +373,21 @@ insertint(PyObject *d, char *name, int value) /* 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}, #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} };