diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -15,7 +15,7 @@ and write data starting at the current f and write data starting at the current file position, and :meth:`seek` through the file to different positions. -A memory-mapped file is created by the :func:`mmap` function, which is different +A memory-mapped file is created by the :class:`mmap` constructor, which is different on Unix and on Windows. In either case you must provide a file descriptor for a file opened for update. If you wish to map an existing Python file object, use its :meth:`fileno` method to obtain the correct value for the *fileno* @@ -23,7 +23,7 @@ which returns a file descriptor directly which returns a file descriptor directly (the file still needs to be closed when done). -For both the Unix and Windows versions of the function, *access* may be +For both the Unix and Windows versions of the constructor, *access* may be specified as an optional keyword parameter. *access* accepts one of three values: :const:`ACCESS_READ`, :const:`ACCESS_WRITE`, or :const:`ACCESS_COPY` to specify readonly, write-through or copy-on-write memory respectively. *access* @@ -39,11 +39,14 @@ not update the underlying file. To map anonymous memory, -1 should be passed as the fileno along with the length. +.. versionchanged:: 2.6 + mmap.mmap has formerly been a factory function creating mmap objects. Now + mmap.mmap is the class itself. -.. function:: mmap(fileno, length[, tagname[, access[, offset]]]) +.. class:: mmap(fileno, length[, tagname[, access[, offset]]]) **(Windows version)** Maps *length* bytes from the file specified by the file - handle *fileno*, and returns a mmap object. If *length* is larger than the + handle *fileno*, and creates a mmap object. If *length* is larger than the current size of the file, the file is extended to contain *length* bytes. If *length* is ``0``, the maximum length of the map is the current size of the file, except that if the file is empty Windows raises an exception (you cannot @@ -61,12 +64,12 @@ not update the underlying file. *offset* must be a multiple of the ALLOCATIONGRANULARITY. -.. function:: mmap(fileno, length[, flags[, prot[, access[, offset]]]]) +.. class:: mmap(fileno, length[, flags[, prot[, access[, offset]]]]) :noindex: **(Unix version)** Maps *length* bytes from the file specified by the file descriptor *fileno*, and returns a mmap object. If *length* is ``0``, the - maximum length of the map will be the current size of the file when :func:`mmap` + maximum length of the map will be the current size of the file when :class:`mmap` is called. *flags* specifies the nature of the mapping. :const:`MAP_PRIVATE` creates a @@ -87,7 +90,7 @@ not update the underlying file. be relative to the offset from the beginning of the file. *offset* defaults to 0. *offset* must be a multiple of the PAGESIZE or ALLOCATIONGRANULARITY. - This example shows a simple way of using :func:`mmap`:: + This example shows a simple way of using :class:`mmap`:: import mmap diff --git a/Misc/NEWS b/Misc/NEWS --- a/Misc/NEWS +++ b/Misc/NEWS @@ -368,6 +368,8 @@ Core and builtins Library ------- +- #1087741: mmap.mmap is now a class, not a factory function. It is also + subclassable now. - #1669: don't allow shutil.rmtree() to be called on a symlink to a directory. diff --git a/Modules/mmapmodule.c b/Modules/mmapmodule.c --- a/Modules/mmapmodule.c +++ b/Modules/mmapmodule.c @@ -974,6 +974,9 @@ static PyBufferProcs mmap_as_buffer = { (charbufferproc)mmap_buffer_getcharbuffer, }; +static PyObject * +new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict); + PyDoc_STRVAR(mmap_doc, "Windows: mmap(fileno, length[, tagname[, access[, offset]]])\n\ \n\ @@ -1019,16 +1022,26 @@ static PyTypeObject mmap_object_type = { PyObject_GenericGetAttr, /*tp_getattro*/ 0, /*tp_setattro*/ &mmap_as_buffer, /*tp_as_buffer*/ - Py_TPFLAGS_HAVE_GETCHARBUFFER, /*tp_flags*/ + Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GETCHARBUFFER, /*tp_flags*/ mmap_doc, /*tp_doc*/ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */ 0, /* tp_weaklistoffset */ - 0, /* tp_iter */ - 0, /* tp_iternext */ + 0, /* tp_iter */ + 0, /* tp_iternext */ mmap_object_methods, /* tp_methods */ - + 0, /* tp_members */ + 0, /* tp_getset */ + 0, /* tp_base */ + 0, /* tp_dict */ + 0, /* tp_descr_get */ + 0, /* tp_descr_set */ + 0, /* tp_dictoffset */ + 0, /* tp_init */ + PyType_GenericAlloc, /* tp_alloc */ + new_mmap_object, /* tp_new */ + PyObject_Del, /* tp_free */ }; @@ -1060,7 +1073,7 @@ _GetMapSize(PyObject *o, const char* par #ifdef UNIX static PyObject * -new_mmap_object(PyObject *self, PyObject *args, PyObject *kwdict) +new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict) { #ifdef HAVE_FSTAT struct stat st; @@ -1128,7 +1141,7 @@ new_mmap_object(PyObject *self, PyObject } } #endif - m_obj = PyObject_New(mmap_object, &mmap_object_type); + m_obj = (mmap_object *)type->tp_alloc(type, 0); if (m_obj == NULL) {return NULL;} m_obj->data = NULL; m_obj->size = (size_t) map_size; @@ -1182,7 +1195,7 @@ new_mmap_object(PyObject *self, PyObject #ifdef MS_WINDOWS static PyObject * -new_mmap_object(PyObject *self, PyObject *args, PyObject *kwdict) +new_mmap_object(PyTypeObject *type, PyObject *args, PyObject *kwdict) { mmap_object *m_obj; PyObject *map_size_obj = NULL, *offset_obj = NULL; @@ -1250,7 +1263,7 @@ new_mmap_object(PyObject *self, PyObject lseek(fileno, 0, SEEK_SET); } - m_obj = PyObject_New(mmap_object, &mmap_object_type); + m_obj = (mmap_object *)type->tp_alloc(type, 0); if (m_obj == NULL) return NULL; /* Set every field to an invalid marker, so we can safely @@ -1364,13 +1377,6 @@ new_mmap_object(PyObject *self, PyObject } #endif /* MS_WINDOWS */ -/* List of functions exported by this module */ -static struct PyMethodDef mmap_functions[] = { - {"mmap", (PyCFunction) new_mmap_object, - METH_VARARGS|METH_KEYWORDS, mmap_doc}, - {NULL, NULL} /* Sentinel */ -}; - static void setint(PyObject *d, const char *name, long value) { @@ -1388,7 +1394,7 @@ PyMODINIT_FUNC /* Patch the object type */ Py_TYPE(&mmap_object_type) = &PyType_Type; - module = Py_InitModule("mmap", mmap_functions); + module = Py_InitModule("mmap", NULL); if (module == NULL) return; dict = PyModule_GetDict(module); @@ -1396,6 +1402,7 @@ PyMODINIT_FUNC return; mmap_module_error = PyExc_EnvironmentError; PyDict_SetItemString(dict, "error", mmap_module_error); + PyDict_SetItemString(dict, "mmap", (PyObject*) &mmap_object_type); #ifdef PROT_EXEC setint(dict, "PROT_EXEC", PROT_EXEC); #endif