PyMarvel Documentation - Read the Docs · 2019-04-02 · 5 Comic Module 19 6 Creator Module 21 7...

PyMarvel DocumentationRelease 0.1.0

Garrett Pennington

September 03, 2015

Contents

1 API 31.1 Marvel API to PyMarvel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Marvel Module 7

3 Core Module 11

4 Character Module 17

5 Comic Module 19

6 Creator Module 21

7 Story Module 23

8 Series Module 25

9 Event Module 27

10 Documentation 29

11 Installation 31

12 Basic Usage 33

13 Response Anatomy 35

14 Related Resources 37

15 Pagination 39

16 Contributing 41

17 Licensing 43

Python Module Index 45

i

PyMarvel Documentation, Release 0.1.0

Python wrapper for the Marvel API

Contents 1


2 Contents

CHAPTER 1

API

Python wrapper for the Marvel API

1.1 Marvel API to PyMarvel

get /v1/public/characters Fetches lists of characters.

Marvel.get_characters()

get /v1/public/characters/{characterId} Fetches a single character by id.

Marvel.get_character()

get /v1/public/characters/{characterId}/comics Fetches lists of comics filtered by a character id.

Character.get_comics()

get /v1/public/characters/{characterId}/events Fetches lists of events filtered by a character id.

Character.get_events()

get /v1/public/characters/{characterId}/series Fetches lists of series filtered by a character id.

Character.get_series()

get /v1/public/characters/{characterId}/stories Fetches lists of stories filtered by a character id.

Character.get_stories()

get /v1/public/comics Fetches lists of comics.

X Marvel.get_comics()

get /v1/public/comics/{comicId} Fetches a single comic by id.

X Marvel.get_comic()

get /v1/public/comics/{comicId}/characters Fetches lists of characters filtered by a comic id.

Comic.get_characters()

get /v1/public/comics/{comicId}/creators Fetches lists of creators filtered by a comic id.

Comic.get_creators()

get /v1/public/comics/{comicId}/events Fetches lists of events filtered by a comic id.

Comic.get_events()

3


get /v1/public/comics/{comicId}/stories Fetches lists of stories filtered by a comic id.

Comic.get_stories()

get /v1/public/creators Fetches lists of creators.

Marvel.get_creators()

get /v1/public/creators/{creatorId} Fetches a single creator by id.

Marvel.get_creator()

get /v1/public/creators/{creatorId}/comics Fetches lists of comics filtered by a creator id.

Creator.get_comics()

get /v1/public/creators/{creatorId}/events Fetches lists of events filtered by a creator id.

Creator.get_events()

get /v1/public/creators/{creatorId}/series Fetches lists of series filtered by a creator id.

Creator.get_series()

get /v1/public/creators/{creatorId}/stories Fetches lists of stories filtered by a creator id.

Creator.get_stories()

get /v1/public/events Fetches lists of events.

Marvel.get_events()

get /v1/public/events/{eventId} Fetches a single event by id.

Marvel.get_event()

get /v1/public/events/{eventId}/characters Fetches lists of characters filtered by an event id.

Event.get_characters()

get /v1/public/events/{eventId}/comics Fetches lists of comics filtered by an event id.

Event.get_comics()

get /v1/public/events/{eventId}/creators Fetches lists of creators filtered by an event id.

Event.get_creators()

get /v1/public/events/{eventId}/series Fetches lists of series filtered by an event id.

Event.get_series()

get /v1/public/events/{eventId}/stories Fetches lists of stories filtered by an event id.

Event.get_stories()

get /v1/public/series Fetches lists of series.

Marvel.get_series()

get /v1/public/series/{seriesId} Fetches a single comic series by id.

Marvel.get_series()

get /v1/public/series/{seriesId}/characters Fetches lists of characters filtered by a series id.

Series.get_characters()

get /v1/public/series/{seriesId}/comics Fetches lists of comics filtered by a series id.

Series.get_comics()

4 Chapter 1. API


get /v1/public/series/{seriesId}/creators Fetches lists of creators filtered by a series id.

Series.get_creators()

get /v1/public/series/{seriesId}/events Fetches lists of events filtered by a series id.

Series.get_events()

get /v1/public/series/{seriesId}/stories Fetches lists of stories filtered by a series id.

