python/cdrom.cc: Adjust to new coding style and add docstrings.

1 files changed, 128 insertions, 115 deletions

diff --git a/python/cdrom.cc b/python/cdrom.cc
index 5044f3fa..521937f5 100644
--- a/python/cdrom.cc
+++ b/python/cdrom.cc
@@ -1,10 +1,26 @@
-// Description								/*{{{*/
-// $Id: cdrom.cc,v 1.1 2003/06/03 03:03:23 mvo Exp $
-/* ######################################################################
-
-   Cdrom - Wrapper for the apt-cdrom support
-
-   ##################################################################### */
+/* cdrom.cc - Wrapper for pkgCdrom.
+ *
+ * Copyright 2004-2009 Canonical Ltd.
+ * Copyright 2009 Julian Andres Klode <jak@debian.org>
+ *
+ * Authors: Michael Vogt
+ *          Julian Andres Klode
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301, USA.
+ */
 
 #include "generic.h"
 #include "apt_pkgmodule.h"
@@ -12,146 +28,143 @@
 
 #include <apt-pkg/cdrom.h>
 
-static PyObject *PkgCdromAdd(PyObject *Self,PyObject *Args)
+static char *cdrom_add_doc =
+    "add(progress: apt_pkg.CdromProgress) -> bool\n\n"
+    "Add the given CD-ROM to the sources.list. Returns True on success, may\n"
+    "raise an error on failure or return False.";
+static PyObject *cdrom_add(PyObject *Self,PyObject *Args)
 {
-   pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
+    pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
 
-   PyObject *pyCdromProgressInst = 0;
-   if (PyArg_ParseTuple(Args, "O", &pyCdromProgressInst) == 0) {
-      return 0;
-   }
+    PyObject *pyCdromProgressInst = 0;
+    if (PyArg_ParseTuple(Args, "O", &pyCdromProgressInst) == 0) {
+        return 0;
+    }
 
-   PyCdromProgress progress;
-   progress.setCallbackInst(pyCdromProgressInst);
+    PyCdromProgress progress;
+    progress.setCallbackInst(pyCdromProgressInst);
 
-   bool res = Cdrom.Add(&progress);
+    bool res = Cdrom.Add(&progress);
 
-   return HandleErrors(Py_BuildValue("b", res));
+    return HandleErrors(PyBool_FromLong(res));
 }
 
-static PyObject *PkgCdromIdent(PyObject *Self,PyObject *Args)
+static char *cdrom_ident_doc =
+    "ident(progress: apt_pkg.CdromProgress) -> str\n\n"
+    "Try to identify the CD-ROM and if successful return the identity as a\n"
+    "string. Otherwise, return None or raise an error.";
+static PyObject *cdrom_ident(PyObject *Self,PyObject *Args)
 {
-   pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
-   PyObject *pyCdromProgressInst = 0;
-   if (PyArg_ParseTuple(Args, "O!", &PyCdromProgress_Type,
-                        &pyCdromProgressInst) == 0) {
-      return 0;
-   }
-
-   PyCdromProgress progress;
-   progress.setCallbackInst(pyCdromProgressInst);
-
-   string ident;
-   bool res = Cdrom.Ident(ident, &progress);
-
-   if (res)
-       return CppPyString(ident);
-   else {
-       Py_INCREF(Py_None);
-       return HandleErrors(Py_None);
-   }
+    pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
+    PyObject *pyCdromProgressInst = 0;
+    if (PyArg_ParseTuple(Args, "O!", &PyCdromProgress_Type,
+                         &pyCdromProgressInst) == 0) {
+        return 0;
+    }
+
+    PyCdromProgress progress;
+    progress.setCallbackInst(pyCdromProgressInst);
+
+    string ident;
+    bool res = Cdrom.Ident(ident, &progress);
+
+    if (res)
+        return CppPyString(ident);
+    else {
+        Py_INCREF(Py_None);
+        return HandleErrors(Py_None);
+    }
 }
 
 #ifdef COMPAT_0_7
-static PyObject *PkgCdromIdent_old(PyObject *Self,PyObject *Args)
+static PyObject *cdrom_ident_old(PyObject *Self,PyObject *Args)
 {
-   pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
+    pkgCdrom &Cdrom = GetCpp<pkgCdrom>(Self);
 
-   PyObject *pyCdromProgressInst = 0;
-   if (PyArg_ParseTuple(Args, "O", &pyCdromProgressInst) == 0) {
-      return 0;
-   }
+    PyObject *pyCdromProgressInst = 0;
+    if (PyArg_ParseTuple(Args, "O", &pyCdromProgressInst) == 0) {
+        return 0;
+    }
 
-   PyCdromProgress progress;
-   progress.setCallbackInst(pyCdromProgressInst);
+    PyCdromProgress progress;
+    progress.setCallbackInst(pyCdromProgressInst);
 
-   string ident;
-   bool res = Cdrom.Ident(ident, &progress);
+    string ident;
+    bool res = Cdrom.Ident(ident, &progress);
 
-   PyObject *result = Py_BuildValue("(bs)", res, ident.c_str());
+    PyObject *result = Py_BuildValue("(bs)", res, ident.c_str());
 
-   return HandleErrors(result);
+    return HandleErrors(result);
 }
 #endif
 
