Welcome to the documentation for python-xkcd!

Contents:

Python library for accessing xkcd.com.

This is a Python library for accessing and retrieving links to comics from the xkcd webcomic by Randall Munroe. It is NOT endorsed or made by him, it’s an entirely independent project.

It makes use of the JSON interface to Randall’s site to retrieve comic data. Both Python 2 and Python 3 are supported, and there are no dependencies beyond the Python standard library, so xkcd’s footprint should be very light.

There is support for accessing specific comics, the latest comic, or a random comic. Comic metadata can be queried and the comics themselves can be downloaded onto your local system. The goal is simply to provide a relatively Pythonic wrapper around the xkcd API for any Python program or library that wants to access information about xkcd comics, for one reason or another.

The xkcd module, as of version 2.4.0, also supports getting information on What If articles from whatif.xkcd.com. This information is generated by scraping the What If archive page with a HTML parser.

class xkcd.Comic(number)

Class representing a single xkcd comic. These can be produced via number of ways; if you know the number of the comic you want to query, you can just construct them yourself (e.g. Comic(integer)), but the recommended way is to use the getComic() function.

There are also helper functions available to get the latest comic (getLatestComic()) and a random comic(getRandomComic()) as comic objects.

download(output='', outputFile='', silent=True)

Downloads the image of the comic onto your computer.

Arguments:

output: the output directory where comics will be downloaded to. The default argument for ‘output is the empty string; if the empty string is passed, it defaults to a “Downloads” directory in your home folder (this directory will be created if it does not exist).

outputFile: the filename that will be written. If the empty string is passed, outputFile will default to a string of the form xkcd-(comic number)-(image filename), so for example, xkcd-1691-optimization.png.

silent: boolean, defaults to True. If set to False, an error will be printed to standard output should the provided integer argument not be valid.

Returns the path to the downloaded file, or an empty string in the event of failure.

getAltText()

Returns the alt-text of the comic (the text that appears when one places their cursor over the image in a web browser) as a UTF-8 formatted Unicode string.

getAsciiAltText()

Returns the ASCII-formatted version of the comic’s alt-text. See getAsciiTitle() and getAltText() for more information.

Returns the ASCII-formatted version of the link to the comic’s image. See getAsciiTitle() and getImageLink() for more information.

getAsciiTitle()

Returns the ASCII-formatted version of the title.

This function, and the other ASCII getters in the Comic class, exists so that code which depends on some legacy Python 2 component, like Twisted (which as of this writing does not support Unicode terribly well) can retrieve a version of comic metadata that they can use. It uses the convertToAscii() helper function to replace characters Python cannot automatically convert with a ”?”.

You should do your best to not need to use this routine and prefer getTitle() wherever possible.

getExplanation()

Returns an explainxkcd link for the comic. explainxkcd is a wiki with community contributed explanations for xkcd comics; this function produces the URL for a given comic and returns that URL.

Returns a URL linking to the comic’s image as a UTF-8 formatted Unicode string.

getImageName()

Returns the filename of the comic’s image as a UTF-8 formatted Unicode string.

getTitle()

Returns the title of the comic, as a UTF-8 formatted Unicode string.

show()

Uses the Python webbrowser module to open the comic in your system’s web browser.

class xkcd.WhatIf

Class representing an xkcd What If article.

The WhatIf class is somewhat simpler than the Comic class. It simply provides functions for querying information about the link to, title of, and index of a What If article.

Unlike the Comic class, you are not meant to construct them directly. Instead, call getWhatIfArchive() to produce a dictionary mapping numbers to WhatIf objects and then select the one(s) you are interested in.

Returns a link to the What If article.

getNumber()

Returns the number of the What If article.

getTitle()

Returns the title of the What If article.

class xkcd.WhatIfArchiveParser

The WhatIfArchiveParser is a subclass of the Python standard library HTML parser. It is invoked by getWhatIfArchive() to parse the xkcd What If archive page, and automatically populate WhatIf objects

As there is not a JSON API for the What If blog (or at least, the author was unable to find one), this seemed the simplest way to implement fetching of information about them.

This class is designed for internal usage only; there should be no reason for you to use it directly outside of the xkcd module.

getWhatIfs()

Returns a dictionary of WhatIf objects, indexed into by their number. This function must be invoked after the HTML parsing has finished, i.e. after calling self.feed.

If for some reason the parsing has failed, the dictionary will be empty.

xkcd.convertToAscii(string, error='?')

Utility function that converts a unicode string to ASCII. This exists so the Comic class can be compatible with Python 2 libraries that expect ASCII strings, such as Twisted (as of this writing, anyway). It is unlikely something you will need directly, and its use is discouraged.

Arguments:

string: the string to attempt to convert.

error: a string that will be substituted into ‘string’ wherever Python is unable to automatically do the conversion.

convertToAscii returns the converted string.

xkcd.getComic(number, silent=True)

Produces a Comic object with index equal to the provided argument. Prints an error in the event of a failure (i.e. the number is less than zero or greater than the latest comic number) and returns an empty Comic object.

Arguments:

an integer or string that represents a number, “number”, that is the index of the comic in question.

silent: boolean, defaults to True. If set to False, an error will be printed to standard output should the provided integer argument not be valid.

Returns the resulting Comic object for the provided index if successful, or a Comic object with -1 as the index if not.

xkcd.getLatestComic()

Produces a Comic object for the latest xkcd comic. This function is just a wrapper around a call to getLatestComicNum(), and then constructs a Comic object on its return value.

Returns the resulting comic object.

xkcd.getLatestComicNum()

Uses the xkcd JSON API to look up the number of the latest xkcd comic.

Returns that number as an integer.

xkcd.getLatestWhatIf(archive=None)

Returns a WhatIf object representing the latest What If article.

Takes an optional “archive” argument. If this argument is None, the getWhatIfArchive() routine is first called to populate the archive of published What If articles. If it is not, however, “archive” is assumed to be a dictionary and used as the set of articles to chooose from.

xkcd.getLatestWhatIfNum(archive=None)

Returns an integer representing the number of the latest What If article published. This is done by calling getLatestWhatIf and returning the number of that method’s result.

Takes an optional “archive” argument. If this argument is None, the getWhatIfArchive() routine is first called to populate the archive of published What If articles. If it is not, however, “archive” is assumed to be a dictionary and used as the set of articles to chooose from.

xkcd.getRandomComic()

Produces a Comic object for a random xkcd comic. Uses the Python standard library random number generator in order to select a comic.

Returns the resulting comic object.

xkcd.getRandomWhatIf()

Returns a randomly generated WhatIf object, using the Python standard library random number generator to select the object. The object is returned from the dictionary produced by getWhatIfArchive(); like the other What If routines, this function is called first in order to get a list of all previously published What Ifs.

xkcd.getWhatIf(number)

Returns a WhatIf object corresponding to the What If article of index passed to the function. If the index is less than zero or greater than the maximum number of articles published thus far, None is returned instead.

Like all the routines for handling What If articles, getWhatIfArchive() is called first in order to establish a list of all previously published What Ifs.

Arguments:

number: an integer or string that represents a number, this is the index of article to retrieve.

Returns the resulting WhatIf object.

xkcd.getWhatIfArchive()

Parses the xkcd What If archive. getWhatIfArchive passes the HTML text of the archive page into a WhatIfArchiveParser and then calls the parser’s WhatIfArchiveParser.getWhatIfs() method and returns the dictionary produced.

This function returns a dictionary mapping article numbers to WhatIf objects for every What If article published thus far. If the parsing fails, for whatever reason, the dictionary will be empty.

Indices and tables