X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/mLib-python/blobdiff_plain/704500e11c6a7e240acc047607d34bc6db520f15..c316167fdcbce41e8cc731e8c19cb00f53c1b9cd:/codec.pyx

diff --git a/codec.pyx b/codec.pyx
index b9f910f..1274afd 100644
--- a/codec.pyx
+++ b/codec.pyx
@@ -81,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)
@@ -88,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:
@@ -98,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
@@ -125,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)
 
 ###--------------------------------------------------------------------------
@@ -144,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)
 
@@ -175,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)
 
@@ -197,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)