Series.get_stories()

get /v1/public/stories Fetches lists of stories.

Marvel.get_stories()

get /v1/public/stories/{storyId} Fetches a single comic story by id.

Marvel.get_story()

get /v1/public/stories/{storyId}/characters Fetches lists of characters filtered by a story id.

Story.get_characters()

get /v1/public/stories/{storyId}/comics Fetches lists of comics filtered by a story id.

Story.get_comics()

get /v1/public/stories/{storyId}/creators Fetches lists of creators filtered by a story id.

Story.get_creators()

get /v1/public/stories/{storyId}/events Fetches lists of events filtered by a story id.

Story.get_events()

• genindex

• modindex

• search

1.1. Marvel API to PyMarvel 5


6 Chapter 1. API

CHAPTER 2

Marvel Module

class marvel.marvel.Marvel(public_key, private_key)Marvel API class

This class provides methods to interface with the Marvel API

>>> m = Marvel("acb123....", "efg456...")

get_character(id)Fetches a single character by id.

get /v1/public/characters

Parameters id – ID of Character

Returns CharacterDataWrapper

>>> m = Marvel(public_key, private_key)>>> cdw = m.get_character(1009718)>>> print cdw.data.count1>>> print cdw.data.results[0].nameWolverine

get_characters(*args, **kwargs)Fetches lists of comic characters with optional filters.

get /v1/public/characters/{characterId}

Returns CharacterDataWrapper

>>> m = Marvel(public_key, private_key)>>> cdw = m.get_characters(orderBy="name,-modified", limit="5", offset="15")>>> print cdw.data.count1401>>> for result in cdw.data.results:... print result.nameAginarAir-Walker (Gabriel Lan)AjakAjaxisAkemi

get_comic(id)Fetches a single comic by id.

get /v1/public/comics/{comicId}

7


Parameters id – ID of Comic

Returns ComicDataWrapper

>>> m = Marvel(public_key, private_key)>>> cdw = m.get_comic(1009718)>>> print cdw.data.count1>>> print cdw.data.result.nameSome Comic

get_comics(*args, **kwargs)Fetches list of comics.

get /v1/public/comics

Returns ComicDataWrapper

>>> m = Marvel(public_key, private_key)>>> cdw = m.get_comics(orderBy="issueNumber,-modified", limit="10", offset="15")>>> print cdw.data.count10>>> print cdw.data.results[0].nameSome Comic

get_creator(id)Fetches a single creator by id.

get /v1/public/creators/{creatorId}

Parameters id – ID of Creator

Returns CreatorDataWrapper

>>> m = Marvel(public_key, private_key)>>> cdw = m.get_creator(30)>>> print cdw.data.count1>>> print cdw.data.result.fullNameStan Lee

get_creators(*args, **kwargs)Fetches lists of creators.

get /v1/public/creators

Returns CreatorDataWrapper

>>> m = Marvel(public_key, private_key)>>> cdw = m.get_creators(lastName="Lee", orderBy="firstName,-modified", limit="5", offset="15")>>> print cdw.data.total25>>> print cdw.data.results[0].fullNameAlvin Lee

get_event(id)Fetches a single event by id.

get /v1/public/event/{eventId}

Parameters id – ID of Event

Returns EventDataWrapper

8 Chapter 2. Marvel Module


>>> m = Marvel(public_key, private_key)>>> response = m.get_event(253)>>> print response.data.result.titleInfinity Gauntlet

get_events(*args, **kwargs)Fetches lists of events.

get /v1/public/events

Returns EventDataWrapper

>>> #Find all the events that involved both Hulk and Wolverine>>> #hulk's id: 1009351>>> #wolverine's id: 1009718>>> m = Marvel(public_key, private_key)>>> response = m.get_events(characters="1009351,1009718")>>> print response.data.total38>>> events = response.data.results>>> print events[1].titleAge of Apocalypse

get_series(*args, **kwargs)Fetches lists of events.

get /v1/public/events

Returns SeriesDataWrapper

>>> #Find all the series that involved Wolverine>>> #wolverine's id: 1009718>>> m = Marvel(public_key, private_key)>>> response = m.get_series(characters="1009718")>>> print response.data.total435>>> series = response.data.results>>> print series[0].title5 Ronin (2010)

