API

The following section outlines the API of Roboragi.

Default Logger

get_default_logger()

Return a basic default logging.Logger

Returns

A basic logger with a logging.StreamHandler attatched and with level INFO

Roboragi

class Roboragi(db_controller, mal_config, *, logger=None, loop=None)

Represents the search instance.

It is suggested to use one of the class methods to create the instance if you wish to use one of the data controllers provided by the library.

Make sure you run the pre_cache() method if you initialized the class directly from the __init__ method.

Parameters

  • db_controller(DataController) - Any sub class of DataController will work here.

  • mal_config(dict) - A dict for MAL authorization.
    It must contain the keys:

    user: Your MAL username

    password: Your MAL password

    It may also contain a key description for the description you wish to use in the auth header.

    If this key is not present, the description defaults to: A Python library for anime search.

  • logger(Optional[logging.Logger]) - The logger object. If it’s not provided, will use the defualt logger provided by the library.

  • loop(Optional[Event loop]) - An asyncio event loop. If not provided will use the default event loop.

classmethod from_postgres(mal_config, db_config = None, pool=None, *, schema='roboragi', cache_pages=0, cache_mal_entries=0, logger=None, loop=None)

This method is a coroutine

Get an instance of Roboragi with PostgresController as the database controller.

Parameters

  • mal_config(dict) - A dict for MAL authorization.
    It must contain the keys:

    user: Your MAL username

    password: Your MAL password

    It may also contain a key description for the description you wish to use in the auth header.

    If this key is not present, the description defaults to: A Python library for anime search.

  • db_config(dict) - A dict of database config for the connection. It should contain the keys in keyword arguments for the asyncpg.connection.connect function.

    An example config might look like this:

    db_config = {
    "host": 'localhost',
    "port": '5432',
    "user": 'postgres',
    "database": 'postgres'
}

  • pool(Pool) - an existing asyncpg connection pool.

    One of db_config or pool must not be None.

  • schema(Optional[str]) - the name for the schema used. Defaults to roboragi

  • cache_pages(Optional[int]) - The number of pages of anime and manga from Anilist to cache before the instance is created. Each page contains 40 entries max.

  • cache_mal_entries(Optional[int]) - The number of MAL entries you wish to cache. cache_pages must be greater than 0 to cache MAL entries.

  • logger(Optional[logging.Logger]) - The logger object. If it’s not provided, will use the defualt logger provided by the library.

  • loop(Optional[Event loop]) - An asyncio event loop. If not provided will use the default event loop.

Returns

Instance of Roboragi with PostgresController as the database controller.

classmethod from_sqlite(mal_config, path, *, cache_pages=0, cache_mal_entries=0, logger=None, loop=None)

This method is a coroutine

Get an instance of Roboragi with SqliteController as the database controller.

Parameters

  • mal_config(dict) - A dict for MAL authorization.
    It must contain the keys:

    user: Your MAL username

    password: Your MAL password

    It may also contain a key description for the description you wish to use in the auth header.

    If this key is not present, the description defaults to: A Python library for anime search.

  • path(Union[str, pathlib.Path]) - The path to the SQLite3 database, can either be a string or a Pathlib Path object.

  • cache_pages(Optional[int]) - The number of pages of anime and manga from Anilist to cache before the instance is created. Each page contains 40 entries max.

  • cache_mal_entries(Optional[int]) - The number of MAL entries you wish to cache. cache_pages must be greater than 0 to cache MAL entries.

  • logger(Optional[logging.Logger]) - The logger object. If it’s not provided, will use the defualt logger provided by the library.

  • loop(Optional[Event loop]) - An asyncio event loop. If not provided will use the default event loop.

Returns

Instance of Roboragi with PostgresController as the database controller.

pre_cache(cache_pages, cache_mal_entries)

This method is a coroutine

Pre cache the database with anime and managa data.

This method is called by from_postgres() and from_sqlite(), so you do not need to call this method if you created ths class instance with those two methods.

Parameters

  • cache_pages(int) - Number of Anilist pages to cache. There are 40 entries per page.
  • cache_mal_entries(int) - Number of MAL entries you wish to cache.
yield_data(query, medium, sites)

This method is a coroutine

Yield the data for the search query from all sites.

Sites with no data found will be skipped.

Parameters

  • query(str) - the search query
  • medium(Medium) - the medium type
  • sites(Optional[Iterable[Site]]) - an iterable of sites desired. If None is provided, will search all sites by default

Returns

An asynchronous generator that yields the site and data in a tuple for all sites requested.

get_data(query, medium, sites)

This method is a coroutine

Get the data for the search query in a dict.

Sites with no data found will not be in the return value.

Parameters

  • query(str) - the search query
  • medium(Medium) - the medium type
  • sites(Optional[Iterable[Site]]) - an iterable of sites desired. If None is provided, will search all sites by default

Returns

Data for all sites in a dict {Site: data}

Note

When retrieving data from the result of this method, use the dict.get() method instead of square brackets.

Example:

results = await search_instance.get_data(
    'Non Non Biyori', Medium.ANIME
)

# Good
anilist = results.get(Site.ANILIST)

# Bad, might raise KeyError
anilist = results[Site.ANILIST]

Enums

Roboragi uses two enums to represent medium type and website.

class Site
MAL = 1
ANILIST = 2
ANIMEPLANET = 3
ANIDB = 4
KITSU = 5
MANGAUPDATES = 6
LNDB = 7
NOVELUPDATES = 8
VNDB = 9
class Medium
ANIME = 1
MANGA = 2
LN = 3
VN = 4

Database Controllers

class DataController(logger)

An ABC (abstract base class) that deals with database caching.

See Extending DatabaseController for details.

class PostgresController(pool, logger, schema='roboragi')

To be able to integrate with an existing database, all tables for roboragi will be put under the roboragi schema unless a different schema name is passed to the __init__ method.

Create the instance with the get_instance() method to make sure you have all the tables needed.

classmethod get_instance(logger, connect_kwargs=None, pool=None, schema='roboragi')

This method is a coroutine

Get a new instance of PostgresController

This method will create the appropriate tables needed.

Parameters

  • logger(Optional[logging.Logger]) - The logger object. If it’s not provided, will use the defualt logger provided by the library.

  • connect_kwargs(dict) - A dict of database config for the connection. It should contain the keys in keyword arguments for the asyncpg.connection.connect function.

    An example config might look like this:

    db_config = {
    "host": 'localhost',
    "port": '5432',
    "user": 'postgres',
    "database": 'postgres'
}

  • pool(Pool) - an existing asyncpg connection pool.

    One of db_config or pool must not be None.

  • schema(str) - the name for the schema used. Defaults to roboragi

Returns

a new instance of PostgresController

class SqliteController(path, logger, loop=None)

A SQLite3 data controller.

Create the instance with the get_instance() method to make sure you have all the tables needed.

classmethod get_instance(path, logger=None, loop=None)

This method is a coroutine

Get a new instance of SqliteController

This method will create the appropriate tables needed.

Parameters

  • path(Union[str, pathlib.Path]) - The path to the SQLite3 database, can either be a string or a Pathlib Path object.
  • logger(Optional[logging.Logger]) - The logger object. If it’s not provided, will use the defualt logger provided by the library.
  • loop(Optional[Event loop]) - An asyncio event loop. If not provided will use the default event loop.

Returns

A new instance of SqliteController