Skip to content


louist87 edited this page Jan 17, 2013 · 5 revisions

Simple API Call

    import scrappy.core as scrappy

    # Initialize a scrape
    # Series name is automatically inferred
    scrape = scrappy.Scrape('its always sunny in philadelphia 101.mkv')

    # Query TheTVDB for data and rename
    if scrape.map_episode_info():  # Returns false if series not found.  Try increasing err.
        scrape.rename_files(test=True)  # test file rename (no changes committed when test == True)

Advanced API Use

Selecting Video Files

You can use glob matching with the scrape constructor. Note that all video files included in the wildcard (or sequence, as per the examples below) must be from the same series.

Again, for good measure: Create a Scrape object for each series.

scrape = scrappy.Scrape('*.mkv')
print scrape.files
['its always sunny in philadelphia 101.mkv']

You can also pass sequences to the constructor. Sequences can be a mix of:

  • Paths to individual files
  • Glob patterns
  • Directories

Directories are recursively searched for all files with a video mimetype, and duplicate paths are automatically filtered.

scrape = scrappy.Scrape(['it's always sunny in philadelphia 101.mkv', '*.avi'])
print scrape.files
['its always sunny in philadelphia 101.mkv', 'its always sunny in philadelphia 102.avi']

Eliminating Guesswork

On rare occasions, Scrappy has trouble inferring the TV series. When this happens, you have three choices:

  1. pass a TVDB id number to the tvdbid argument when initializing Scrape. Doing so guaratees that the series is correctly detected.
  2. set the query_thresh kwarg for the Scrape constructor.
  3. set the interactive kwarg for the Scrape constructor to True. This invokes a CLI menu to select the correct series

Be sure to set the lang parameter to the correct value, as well. Shows will likely not be found on TheTVDB if you're searching for a show with the incorrect language! By default, all languages are searched.

Here is an example of setting the tvdbid and lang parameters:

max_err = .1  # maximum %error in matching inferred series name to query result
scrape = scrappy.Scrape('*kaamelott*', tvdbid=79175, lang='fr', query_thresh=max_err)  # tvdbid should be int
if scrape.map_episode_info():

File-Name Formats

By default, Scrappy employs the seriesname.SXX.EXX.episodename.ext format. This is a widely-used format that most video library scrapers will recognize. Under some conditions, however, it may be desireable to define your own formats. For this purpose, Scrappy exposes the scrappy.formatters.Formatter class.

Using the Formatter class is easy. It requires three elements:

  1. a python advanced formatted string
  2. a separator
  3. a parser, which is just a dictionary mapping strings to lists of functions.

Don't panic! It's very simple, and explained in full detail here

Fixing Goofs

If you make a mistake, you can always revert changes made on the local filesystem.

err = .2  # Max error (difference coefficient) to accept result
scrape = scrappy.Scrape('its always sunny in philadelphia 101.mkv', query_thresh=err)
if scrape.map_episode_info():
    scrape.rename_files()  # No test this time!

print scrape.files
print scrape.files
['its always sunny in philadelphia 101.mkv']
Something went wrong with that request. Please try again.