transformed into py8chan, basic proof of concept

Author: antonizoon

.vscode/settings.json

@@ -0,0 +1,8 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+	// Controls the rendering size of tabs in characters. Accepted values: "auto", 2, 4, 6, etc. If set to "auto", the value will be guessed when a file is opened.
+	"editor.tabSize": "4",
+	
+	// Controls if the editor will insert spaces for tabs. Accepted values:  "auto", true, false. If set to "auto", the value will be guessed when a file is opened.
+	"editor.insertSpaces": "true"
+}

README.rst

@@ -1,46 +1,37 @@
-4chan Python Library
+8chan/vichan Python Library
 ====================
-The Bibliotheca Anonoma's **complete Python Wrapper for the 4chan API.**
+The Bibliotheca Anonoma's **complete Python Wrapper for the 8chan API.**
 Uses requests, respects if-modified-since headers on updating threads.
 Caches thread objects. Fun stuff.
 
-An absolute must if you want to interface with or scrape from 4chan,
-using a Python script.
-
-`Hosted Documentation <http://basc-py4chan.readthedocs.org/en/latest/index.html>`_
+An absolute must if you want to interface with or scrape from 8chan or other vichan-based imageboards/textboards,
+using a Python script._
 
 `Github Repository <https://github.com/bibanon/BASC-py4chan>`_
 
 You can install this library `straight from
-PyPi <https://pypi.python.org/pypi/BASC-py4chan>`_ with::
+PyPi <https://pypi.python.org/pypi/py8chan>`_ with::
 
-    pip install basc-py4chan
+    pip install py8chan
 
 
 **Getting Help**
 
 If you want help, or you have some trouble using this library, our primary IRC channel
 is `#bibanon on irc.rizon.net <http://qchat2.rizon.net/?channels=bibanon>`_. Simply head
 in there and talk to dan or antonizoon. Otherwise, you can put a issue on our `Github
-Issue Tracker <https://github.com/bibanon/BASC-py4chan>`_ and we'll respond as soon as
+Issue Tracker <https://github.com/bibanon/py8chan>`_ and we'll respond as soon as
 we can!
 
 --------
 
-Originally written by `Edgeworth <https://github.com/e000/py-4chan>`_, the library
-has been adopted and extended by `Bibliotheca Anonoma <https://github.com/bibanon>`_.
-
-**Note:** If you're a developer that still uses Edgeworth's py-4chan, and don't
-want to change the function names, Bibliotheca Anonoma maintains an `up-to-date,
-API-compatible version of py-4chan here. <https://github.com/bibanon/py-4chan>`_
-
 Usage
 -----
 
 .. code:: python
 
-    import basc_py4chan
-    b = basc_py4chan.Board('b')
+    import py8chan
+    b = py8chan.Board('b')
     thread = b.get_thread(423491034)
 
     print(thread)
@@ -51,57 +42,15 @@ Usage
     # In a while...
     print("I fetched", thread.update(), "new replies.")
 
-Documentation is located `here <http://basc-py4chan.readthedocs.org/en/latest/index.html>`_.
-
-Extending this Library
-----------------------
+Documentation
+-------------
 
-There are a wealth of other imageboard APIs that have adopted a similar structure to the 4chan API (such as 8chan/vichan, or 420chan).
-
-So instead of writing a whole new class from scratch, you could inherit and override BASC-py4chan to support them. Here's how:
-
-.. code:: python
+This library extends the classes of `BASC-py4chan <https://github.com/bibanon/BASC-py4chan>`_. For the most part, it inherits all functions and remains compatible. See the BASC-py4chan documentation for more info.
 
