5 files changed, 304 insertions, 17 deletions

diff --git a/README.md b/README.md
index d1ae1ce..4f9be77 100644
--- a/README.md
+++ b/README.md
@@ -182,8 +182,14 @@ From here you can call the library functions directly, for example:
 'ASTUGFBH=DACXEZGBLIKF'
 ```
 
-Please note: as this is work in progress, not all functions are currently
-available from the Python module.
+Some methods have a different signature in the Pythn module than in
+libnissy: for example `solve()` returns the solutions as a list of
+strings instead of writing them to a return parameter buffer.
+You can access the documentation for the Python module from within
+a Python interpreter with `help(nissy)`. Cross-check this documentation
+with the comments in nissy.h for more details.
+
+Please note: the support for the Python module is still rudimentary.
 
 ## Cube formats
 
diff --git a/python/example.py b/python/example.py
new file mode 100644
index 0000000..fdea2d4
--- /dev/null
+++ b/python/example.py
@@ -0,0 +1,37 @@
+# Small example of nissy_python_module usage
+
+# Compile the python module with "make python", then run this from the main
+# folder containing nissy_python_module.so
+
+# Append the main folder to the python path so we can load the module
+from sys import path
+path.append("./")
+
+# Import with a nicer name
+import nissy_python_module as nissy
+
+# Choose the solver you prefer
+solver = "h48h0k4"
+
+# Load the pruning table from file
+data = bytearray(open("tables/" + solver, "rb").read())
+
+# If you have not generated the table yet, you can do so:
+# data = nissy.gendata("h48h0k4")
+
+# Get a scrambled cube
+cube = nissy.applymoves(nissy.solved_cube, "U F R2");
+
+# Solve!
+solutions = nissy.solve(cube, solver, nissy.nissflag_normal, 0, 9, 3, -1, data)
+
+# Print the solutions, one per line
+print("Found ", len(solutions), " solutions:")
+for s in solutions:
+        print(s)
+
+# You can use help(nissy) for more info about the available methods:
+# help(nissy)
+
+# Or help(nissy.methodname) if you want to know more about a specific method:
+# help(nissy.solve)
diff --git a/python/nissy_module.c b/python/nissy_module.c
index d02d9fc..2357b90 100644
--- a/python/nissy_module.c
+++ b/python/nissy_module.c
@@ -5,12 +5,17 @@
 #include "../src/nissy.h"
 
 #define MAX_CUBE_STR_LEN 1024 /* Update when adding formats */
+#define MAX_SOLUTIONS_SIZE 250000
 
 static bool
 check_error(long long err)
 {
         char err_string[255];
 
+        /* A positive value always denotes a success */
+        if (err > 0)
+                return true;
+
         switch (err) {
         case NISSY_OK: /* Fallthrough */
         case NISSY_WARNING_UNSOLVABLE:
@@ -58,6 +63,18 @@ long_result(long long result)
         return PyLong_FromLong(result);
 }
 
+
+PyDoc_STRVAR(compose_doc,
+"compose(cube, permutation)\n"
+"--\n\n"
+"Apply 'permutation' on 'cube'.\n"
+"\n"
+"Parameters:\n"
+"  - cube: a cube in B32 format\n"
+"  - permutation: another cube in B32 format\n"
+"\n"
+"Returns: the resulting cube string in B32 format\n"
+);
 static PyObject *
 compose(PyObject *self, PyObject *args)
 {
@@ -72,6 +89,16 @@ compose(PyObject *self, PyObject *args)
         return string_result(err, result);
 }
 
+PyDoc_STRVAR(inverse_doc,
+"inverse(cube)\n"
+"--\n\n"
+"Invert 'cube'.\n"
+"\n"
+"Parameters:\n"
+"  - cube: a cube in B32 format\n"
+"\n"
+"Returns: the inverse cube in B32 format\n"
+);
 static PyObject *
 inverse(PyObject *self, PyObject *args)
 {
@@ -86,6 +113,17 @@ inverse(PyObject *self, PyObject *args)
         return string_result(err, result);
 }
 
+PyDoc_STRVAR(applymoves_doc,
+"applymoves(cube, moves)\n"
+"--\n\n"
+"Apply 'moves' to 'cube'.\n"
+"\n"
+"Parameters:\n"
+"  - cube: a cube in B32 format\n"
+"  - moves: the moves to apply on the cube\n"
+"\n"
+"Returns: the resulting cube in B32 format\n"
+);
 static PyObject *
 applymoves(PyObject *self, PyObject *args)
 {
@@ -100,6 +138,19 @@ applymoves(PyObject *self, PyObject *args)
         return string_result(err, result);
 }
 
+PyDoc_STRVAR(applytrans_doc,
+"applytrans(cube, transformation)\n"
+"--\n\n"
+"Apply 'transformation' to 'cube'.\n"
+"\n"
+"Parameters:\n"
+"  - cube: a cube in B32 format\n"
+"  - transformation: the transformation to apply on the cube, formatted as\n"
+"    (rotation|mirrored) (2 letters)\n"
+"    for example 'mirrored ur' or 'rotation lf'\n"
+"\n"
+"Returns: the resulting cube in B32 format\n"
+);
 static PyObject *
 applytrans(PyObject *self, PyObject *args)
 {
@@ -114,6 +165,18 @@ applytrans(PyObject *self, PyObject *args)
         return string_result(err, result);
 }
 
+PyDoc_STRVAR(convert_doc,
+"convert(fin, fout, cube)\n"
+"--\n\n"
+"Convert 'cube' from format 'fin' to format 'fout'.\n"
+"\n"
+"Parameters:\n"
+"  - fin: the format in which 'cube' is given\n"
+"  - fout: the format to which 'cube' has to be converted\n"
+"  - cube: a cube in B32 format\n"
+"\n"
+"Returns: 'cube' in 'fout' format\n"
+);
 static PyObject *
 convert(PyObject *self, PyObject *args)
 {
@@ -128,6 +191,20 @@ convert(PyObject *self, PyObject *args)
         return string_result(err, result);
 }
 
+PyDoc_STRVAR(getcube_doc,
+"getcube(ep, eo, cp, co, options)\n"
+"--\n\n"
+"Constructs the cube from the given coordinates and options\n"
+"\n"
+"Parameters:\n"
+"  - ep: the edge permutation coordinate\n"
+"  - eo: the edge orientation coordinate\n"
+"  - cp: the corner permutation coordinate\n"
+"  - co: the corner orientation coordinate\n"
+"  - options: a string, for example \"fix\"\n"
+"\n"
+"Returns: the cube constructed from the given coordinates\n"
+);
 static PyObject *
 getcube(PyObject *self, PyObject *args)
 {
@@ -142,6 +219,16 @@ getcube(PyObject *self, PyObject *args)
         return string_result(err, result);
 }
 
+PyDoc_STRVAR(datasize_doc,
+"datasize(solver)\n"
+"--\n\n"
+"Returns the size of the data (pruning table) for the given solver\n"
+"\n"
+"Parameters:\n"
+"  - solver: the name of the solver\n"
+"\n"
+"Returns: the size of the data for the solver, in bytes\n"
+);
 static PyObject *
 datasize(PyObject *self, PyObject *args)
 {
@@ -155,23 +242,168 @@ datasize(PyObject *self, PyObject *args)
         return long_result(result);
 }
 
-/* TODO: gendata, checkdata and solve and countmoves */
+PyDoc_STRVAR(gendata_doc,
+"gendata(solver)\n"
+"--\n\n"
+"Generates the data (pruning table) for the given solver\n"
+"\n"
+"Parameters:\n"
+"  - solver: the name of the solver\n"
+"\n"
+"Returns: a bytearray containing the data for the solver\n"
+);
+static PyObject *
+gendata(PyObject *self, PyObject *args)
+{
+        long long size, err;
+        const char *solver;
+        char *buf;
+
+        if (!PyArg_ParseTuple(args, "s", &solver))
+                return NULL;
+
+        size = nissy_datasize(solver);
+        if (!check_error(size))
+                return NULL;
+
+        buf = PyMem_Malloc(size);
+
+        Py_BEGIN_ALLOW_THREADS
+        err = nissy_gendata(solver, size, buf);
+        Py_END_ALLOW_THREADS
+
+        if (check_error(err))
+                return PyByteArray_FromStringAndSize(buf, size);
+        else
+                return NULL;
+}
+
+PyDoc_STRVAR(checkdata_doc,
+"checkdata(data)\n"
+"--\n\n"
+"Checks if the data (pruning table) given is valid or not\n"
+"\n"
+"Parameters:\n"
+"  - data: a bytearray containing the data for a solver"
+"\n"
+"Returns: true if the data is valid, false otherwise\n"
+);
+PyObject *
+checkdata(PyObject *self, PyObject *args)
+{
+        long long result;
+        PyByteArrayObject *data;
+
+        if (!PyArg_ParseTuple(args, "Y", &data))
+                return NULL;
+
+        result = nissy_checkdata(data->ob_alloc, data->ob_bytes);
+
+        if (check_error(result))
+                return Py_True;
+        else
+                return Py_False;
+}
+
+PyDoc_STRVAR(solve_doc,
+"solve(cube, solver, nissflag, minmoves, maxmoves, maxsolutions, optimal, data)\n"
+"--\n\n"
+"Solves the given 'cube' with the given 'solver' and other parameters."
+"See the documentation for libnissy (in nissy.h) for details.\n"
+"\n"
+"Parameters:\n"
+"  - cube: a cube in B32 format\n"
+"  - solver: the solver to use\n"
+"  - minmoves: the minimum number of moves to use\n"
+"  - maxmoves: the maximum number of moves to use\n"
+"  - maxsolution: the maximum number of solutions to return\n"
+"  - optimal: the largest number of moves from the shortest solution"
+"(set to -1 to ignore)\n"
+"  - data: a bytearray containing the data for the solver\n"
+"\n"
+"Returns: a list with the solutions found\n"
+);
+PyObject *
+solve(PyObject *self, PyObject *args)
+{
+        long long result;
+        unsigned nissflag, minmoves, maxmoves, maxsolutions;
+        int optimal, i, j, k;
+        const char *cube, *solver;
+        char solutions[MAX_SOLUTIONS_SIZE];
+        long long stats[NISSY_SIZE_SOLVE_STATS];
+        PyByteArrayObject *data;
+        PyObject *list, *item;
+
+        if (!PyArg_ParseTuple(args, "ssIIIIiY", &cube, &solver, &nissflag,
+            &minmoves, &maxmoves, &maxsolutions, &optimal, &data))
+                return NULL;
+
+        Py_BEGIN_ALLOW_THREADS
+        result = nissy_solve(cube, solver, nissflag, minmoves, maxmoves,
+            maxsolutions, optimal, data->ob_alloc, data->ob_bytes,
+            MAX_SOLUTIONS_SIZE, solutions, stats);
+        Py_END_ALLOW_THREADS
+
+        if(!check_error(result)) {
+                return NULL;
+        } else {
+                list = PyList_New(result);
+                for (i = 0, j = 0, k = 0; solutions[i] != 0; i++) {
+                        if (solutions[i] != '\n')
+                                continue;
+                        solutions[i] = 0;
+                        item = PyUnicode_FromString(&solutions[k]);
+                        PyList_SetItem(list, j, item);
+                        j++;
+                        k = i+1;
+                }
+                return list;
+        }
+}
+
+PyDoc_STRVAR(countmoves_doc,
+"countmoves(moves)\n"
+"--\n\n"
+"Count the moves\n"
+"\n"
+"Parameters:\n"
+"  - moves: the moves to be counted\n"
+"\n"
+"Returns: the number of moves in HTM metric\n"
+);
+PyObject *
+countmoves(PyObject *self, PyObject *args)
+{
+        long long count;
+        const char *moves;
+
+        if (!PyArg_ParseTuple(args, "s", &moves))
+                return NULL;
+
+        count = nissy_countmoves(moves);
+        return long_result(count);
+}
 
 static PyMethodDef nissy_methods[] = {
-        { "compose", compose, METH_VARARGS, NULL },
-        { "inverse", inverse, METH_VARARGS, NULL },
-        { "applymoves", applymoves, METH_VARARGS, NULL },
-        { "applytrans", applytrans, METH_VARARGS, NULL },
-        { "convert", convert, METH_VARARGS, NULL },
-        { "getcube", getcube, METH_VARARGS, NULL },
-        { "datasize", datasize, METH_VARARGS, NULL },
+        { "compose", compose, METH_VARARGS, compose_doc },
+        { "inverse", inverse, METH_VARARGS, inverse_doc },
+        { "applymoves", applymoves, METH_VARARGS, applymoves_doc },
+        { "applytrans", applytrans, METH_VARARGS, applytrans_doc },
+        { "convert", convert, METH_VARARGS, convert_doc },
+        { "getcube", getcube, METH_VARARGS, getcube_doc },
+        { "datasize", datasize, METH_VARARGS, datasize_doc },
+        { "gendata", gendata, METH_VARARGS, gendata_doc },
+        { "checkdata", checkdata, METH_VARARGS, checkdata_doc },
+        { "solve", solve, METH_VARARGS, solve_doc },
+        { "countmoves", countmoves, METH_VARARGS, countmoves_doc },
         { NULL, NULL, 0, NULL }
 };
 
 static struct PyModuleDef nissy_python_module = {
         .m_base = PyModuleDef_HEAD_INIT,
         .m_name = "nissy",
-        .m_doc = NULL,
+        .m_doc = "python module for libnissy",
         .m_size = -1,
         .m_methods = nissy_methods,
         .m_slots = NULL,
@@ -195,7 +427,13 @@ PyMODINIT_FUNC PyInit_nissy_python_module(void) {
 
         nissy_setlogger(log_stdout);
         module = PyModule_Create(&nissy_python_module);
-        PyModule_AddStringConstant(module, "solvedcube", NISSY_SOLVED_CUBE);
+
+        PyModule_AddStringConstant(module, "solved_cube", NISSY_SOLVED_CUBE);
+        PyModule_AddIntConstant(module, "nissflag_normal", NISSY_NISSFLAG_NORMAL);
+        PyModule_AddIntConstant(module, "nissflag_inverse", NISSY_NISSFLAG_INVERSE);
+        PyModule_AddIntConstant(module, "nissflag_mixed", NISSY_NISSFLAG_MIXED);
+        PyModule_AddIntConstant(module, "nissflag_linear", NISSY_NISSFLAG_LINEAR);
+        PyModule_AddIntConstant(module, "nissflag_all", NISSY_NISSFLAG_ALL);
 
         return module;
 }
diff --git a/src/nissy.c b/src/nissy.c
index c5cf1d5..793d659 100644
--- a/src/nissy.c
+++ b/src/nissy.c
@@ -71,7 +71,10 @@ checkdata(const char *buf, const tableinfo_t *info)
 {
         uint64_t distr[INFO_DISTRIBUTION_LEN];
 
-        if (!strncmp(info->solver, "cocsep", 6)) {
+        if (info == NULL) {
+                LOG("checkdata: error reading table info\n");
+                return false;
+        } else if (!strncmp(info->solver, "cocsep", 6)) {
                 getdistribution_cocsep(
                     (uint32_t *)((char *)buf + INFOSIZE), distr);
         } else if (!strncmp(info->solver, "h48", 3)) {
@@ -442,21 +445,23 @@ nissy_checkdata(
 {
         char *buf;
         tableinfo_t info;
+        int64_t err;
 
         for (buf = (char *)data;
-             readtableinfo(data_size, buf, &info);
+             (err = readtableinfo(data_size, buf, &info)) == NISSY_OK;
              buf += info.next, data_size -= info.next)
         {
                 if (!checkdata(buf, &info)) {
-                        LOG("Error: data for %s is inconsistent with info!\n",
+                        LOG("Error: data for solver '%s' is corrupted!\n",
                             info.solver);
                         return NISSY_ERROR_DATA;
                 }
+
                 if (info.next == 0)
                         break;
         }
 
-        return NISSY_OK;
+        return err;
 }
 
 long long
diff --git a/src/solvers/tables.h b/src/solvers/tables.h
index 060b018..3147416 100644
--- a/src/solvers/tables.h
+++ b/src/solvers/tables.h
@@ -35,7 +35,8 @@ readtableinfo(uint64_t buf_size, const char *buf, tableinfo_t *info)
 
         if (buf_size < INFOSIZE) {
                 LOG("Error reading table: buffer size is too small "
-                    "(smaller than INFOSIZE = %" PRId64 ")\n", INFOSIZE);
+                    "(given size %" PRIu64 " is smaller than INFOSIZE = %"
+                    PRId64 ")\n", buf_size, INFOSIZE);
                 return NISSY_ERROR_BUFFER_SIZE;
         }