`aniping.plugins`¶

class aniping.plugins.AniPlugin(config, plugin_manager)¶

Base Aniping Plugin Class.

This class should never be extended from directly by a plugin, with the exception of the front-end. Everything else should extend from one of this class’ subclasses.

Several attributes are defined here that should be defined for all plugins.

__name__¶: str – The name of the plugin.

__id__¶: str – The plugin’s ID. This is what is used to load the plugin.

__author__¶: str – The plugin’s author.

__version__¶: str – The version of the plugin. Optional, but set it to 0.01 if not in use.

apm¶: AniPluginManager – An AniPluginManager instantiation. Should only be used by plugins sparingly, use helper methods when possible.

back_end(func, *args, **kwargs)¶

Calls back_end functions.

This is a helper function which calls functions from the back_end category. Remember back_ends are not multiloaded, so you will only get a single response from whatever function is called.

Parameters:	func (str) – The function to call from the back_end plugin. args – The arguments to pass to the plugin. *kwargs – The keyword arguments to pass to the plugin.
Returns:	The response of the function you called.

db(func, *args, **kwargs)¶

Calls database functions.

This is a helper function which calls functions from the database category. Remember databases are not multiloaded, so you will only get a single response from whatever function is called.

Parameters:	func (str) – The function to call from the database plugin. args – The arguments to pass to the plugin. *kwargs – The keyword arguments to pass to the plugin.
Returns:	The response of the function you called.

name¶: str – Should return the name of your plugin, but is optional.

scraper(func, *args, **kwargs)¶

Calls scraper functions.

This is a helper function which calls functions from the scraper category. Remember that scrapers are multiloaded, so you will get a list of responses.

Parameters:	func (str) – The function to call from the scraper plugins. args – The arguments to pass to the plugins. *kwargs – The keyword arguments to pass to the plugins.
Returns:	A list of responses of the function you called from each plugin.

search(func, *args, **kwargs)¶

Calls search_engine functions.

This is a helper function which calls functions from the search_engine category. Remember that search_engines are multiloaded, so you will get a list of responses.

Parameters:	func (str) – The function to call from the search_engine plugins. args – The arguments to pass to the plugins. *kwargs – The keyword arguments to pass to the plugins.
Returns:	A list of responses of the function you called from each plugin.

class aniping.plugins.AniPluginManager(config)¶

Plugin manager for aniping plugins.

Handles loading and scanning of plugins, as well as calling functions within those plugins. Some plugins can be multiloaded - meaning multiple plugins of that type can be loaded - and others can only be loaded once, like the database.

available_plugins¶: dict – Dictionary of available plugins, keyed by plugin type.

load_plugins()¶

Plugin loader.

Loads plugins that are configured in config.yml. Adds the instanciated class instance to a dictionary for use by the plugin callers.

Returns:	The loaded plugins dictionary.

loaded_plugins¶: dict – Dictionary of loaded plugin classes, keyed by plugin type.

plugin_categories¶: dict – Plugin categories that key available and loaded plugins.

plugin_category_function(category, func, *args, **kwargs)¶

Call all plugins of a specified category with a function.

Attempts to call the function in all plugins. Function should only be something defined in the plugin’s base class.

Parameters:	category (str) – The plugin category to call. func (str) – The function to call in that category. args – Arguments that will be passed to the function. *kwargs – Keyword arguments that will be passed to the function.
Returns:	If it’s a multiloaded function, it will return a list of all of the responses from the all of the plugins. If it is not, it will just return the response from the function.

plugin_function(plugin, func, *args, **kwargs)¶

Call a specific plugin’s function.

This is useful if you have plugins of different types that interact directly. Should be used incredibly sparingly.

Parameters:	plugin (str) – The plugin to call. func (str) – The function to call from the plugin. args – Arguments that will be passed to the function. *kwargs – Keyword arguments that will be passed to the function.
Returns:	The plugin function’s response.

scan_for_plugins()¶

Plugin scanner.

Scans for plugins in the known plugin directories. Adds them to the available plugins dictionary, ready to be loaded.

Returns:	The available plugins dictionary.