-    import basc_py4chan
-    
-    class URL (basc_py4chan.URL):
-        # see BASC-py4chan's `url.py` for an example of how to set up
-        # the URLs.
-        def __init__(self, https=False):
-            # Your API URL Subdomains
-            DOMAIN = { }
-            
-            # Your API URL Templates
-            TEMPLATE = { }
-            
-            # Your API Listings
-            LISTING = { }
-            
-            # combine all dictionaries into self.URL dictionary
-            self.URL = TEMPLATE
-            self.URL.update({'domain': DOMAIN})
-            self.URL.update({'listing': LISTING})
-    
-    class Board(basc_py4chan.Board):
-        # add your own overrides here, or leave it alone
-        pass
-           
-    class Thread(basc_py4chan.Threads):
-        # add your own overrides here, or leave it alone
-        pass
-
-    class Post(basc_py4chan.Post):
-        # add your own overrides here, or leave it alone
-        pass
-
-    # note that all classes must be in one file (we recommend
-    #   py?chan/__init__.py ), due to how python modules work
-
-
-From there, just override any methods in classes Board, Thread or Post as necessary. 
-
-Notice that if your imageboard's API does not support a certain feature in the 4chan API, `you should have the function raise an AttributeError. <http://stackoverflow.com/a/23126260>`_
+`BASC-py4chan Documentation <http://basc-py4chan.readthedocs.org/en/latest/index.html>`_
 
+Notice that some functions are not implemented in the 8chan API. These functions will `raise an AttributeError when used. <http://stackoverflow.com/a/23126260>`_
+  
 License
 -------
 

examples/example1.py

@@ -1,9 +1,9 @@
 # credits to Anarov for improved example.py
-import basc_py4chan
+import py8chan
 
 
 def main():
-    v = basc_py4chan.Board('v')
+    v = py8chan.Board('v')
     thread = v.get_thread(152900882)
     print(thread)
     print('Sticky?', thread.sticky)

examples/example2.py

@@ -1,5 +1,5 @@
 # credits to Anarov for improved example.py
-import basc_py4chan
+import py8chan
 
 
 def main():
@@ -10,7 +10,7 @@ def main():
               % sys.argv[0])
         return
 
-    board = basc_py4chan.Board(sys.argv[1])
+    board = py8chan.Board(sys.argv[1])
     thread = board.get_thread(int(sys.argv[2]))
     for f in thread.files():
         print(f)

examples/example3.py

@@ -1,7 +1,7 @@
 # credits to Anarov for improved example.py
-import basc_py4chan
+import py8chan
 
-b = basc_py4chan.Board('b')
+b = py8chan.Board('b')
 threads = b.get_threads()
 print("Got %i threads" % len(threads))
 first_thread = threads[0]

basc_py4chan/__init__.py py8chan/__init__.py

@@ -189,18 +189,19 @@ def _request_threads(self, url):
 
         return threads
 
-    def get_threads(self, page=1):
+    # 8chan/vichan board pages actually start at 0, not 1!
+    def get_threads(self, page=0):
         """Returns all threads on a certain page.
-
+    
         Gets a list of Thread objects for every thread on the given page. If a thread is
         already in our cache, the cached version is returned and thread.want_update is
         set to True on the specific thread object.
-
-        Pages on 4chan are indexed from 1 onwards.
-
+    
+        Pages on 8chan/vichan are indexed from 0 onwards. (not 1 as in modern 4chan: 4chan used to start from 0)
+    
         Args:
             page (int): Page to request threads for. Defaults to the first page.
-
+    
         Returns:
             list of :mod:`basc_py4chan.Thread`: List of Thread objects representing the threads on the given page.
         """
@@ -258,23 +259,25 @@ def clear_cache(self):
     def name(self):
         return self._board_name
 
+    # py8chan does not use thread titles, unlike BASC-py4chan
     @property
     def title(self):
-        return self._get_metadata('title')
-
+        raise AttributeError( "'py8chan.Board' object has no attribute 'title'" )
+    
+    # py8chan does not use worksafe tag, unlike BASC-py4chan
     @property
     def is_worksafe(self):
-        if self._get_metadata('ws_board'):
-            return True
-        return False
-
+        raise AttributeError( "'py8chan.Board' object has no attribute 'is_worksafe'" )
+    
+    # py8chan does not use page_count variable, unlike BASC-py4chan
     @property
     def page_count(self):
