#7579: Add docstrings to the msvcrt module
diff --git a/PC/msvcrtmodule.c b/PC/msvcrtmodule.c
index cad22b1..24e0cd5 100755
--- a/PC/msvcrtmodule.c
+++ b/PC/msvcrtmodule.c
@@ -43,6 +43,13 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
/* 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}
};