API

The following section outlines the API of Minoshiro.

Default Logger

get_default_logger()

Return a basic default logging.Logger

Returns

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

Minoshiro

class Minoshiro(db_controller, *, 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.
  • 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(db_config = None, pool=None, *, schema='minoshiro', cache_pages=0, logger=None, loop=None)

This method is a coroutine

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

Parameters

  • 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 minoshiro

  • 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.

  • 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 Minoshiro with PostgresController as the database controller.

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

This method is a coroutine

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

Parameters

  • 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.
  • 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 Minoshiro with PostgresController as the database controller.

pre_cache(cache_pages)

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.
yield_data(query, medium, sites, *, timeout=3)

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
  • timeout(Optional[int]) - The timeout in seconds for each HTTP request. Defualt is 3.

Returns

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

get_data(query, medium, sites, *, timeout=3)

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
  • timeout(Optional[int]) - The timeout in seconds for each HTTP request. Defualt is 3.

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

Minoshiro 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='minoshiro')

To be able to integrate with an existing database, all tables for minoshiro will be put under the minoshiro 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='minoshiro')

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 minoshiro

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