-        return self._get_metadata('pages')
-
+        raise AttributeError( "'py8chan.Board' object has no attribute 'page_count'" )
+    
+    # py8chan does not use threads_per_page variable, unlike BASC-py4chan
     @property
     def threads_per_page(self):
-        return self._get_metadata('per_page')
+        raise AttributeError( "'py8chan.Board' object has no attribute 'threads_per_page'" )
 
     @property
     def https(self):

basc_py4chan/board.py py8chan/board.py

@@ -0,0 +1,124 @@
+# brand new class to handle 8chan/vichan's multiple files per post
+# supersedes py4chan's file generators in Thread and Post
+
+class File(object):
+	""" Represents File objects and their thumbnails.
+	
+	Constructor:
+		post (py8chan.Post) - parent Post object.
+		data (dict) - The extra_files dict from the 8chan API.
+	
+	Attributes:
+		file_md5 (string): MD5 hash of the file attached to this post.
+		file_md5_hex (string): Hex-encoded MD5 hash of the file attached to this post.
+		filename (string): Original name of the file attached to this post.
+		file_url (string): URL of the file attached to this post.
+		file_extension (string): Extension of the file attached to this post. Eg: ``png``, ``webm``, etc.
+		file_size (int): Size of the file attached to this post.
+		file_width (int): Width of the file attached to this post.
+		file_height (int): Height of the file attached to this post.
+		file_deleted (bool): Whether the file attached to this post was deleted after being posted.
+		thumbnail_width (int): Width of the thumbnail attached to this post.
+		thumbnail_height (int): Height of the thumbnail attached to this post.
+		thumbnail_fname (string): Filename of the thumbnail attached to this post.
+		thumbnail_url (string): URL of the thumbnail attached to this post.
+		has_file (bool): Whether this post has a file attached to it.
+		url (string): URL of this post.
+	"""
+	
+	def __init__(self, post, data):
+		self._post = post
+		self._data = data
+		self._url = Url(board=self._post._thread._board.name, https=self._post._thread._board.https)       # 8chan URL generator
+		
+	@property
+	def file_md5(self):
+		if not self.has_file:
+			return None
+
+		return self._data['md5'].decode('base64')
+
+	@property
+	def file_md5_hex(self):
+		if not self.has_file:
+			return None
+
+		return self.file_md5.encode('hex')
+
+	@property
+	def filename(self):
+		if not self.has_file:
+			return None
+
+		board = self._thread._board
+		
+		return '%i%s' % (
+			self._data['tim'],
+			self._data['ext']
+		)
+
+	@property
+	def file_url(self):
+		if not self.has_file:
+			return None
+
+		board = self._thread._board
+		return self._url.file_url(
+			self._data['tim'],
+			self._data['ext']
+		)
+
+	@property
+	def file_extension(self):
+		return self._data.get('ext')
+
+	@property
+	def file_size(self):
+		return self._data.get('fsize')
+
+	@property
+	def file_width(self):
+		return self._data.get('w')
+
+	@property
+	def file_height(self):
+		return self._data.get('h')
+
+	@property
+	def file_deleted(self):
+		return self._data.get('filedeleted') == 1
+
+	@property
+	def thumbnail_width(self):
+		return self._data.get('tn_w')
+
+	@property
+	def thumbnail_height(self):
+		return self._data.get('tn_h')
+
+	@property
+	def thumbnail_fname(self):
+		if not self.has_file:
+			return None
+
+		board = self._thread._board
+
+		return '%is.jpg' % (
+			self._data['tim']
+		)
+
+	@property
+	def thumbnail_url(self):
+		if not self.has_file:
+			return None
+
+		board = self._thread._board
+		return self._url.thumb_url(
+			self._data['tim']
+		)
+
+	def file_request(self):
+		return self._thread._board._requests_session.get(self.file_url)
+
+	def thumbnail_request(self):
+		return self._thread._board._requests_session.get(self.thumbnail_url)