Suite API

Vidscraper defines a simple API for “Suites”, classes which provide the functionality necessary for scraping video information from a specific video service.

The Suite Registry

vidscraper.suites.registry = <vidscraper.suites.base.SuiteRegistry object at 0x39bff90>

An instance of SuiteRegistry which is used by vidscraper to track registered suites.

class vidscraper.suites.base.SuiteRegistry

A registry of suites. Suites may be registered, unregistered, and iterated over.

get_feed(url, last_modified=None, etag=None, start_index=1, max_results=None, video_fields=None, api_keys=None)

For each registered suite, calls get_feed() with the given parameters, until a suite returns a feed instance.

Returns:An instance of a specific suite’s feed_class with no data loaded. Raises :UnhandledFeed if no registered suites know how to handle this url.

get_searches(query, order_by='relevant', start_index=1, max_results=None, video_fields=None, api_keys=None)

For each registered suite, calls get_search() with the given parameters.

Returns:a list of iterators over search results for suites which support the given parameters.

get_video(url, fields=None, api_keys=None, require_loaders=True)

For each registered suite, calls get_video() with the given url, fields, and api_keys, until a suite returns a Video instance.

Parameters:require_loaders – Changes the behavior if no suite is found which handles the given parameters. If True (default), UnhandledVideo will be raised; otherwise, a video will returned with the given url and fields, but it will not be able to load any additional data. Raises :UnhandledVideo if require_loaders is True and no registered suite returns a video for the given parameters. Returns:Video instance with no data loaded.

handles_feed(*args, **kwargs)

Returns True if any registered suite can make a feed with the given parameters, and False otherwise.

Note

This does all the work of creating a feed, then discards it. If you are going to use a feed instance if one is created, it would be more efficient to use get_feed() directly.

handles_video(*args, **kwargs)

Returns True if any registered suite can make a video with the given parameters, and False otherwise.

Note

This does all the work of creating a video, then discards it. If you are going to use a video instance if one is created, it would be more efficient to use get_video() directly.

register(suite)

Registers a suite if it is not already registered.

register_fallback(suite)

Registers a fallback suite, which is tried only if no other suite successfully handles a given video, feed, or search.

suites

Returns a tuple of registered suites. If a fallback is registered, it will always be at the end of this tuple.

unregister(suite)

Unregisters a suite if it is registered.

Built-in Suites

class vidscraper.suites.BaseSuite

This is a base class for suites, demonstrating the API which is expected when interacting with suites. It is not suitable for actual use; some vital methods must be defined on a suite-by-suite basis.

available_fields

Returns a set of all of the fields we could possibly get from this suite.

feed_class = None

A BaseFeed subclass that will be used to parse feeds for this suite.

feed_regex = None

A string or precompiled regular expression which will be matched against feed urls to check if they can be handled by this suite.

get_feed(url, *args, **kwargs)

Returns an instance of feed_class, which should be a subclass of BaseFeed.

Raises :UnhandledFeed if feed_class is None.

get_search(*args, **kwargs)

Returns an instance of search_class, which should be a subclass of BaseSearch.

Raises :UnhandledSearch if search_class is None.

get_video(url, fields=None, api_keys=None)

Returns a video using this suite’s loaders. This instance will not have data loaded.

Parameters:

• url – A video URL. Video website URLs generally work; more obscure urls (like API urls) might work as well.
• fields –

  A list of fields to be fetched for the video. Limiting this may decrease the number of HTTP requests required for loading the video.

  See also

  Limiting metadata

• api_keys – A dictionary of API keys for various services. Check the documentation for each suite to find what API keys they may want or require.

Raises :

UnhandledVideo if none of this suite’s loaders can handle the given url and api keys.

handles_feed(*args, **kwargs)

Returns True if this suite can make a feed with the given parameters, and False otherwise.

Note

This does all the work of creating a feed, then discards it. If you are going to use a feed instance if one is created, it would be more efficient to use get_feed() directly.

handles_search(*args, **kwargs)

Returns True if this suite can make a search with the given parameters, and False otherwise.

handles_video(*args, **kwargs)

Returns True if this suite can make a video with the given parameters, and False otherwise.

Note

This does all the work of creating a video, then discards it. If you are going to use a video instance if one is created, it would be more efficient to use get_video() directly.

loader_classes = ()

A list or tuple of VideoLoader classes which will be used to populate videos with data. These loaders will be run in the order they are given, so it’s a good idea to order them by the effort they would require; for example, OEmbed should generally come first, since the response is small and easy to parse compared to, say, a page scrape.

See also

Video.run_loaders()

search_class = None

A BaseSearch subclass that will be used to run searches for this suite.

video_regex = None

A string or precompiled regular expression which will be matched against video urls to check if they can be handled by this suite.