get_single_series(id)Fetches a single comic series by id.

get /v1/public/series/{seriesId}

Parameters id – ID of Series

Returns SeriesDataWrapper

>>> m = Marvel(public_key, private_key)>>> response = m.get_single_series(12429)>>> print response.data.result.title5 Ronin (2010)

get_stories(*args, **kwargs)Fetches lists of stories.

get /v1/public/stories

Returns StoryDataWrapper

9


>>> #Find all the stories that involved both Hulk and Wolverine>>> #hulk's id: 1009351>>> #wolverine's id: 1009718>>> m = Marvel(public_key, private_key)>>> response = m.get_stories(characters="1009351,1009718")>>> print response.data.total4066>>> stories = response.data.results>>> print stories[1].titleCover #477

get_story(id)Fetches a single story by id.

get /v1/public/stories/{storyId}

Parameters id – ID of Story

Returns StoryDataWrapper

>>> m = Marvel(public_key, private_key)>>> response = m.get_story(29)>>> print response.data.result.titleCaught in the heart of a nuclear explosion, mild-mannered scientist Bruce Banner finds himself...

10 Chapter 2. Marvel Module

CHAPTER 3

Core Module

class marvel.core.DataContainer(marvel, dict)Base DataContainer

countThe total number of results returned by this call.

Returns int

get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs)Takes a related resource Class and returns the related resource DataWrapper. For Example: Given aCharacter instance, return a ComicsDataWrapper related to that character. /character/{characterId}/comics

Parameters

• _Class (core.MarvelObject) – The Resource class retrieve

• _ClassDataWrapper – The Resource response object

• kwargs (dict) – dict of query params for the API

Returns DataWrapper – DataWrapper for requested Resource

limitThe requested result limit.

Returns int

list_to_instance_list(_self, _list, _Class)Takes a list of resource dicts and returns a list of resource instances, defined by the _Class param.

Parameters

• _self (core.MarvelObject) – Original resource calling the method

• _list (list) – List of dicts describing a Resource.

• _Class (core.MarvelObject) – The Resource class to create a list of (Comic, Creator,etc).

Returns list – List of Resource instances (Comic, Creator, etc).

offsetThe requested offset (number of skipped results) of the call.

Returns int

resource_url()

Returns str – Resource URL

11


resultReturns the first item in the results list. Useful for methods that should return only one results.

Returns marvel.MarvelObject

str_to_datetime(_str)Converts ‘2013-11-20T17:40:18-0500’ format to ‘datetime’ object

Returns datetime

to_dict()

Returns dict – Dictionary representation of the Resource

totalThe total number of resources available given the current filter set.

Returns int

class marvel.core.DataWrapper(marvel, dict, params=None)Base DataWrapper

codeThe HTTP status code of the returned result.

Returns int

etagA digest value of the content returned by the call.

Returns str


Parameters






Parameters





resource_url()


statusA string description of the call status.

Returns str

12 Chapter 3. Core Module


to_dict()


class marvel.core.Image(marvel, dict)

extensionThe file extension for the image.

Returns str


Parameters






Parameters





pathThe directory path of to the image.

Returns str

resource_url()


to_dict()


class marvel.core.List(marvel, dict)Base List object

availableThe number of total available resources in this list. Will always be greater than or equal to the “returned”value.

Returns int

collectionURIThe path to the full list of resources in this collection.

Returns str

13



Parameters






Parameters





resource_url()


returnedThe number of resources returned in this collection (up to 20).

Returns int

to_dict()


class marvel.core.MarvelObject(marvel, dict)Base class for all Marvel API classes


Parameters






Parameters







classmethod resource_url()


to_dict()


class marvel.core.Summary(marvel, dict)Base Summary object


Parameters






Parameters





nameThe canonical name of the resource.

Returns str

resourceURIThe path to the individual resource.

Returns str

resource_url()


to_dict()


class marvel.core.TextObject(marvel, dict)


15


Parameters





languageThe IETF language tag denoting the language the text object is written in.

Returns str


Parameters





resource_url()


textThe text.

Returns str

to_dict()


typeThe canonical type of the text object (e.g. solicit text, preview text, etc.).

Returns str


CHAPTER 4

Character Module

Coming Soon

17


