Updated the Python API for bitfields.

3 files changed, 153 insertions, 93 deletions

diff --git a/plugins/pychrysalide/common/bits.c b/plugins/pychrysalide/common/bits.c
index 236bcd6..73fd55b 100644
--- a/plugins/pychrysalide/common/bits.c
+++ b/plugins/pychrysalide/common/bits.c
@@ -47,9 +47,6 @@ static void py_bitfield_dealloc(py_bitfield_t *);
 /* Initialise un objet Python de type 'bitfield_t'. */
 static int py_bitfield_init(py_bitfield_t *, PyObject *, PyObject *);
 
-/* Crée une copie d'un champ de bits classique. */
-static PyObject *py_bitfield_dup(PyObject *, PyObject *);
-
 /* Effectue une opération de type 'and' avec le type 'bitfield'. */
 static PyObject *py_bitfield_nb_and(PyObject *, PyObject *);
 
@@ -65,6 +62,9 @@ static PyObject *py_bitfield_sequence_item(PyObject *, Py_ssize_t);
 /* Effectue une comparaison avec un objet Python 'bitfield'. */
 static PyObject *py_bitfield_richcompare(PyObject *, PyObject *, int);
 
+/* Crée une copie d'un champ de bits classique. */
+static PyObject *py_bitfield_dup(PyObject *, PyObject *);
+
 /* Bascule à 0 un champ de bits dans son intégralité. */
 static PyObject *py_bitfield_reset_all(PyObject *, PyObject *);
 
@@ -90,7 +90,7 @@ static PyObject *py_bitfield_test_all(PyObject *, PyObject *);
 static PyObject *py_bitfield_get_size(PyObject *, void *);
 
 /* Détermine le nombre de bits à 1 dans un champ. */
-static PyObject *py_bitfield_popcount(PyObject *, void *);
+static PyObject *py_bitfield_get_popcount(PyObject *, void *);
 
 
 
@@ -136,6 +136,17 @@ static int py_bitfield_init(py_bitfield_t *self, PyObject *args, PyObject *kwds)
     int state;                              /* Initialisation par défaut   */
     int ret;                                /* Bilan de lecture des args.  */
 
+#define BITFIELD_DOC                                                \
+    "The BitField object describes a group of bits and provides"    \
+    " operations on it.\n"                                          \
+    "\n"                                                            \
+    "Instances can be created using the following constructor:\n"   \
+    "\n"                                                            \
+    "    BitField(length, state)"                                   \
+    "\n"                                                            \
+    "Where *length* is the size of the bitfield and *state*"        \
+    " defines the initial state of each bits."                      \
+
     result = -1;
 
     ret = PyArg_ParseTuple(args, "kp", &length, &state);