-
-static PyMethodDef PkgCdromMethods[] =
-{
-   {"add",PkgCdromAdd,METH_VARARGS,"add(progress) -> Add a cdrom"},
-   {"ident",PkgCdromIdent,METH_VARARGS,"ident(progress) -> Ident a cdrom"},
+static PyMethodDef cdrom_methods[] = {
+    {"add",cdrom_add,METH_VARARGS,cdrom_add_doc},
+    {"ident",cdrom_ident,METH_VARARGS,cdrom_ident_doc},
 #ifdef COMPAT_0_7
-   {"Add",PkgCdromAdd,METH_VARARGS,"Add(progress) -> Add a cdrom"},
-   {"Ident",PkgCdromIdent_old,METH_VARARGS,"Ident(progress) -> Ident a cdrom"},
+    {"Add",cdrom_add,METH_VARARGS,"Add(progress) -> Add a cdrom"},
+    {"Ident",cdrom_ident_old,METH_VARARGS,"Ident(progress) -> Ident a cdrom"},
 #endif
-   {}
+    {}
 };
 
-
-static PyObject *PkgCdromNew(PyTypeObject *type,PyObject *Args,PyObject *kwds)
+static PyObject *cdrom_new(PyTypeObject *type,PyObject *Args,PyObject *kwds)
 {
-   pkgCdrom *cdrom = new pkgCdrom();
-
-   CppOwnedPyObject<pkgCdrom> *CdromObj =
-	   CppOwnedPyObject_NEW<pkgCdrom>(0,type, *cdrom);
-
-   return CdromObj;
+    return CppPyObject_NEW<pkgCdrom>(type);
 }
 
-
-PyTypeObject PyCdrom_Type =
-{
-   PyVarObject_HEAD_INIT(&PyType_Type, 0)
-   "apt_pkg.Cdrom",                     // tp_name
-   sizeof(CppOwnedPyObject<pkgCdrom>),   // tp_basicsize
-   0,                                   // tp_itemsize
-   // Methods
-   CppOwnedDealloc<pkgCdrom>,     // tp_dealloc
-   0,                                   // tp_print
-   0,                                   // tp_getattr
-   0,                                   // tp_setattr
-   0,                                   // tp_compare
-   0,                                   // tp_repr
-   0,                                   // tp_as_number
-   0,                                   // tp_as_sequence
-   0,	                                // tp_as_mapping
-   0,                                   // tp_hash
-   0,                                   // tp_call
-   0,                                   // tp_str
-   0,                                   // tp_getattro
-   0,                                   // tp_setattro
-   0,                                   // tp_as_buffer
-   (Py_TPFLAGS_DEFAULT |                // tp_flags
-    Py_TPFLAGS_BASETYPE),
-   "Cdrom Object",                      // tp_doc
-   0,                                   // tp_traverse
-   0,                                   // tp_clear
-   0,                                   // tp_richcompare
-   0,                                   // tp_weaklistoffset
-   0,                                   // tp_iter
-   0,                                   // tp_iternext
-   PkgCdromMethods,                     // 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
-   0,                                   // tp_alloc
-   PkgCdromNew,                         // tp_new
+static char *cdrom_doc =
+    "Cdrom()\n\n"
+    "Cdrom objects can be used to identify Debian installation media and to\n"
+    "add them to /etc/apt/sources.list.";
+PyTypeObject PyCdrom_Type = {
+    PyVarObject_HEAD_INIT(&PyType_Type, 0)
+    "apt_pkg.Cdrom",                     // tp_name
+    sizeof(CppPyObject<pkgCdrom>),       // tp_basicsize
+    0,                                   // tp_itemsize
+    // Methods
+    CppDealloc<pkgCdrom>,                // tp_dealloc
+    0,                                   // tp_print
+    0,                                   // tp_getattr
+    0,                                   // tp_setattr
+    0,                                   // tp_compare
+    0,                                   // tp_repr
+    0,                                   // tp_as_number
+    0,                                   // tp_as_sequence
+    0,                                 // tp_as_mapping
+    0,                                   // tp_hash
+    0,                                   // tp_call
+    0,                                   // tp_str
+    0,                                   // tp_getattro
+    0,                                   // tp_setattro
+    0,                                   // tp_as_buffer
+    Py_TPFLAGS_DEFAULT |                 // tp_flags
+    Py_TPFLAGS_BASETYPE,
+    cdrom_doc,                           // tp_doc
+    0,                                   // tp_traverse
+    0,                                   // tp_clear
+    0,                                   // tp_richcompare
+    0,                                   // tp_weaklistoffset
+    0,                                   // tp_iter
+    0,                                   // tp_iternext
+    cdrom_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
+    0,                                   // tp_alloc
+    cdrom_new,                           // tp_new
 };
 
 #ifdef COMPAT_0_7
 PyObject *GetCdrom(PyObject *Self,PyObject *Args)
 {
-   PyErr_WarnEx(PyExc_DeprecationWarning, "apt_pkg.GetCdrom() is deprecated. "
+    PyErr_WarnEx(PyExc_DeprecationWarning, "apt_pkg.GetCdrom() is deprecated. "
                  "Please see apt_pkg.Cdrom() for the replacement.", 1);
-   return PkgCdromNew(&PyCdrom_Type,Args,0);
+    return PkgCdromNew(&PyCdrom_Type,Args,0);
 }
 #endif
-
-
-
-
-									/*}}}*/