comics

GoComics API wrapper

Installation

pip install comics

Warning

Breaking changes since v0.9.1 Versions prior to v0.9.1 are incompatible due to an upstream change. Upgrading to the latest release is required.

pip install comics --upgrade

Note

Playwright must be installed after installing comics to enable browser-based features:

python -m playwright install --with-deps

Quick start

Find and download the Calvin and Hobbes comic strip published on January 2, 1990:

import comics

ch = comics.search("calvinandhobbes", date="1990-01-02")
ch.download("calvinandhobbes.png")

Find comics

Available comics can be found using the directory class:

import comics

# List available comics - total of 401
comics.directory.listall()
# >>> ("1-and-done", "9-chickweed-lane-classics", "9chickweedlane", "9to5", ... )

# Find endpoints for Calvin and Hobbes
comics.directory.search("Calvin and Hobbes")
# >>> ("calvinandhobbes", "calvinandhobbesenespanol")

First, pass the desired endpoint to comics.search. For example, to search for Calvin and Hobbes comics in english use comics.search("calvinandhobbes"); for spanish, use comics.search("calvinandhobbesenespanol").

Search and download comics

Then, search for a comic strip by passing date into search():

import comics

# Get a Calvin and Hobbes comic strip by date
ch = comics.search("calvinandhobbes", date="2013-05-13")  # Also accepts datetime.date or datetime object

# Get a random Calvin and Hobbes comic strip
random_ch = comics.search("calvinandhobbes", date="random")

Finally, show, download, or stream the comic strip:

# Show comic strip - opens in Jupyter notebook or default image viewer application
ch.show()

# Download comic strip - defaults to {endpoint}.png if an export path is not provided
# E.g., a Calvin and Hobbes comic strip will be exported as "calvinandhobbes.png" in the current working directory
ch.download()

# Stream comic strip - useful if custom image content manipulation is desired
ch.stream()

Retry logic

If a comic strip fails to load due to CDN delays or missing image data, a retry mechanism is built into download(), show(), and stream(). You can control this behavior via:

• retries: number of attempts before failing (default = 5)
• base_delay: exponential backoff seed time in seconds (default = 0.5)

This improves reliability when fetching newly released strips or handling transient issues.

Attempt	Wait Before Attempt (sec)	Cumulative Time (sec)
1	0.0	0.0
2	0.5	0.5
3	1.0	1.5
4	2.0	3.5
5	4.0	7.5
6	8.0	15.5

Retry behavior can be customized per call:

# Try 3 times total with shorter delay
ch.download(retries=2, base_delay=0.25)

Attributes

An instantiated search class will have the following public attributes:

import comics

garfield = comics.search("garfield")
garfield.endpoint
# >>> "garfield"
garfield.title
# >>> "Garfield"
garfield.start_date
# >>> "1978-06-19"

An instantiated search class with date will have the following public attributes:

import comics

garfield = comics.search("garfield", date="2000-08-20")
garfield.endpoint
# >>> "garfield"
garfield.title
# >>> "Garfield"
garfield.date
# >>> "2000-08-20"
garfield.url
# >>> "https://www.gocomics.com/garfield/2000/08/20"
garfield.image_url
# >>> "https://assets.amuniversal.com/6694c52099bd01365606005056a9545d"

Exceptions

An exception will be thrown if the queried date is unregistered or before the comic's origin date:

import comics

try:
    peanuts = comics.search("peanuts", date="1900-01-01")
    peanuts.download()
except comics.exceptions.InvalidDateError:
    print("Whoops, an invalid date was queried.")

An exception will be thrown if the queried endpoint is unregistered:

import comics

try:
    invalid_comic = comics.search("invalid_endpoint", date="2000-01-01")
    invalid_comic.download()
except comics.exceptions.InvalidEndpointError:
    print("Whoops, an invalid endpoint was queried.")

An exception will be thrown if Playwright fails to fetch a comic (e.g., browser not installed or page error):

import comics

try:
    garfield = comics.search("garfield", date="2020-05-05", force_playwright=True)
    garfield.download()
except comics.exceptions.ComicsPlaywrightError:
    print("Playwright failed to fetch the page. Check your Playwright installation.")

Contribute

• Issues Tracker
• Source Code

Support

If you are having issues or would like to propose a new feature, please use the issues tracker.

License

This project is licensed under the MIT license.