class aniping.plugins.BackEnd(config, plugin_manager)¶

Base backend class.

Extend this class if you are making a Back End plugin.

Backends are what actually perform the download operations, and keep track of everything that is currently being watched. They can also be configured to perform other opeations, such as adding things to a watch list or similar.

Examples of backends include sonarr and couchpotato.

Note

Check the AniPlugin Class documentation for details on what must be included with all plugins. This documentation only describes what is needed with search engine plugins.

add_update_show(beid, subgroup)¶

Adds or edits a show in the backend.

As all aniping ever really deals with in the backend is the subgroup, that is all that should be expected in this method. Additionally, this method should be capable of both adding and editing a show. Ideally, it should also initiate a search and attempt to download anything new once a show has been added or edited.

Parameters:	beid (int) – The backend ID of the show we’re adding or editing. subgroup (str) – The subgroup or release group we’re using for this show.

api_key¶: str – Should return the the API key of your backend, if it needs one.

check_auth(username, password)¶

Authentication check function.

Should check if a user gives a correct username and password. These should be checked against the backend login database somehow, a new username and password pair should not be necessary to log into aniping.

Parameters:

username (str) – The username to check.
password (str) – The password to check.

Returns:

bool.

True – user is authenticated

False – user is not authenticated or an error occurred

check_for_login()¶

Checks if a login is necessary.

Not all backends require logins all the time, so this function should check to see if one is necessary.

Returns:	bool. True – Login is required. False – Login is not required, proceed assuming already logged in.

fanart(beid)¶

Returns fanart from the backend.

If this backend does not support fanart, try calling to another service to collect it. Returning an empty list is acceptable as well.

Parameters:	beid (int) – The backend ID for the show to get fanart from.
Returns:	list. All fanart urls in the results.

get_show(beid)¶

Get a show from the backend.

Uses a backend id - typically something like the TVDB ID but can be whatever - to get a show from the backend.

Parameters: id (int) – The backend ID for the show.

Returns:

dict. A dictionary describing the show. The response format should contain

title - the show’s title (str)

overview - an overview of the show (str)

tvdbId - the TVDB ID of the show (int)

remotePoser - a URL to an image of the show’s poster (str)

year - The year the show is airing (int)

network - The network the show is airing on (str)

beid - an ID this show can be used to refer to in the backend, usually the TVDB ID (int)

images - A list of dictionaries describing images for the show, each in the following format: {“coverType”: “fanart, banner, or poster”, “url”: “image URL”} (list)

get_watching_shows()¶

Get all of the shows being tracked by the backend for downloading or watching.

Returns:

list. A list of dictionaries describing the show. The response format should contain

title - the show’s title (str)

overview - an overview of the show (str)

tvdbId - the TVDB ID of the show (int)

remotePoser - a URL to an image of the show’s poster (str)

year - The year the show is airing (int)

network - The network the show is airing on (str)

beid - an ID this show can be used to refer to in the backend, usually the TVDB ID (int)

password¶: str – Should return the password used to log into your backend if there is no api key.

remove_show(beid)¶

Remove a given show from the backend.

This should only delete files if the end user wants it to.

Parameters:	beid (int) – The Backend ID of the show.

search(title)¶

Searches the backend for a particular show.

This should search whatever indexes the backend has configured. It should return shows that may not yet be added to the backend. If the backend isn’t capable of this, try calling search.query(title) and parsing the results there.

Parameters: title (str) – The title of the show we’re searching for.

Returns:

list. A list of dictionaries describing the show. The response format should contain

title - the show’s title (str)

overview - an overview of the show (str)

tvdbId - the TVDB ID of the show (int)

remotePoser - a URL to an image of the show’s poster (str)

year - The year the show is airing (int)

network - The network the show is airing on (str)

beid - an ID this show can be used to refer to in the backend, usually the TVDB ID (int)

images - A list of dictionaries describing images for the show, each in the following format: {“coverType”: “fanart, banner, or poster”, “url”: “image URL”} (list)

subgroup_selected(beid)¶

Returns the selected subgroup for the show.

The backend is the only place this information should be stored.

