chiark / gitweb /
rand.c: Show keyword argument as optional.
[catacomb-python] / rand.c
diff --git a/rand.c b/rand.c
index 54027370dc1be174e4f98e29f5c32dc889ea8718..b662fd53cd73ca384ab46e3399338784dbf21823 100644 (file)
--- a/rand.c
+++ b/rand.c
@@ -69,15 +69,25 @@ PyObject *grand_pywrap(grand *r, unsigned f)
 
 CONVFUNC(grand, grand *, GRAND_R)
 
+static int grand_check(PyObject *me)
+{
+  if (!GRAND_R(me)) VALERR("random generator object is no longer valid");
+  return (0);
+end:
+  return (-1);
+}
+
 static PyObject *grmeth_byte(PyObject *me, PyObject *arg)
 {
   if (!PyArg_ParseTuple(arg, ":byte")) return (0);
+  if (grand_check(me)) return (0);
   return (PyInt_FromLong(grand_byte(GRAND_R(me))));
 }
 
 static PyObject *grmeth_word(PyObject *me, PyObject *arg)
 {
   if (!PyArg_ParseTuple(arg, ":word")) return (0);
+  if (grand_check(me)) return (0);
   return (getulong(grand_word(GRAND_R(me))));
 }
 
@@ -88,6 +98,7 @@ static PyObject *grmeth_range(PyObject *me, PyObject *arg)
   mp *y = 0;
 
   if (!PyArg_ParseTuple(arg, "O:range", &m)) return (0);
+  if (grand_check(me)) return (0);
   if (PyInt_Check(m)) {
     long mm = PyInt_AS_LONG(m);
     if (mm <= 0)
@@ -113,11 +124,12 @@ static PyObject *grmeth_mp(PyObject *me, PyObject *arg, PyObject *kw)
 {
   size_t l;
   mpw o = 0;
-  char *kwlist[] = { "bits", "or", 0 };
+  static const char *const kwlist[] = { "bits", "or", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "O&|O&:mp", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "O&|O&:mp", KWLIST,
                                   convszt, &l, convmpw, &o))
     goto end;
+  if (grand_check(me)) return (0);
   if (l < MPW_BITS && (o >> l)) VALERR("or mask too large");
   return (mp_pywrap(mprand(MP_NEW, l, GRAND_R(me), o)));
 end:
@@ -130,6 +142,7 @@ static PyObject *grmeth_block(PyObject *me, PyObject *arg)
   PyObject *rc = 0;
 
   if (!PyArg_ParseTuple(arg, "O&:block", convulong, &n)) goto end;
+  if (grand_check(me)) return (0);
   rc = bytestring_pywrap(0, n);
   grand_fill(GRAND_R(me), PyString_AS_STRING(rc), n);
 end:
@@ -138,8 +151,7 @@ end:
 
 static int checkop(grand *r, unsigned op, const char *what)
 {
-  if (r->ops->misc(r, GRAND_CHECK, op))
-    return (0);
+  if (r->ops->misc(r, GRAND_CHECK, op)) return (0);
   PyErr_Format(PyExc_TypeError, "operation %s not supported", what);
   return (-1);
 }
@@ -149,7 +161,7 @@ static PyObject *grmeth_seedint(PyObject *me, PyObject *arg)
   int i;
   grand *r = GRAND_R(me);
   if (!PyArg_ParseTuple(arg, "i:seedint", &i) ||
-      checkop(r, GRAND_SEEDINT, "seedint"))
+      grand_check(me) || checkop(r, GRAND_SEEDINT, "seedint"))
     goto end;
   r->ops->misc(r, GRAND_SEEDINT, i);
   RETURN_ME;
@@ -162,7 +174,7 @@ static PyObject *grmeth_seedword(PyObject *me, PyObject *arg)
   uint32 u;
   grand *r = GRAND_R(me);
   if (!PyArg_ParseTuple(arg, "O&:seedword", convu32, &u) ||
-      checkop(r, GRAND_SEEDUINT32, "seedword"))
+      grand_check(me) || checkop(r, GRAND_SEEDUINT32, "seedword"))
     goto end;
   r->ops->misc(r, GRAND_SEEDUINT32, u);
   RETURN_ME;