18 Chapter 4. Character Module

CHAPTER 5

Comic Module

Coming Soon

19


20 Chapter 5. Comic Module

CHAPTER 6

Creator Module

Coming Soon

21


22 Chapter 6. Creator Module

CHAPTER 7

Story Module

Coming Soon

23


24 Chapter 7. Story Module

CHAPTER 8

Series Module

Coming Soon

25


26 Chapter 8. Series Module

CHAPTER 9

Event Module

Coming Soon

27


28 Chapter 9. Event Module

CHAPTER 10

Documentation

Read the full documentation.

29

http://pymarvel.readthedocs.org


30 Chapter 10. Documentation

CHAPTER 11

Installation

Use pip:

pip install PyMarvel

or:

easy_install PyMarvel

Python Package Index.

31

https://pypi.python.org/pypi/PyMarvel


32 Chapter 11. Installation

CHAPTER 12

Basic Usage

Create a Marvel instance using your public and private api keys:

>>> from marvel.marvel import Marvel>>> m = Marvel(public_key, private_key)>>> character_data_wrapper = m.get_characters(orderBy="name,-modified", limit="5", offset="15")>>> print character_data_wrapper.statusOk>>> print character_data_wrapper.data.total1402>>> for character in character_data_wrapper.data.results>>> print character.nameAginarAir-Walker (Gabriel Lan)AjakAjaxisAkemi

33


34 Chapter 12. Basic Usage

CHAPTER 13

Response Anatomy

Requesting a resource returns a DataWrapper, which containers information about the the success of response. Thedata property of a DataWrapper is a DataContainer, which contains information about the set of resources returned.The results property of a DataContainer is a List of Resources (Character, Comic, Event, etc).

Note: The results property returns a List, even if only one item is returned. You can use result property toretrieve the first (or only) item in the list. This is useful for methods like get_comic(some_comic_id) whereonly only Comic is expected. result is equivalent to results[0].

>>> m = Marvel(public_key, private_key)>>> character_data_wrapper = m.get_characters(limit="10", offset="700")>>> print(character_data_wrapper)<marvel.character.CharacterDataWrapper object>>>> print(character_data_wrapper.data)<marvel.character.CharacterDataContainer object>>>> print(character_data_wrapper.data.results[0])<marvel.character.Character object>

The json response maps like this:

