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

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page