@@ -176,7 +188,7 @@ static PyObject *grmeth_seedblock(PyObject *me, PyObject *arg)
   Py_ssize_t n;
   grand *r = GRAND_R(me);
   if (!PyArg_ParseTuple(arg, "s#:seedblock", &p, &n) ||
-      checkop(r, GRAND_SEEDBLOCK, "seedblock"))
+      grand_check(me) || checkop(r, GRAND_SEEDBLOCK, "seedblock"))
     goto end;
   r->ops->misc(r, GRAND_SEEDBLOCK, p, (size_t)n);
   RETURN_ME;
@@ -190,7 +202,7 @@ static PyObject *grmeth_seedmp(PyObject *me, PyObject *arg)
   mp *xx;
   grand *r = GRAND_R(me);
   if (!PyArg_ParseTuple(arg, "O:seedmp", &x) ||
-      checkop(r, GRAND_SEEDMP, "seedmp") ||
+      grand_check(me) || checkop(r, GRAND_SEEDMP, "seedmp") ||
       (xx = getmp(x)) == 0)
     goto end;
   r->ops->misc(r, GRAND_SEEDMP, xx);
@@ -202,12 +214,12 @@ end:
 
 static PyObject *grmeth_seedrand(PyObject *me, PyObject *arg, PyObject *kw)
 {
-  char *kwlist[] = { "rng", 0 };
+  static const char *const kwlist[] = { "rng", 0 };
   grand *r = GRAND_R(me);
   grand *rr = &rand_global;
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&:seedrand", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&:seedrand", KWLIST,
                                   convgrand, &rr) ||
-      checkop(r, GRAND_SEEDRAND, "seedrand"))
+      grand_check(me) || checkop(r, GRAND_SEEDRAND, "seedrand"))
     goto end;
   r->ops->misc(r, GRAND_SEEDRAND, rr);
   RETURN_ME;
@@ -223,6 +235,7 @@ static PyObject *grmeth_mask(PyObject *me, PyObject *arg)
   PyObject *rc;
 
   if (!PyArg_ParseTuple(arg, "s#:mask", &p, &sz)) return (0);
+  if (grand_check(me)) return (0);
   rc = bytestring_pywrap(0, sz);
   q = PyString_AS_STRING(rc);
   GR_FILL(r, q, sz);
@@ -233,16 +246,15 @@ static PyObject *grmeth_mask(PyObject *me, PyObject *arg)
 static void grand_pydealloc(PyObject *me)
 {
   grand_pyobj *g = (grand_pyobj *)me;
-  if (g->f & f_freeme)
-    GR_DESTROY(g->r);
+  if ((g->f & f_freeme) && g->r) GR_DESTROY(g->r);
   FREEOBJ(me);
 }
 
 static PyObject *grget_name(PyObject *me, void *hunoz)
-  { return (PyString_FromString(GRAND_R(me)->ops->name)); }
+  { return (grand_check(me) ? 0 : PyString_FromString(GRAND_R(me)->ops->name)); }
 
 static PyObject *grget_cryptop(PyObject *me, void *hunoz)
