Skip to main content

A Python wrapper for the 4chan API and other imageboards

Project description



  • Unification: Have one library to use for multiple imageboards. Convert them to 4chan compliant API specifications.
  • Wrapper: Parse the JSON to programming-language-specific data structures (in this case, to Python).

API Documentation


FFuuka based Imageboards

Feature Source
✔️ Single thread{board}/thread/{threadnumber}.json
✔️ Thread index{board}/{pagenumber}.json (threads @ pg #)
✔️ Board list
✔️ Board catalog{board}/catalog.json
✔️ Thread list{board}/threads.json
✔️ Archived threads{board}/archive.json
🚧 HTTPS On by default in urllib3
🚧 Rate limiting x requests allowed in n seconds
🚧 If-Modified-Since req.headers['last-modified']
🚧 In-place thread updating req.headers['last-modified']; difflib

Extra Support

Extra Imageboards Compatibility
✔️ FFuuka Thread, Post


$ pip install py-chan-api             # NOTE: Only Python 3.7+

# Or with virtualenv
$ pip install virtualenv              # Install virtualenv if you haven't already
$ virtualenv venv                     # Create a virtualenv
$ source venv/bin/activate            # Activate it
$ pip install py-chan-api             # Install py-chan-api


import pychan

# pychan infers what type of object you're giving it. See the above table.
# Whether its a string pointing to a file/dict/dict in string format.

threadIndex     = pychan.FourChan("thread_index.json")
board           = pychan.FourChan("boards.json")
thread          = pychan.FourChan("thread.json")
threadList      = pychan.FourChan("thread_list.json")
archivedThread  = pychan.FourChan("archived_threads.json")
post            = thread.posts[0]

print(thread.posts[0].com)              # Get the first post and its comment

print(post)                             # If you're unsure of what fields to call
                                        # just print the object itself to see a list of key/values

# Or see the type of the unknown object


# To get individual key value/pairs
jdb = thread.posts[0].json              # Convert the Post object to a dictionary
for k,v in jdb.items():                 # Iterate through the key/value pairs
    print(k, v)


import pychan
fuukaThread = pychan.Fuuka("desu_thread.json")    # Specify the imageboard implementation

# Parallelism (multiprocessing) is turned on automatically if you supply more
# than one key/value pairs in a dictionary.
# You can override this behaviour by specifying the parallel field
# By using a dictionary, you can also output it to a file.
fthread1 = pychan.Fuuka({"desu_thread.json" : "out1.json"}, parallel = True)

# Which then you could read it as a normal 4chan json
fthread = pychan.FourChan("out1.json")

# We can also just use the outputed value from before
print(fthread1.posts[1])      # Note: fthread1 is the same as fthread and fuukaThread


Tests are done with pytest.

$ pip install -U pytest pytest-xdist
$ pytest -v


Pull requests are welcome. Feel free to ping shiimizu @ this Matrix server.

⚠️ Archiving (polling)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for py-chan-api, version 0.1.3
Filename, size File type Python version Upload date Hashes
Filename, size py_chan_api-0.1.3-py3-none-any.whl (8.4 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size py-chan-api-0.1.3.tar.gz (7.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page