*.pyx: Add some rather laconic docstrings.

[mLib-python] / codec.pyx

diff --git a/codec.pyx b/codec.pyx
index 815e6b236bbcad80508c5fcb6789aee619a4e35c..1274afde2c8163074c296658eea99bd8b1522277 100644 (file)
--- a/codec.pyx
+++ b/codec.pyx
@@ -50,6 +50,7 @@ cdef extern from 'mLib/codec.h':
     CDCF_IGNEQMID
     CDCF_IGNZPAD
     CDCF_IGNNEWL
+    CDCF_IGNSPC
     CDCF_IGNINVCH
     CDCF_IGNJUNK
 
@@ -69,6 +70,7 @@ class CDCF:
   IGNEQMID = CDCF_IGNEQMID
   IGNZPAD = CDCF_IGNZPAD
   IGNNEWL = CDCF_IGNNEWL
+  IGNSPC = CDCF_IGNSPC
   IGNINVCH = CDCF_IGNINVCH
   IGNJUNK = CDCF_IGNJUNK
 
@@ -79,6 +81,11 @@ class CDCERR:
   INVZPAD = CDCERR_INVZPAD
 
 class CodecError (Exception):
+  """
+  Exception from decoding operation.
+
+  Attributes: err = CDCERR.* code, msg = message string
+  """
   def __init__(me, err):
     me.err = err
     me.msg = _codec_strerror(err)
@@ -86,6 +93,7 @@ class CodecError (Exception):
     return me.msg
 
 def codec_strerror(err):
+  """codec_strerror(ERR) -> STR: message for CDCERR.* code"""
   return _codec_strerror(err)
 
 cdef int code(codec *c, void *p, size_t len, dstr *d) except -1:
@@ -96,6 +104,7 @@ cdef int code(codec *c, void *p, size_t len, dstr *d) except -1:
   return 0
 
 cdef class _BaseCodec:
+  """Abstract superclass for codecs."""
   cdef codec *c
   def __cinit__(me, *hunoz, **hukairz):
     me.c = NULL
@@ -106,14 +115,14 @@ cdef class _BaseCodec:
       me.c.ops.destroy(me.c)
   cdef code(me, text, int finishp):
     cdef void *p
-    cdef int len
+    cdef Py_ssize_t len
     cdef dstr d
     cdef int err
     if me.c is NULL:
       raise ValueError, 'Encoding finished'
     DCREATE(&d)
     try:
-      PyObject_AsReadBuffer(text, &p, &len)
+      PyObject_AsReadBuffer(text, <cvp *>&p, &len)
       code(me.c, p, len, &d)
       if finishp:
         code(me.c, NULL, 0, &d)
@@ -123,14 +132,17 @@ cdef class _BaseCodec:
     finally:
       dstr_destroy(&d)
   def done(me):
+    """C.done() -> OUT: final output"""
     me.code('', True)
 
 cdef class _BaseEncoder (_BaseCodec):
   def encode(me, text, finishp = False):
+    """C.encode(IN, [finishp = False]) -> OUT: continue/finish encoding"""
     return me.code(text, finishp)
 
 cdef class _BaseDecoder (_BaseCodec):
   def decode(me, text, finishp = False):
+    """C.decode(IN, [finishp = False]) -> OUT: continue/finish decoding"""
     return me.code(text, finishp)
 
 ###--------------------------------------------------------------------------
@@ -142,26 +154,60 @@ cdef extern from 'mLib/base64.h':
   codec_class base64url_class
 
 cdef class Base64Encoder (_BaseEncoder):
+  """
+  Base64Encoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base64 encoder.
+  """
   def __init__(me, indent = '\n', maxline = 72, flags = CDCF_IGNJUNK):
     me.c = base64_class.encoder(flags, indent, maxline)
 
 cdef class Base64Decoder (_BaseDecoder):