-  { return (getbool(GRAND_R(me)->ops->f & GRAND_CRYPTO)); }
+  { return (grand_check(me) ? 0 : getbool(GRAND_R(me)->ops->f & GRAND_CRYPTO)); }
 
 static PyGetSetDef grand_pygetset[] = {
 #define GETSETNAME(op, name) gr##op##_##name
@@ -320,8 +332,8 @@ static PyTypeObject grand_pytype_skel = {
 static PyObject *lcrand_pynew(PyTypeObject *me, PyObject *arg, PyObject *kw)
 {
   uint32 n = 0;
-  char *kwlist[] = { "seed", 0 };
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&:new", kwlist, convu32, &n))
+  static const char *const kwlist[] = { "seed", 0 };
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&:new", KWLIST, convu32, &n))
     return (0);
   return (grand_dopywrap(lcrand_pytype, lcrand_create(n), f_freeme));
 }
@@ -351,7 +363,7 @@ static PyTypeObject lcrand_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"Linear congruential generator.",
+"LCRand([seed = 0]): linear congruential generator.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -377,8 +389,8 @@ static PyTypeObject lcrand_pytype_skel = {
 static PyObject *fibrand_pynew(PyTypeObject *me, PyObject *arg, PyObject *kw)
 {
   uint32 n = 0;
-  char *kwlist[] = { "seed", 0 };
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&:new", kwlist, convu32, &n))
+  static const char *const kwlist[] = { "seed", 0 };
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&:new", KWLIST, convu32, &n))
     return (0);
   return (grand_dopywrap(fibrand_pytype, fibrand_create(n), f_freeme));
 }
@@ -408,7 +420,7 @@ static PyTypeObject fibrand_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"Fibonacci generator.",
+"FibRand([seed = 0]): Fibonacci generator.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -491,10 +503,10 @@ static PyObject *trmeth_timer(PyObject *me, PyObject *arg)
 static PyObject *truerand_pynew(PyTypeObject *ty,
                                PyObject *arg, PyObject *kw)
 {
-  char *kwlist[] = { 0 };
+  static const char *const kwlist[] = { 0 };
   grand *r;
   PyObject *rc = 0;
-  if (PyArg_ParseTupleAndKeywords(arg, kw, ":new", kwlist)) goto end;
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, ":new", KWLIST)) goto end;
   r = rand_create();
   r->ops->misc(r, RAND_NOISESRC, &noise_source);
   r->ops->misc(r, RAND_SEED, 160);
@@ -553,7 +565,7 @@ static PyTypeObject truerand_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"True random number source.",
+"TrueRand(): true random number source.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -583,6 +595,12 @@ static PyTypeObject *gccrand_pytype, *gcrand_pytype, *gclatinrand_pytype;
 typedef grand *gcrand_func(const void *, size_t sz);
 typedef grand *gcirand_func(const void *, size_t sz, uint32);
 typedef grand *gcnrand_func(const void *, size_t sz, const void *);
+typedef grand *gcshakerand_func(const void *, size_t,
+                               const void *, size_t,
+                               const void *, size_t);
+typedef grand *gcshafuncrand_func(const void *, size_t,
+                                 const void *, size_t);
+typedef grand *gckmacrand_func(const void *, size_t, const void *, size_t);
 typedef struct gccrand_info {
   const char *name;
   const octet *keysz;
@@ -621,11 +639,11 @@ static const gccrand_info *const gcrandtab[] = {
 static PyObject *gcrand_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
 {
   const gccrand_info *info = GCCRAND_INFO(ty);
-  static char *kwlist[] = { "key", 0 };
+  static const char *const kwlist[] = { "key", 0 };
   char *k;
   Py_ssize_t n;
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#:new", kwlist, &k, &n))
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#:new", KWLIST, &k, &n))
     goto end;
   if (keysz(n, info->keysz) != n) VALERR("bad key length");
   return (grand_dopywrap(ty, info->func(k, n), f_freeme));
@@ -637,11 +655,11 @@ static PyObject *gcirand_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
 {
   const gccrand_info *info = GCCRAND_INFO(ty);
   uint32 i = 0;
-  static char *kwlist[] = { "key", "i", 0 };
+  static const char *const kwlist[] = { "key", "i", 0 };
   char *k;
   Py_ssize_t n;
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#O&:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#O&:new", KWLIST,
                                   &k, &n, convu32, &i))
     goto end;
   if (keysz(n, info->keysz) != n) VALERR("bad key length");
@@ -655,11 +673,11 @@ end:
 static PyObject *gcnrand_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
 {
   const gccrand_info *info = GCCRAND_INFO(ty);
-  static char *kwlist[] = { "key", "nonce", 0 };
+  static const char *const kwlist[] = { "key", "nonce", 0 };
   char *k, *n;
   Py_ssize_t ksz, nsz;
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#:new", KWLIST,
                                   &k, &ksz, &n, &nsz))
     goto end;
   if (keysz(ksz, info->keysz) != ksz) VALERR("bad key length");
@@ -671,6 +689,37 @@ end:
   return (0);
 }
 
+static PyObject *gcshakyrand_pynew(PyTypeObject *ty,
+                                  PyObject *arg, PyObject *kw)
+{
+  const gccrand_info *info = GCCRAND_INFO(ty);
+  static const char
+    *const kwlist_shake[] = { "key", "func", "perso", 0 },
+    *const kwlist_func[] = { "key", "perso", 0 };
+  char *k, *f = 0, *p = 0;
+  Py_ssize_t ksz, fsz = 0, psz = 0;
+
+  if ((info->f&RNGF_MASK) == RNG_SHAKE
+       ? !PyArg_ParseTupleAndKeywords(arg, kw, "s#|s#s#:new",
+                                      (/*unconst*/ char **)kwlist_shake,
+                                      &k, &ksz, &f, &fsz, &p, &psz)
+       : !PyArg_ParseTupleAndKeywords(arg, kw, "s#|s#:new",
+                                      (/*unconst*/ char **)kwlist_func,
+                                      &k, &ksz, &p, &psz))
+    goto end;
+  if (keysz(ksz, info->keysz) != ksz) VALERR("bad key length");
+  return (grand_dopywrap(ty,
+                        (info->f&RNGF_MASK) == RNG_SHAKE
+                          ? ((gcshakerand_func *)info->func)(f, fsz,
+                                                             p, psz,
+                                                             k, ksz)
+                          : ((gcshafuncrand_func *)info->func)(p, psz,
+                                                               k, ksz),
+                        f_freeme));
+end:
+  return (0);
+}
+
 static PyObject *gccrand_pywrap(const gccrand_info *info)
 {
   gccrand_pyobj *g = newtype(gccrand_pytype, 0, info->name);
@@ -689,6 +738,8 @@ static PyObject *gccrand_pywrap(const gccrand_info *info)
   switch (info->f&RNGF_MASK) {
     case RNG_LATIN: g->ty.ht_type.tp_new = gcnrand_pynew; break;
     case RNG_SEAL: g->ty.ht_type.tp_new = gcirand_pynew; break;
+    case RNG_SHAKE: case RNG_KMAC:
+      g->ty.ht_type.tp_new = gcshakyrand_pynew; break;
     default: g->ty.ht_type.tp_new = gcrand_pynew; break;
   }
   typeready(&g->ty.ht_type);
@@ -890,9 +941,9 @@ static PyObject *sslprf_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
   int ksz, ssz;
   const gchash *hco = &md5, *hci = &sha;
   PyObject *rc = 0;
-  char *kwlist[] = { "key", "seed", "ohash", "ihash", 0 };
+  static const char *const kwlist[] = { "key", "seed", "ohash", "ihash", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#|O&O&:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#|O&O&:new", KWLIST,
                                   &k, &ksz, &s, &ssz,
                                   convgchash, &hco, convgchash, &hci))
     goto end;
@@ -907,9 +958,9 @@ static PyObject *tlsdx_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
   int ksz, ssz;
   const gcmac *mc = &sha_hmac;
   PyObject *rc = 0;
-  char *kwlist[] = { "key", "seed", "mac", 0 };
+  static const char *const kwlist[] = { "key", "seed", "mac", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#|O&:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#|O&:new", KWLIST,
                                   &k, &ksz, &s, &ssz,
                                   convgcmac, &mc))
     goto end;
