PyPKM is a Python package for creating, editing, and manipulating individual Pokémon file data (commonly referred to as PKM or .pkm files). The goal of this project is to allow a cross-platform way to easily work with these files.

PyPKM supports generation IV and generation V PKM files.

To install PyPKM, download and unarchive the package from its git repository. Then, you can either cd into the newly-created directory and run python setup.py install to install in your global Python path, or you can enter the directory and manually copy the pypkm subdirectory to a place in your Python path. PyPKM requires Construct==2.06 to parse file data.

First, import the pypkm package:

>>> import pypkm

Then, create or load a PKM file (making sure to specify the file's game generation):

# Create from scratch
>>> my_pkm = pypkm.new(gen=4)

# Load from data
>>> pkm_data = open('/path/to/MyPokemon.pkm', 'r').read()
>>> my_pkm = pypkm.load(gen=4, data=pkm_data)

From here, you can edit your Pokémon's data by calling attributes of the my_pkm instance. For example, to give your Pokémon the Leftovers item to hold:

>>> my_pkm.item = 234

To teach your Pokémon the Roar of Time move:

>>> my_pkm.moves.move1 = 459

To see your Pokémon trainer's secret ID:

>>> my_pkm.ot_secret_id
65534

You might even want to change your Pokémon's species all together:

>>> my_pkm.id = 94

As you can tell, you need to know the correct index number for most editing. A proper API reference will be made available in time. Until then, refer to the Struct declaration in pypkm.structs.

If you have GTS data, you can edit that as well:

>>> gts_data = open('/path/to/gts_pkm.pkm.proper', 'r').open()
>>> proper_pkm = pypkm.load(gen=4, data=gts_data)

>>> proper_pkm.level
5

>>> proper_pkm.ot_name
u'Trainer'

PyPKM also handles converting data. You can convert PC box data to party data, to/from GTS server-sent data, and to/from GTS client-sent data. The list of conversion methods are as follows:

• .togen5() - converts Gen 4 data to Gen 5
• .toparty() - adds battle data
• .togtsserver() - converts to data sent by the GTS server
• .togtsclient() - converts to data sent by the DS
• .topkm() - converts GTS data to a Pkm object

If you've edited the data, you probably want to save. PyPKM does not handle saving data; you must save the file yourself. However, to convert an object into a string of byte data:

# you can call tostring() to return byte data
>>> my_pkm.tostring()

If you'd like to contribute, you can do so at my git repository. I'd love to hear any bugs or feature requests you have.

The folks at Project Pokemon for all of their research into the structure of Pokémon data.

maxg for answering my questions.

Veekun for looking over my code, introducing me to Construct, and providing an awesome database of Pokémon information.

Stephen Anthony Uy for his pycrypto module. Somehow I came across this module whilst looking for a way to encrypt and decrypt Pokémon data, and it's been a huge help (the shuffle() function comes directly from his work).