Parameters:	beid (int) – The backend id of the show to get the subgroup for.
Returns:	A string of the subgroup the show is using. None if none is found.

url¶: str – Should return the URL of your search engine.

username¶: str – Should return the username used to log into your backend if there is no api key.

class aniping.plugins.DataBase(config, plugin_manager)¶

Base Database Class.

Extend this class if you are making a database plugin.

Databases store the ongoing shows and shows being watched for aniping, as well as the shows that are starred and the like. Check the add_show method for the expected schema for that table, and the add_login_id method for the exepcted schema for the session_id table.

Examples of databases include sqlite3 and mysql, but plugins can also be configured for things such as json or even plain text.

Note

Check the AniPlugin Class documentation for details on what must be included with all plugins. This documentation only describes what is needed with search engine plugins.

add_login_id(session_id, expiry)¶

Adds session IDs to the database.

Writes a session ID for a user to the database. The table should include a minimum of the two columns below. They are the only two used by the rest of aniping.

Note

The column names do not need to match the argument names, provided they are stored as expected. Also, any additional columns you add will not be used by aniping, so will be limited to internal use to this plugin, and potentially other plugins.

Parameters:	session_id (int) – the session ID to add to the database. expiry (int) – The expiration date and time of the session id as a unix timestamp. Typically now + 2 hours.

add_show(aid, show_type, title, alt_title, synonyms, total_episodes, next_episode, next_episode_date, start_date, genre, studio, description, link, image, airing, season_name)¶

Adds show to the database.

All arguments are required. The scraper should gather these arguments and pass them to this function in the expected format, which is described below. Build your database schema based on that.

Note

The column names do not need to match the argument names, provided they are stored as expected. Also, any additional columns you add will not be used by aniping, so will be limited to intenal use to this plugin, and potentially other plugins.

Parameters:

aid (int) – The scraper ID of the show
show_type (str) – The type of show being added (tv, ona, ova, movie, etc.)
title (str) – The show’s title
alt_title (str) – The show’s alternate title. May be the same as the title.
synonyms (str) – A pipe-separated (|) list of synonyms for the show.
total_episodes (int) – The show’s total number of episodes
next_episode (int) – The next airing episode
next_episode_date (int) – The next airing episode’s scheduled date as a unix timestamp.
start_date (int) – The date the show starts or started as a unix timestamp.
genre (str) – A comma-separated list of genres for the show
studio (str) – The show’s primary studio
description (str) – A brief description or synopsis for the show
link (str) – A link to more info - anilist, mal, etc.
image (str) – The locally cached link to the image for the show.
airing (str) – The airing status of the show.
season_name (str) – The season string of the show (winter, spring, summer, fall)

change_show(id=None, aid=None, beid=None, show_type=None, title=None, alt_title=None, synonyms=None, total_episodes=None, next_episode=None, next_episode_date=None, start_date=None, genre=None, studio=None, description=None, link=None, image=None, airing=None, season_name=None, starred=None, sub_groups=None)¶

Modifies a show in the database.

One of id, aid, or beid is required to look up the show, but all other arguments are optional. If multiple of id, aid, and beid are provided, they should be handled in the order id, aid, beid, and anything following the first match should be considered an update for the database.

Example

If you want to change the title for a show and have it’s beid:

db.change_show(beid=12345, title="My Show")

But if you want to change the beid for a show and you have it’s database id:

db.change_show(id=10, beid=54321)

Keyword Arguments:

id (int) – The show’s database ID
aid (int) – The scraper ID of the show
beid (int) – The backend ID of the show
show_type (str) – The type of show being added (tv, ona, ova, movie, etc.)
title (str) – The show’s title
alt_title (str) – The show’s alternate title. May be the same as the title.
synonyms (str) – A pipe-separated (|) list of synonyms for the show.
total_episodes (int) – The show’s total number of episodes
next_episode (int) – The next airing episode
next_episode_date (int) – The next airing episode’s scheduled date as a unix timestamp.
start_date (int) – The date the show starts or started. as a unix timestamp.
genre (str) – A comma-separated list of genres for the show
studio (str) – The show’s primary studio
description (str) – A brief description or synopsis for the show
link (str) – A link to more info - anilist, mal, etc.
image (str) – The locally cached link to the image for the show.
airing (str) – The airing status of the show.
season_name (str) – The season string of the show (winter, spring, summer, fall)
starred (int) – The highlight status of the show. 1=True, 0=False.
sub_groups (str) – A pipe-separated (|) list of subgroups running the show.