@@ -924,9 +975,9 @@ static PyObject *tlsprf_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
   int ksz, ssz;
   const gcmac *mcl = &md5_hmac, *mcr = &sha_hmac;
   PyObject *rc = 0;
-  char *kwlist[] = { "key", "seed", "lmac", "rmac", 0 };
+  static const char *const kwlist[] = { "key", "seed", "lmac", "rmac", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#|O&O&:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#s#|O&O&:new", KWLIST,
                                   &k, &ksz, &s, &ssz,
                                   convgcmac, &mcl, convgcmac, &mcr))
     goto end;
@@ -960,7 +1011,8 @@ static PyTypeObject sslprf_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"Random number generator for SSL master secret.",
+"SSLRand(KEY, SEED, [ohash = md5], [ihash = sha]):\n\
+  RNG for SSL master secret.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -1008,7 +1060,8 @@ static PyTypeObject tlsdx_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"TLS data expansion function.",
+"TLSDataExpansion(KEY, SEED, [mac = sha_hmac]):\n\
+  TLS data expansion function.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -1056,7 +1109,8 @@ static PyTypeObject tlsprf_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"TLS pseudorandom function.",
+"TLSPRF(KEY, SEED, [lmac = md5_hmac], [rmac = sha_hmac]):\n\
+  TLS pseudorandom function.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -1086,9 +1140,9 @@ static PyObject *dsarand_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
   char *p;
   int sz;
   PyObject *rc = 0;
-  char *kwlist[] = { "seed", 0 };
+  static const char *const kwlist[] = { "seed", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#:new", kwlist, &p, &sz))
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "s#:new", KWLIST, &p, &sz))
     goto end;
   rc = grand_dopywrap(ty, dsarand_create(p, sz), f_freeme);
 end:
@@ -1136,7 +1190,7 @@ static PyTypeObject dsarand_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"Pseudorandom number generator for constructing DSA parameters.",
+"DSARand(SEED): pseudorandom number generator for DSA parameters.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -1165,9 +1219,9 @@ static PyObject *bbs_pynew(PyTypeObject *ty, PyObject *arg, PyObject *kw)
 {
   mp *n = 0, *x = MP_TWO;
   PyObject *rc = 0;
-  char *kwlist[] = { "n", "x", 0 };
+  static const char *const kwlist[] = { "n", "x", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "O&|O&:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "O&|O&:new", KWLIST,
                                   convmp, &n, convmp, &x))
     goto end;
   rc = grand_dopywrap(ty, bbs_rand(n, x), f_freeme);
