From 6a1e046b70ed20e46107010641f8fc00c6c4f33f Mon Sep 17 00:00:00 2001
From: Fredrik Tolf <fredrik@dolda2000.com>
Date: Wed, 29 Feb 2012 08:56:25 +0100
Subject: [PATCH] Documented the behavior of the basic library classes.

---
 manga/lib.py      | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 manga/mangafox.py |  6 -----
 2 files changed, 74 insertions(+), 9 deletions(-)

diff --git a/manga/lib.py b/manga/lib.py
index 7988438..b5d13c1 100644
--- a/manga/lib.py
+++ b/manga/lib.py
@@ -1,14 +1,85 @@
 class library(object):
-    pass
+    """Class representing a single source of multiple mangas."""
+    
+    def byname(self, prefix):
+        """Returns an iterable object of all mangas in this library
+        whose names (case-insensitively) begin with the given
+        prefix.
+
+        All libraries should implement this."""
+        raise NotImplementedError()
+
+    def __iter__(self):
+        """Return an iterator of all known mangas in this library.
+
+        Not all libraries need implement this."""
+        raise NotImplementedError("manga.lib.library iterator")
 
 class pagelist(object):
-    pass
+    """Class representing a list of either pages, or nested
+    pagelists. Might be, for instance, a volume or a chapter.
+
+    All pagelists should contain an attribute `name', containing some
+    human-readable Unicode representation of the pagelist."""
+
+    def __len__(self):
+        """Return the number of (direct) sub-nodes in this pagelist.
+
+        All pagelists need to implement this."""
+        raise NotImplementedError()
+
+    def __getitem__(self, idx):
+        """Return the direct sub-node of the given index in this
+        pagelist. Sub-node indexes are always zero-based and
+        contiguous, regardless of any gaps in the underlying medium,
+        which should be indicated instead by way of the `name'
+        attribute.
+
+        All pagelists need to implement this."""
+        raise NotImplementedError()
 
 class manga(pagelist):
+    """Class reprenting a single manga. Includes the pagelist class,
+    and all constraints valid for it."""
     pass
 
 class page(object):
-    pass
+    """Class representing a single page of a manga. Pages make up the
+    leaf nodes of a pagelist tree.
+
+    All pages should contain an attribute `manga', referring back to
+    the containing manga instance."""
+    
+    def open(self):
+        """Open a stream for the image this page represents. The
+        returned object should be an imgstream class.
+
+        All pages need to implement this."""
+        raise NotImplementedError()
+
+class imgstream(object):
+    """An open image I/O stream for a manga page. Generally, it should
+    be file-like. This base class implements the resource-manager
+    interface for use in `with' statements, calling close() on itself
+    when exiting the with-scope.
+
+    All imgstreams should contain an attribute `ctype', being the
+    Content-Type of the image being read by the stream."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc_info):
+        self.close()
+
+    def close(self):
+        """Close this stream."""
+        raise NotImplementedError()
+
+    def read(self, sz = None):
+        """Read SZ bytes from the stream, or the entire rest of the
+        stream of SZ is not given."""
+        raise NotImplementedError()
 
 class pageiter(object):
     def __init__(self, root):
diff --git a/manga/mangafox.py b/manga/mangafox.py
index b0a4aee..302edc5 100644
--- a/manga/mangafox.py
+++ b/manga/mangafox.py
@@ -11,12 +11,6 @@ class imgstream(object):
     def close(self):
         self.bk.close()
 
-    def __enter__(self):
-        return self
-
-    def __exit__(self, *exc_info):
-        self.close()
-
     def read(self, sz = None):
         if sz is None:
             return self.bk.read()
-- 
2.11.0