check_for_update()¶

Check for update to database.

Occasionally aniping will need to make a change that involves updating the way the database is configured - adding or removing columns and the like. There should be a version field in your database somewhere that you can check against, and this function should check if an update is needed.

If an update is needed, this function should also migrate the database forward, or, in the unlikely event this requires user iteraction or data loss, error out and notify the user in the logs.

db_loc¶: str – the location of your database. Can be a url or a filename, or anything else really.

db_schema¶: str – The database’s schema. Can be read from an external file or simply added here.

delete_login_id(session_id)¶

Deletes session IDs from the database.

Deletes a session id from the database.

Parameters:	session_id (int) – The session id to delete.

get_all_shows()¶

Should get all shows from the database.

Returns:

A list of dictionaries describing shows from the scraper.

A database show should be a dictionary with the following structure, based on the schema defined in add_show.

id: database id (int)

aid: scraper id (int)

beid: backend id (int)

type: type of show, such as ‘tv’, ‘ova’, or ‘movie’. (str)

title: the official show title from the scraper (str)

alt_title: the shows alternate title, such as an english

translated title. (str)

synonyms: A pipe-separated (|) list of synonyms for the show (str)

total_episodes: The total number of episodes in the show (int)

next_episode: The next episode to air, according to the scraper (int)

next_episode_date:The day the next episode is due to air from the scraper (int)

start_date: The day the first episode starts, from the scraper (int)

genre: A comma separated list of show genres. (str)

studio: The primary studio producing the show (str)

description: A synopsis or description for the show (str)

link: A link to a page describing the show, such as anilist. (str)

image: A relative link to the show’s poster. (str)

airing: The airing status of the show according to the scraper (str)

season_name: The name of the season: winter, spring, summer, or fall (str)

starred: Whether the show is highlighted or not (int)

sub_groups: A pipe-separated (|) list of subgroups running the show (str)

get_login_id(session_id)¶

Gets a session ID from the database.

Should get a session id from the database if it hasn’t expired. Should delete it if it has.

Parameters:	session_id (int) – The session id to lookup in the database.
Returns:	Should return the session_id if it is valid, or None if it is not.

get_show(id=None, aid=None, beid=None)¶

Should get a single show from the database.

Should get a given single show from the database. Only one of the three arguments is required, and they should be handled in order: id, aid, beid.

Keyword Arguments:

id (int) – The database ID for the show
aid (int) – The scraper ID for the show
beid (int) – The backend ID for the show

Returns:

A database show dictionary with the following structure if it exists, None otherwise.

id: database id (int)

aid: scraper id (int)

beid: backend id (int)

type: type of show, such as ‘tv’, ‘ova’, or ‘movie’. (str)

title: the official show title from the scraper (str)

alt_title: the shows alternate title, such as an english

translated title. (str)

synonyms: A pipe-separated (|) list of synonyms for the show (str)

total_episodes: The total number of episodes in the show (int)

next_episode: The next episode to air, according to the scraper (int)

next_episode_date:The day the next episode is due to air from the scraper (int)

start_date: The day the first episode starts, from the scraper (int)

genre: A comma separated list of show genres. (str)

studio: The primary studio producing the show (str)

description: A synopsis or description for the show (str)

link: A link to a page describing the show, such as anilist. (str)

image: A relative link to the show’s poster. (str)

airing: The airing status of the show according to the scraper (str)

season_name: The name of the season: winter, spring, summer, or fall (str)

starred: Whether the show is highlighted or not (int)

sub_groups: A pipe-separated (|) list of subgroups running the show (str)

remove_show(id=None, aid=None, beid=None)¶

Show deleter.