@@ -154,33 +165,6 @@ static int py_bitfield_init(py_bitfield_t *self, PyObject *args, PyObject *kwds)
 
 /******************************************************************************
 *                                                                             *
-*  Paramètres  : self = champ de bits à dupliquer.                            *
-*                args = non utilisé ici.                                      *
-*                                                                             *
-*  Description : Crée une copie d'un champ de bits classique.                 *
-*                                                                             *
-*  Retour      : Champ de bits mis en place.                                  *
-*                                                                             *
-*  Remarques   : -                                                            *
-*                                                                             *
-******************************************************************************/
-
-static PyObject *py_bitfield_dup(PyObject *self, PyObject *args)
-{
-    PyObject *result;                       /* Instance à retourner        */
-    py_bitfield_t *bf;                      /* Instance à manipuler        */
-
-    bf = (py_bitfield_t *)self;
-
-    result = build_from_internal_bitfield(bf->native);;
-
-    return result;
-
-}
-
-
-/******************************************************************************
-*                                                                             *
 *  Paramètres  : o1 = premier élément concerné par l'opération.               *
 *                o2 = second élément concerné par l'opération.                *
 *                                                                             *
@@ -378,6 +362,43 @@ static PyObject *py_bitfield_richcompare(PyObject *a, PyObject *b, int op)
 
 /******************************************************************************
 *                                                                             *
+*  Paramètres  : self = champ de bits à dupliquer.                            *
+*                args = non utilisé ici.                                      *
+*                                                                             *
+*  Description : Crée une copie d'un champ de bits classique.                 *
+*                                                                             *
+*  Retour      : Champ de bits mis en place.                                  *
+*                                                                             *
+*  Remarques   : -                                                            *
+*                                                                             *
+******************************************************************************/
+
+static PyObject *py_bitfield_dup(PyObject *self, PyObject *args)
+{
+    PyObject *result;                       /* Instance à retourner        */
+    py_bitfield_t *bf;                      /* Instance à manipuler        */
+
+#define BITFIELD_DUP_METHOD PYTHON_METHOD_DEF                           \
+(                                                                       \
+    dup, "$self, /",                                                    \
+    METH_NOARGS, py_bitfield,                                           \
+    "Duplicate a bitfield.\n"                                           \
+    "\n"                                                                \
+    "The result is a new pychrysalide.common.BitField with the same"    \
+    " content."                                                         \
+)
+
+    bf = (py_bitfield_t *)self;
+
+    result = build_from_internal_bitfield(bf->native);;
+
+    return result;
+
+}
+
+
+/******************************************************************************
+*                                                                             *
 *  Paramètres  : self = champ de bits à modifier.                             *
 *                args = non utilisé ici.                                      *
 *                                                                             *
@@ -393,6 +414,13 @@ static PyObject *py_bitfield_reset_all(PyObject *self, PyObject *args)
 {
     py_bitfield_t *bf;                      /* Instance à manipuler        */
 
+#define BITFIELD_RESET_ALL_METHOD PYTHON_METHOD_DEF \
+(                                                   \
+    reset_all, "$self, /",                          \
+    METH_NOARGS, py_bitfield,                       \
+    "Switch to 0 all bits in a bitfield."           \
+)
+
     bf = (py_bitfield_t *)self;
 
     reset_all_in_bit_field(bf->native);