+  """
+  Base64Decoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base64 decoder.
+  """
   def __init__(me, flags = CDCF_IGNJUNK):
     me.c = base64_class.decoder(flags)
 
 cdef class File64Encoder (_BaseEncoder):
+  """
+  File64Encoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base64 encoder, using `%' instead of `/', so encoded strings are safe as
+  filenames.
+  """
   def __init__(me, indent = '\n', maxline = 72, flags = CDCF_IGNJUNK):
     me.c = file64_class.encoder(flags, indent, maxline)
 
 cdef class File64Decoder (_BaseDecoder):
+  """
+  File64Decoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base64 encoder, using `%' instead of `/', so encoded strings are safe as
+  filenames.
+  """
   def __init__(me, flags = CDCF_IGNJUNK):
     me.c = file64_class.decoder(flags)
 
 cdef class Base64URLEncoder (_BaseEncoder):
+  """
+  Base64URLEncoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base64 encoder, using `-' and `_' instead of `+' and `/', so encoded
+  strings are safe as URL components.
+  """
   def __init__(me, indent = '\n', maxline = 72, flags = CDCF_IGNJUNK):
     me.c = base64url_class.encoder(flags, indent, maxline)
 
 cdef class Base64URLDecoder (_BaseDecoder):
+  """
+  Base64URLDecoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base64 decoder, using `-' and `_' instead of `+' and `/', so encoded
+  strings are safe as URL components.
+  """
   def __init__(me, flags = CDCF_IGNJUNK):
     me.c = base64url_class.decoder(flags)
 
@@ -173,18 +219,40 @@ cdef extern from 'mLib/base32.h':
   codec_class base32hex_class
 
 cdef class Base32Encoder (_BaseEncoder):
+  """
+  Base32Encoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base32 encoder.
+  """
   def __init__(me, indent = '\n', maxline = 72, flags = CDCF_IGNJUNK):
     me.c = base32_class.encoder(flags, indent, maxline)
 
 cdef class Base32Decoder (_BaseDecoder):
+  """
+  Base32Decoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base32 decoder.
+  """
   def __init__(me, flags = CDCF_IGNJUNK):
     me.c = base32_class.decoder(flags)
 
 cdef class Base32HexEncoder (_BaseEncoder):
+  """
+  Base32Encoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base32 encoder, using digits and letters in ascending order, rather than
+  avoiding digits which visually resemble letters.
+  """
   def __init__(me, indent = '\n', maxline = 72, flags = CDCF_IGNJUNK):
     me.c = base32hex_class.encoder(flags, indent, maxline)
 
 cdef class Base32HexDecoder (_BaseDecoder):
+  """
+  Base32Decoder([indent = '\\n'], [maxline = 72], [flags = CDCF.IGNJUNK])
+
+  Base32 decoder, using digits and letters in ascending order, rather than
+  avoiding digits which visually resemble letters.
+  """
   def __init__(me, flags = CDCF_IGNJUNK):
     me.c = base32hex_class.decoder(flags)
 
@@ -195,11 +263,23 @@ cdef extern from 'mLib/hex.h':
   codec_class hex_class
 
 cdef class HexEncoder (_BaseEncoder):
+  """
+  HexEncoder([indent = '\\n'], [maxline = 72],
+             [flags = CDCF.IGNJUNK | CDCF.LOWERC])
+
+  Hexadecimal encoder.
+  """
   def __init__(me, indent = '\n', maxline = 72,
                flags = CDCF_IGNJUNK | CDCF_LOWERC):
     me.c = hex_class.encoder(flags, indent, maxline)
 
 cdef class HexDecoder (_BaseDecoder):
+  """
+  HexDecoder([indent = '\\n'], [maxline = 72],
+             [flags = CDCF.IGNJUNK | CDCF.LOWERC])
+
+  Hexadecimal decoder.
+  """
   def __init__(me, flags = CDCF_IGNJUNK | CDCF_LOWERC):
     me.c = hex_class.decoder(flags)