Removes a given show from the database. Only one of the three arguments is required, and they should be handled in order: id, aid, beid.

Keyword Arguments:
	id (int) – The database ID for the show. aid (int) – The scraper ID for the show. beid (int) – The backend ID for the show.

search_show(term)¶

Show full-text search.

When this method is called, a full-text search is expected to be performed against the database. If a full-test search can not be performed with your database of choice, try returning None for this function.

Parameters: term (str) – The term to search for in the database.

Returns:

A list of dictionaries describing shows from the scraper.

A database show is a dictionary with the following structure.

id: database id (int)

aid: scraper id (int)

beid: backend id (int)

type: type of show, such as ‘tv’, ‘ova’, or ‘movie’. (str)

title: the official show title from the scraper (str)

alt_title: the shows alternate title, such as an english

translated title. (str)

synonyms: A pipe-separated (|) list of synonyms of the show (str)

total_episodes: The total number of episodes in the show (int)

next_episode: The next episode to air, according to the scraper (int)

next_episode_date:The day the next episode is due to air from the scraper (int)

start_date: The day the first episode starts, from the scraper (int)

genre: A comma separated list of show genres. (str)

studio: The primary studio producing the show (str)

description: A synopsis or description for the show (str)

link: A link to a page describing the show, such as anilist. (str)

image: A relative link to the show’s poster. (str)

airing: The airing status of the show according to the scraper (str)

season_name: The name of the season: winter, spring, summer, or fall (str)

starred: Whether the show is highlighted or not (int)

sub_groups: A pipe-separated (|) list of subgroups running the show (str)

class aniping.plugins.Scraper(config, plugin_manager)¶

Base scraper class.

Extend this class if you are making a Scraper plugin.

Scrapers are used to collect the list of shows airing in a given season, as well as their descriptions, air dates, images, and most of the other metadata. Most of this class is usually run in a separate, spawned thread to download information without blocking the web server.

Examples of scrapers include anilist, myanimelist, or hummingbird.

Note

Check the AniPlugin Class documentation for details on what must be included with all plugins. This documentation only describes what is needed with search engine plugins.

get_shows_by_category(search_results=None)¶

Gets show from the database and backend by category.

Should gets all shows from the DB and seperates into watching, tv, movies, and specials. You’ll probably need to contact the backend to get shows being watched.

This is a scraper function because it relies on categories that should be provided by the scraper. However, they should be separated into the 4 described below.

Keyword Arguments:
	search_results (str) – A list of database shows to parse into the separate lists instead of all shows. When none, should return all shows from db using `self.db("get_all_shows")`
Returns:	tuple. 4 lists of shows. watching – Shows currently being watched. airing – TV shows being aired. specials – TV and Web Specials (OVA, ONA, etc.) airing or due to air. movies – Movies airing or due to premiere.

scrape_shows()¶

Gets shows from the scraper service and adds them to the database.

Scraper is a bit of a misnomer, but don’t worry about that.

This should check your scraper service for all shows airing this season and either add them to the database or update them if they are already there. It should delete anything in the database that is not airing - the back end should keep track of shows that have not yet finished but still ongoing.

This will almost always be run in a separate thread from the main server instance, so keep that in mind when building and debugging, because things like “print” may not work as expected.

This will run weekly or as configured.

url¶: str – Should return the URL of your scraper.

class aniping.plugins.SearchEngine(config, plugin_manager)¶

Base Search Engine Class.

Extend this class if you are making a SearchEngine plugin.

Search engines are only used by aniping to find specific sub and release groups that are work on a given show. Examples of search engines include Nyaa Torrents or Google if you’re ambitious.

Note

Check the AniPlugin Class documentation for details on what must be included with all plugins. This documentation only describes what is needed with search engine plugins.

results(query)¶

Searches for a show and returns results.

This function will search the search engine for a given query, typically a show title.

Parameters:	query (str) – The query to pass to the search engine. Typically a show title.
Returns:	Should return a tuple with two lists. groups - A list of subgroups parsed from search results. results - The raw search results.

url¶: str – Should return the URL of your search engine.

aniping.plugins¶

`aniping.plugins`¶