@@ -1213,8 +1267,9 @@ static PyObject *bbsget_x(PyObject *me, void *hunoz)
 
 static int bbsset_x(PyObject *me, PyObject *val, void *hunoz)
 {
-  mp *x = 0; grand *r = GRAND_R(me); int rc = -1; if (!x) NIERR("__del__");
-  if ((x = getmp(val)) == 0) goto end; r->ops->misc(r, BBS_SET, x); rc = 0;
+  mp *x = 0; grand *r = GRAND_R(me); int rc = -1; if (!val) NIERR("__del__");
+  if ((x = getmp(val)) == 0) goto end;
+  r->ops->misc(r, BBS_SET, x); rc = 0;
   end: mp_drop(x); return (rc);
 }
 
@@ -1267,7 +1322,7 @@ static PyTypeObject bbs_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"Blum-Blum-Shub strong pseudorandom number generator.",
+"BlumBlumShub(N, [x = 2]): Blum-Blum-Shub pseudorandom number generator.",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -1302,9 +1357,9 @@ static PyObject *bbspriv_pynew(PyTypeObject *ty,
 {
   mp *p = 0, *q = 0, *n = 0, *x = MP_TWO;
   bbspriv_pyobj *rc = 0;
-  char *kwlist[] = { "n", "p", "q", "seed", 0 };
+  static const char *const kwlist[] = { "n", "p", "q", "seed", 0 };
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&O&O&O&:new", kwlist,
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "|O&O&O&O&:new", KWLIST,
                                   convmp, &n, convmp, &p, convmp, &q,
                                   convmp, &x))
     goto end;
@@ -1328,18 +1383,21 @@ static PyObject *meth__BBSPriv_generate(PyObject *me,
 {
   bbs_priv bp = { 0 };
   mp *x = MP_TWO;
-  pgev evt = { 0 };
+  struct excinfo exc = EXCINFO_INIT;
+  pypgev evt = { { 0 } };
   unsigned nbits, n = 0;
   grand *r = &rand_global;
-  char *kwlist[] = { "class", "nbits", "event", "rng", "nsteps", "seed", 0 };
+  static const char *const kwlist[] =
+    { "class", "nbits", "event", "rng", "nsteps", "seed", 0 };
   bbspriv_pyobj *rc = 0;
 
-  if (!PyArg_ParseTupleAndKeywords(arg, kw, "OO&|O&O&O&O&:generate", kwlist,
+  evt.exc = &exc;
+  if (!PyArg_ParseTupleAndKeywords(arg, kw, "OO&|O&O&O&O&:generate", KWLIST,
                                   &me, convuint, &nbits, convpgev, &evt,
                                   convgrand, &r, convuint, &n, convmp, &x))
     goto end;
-  if (bbs_gen(&bp, nbits, r, n, evt.proc, evt.ctx))
-    VALERR("prime genration failed");
+  if (bbs_gen(&bp, nbits, r, n, evt.ev.proc, evt.ev.ctx))
+    PGENERR(&exc);
   rc = PyObject_New(bbspriv_pyobj, bbspriv_pytype);
   rc->gr.r = bbs_rand(bp.n, x);
   rc->gr.f = f_freeme;
@@ -1425,7 +1483,8 @@ static PyTypeObject bbspriv_pytype_skel = {
     Py_TPFLAGS_BASETYPE,
 
   /* @tp_doc@ */
-"Blum-Blum-Shub strong pseudorandom generator, with private key.",
+"BBSPriv(..., [seed = 2]): Blum-Blum-Shub, with private key.\n\
+  Keywords: n, p, q; must provide at least two",
 
   0,                                   /* @tp_traverse@ */
   0,                                   /* @tp_clear@ */
@@ -1453,7 +1512,8 @@ static PyTypeObject bbspriv_pytype_skel = {
 static PyMethodDef methods[] = {
 #define METHNAME(name) meth_##name
   KWMETH(_BBSPriv_generate,            "\
-generate(NBITS, [event = pgen_nullev, rng = rand, nsteps = 0, seed = 2])")
+generate(NBITS, [event = pgen_nullev], [rng = rand],\n\
+        [nsteps = 0], [seed = 2]) -> R")
 #undef METHNAME
   { 0 }
 };