@@ -419,6 +447,13 @@ static PyObject *py_bitfield_set_all(PyObject *self, PyObject *args)
 {
     py_bitfield_t *bf;                      /* Instance à manipuler        */
 
+#define BITFIELD_SET_ALL_METHOD PYTHON_METHOD_DEF   \
+(                                                   \
+    set_all, "$self, /",                            \
+    METH_NOARGS, py_bitfield,                       \
+    "Switch to 1 all bits in a bitfield."           \
+)
+
     bf = (py_bitfield_t *)self;
 
     set_all_in_bit_field(bf->native);
@@ -448,6 +483,16 @@ static PyObject *py_bitfield_reset(PyObject *self, PyObject *args)
     int ret;                                /* Bilan de lecture des args.  */
     py_bitfield_t *bf;                      /* Instance à manipuler        */
 
+#define BITFIELD_RESET_METHOD PYTHON_METHOD_DEF             \
+(                                                           \
+    reset, "$self, first, count, /",                        \
+    METH_VARARGS, py_bitfield,                              \
+    "Switch to 0 a part of bits in a bitfield.\n"           \
+    "\n"                                                    \
+    "The area to process starts at bit *first* and has a"   \
+    " size of *count* bits."                                \
+)
+
     ret = PyArg_ParseTuple(args, "kk", &first, &count);
     if (!ret) return NULL;
 
@@ -480,6 +525,16 @@ static PyObject *py_bitfield_set(PyObject *self, PyObject *args)
     int ret;                                /* Bilan de lecture des args.  */
     py_bitfield_t *bf;                      /* Instance à manipuler        */
 
+#define BITFIELD_SET_METHOD PYTHON_METHOD_DEF               \
+(                                                           \
+    set, "$self, first, count, /",                          \
+    METH_VARARGS, py_bitfield,                              \
+    "Switch to 1 a part of bits in a bitfield.\n"           \
+    "\n"                                                    \
+    "The area to process starts at bit *first* and has a"   \
+    " size of *count* bits."                                \
+)
+
     ret = PyArg_ParseTuple(args, "kk", &first, &count);
     if (!ret) return NULL;
 
@@ -513,6 +568,16 @@ static PyObject *py_bitfield_test(PyObject *self, PyObject *args)
     py_bitfield_t *bf;                      /* Instance à manipuler        */
     bool status;                            /* Bilan d'analyse             */
 
+#define BITFIELD_TEST_METHOD PYTHON_METHOD_DEF              \
+(                                                           \
+    test, "$self, n, /",                                    \
+    METH_VARARGS, py_bitfield,                              \
+    "Test if a given bit is set in a bitfield.\n"           \
+    "\n"                                                    \
+    "The result is a boolean value: True if the tested"     \
+    " *n* bit is set, False otherwise."                     \
+)
+
     ret = PyArg_ParseTuple(args, "k", &n);
     if (!ret) return NULL;
 
@@ -521,7 +586,6 @@ static PyObject *py_bitfield_test(PyObject *self, PyObject *args)
     status = test_in_bit_field(bf->native, n);
 
     result = status ? Py_True : Py_False;
-
     Py_INCREF(result);
 
     return result;
@@ -551,6 +615,19 @@ static PyObject *py_bitfield_test_none(PyObject *self, PyObject *args)
     py_bitfield_t *bf;                      /* Instance à manipuler        */
     bool status;                            /* Bilan d'analyse             */
 
+#define BITFIELD_TEST_NONE_METHOD PYTHON_METHOD_DEF         \
+(                                                           \
+    test_none, "$self, first, count, /",                    \
+    METH_VARARGS, py_bitfield,                              \
+    "Test a range of bits against 0.\n"                     \
+    "\n"                                                    \
+    "The area to process starts at bit *first* and has a"   \
+    " size of *count* bits."                                \
+    "\n"                                                    \
+    "The result is a boolean value: True if all tested"     \
+    " bits are unset, False otherwise."                     \
+)
+
     ret = PyArg_ParseTuple(args, "kk", &first, &count);
     if (!ret) return NULL;
 
@@ -559,7 +636,6 @@ static PyObject *py_bitfield_test_none(PyObject *self, PyObject *args)
     status = test_none_in_bit_field(bf->native, first, count);
 
     result = status ? Py_True : Py_False;
-
     Py_INCREF(result);
 
     return result;
@@ -589,6 +665,19 @@ static PyObject *py_bitfield_test_all(PyObject *self, PyObject *args)
     py_bitfield_t *bf;                      /* Instance à manipuler        */
     bool status;                            /* Bilan d'analyse             */
 
+#define BITFIELD_TEST_ALL_METHOD PYTHON_METHOD_DEF          \
+(                                                           \
+    test_all, "$self, first, count, /",                     \
+    METH_VARARGS, py_bitfield,                              \
+    "Test a range of bits against 1.\n"                     \
+    "\n"                                                    \
+    "The area to process starts at bit *first* and has a"   \
+    " size of *count* bits."                                \
+    "\n"                                                    \
+    "The result is a boolean value: True if all tested"     \
+    " bits are set, False otherwise."                       \
+)
+
     ret = PyArg_ParseTuple(args, "kk", &first, &count);
     if (!ret) return NULL;
 
@@ -597,7 +686,6 @@ static PyObject *py_bitfield_test_all(PyObject *self, PyObject *args)
     status = test_all_in_bit_field(bf->native, first, count);
 
     result = status ? Py_True : Py_False;
-
     Py_INCREF(result);
 
     return result;
@@ -624,6 +712,12 @@ static PyObject *py_bitfield_get_size(PyObject *self, void *closure)
     py_bitfield_t *bf;                      /* Instance à manipuler        */
     size_t size;                            /* Taille du champs de bits    */
 
+#define BITFIELD_SIZE_ATTRIB PYTHON_GET_DEF_FULL    \
+(                                                   \
+    size, py_bitfield,                              \
+    "Provide the size of the bitfield."             \
+)
+
     bf = (py_bitfield_t *)self;
 
     size = get_bit_field_size(bf->native);
@@ -648,12 +742,18 @@ static PyObject *py_bitfield_get_size(PyObject *self, void *closure)
 *                                                                             *
 ******************************************************************************/
 
-static PyObject *py_bitfield_popcount(PyObject *self, void *closure)
+static PyObject *py_bitfield_get_popcount(PyObject *self, void *closure)
 {
     PyObject *result;                       /* Conversion à retourner      */
     py_bitfield_t *bf;                      /* Instance à manipuler        */
     size_t count;                           /* Quantité de bits à 1        */
 
+#define BITFIELD_POPCOUNT_ATTRIB PYTHON_GET_DEF_FULL    \
+(                                                       \
+    popcount, py_bitfield,                              \
+    "Get the number of bits set to 1 in the bitfield."  \
+)
+
     bf = (py_bitfield_t *)self;
 
     count = popcount_for_bit_field(bf->native);
@@ -680,10 +780,8 @@ static PyObject *py_bitfield_popcount(PyObject *self, void *closure)
 PyTypeObject *get_python_bitfield_type(void)
 {
     static PyNumberMethods py_bitfield_nb_proto = {
-
         .nb_and = py_bitfield_nb_and,
         .nb_or  = py_bitfield_nb_or
-
     };
 
     static PySequenceMethods py_bitfield_sequence_proto = {
@@ -692,58 +790,20 @@ PyTypeObject *get_python_bitfield_type(void)
     };
 
     static PyMethodDef py_bitfield_methods[] = {
-        {
-            "dup", py_bitfield_dup,
-            METH_NOARGS,
-            "dup(self, /)\n--\n\nDuplicate a bitfield."
-        },
-        {
-            "reset_all", py_bitfield_reset_all,
-            METH_NOARGS,
-            "reset_all(self, /)\n--\n\nSwitch to 0 all bits in a bitfield."
-        },
-        {
-            "set_all", py_bitfield_set_all,
-            METH_NOARGS,
-            "set_all(self, /)\n--\n\nSwitch to 1 all bits in a bitfield."
-        },
-        {
-            "reset", py_bitfield_reset,
-            METH_VARARGS,
-            "reset(self, first, count, /)\n--\n\nSwitch to 0 a part of bits in a bitfield."
-        },
-        {
-            "set", py_bitfield_set,
-            METH_VARARGS,
-            "set(self, first, count, /)\n--\n\nSwitch to 1 a part of bits in a bitfield."
-        },
-        {
-            "test", py_bitfield_test,
-            METH_VARARGS,
-            "test(self, n, /)\n--\n\nTest if a given bit is set in a bitfield."
-        },
-        {
-            "test_none", py_bitfield_test_none,
-            METH_VARARGS,
-            "test_none(self, first, count, /)\n--\n\nTest a range of bits to 0."
-        },
-        {
-            "test_all", py_bitfield_test_all,
-            METH_VARARGS,
-            "test_all(self, first, count, /)\n--\n\nTest a range of bits to 1."
-        },
+        BITFIELD_DUP_METHOD,
+        BITFIELD_RESET_ALL_METHOD,
+        BITFIELD_SET_ALL_METHOD,
+        BITFIELD_RESET_METHOD,
+        BITFIELD_SET_METHOD,
+        BITFIELD_TEST_METHOD,
+        BITFIELD_TEST_NONE_METHOD,
+        BITFIELD_TEST_ALL_METHOD,
         { NULL }
     };
 
     static PyGetSetDef py_bitfield_getseters[] = {
-        {
-            "size", py_bitfield_get_size, NULL,
-            "Provide the size of the bitfield.", NULL
-        },
-        {
-            "popcount", py_bitfield_popcount, NULL,
-            "Get the number of bits set to 1 in the bitfield.", NULL
-        },
+        BITFIELD_SIZE_ATTRIB,
+        BITFIELD_POPCOUNT_ATTRIB,
         { NULL }
     };
 
@@ -751,7 +811,7 @@ PyTypeObject *get_python_bitfield_type(void)
 
         PyVarObject_HEAD_INIT(NULL, 0)
 
-        .tp_name        = "pychrysalide.common.bitfield",
+        .tp_name        = "pychrysalide.common.BitField",
         .tp_basicsize   = sizeof(py_bitfield_t),
 
         .tp_dealloc     = (destructor)py_bitfield_dealloc,
@@ -761,7 +821,7 @@ PyTypeObject *get_python_bitfield_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT,
 
-        .tp_doc         = "Python object for bitfield_t.",
+        .tp_doc         = BITFIELD_DOC,
 
         .tp_richcompare = py_bitfield_richcompare,
 
@@ -782,7 +842,7 @@ PyTypeObject *get_python_bitfield_type(void)
 *                                                                             *
 *  Paramètres  : module = module dont la définition est à compléter.          *
 *                                                                             *
-*  Description : Prend en charge l'objet 'pychrysalide.common.bitfield'.      *
+*  Description : Prend en charge l'objet 'pychrysalide.common.BitField'.      *
 *                                                                             *
 *  Retour      : Bilan de l'opération.                                        *
 *                                                                             *
@@ -818,7 +878,7 @@ bool ensure_python_bitfield_is_registered(void)
 *                                                                             *
 *  Paramètres  : field = structure interne à copier en objet Python.          *
 *                                                                             *
-*  Description : Convertit une structure de type 'bitfield' en objet Python.  *
+*  Description : Convertit une structure de type 'bitfield_t' en objet Python.*
 *                                                                             *
 *  Retour      : Object Python résultant de la conversion opérée.             *
 *                                                                             *
diff --git a/plugins/pychrysalide/common/bits.h b/plugins/pychrysalide/common/bits.h
index 4a3b90b..6ddaaa5 100644
--- a/plugins/pychrysalide/common/bits.h
+++ b/plugins/pychrysalide/common/bits.h
@@ -37,10 +37,10 @@
 /* Fournit un accès à une définition de type à diffuser. */
 PyTypeObject *get_python_bitfield_type(void);
 
-/* Prend en charge l'objet 'pychrysalide.common.bitfield'. */
+/* Prend en charge l'objet 'pychrysalide.common.BitField'. */
 bool ensure_python_bitfield_is_registered(void);
 
-/* Convertit une structure de type 'bitfield' en objet Python. */
+/* Convertit une structure de type 'bitfield_t' en objet Python. */
 PyObject *build_from_internal_bitfield(const bitfield_t *);
 
 
diff --git a/plugins/pychrysalide/common/packed.c b/plugins/pychrysalide/common/packed.c
index c7fa296..405e241 100644
--- a/plugins/pychrysalide/common/packed.c
+++ b/plugins/pychrysalide/common/packed.c
@@ -112,8 +112,8 @@ static int py_packed_buffer_init(py_packed_buffer_t *self, PyObject *args, PyObj
     int result;                             /* Bilan à retourner           */
 
 #define PACKED_BUFFER_DOC                                               \
-    "The PackedBuffer is mainly used as helper for the storage of GLib" \
-    " objects over the network or into files.\n"                        \
+    "The PackedBuffer object is mainly used as helper for the storage"  \
+    " of GLib objects over the network or into files.\n"                \
     "\n"                                                                \
     "The same kind of features as the Python *struct* module are"       \
     " provided to store and retrieve data.\n"                           \