{ __"code": 200, |"status": "Ok", |---- CharacterDataWrapper"etag": "e59a70a964ab45cc40948dcd3fb7faa0783bcae7", |"data": __|

{ __ \/"offset": 700, |"limit": 10, |"total": 1402, |---- CharacterDataContainer"count": 10, |"results": [ __|

{ __ \/"id": 1017477, |"name": "Magneto (X-Men: Battle of the Atom)", |---- Character"description": "", |"modified": "2014-01-15T19:43:09-0500", __|...

35


36 Chapter 13. Response Anatomy

CHAPTER 14

Related Resources

Find Stan Lee’s comics:

>>> stan_lee = m.get_creator(30).data.result>>> comics = stan_lee.get_comics()

You can chain methods into one line:

>>> comics = m.get_creator(30).data.result.get_comics()

or even:

>>> events = self.m.get_series(characters="1009718").data.result.get_characters().data.result.get_comics().data.results.get_creators().data.result.get_events()

would be the equivalent to calling:

http://gateway.marvel.com/v1/public/series?characters=100971http://gateway.marvel.com/v1/public/series/15276/charactershttp://gateway.marvel.com/v1/public/characters/1009351/comicshttp://gateway.marvel.com/v1/public/comics/50372/creatorshttp://gateway.marvel.com/v1/public/creators/4600/events

37


38 Chapter 14. Related Resources

CHAPTER 15

Pagination

>>> xmen = m.get_single_series(403).data.results.get_characters(limit=5)>>> for xm in xmen.data.results:... print xm.name

ArchangelBansheeBeastBishopBlack Panther

>>> more_xmen = xmen.next()>>> for xm in more_xmen.data.results:... print xm.name

CableCannonballColossusCyclopsEmma Frost

39


40 Chapter 15. Pagination

CHAPTER 16

Contributing

Clone the repo at http://github.com/gpennington/PyMarvel.

Feel free to log issues in Github or, better yet, submit a Pull Request against the develop branch.

41

http://github.com/gpennington/PyMarvel


42 Chapter 16. Contributing

CHAPTER 17

Licensing

PyMarvel is distributed under the MIT License.

• genindex

• modindex

• search

43


44 Chapter 17. Licensing

Python Module Index

mmarvel.core, 11marvel.marvel, 7

45


46 Python Module Index

Index

Aavailable (marvel.core.List attribute), 13

Ccode (marvel.core.DataWrapper attribute), 12collectionURI (marvel.core.List attribute), 13count (marvel.core.DataContainer attribute), 11

DDataContainer (class in marvel.core), 11DataWrapper (class in marvel.core), 12

Eetag (marvel.core.DataWrapper attribute), 12extension (marvel.core.Image attribute), 13

Gget_character() (marvel.marvel.Marvel method), 7get_characters() (marvel.marvel.Marvel method), 7get_comic() (marvel.marvel.Marvel method), 7get_comics() (marvel.marvel.Marvel method), 8get_creator() (marvel.marvel.Marvel method), 8get_creators() (marvel.marvel.Marvel method), 8get_event() (marvel.marvel.Marvel method), 8get_events() (marvel.marvel.Marvel method), 9get_related_resource() (marvel.core.DataContainer

method), 11get_related_resource() (marvel.core.DataWrapper

method), 12get_related_resource() (marvel.core.Image method), 13get_related_resource() (marvel.core.List method), 13get_related_resource() (marvel.core.MarvelObject

method), 14get_related_resource() (marvel.core.Summary method),

15get_related_resource() (marvel.core.TextObject method),

15get_series() (marvel.marvel.Marvel method), 9get_single_series() (marvel.marvel.Marvel method), 9get_stories() (marvel.marvel.Marvel method), 9

get_story() (marvel.marvel.Marvel method), 10

IImage (class in marvel.core), 13

Llanguage (marvel.core.TextObject attribute), 16limit (marvel.core.DataContainer attribute), 11List (class in marvel.core), 13list_to_instance_list() (marvel.core.DataContainer

method), 11list_to_instance_list() (marvel.core.DataWrapper

method), 12list_to_instance_list() (marvel.core.Image method), 13list_to_instance_list() (marvel.core.List method), 14list_to_instance_list() (marvel.core.MarvelObject

method), 14list_to_instance_list() (marvel.core.Summary method),

15list_to_instance_list() (marvel.core.TextObject method),

16

MMarvel (class in marvel.marvel), 7marvel.core (module), 11marvel.marvel (module), 7MarvelObject (class in marvel.core), 14

Nname (marvel.core.Summary attribute), 15

Ooffset (marvel.core.DataContainer attribute), 11

Ppath (marvel.core.Image attribute), 13

Rresource_url() (marvel.core.DataContainer method), 11resource_url() (marvel.core.DataWrapper method), 12

47


resource_url() (marvel.core.Image method), 13resource_url() (marvel.core.List method), 14resource_url() (marvel.core.MarvelObject class method),

15resource_url() (marvel.core.Summary method), 15resource_url() (marvel.core.TextObject method), 16resourceURI (marvel.core.Summary attribute), 15result (marvel.core.DataContainer attribute), 11returned (marvel.core.List attribute), 14

Sstatus (marvel.core.DataWrapper attribute), 12str_to_datetime() (marvel.core.DataContainer method),

12Summary (class in marvel.core), 15

Ttext (marvel.core.TextObject attribute), 16TextObject (class in marvel.core), 15to_dict() (marvel.core.DataContainer method), 12to_dict() (marvel.core.DataWrapper method), 12to_dict() (marvel.core.Image method), 13to_dict() (marvel.core.List method), 14to_dict() (marvel.core.MarvelObject method), 15to_dict() (marvel.core.Summary method), 15to_dict() (marvel.core.TextObject method), 16total (marvel.core.DataContainer attribute), 12type (marvel.core.TextObject attribute), 16

48 Index

PyMarvel Documentation - Read the Docs · 2019-04-02 · 5 Comic Module 19 6 Creator Module 21 7...

Documents

Transcript of PyMarvel Documentation - Read the Docs · 2019-04-02 · 5 Comic Module 19 6 Creator Module 21 7...