Improved mangafox, probably.
[automanga.git] / manga / lib.py
1 class library(object):
2     """Class representing a single source of multiple mangas."""
3     
4     def byname(self, prefix):
5         """Returns an iterable object of all mangas in this library
6         whose names (case-insensitively) begin with the given
7         prefix.
8
9         All libraries should implement this."""
10         raise NotImplementedError()
11
12     def search(self, string):
13         """Returns an iterable object of mangas in this library that
14         matches the search string in a library-dependent manner. While
15         each library is at liberty to define its own matching
16         criteria, it is probably likely to involve something akin to
17         searching for keywords in the titles of the library.
18
19         Searching may return very many results and may be slow to
20         iterate.
21
22         Not all libraries need implement this."""
23         raise NotImplementedError()
24
25     def byid(self, id):
26         """Returns a previously known manga by its string ID, or
27         raises KeyError if no such manga could be found.
28
29         All libraries should implement this."""
30         raise KeyError(id)
31
32     def __iter__(self):
33         """Return an iterator of all known mangas in this library.
34
35         Not all libraries need implement this."""
36         raise NotImplementedError("manga.lib.library iterator")
37
38 class pagetree(object):
39     """Base class for objects in the tree of pages and pagelists.
40
41     All pagetree objects should contain an attribute `stack',
42     containing a list of pairs. The last pair in the list should be
43     the pagetree object which yielded this pagetree object, along with
44     the index which yielded it. Every non-last pair should be the same
45     information for the pair following it. The only objects with empty
46     `stack' lists should be `manga' objects.
47     
48     All non-root pagetree objects should also contain an attribute
49     `id', which should be a string that can be passed to the `byid'
50     function of its parent node to recover the node. Such string ID
51     should be more persistent than the node's numeric index in the
52     parent.
53
54     All pagetree objects should contain an attribute `name',
55     containing some human-readable Unicode representation of the
56     pagelist."""
57     
58     def idlist(self):
59         """Returns a list of the IDs necessary to resolve this node
60         from the root node."""
61         if len(self.stack) == 0:
62             return []
63         return self.stack[-1][0].idlist() + [self.id]
64
65     def byidlist(self, idlist):
66         if len(idlist) == 0:
67             return self
68         return self.byid(idlist[0]).byidlist(idlist[1:])
69
70 class pagelist(pagetree):
71     """Class representing a list of either pages, or nested
72     pagelists. Might be, for instance, a volume or a chapter."""
73
74     def __len__(self):
75         """Return the number of (direct) sub-nodes in this pagelist.
76
77         All pagelists need to implement this."""
78         raise NotImplementedError()
79
80     def __getitem__(self, idx):
81         """Return the direct sub-node of the given index in this
82         pagelist. Sub-node indexes are always zero-based and
83         contiguous, regardless of any gaps in the underlying medium,
84         which should be indicated instead by way of the `name'
85         attribute.
86
87         All pagelists need to implement this."""
88         raise NotImplementedError()
89
90     def byid(self, id):
91         """Return the direct sub-node of this pagelist which has the
92         given string ID. If none is found, a KeyError is raised.
93
94         This default method iterates the children of this node, but
95         may be overridden by some more efficient implementation.
96         """
97         for ch in self:
98             if ch.id == id:
99                 return ch
100         raise KeyError(id)
101
102 class manga(pagelist):
103     """Class reprenting a single manga. Includes the pagelist class,
104     and all constraints valid for it.
105
106     A manga is a root pagetree node, but should also contain an `id'
107     attribute, which can be used to recover the manga from its
108     library's `byid' function."""
109     pass
110
111 class page(pagetree):
112     """Class representing a single page of a manga. Pages make up the
113     leaf nodes of a pagelist tree.
114
115     All pages should contain an attribute `manga', referring back to
116     the containing manga instance."""
117     
118     def open(self):
119         """Open a stream for the image this page represents. The
120         returned object should be an imgstream class.
121
122         All pages need to implement this."""
123         raise NotImplementedError()
124
125 class imgstream(object):
126     """An open image I/O stream for a manga page. Generally, it should
127     be file-like. This base class implements the resource-manager
128     interface for use in `with' statements, calling close() on itself
129     when exiting the with-scope.
130
131     All imgstreams should contain an attribute `ctype', being the
132     Content-Type of the image being read by the stream, and `clen`,
133     being either an int describing the total number of bytes in the
134     stream, or None if the value is not known in advance."""
135
136     def __enter__(self):
137         return self
138
139     def __exit__(self, *exc_info):
140         self.close()
141
142     def fileno(self):
143         """If reading the imgstream may block, fileno() should return
144         a file descriptor that can be polled. If fileno() returns
145         None, that should mean that reading will not block."""
146         return None
147
148     def close(self):
149         """Close this stream."""
150         raise NotImplementedError()
151
152     def read(self, sz = None):
153         """Read SZ bytes from the stream, or the entire rest of the
154         stream of SZ is not given."""
155         raise NotImplementedError()
156
157 class cursor(object):
158     def __init__(self, ob):
159         if isinstance(ob, cursor):
160             self.cur = ob.cur
161         else:
162             self.cur = self.descend(ob)
163
164     def descend(self, ob, last=False):
165         while isinstance(ob, pagelist):
166             ob = ob[len(ob) - 1 if last else 0]
167         if not isinstance(ob, page):
168             raise TypeError("object in page tree was unexpectedly not a pagetree")
169         return ob
170
171     def next(self):
172         for n, i in reversed(self.cur.stack):
173             if i < len(n) - 1:
174                 self.cur = self.descend(n[i + 1])
175                 return self.cur
176         raise StopIteration()
177
178     def prev(self):
179         for n, i in reversed(self.cur.stack):
180             if i > 0:
181                 self.cur = self.descend(n[i - 1], True)
182                 return self.cur
183         raise StopIteration()
184
185     def __iter__(self):
186         return self
187
188 loaded = {}
189 def findlib(name):
190     def load(name):
191         mod = __import__(name, fromlist=["dummy"])
192         if not hasattr(mod, "library"):
193             raise ImportError("module " + name + " is not a manga library")
194         return mod.library()
195     if name not in loaded:
196         try:
197             loaded[name] = load("manga." + name)
198         except ImportError:
199             loaded[name] = load(name)
200     return loaded[name]