Usage

To use Pokepy in a project:

>>> import pokepy

API

Pokepy is composed of a single class, V2Client, which implements the whole v2 PokéAPI. This class is usually instantiated without parameters:

>>> client = pokepy.V2Client()

Unless you want to use the caching feature, which is discussed further below.

Each endpoint of PokéAPI is represented in V2Client by a get_<endpoint_name> method, all taking a single parameter (uid), which can be either an integer (for most endpoints) or a string.

The following is an exhaustive list of all the endpoints with links to their respective PokéAPI documentation:

• get_berry
• get_berry_firmness
• get_berry_flavor
• get_contest_type
• get_contest_effect
• get_super_contest_effect
• get_encounter_method
• get_encounter_condition
• get_encounter_condition_value
• get_evolution_chain
• get_evolution_trigger
• get_generation
• get_pokedex
• get_version
• get_version_group
• get_item
• get_item_attribute
• get_item_category
• get_item_fling_effect
• get_item_pocket
• get_location
• get_location_area
• get_pal_park_area
• get_region
• get_machine
• get_move
• get_move_ailment
• get_move_battle_style
• get_move_category
• get_move_damage_class
• get_move_learn_method
• get_move_target
• get_ability
• get_characteristic
• get_egg_group
• get_gender
• get_growth_rate
• get_nature
• get_pokeathlon_stat
• get_pokemon
• get_pokemon_color
• get_pokemon_form
• get_pokemon_habitat
• get_pokemon_shape
• get_pokemon_species
• get_stat
• get_type
• get_language

Each method returns an object containing as many python attributes as there are named attributes. Please refer to the PokéAPI documentation for more information on what each of these methods returns, its description and type.

Then you can start grabbing stuff from the API:

>>> mew = pokepy.V2Client().get_pokemon('mew')
>>> mew
<Pokemon - Mew>
>>> mew.name
mew

>>> kakuna = pokepy.V2Client().get_pokemon(14)
>>> kakuna
<Pokemon - Kakuna>
>>> kakuna.weigth
100

>>> cut = pokepy.V2Client().get_move(15)
>>> cut
<Move - Cut>
>>> cut.power
50

Some resources have subresources:

>>> kakuna = pokepy.V2Client().get_pokemon(14)
>>> kakuna
<Pokemon - Kakuna>
>>> kakuna.types
[<Pokemon_Type>, <Pokemon_Type>]
>>> kakuna.types[0].type.name
poison

>>> insomnia = pokepy.V2Client().get_ability(15)
>>> insomnia
<Ability - Insomnia>
>>> insomnia.effect_entries[0].short_effect
Prevents sleep.

Parameters

Most resources can be requested by using either the name or id of the resource:

>>> pokepy.V2Client().get_pokemon('rotom')
<Pokemon - Rotom>
>>> pokepy.V2Client().get_pokemon(479)
<Pokemon - Rotom>
>>> pokepy.V2Client().get_pokemon('479')
<Pokemon - Rotom>

Cache

If you use the API to get the same resources often, you can enable cache to avoid making unnecessary requests to the PokéAPI server. You can either enable memory-based or disk-based cache.

Memory-based

Memory-based cache is activated by passing in_memory to the cache parameter of V2Client. Resources obtained from the PokéAPI are then saved in RAM. Cache is kept per get method:

>>> client_mem_cache = pokepy.V2Client(cache='in_memory')

You can check the state of the cache in two ways: per get method or as a whole.

To check the state of the cache of a particular method, call the cache_info() of that get method:

>>> client_mem_cache.get_pokemon.cache_info()
CacheInfo(hits=0, misses=0, size=0)

To check the state of the cache as a whole (all get methods combined), call the cache_info() of V2Client:

>>> client_mem_cache.cache_info()
CacheInfo(hits=0, misses=0, size=0)

hits is the number of previously cached parametes which were returned, misses is the number given parameters not previously cached (which are now cached), and size is the total number of cached parameters.

When calling a certain endpoint, the cache_info reflects that call:

>>> kakuna = client_mem_cache.get_pokemon(14)
>>> client_mem_cache.get_pokemon.cache_info()
CacheInfo(hits=0, misses=1, size=1)

Calling the same resource as before with the same parameters will retrieve the cached resource instead of getting it from the server:

>>> kakuna = client_mem_cache.get_pokemon(14)
>>> client_mem_cache.get_pokemon.cache_info()
CacheInfo(hits=1, misses=1, size=1)

To clear the cache of a specific get method:

>>> client_mem_cache.get_pokemon.cache_clear()
>>> client_mem_cache.get_pokemon.cache_info()
CacheInfo(hits=0, misses=0, size=0)

To clear all cache:

>>> client_mem_cache.cache_clear()
>>> client_mem_cache.cache_info()
CacheInfo(hits=0, misses=0, size=0)

Disk-based

Disk-based cache is activated by passing in_disk to the cache parameter of V2Client. Resources obtained from the PokéAPI are then saved to disk. Cache is kept per get method:

>>> client_disk_cache = pokepy.V2Client(cache='in_disk', cache_location='/temp')

In this case it's possible to specify the cache directory with the cache_location parameter. A folder named pokepy_cache will be created inside the specified directory, where the cache of each get method will be located. If no cache directory is specified a system-appropriate cache directory is automatically determined by appdirs.

The methods used to check the state and clear the cache are the same as in the memory-based cache, including the global V2Client methods.

You can also check the cache directory, per get method:

>>> client_disk_cache.get_pokemon.cache_location()
/temp/pokepy_cache/39/cache

Or check the global cache directory:

>>> client_disk_cache.cache_location()
/temp/pokepy_cache/

Disk-based cache is reloaded automatically between runs if the same cache directory is specified.