PyMarvel Documentation

Transcription

1 PyMarvel Documentation Release Garrett Pennington September 03, 2015

2

3 Contents 1 API Marvel API to PyMarvel 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 Documentation Installation Basic Usage Response Anatomy Related Resources Pagination Contributing Licensing 43 Python Module Index 45 i

4 ii

5 Python wrapper for the Marvel API Contents 1

6 2 Contents

7 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

8 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

9 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

10 6 Chapter 1. API

11 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( ) >>> print cdw.data.count 1 >>> print cdw.data.results[0].name Wolverine 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.count 1401 >>> for result in cdw.data.results:... print result.name Aginar Air-Walker (Gabriel Lan) Ajak Ajaxis Akemi get_comic(id) Fetches a single comic by id. get /v1/public/comics/{comicid} 7

12 Parameters id ID of Comic Returns ComicDataWrapper >>> m = Marvel(public_key, private_key) >>> cdw = m.get_comic( ) >>> print cdw.data.count 1 >>> print cdw.data.result.name Some 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.count 10 >>> print cdw.data.results[0].name Some 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.count 1 >>> print cdw.data.result.fullname Stan 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="1 >>> print cdw.data.total 25 >>> print cdw.data.results[0].fullname Alvin 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

13 >>> m = Marvel(public_key, private_key) >>> response = m.get_event(253) >>> print response.data.result.title Infinity 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: >>> #wolverine's id: >>> m = Marvel(public_key, private_key) >>> response = m.get_events(characters=" , ") >>> print response.data.total 38 >>> events = response.data.results >>> print events[1].title Age 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: >>> m = Marvel(public_key, private_key) >>> response = m.get_series(characters=" ") >>> print response.data.total 435 >>> series = response.data.results >>> print series[0].title 5 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.title 5 Ronin (2010) get_stories(*args, **kwargs) Fetches lists of stories. get /v1/public/stories Returns StoryDataWrapper 9

14 >>> #Find all the stories that involved both Hulk and Wolverine >>> #hulk's id: >>> #wolverine's id: >>> m = Marvel(public_key, private_key) >>> response = m.get_stories(characters=" , ") >>> print response.data.total 4066 >>> stories = response.data.results >>> print stories[1].title Cover #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.title Caught in the heart of a nuclear explosion, mild-mannered scientist Bruce Banner finds himse 10 Chapter 2. Marvel Module

15 CHAPTER 3 Core Module class marvel.core.datacontainer(marvel, dict) Base DataContainer count The 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 a Character 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 limit The 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). offset The requested offset (number of skipped results) of the call. Returns int resource_url() Returns str Resource URL 11

16 result Returns the first item in the results list. Useful for methods that should return only one results. Returns marvel.marvelobject str_to_datetime(_str) Converts T17:40: format to datetime object to_dict() Returns datetime Returns dict Dictionary representation of the Resource total The total number of resources available given the current filter set. Returns int class marvel.core.datawrapper(marvel, dict, params=none) Base DataWrapper code The HTTP status code of the returned result. Returns int etag A digest value of the content returned by the call. Returns str get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs) Takes a related resource Class and returns the related resource DataWrapper. For Example: Given a Character 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 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). resource_url() Returns str Resource URL status A string description of the call status. Returns str 12 Chapter 3. Core Module

17 to_dict() Returns dict Dictionary representation of the Resource class marvel.core.image(marvel, dict) extension The file extension for the image. Returns str get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs) Takes a related resource Class and returns the related resource DataWrapper. For Example: Given a Character 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 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). path The directory path of to the image. Returns str resource_url() to_dict() Returns str Resource URL Returns dict Dictionary representation of the Resource class marvel.core.list(marvel, dict) Base List object available The number of total available resources in this list. Will always be greater than or equal to the returned value. Returns int collectionuri The path to the full list of resources in this collection. Returns str 13

18 get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs) Takes a related resource Class and returns the related resource DataWrapper. For Example: Given a Character 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 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). resource_url() Returns str Resource URL returned The number of resources returned in this collection (up to 20). to_dict() Returns int Returns dict Dictionary representation of the Resource class marvel.core.marvelobject(marvel, dict) Base class for all Marvel API classes get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs) Takes a related resource Class and returns the related resource DataWrapper. For Example: Given a Character 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 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. 14 Chapter 3. Core Module

19 _Class (core.marvelobject) The Resource class to create a list of (Comic, Creator, etc). Returns list List of Resource instances (Comic, Creator, etc). classmethod resource_url() to_dict() Returns str Resource URL Returns dict Dictionary representation of the Resource class marvel.core.summary(marvel, dict) Base Summary object get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs) Takes a related resource Class and returns the related resource DataWrapper. For Example: Given a Character 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 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). name The canonical name of the resource. Returns str resourceuri The path to the individual resource. Returns str resource_url() to_dict() Returns str Resource URL Returns dict Dictionary representation of the Resource class marvel.core.textobject(marvel, dict) get_related_resource(_self, _Class, _ClassDataWrapper, *args, **kwargs) Takes a related resource Class and returns the related resource DataWrapper. For Example: Given a Character instance, return a ComicsDataWrapper related to that character. /character/{characterid}/comics 15

20 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 language The IETF language tag denoting the language the text object is written in. Returns str 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). resource_url() text The text. to_dict() Returns str Resource URL Returns str Returns dict Dictionary representation of the Resource type The canonical type of the text object (e.g. solicit text, preview text, etc.). Returns str 16 Chapter 3. Core Module

21 CHAPTER 4 Character Module Coming Soon 17

22 18 Chapter 4. Character Module

23 CHAPTER 5 Comic Module Coming Soon 19

24 20 Chapter 5. Comic Module

25 CHAPTER 6 Creator Module Coming Soon 21

26 22 Chapter 6. Creator Module

27 CHAPTER 7 Story Module Coming Soon 23

28 24 Chapter 7. Story Module

29 CHAPTER 8 Series Module Coming Soon 25

30 26 Chapter 8. Series Module

31 CHAPTER 9 Event Module Coming Soon 27

32 28 Chapter 9. Event Module

33 CHAPTER 10 Documentation Read the full documentation. 29

34 30 Chapter 10. Documentation

35 CHAPTER 11 Installation Use pip: pip install PyMarvel or: easy_install PyMarvel Python Package Index. 31

36 32 Chapter 11. Installation

37 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.status Ok >>> print character_data_wrapper.data.total 1402 >>> for character in character_data_wrapper.data.results >>> print character.name Aginar Air-Walker (Gabriel Lan) Ajak Ajaxis Akemi 33

38 34 Chapter 12. Basic Usage

39 CHAPTER 13 Response Anatomy Requesting a resource returns a DataWrapper, which containers information about the the success of response. The data 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 to retrieve the first (or only) item in the list. This is useful for methods like get_comic(some_comic_id) where only 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": , "name": "Magneto (X-Men: Battle of the Atom)", ---- Character "description": "", "modified": " T19:43: ",... 35

40 36 Chapter 13. Response Anatomy

41 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=" ").data.result.get_characters().data.result.get_com would be the equivalent to calling:

42 38 Chapter 14. Related Resources

43 CHAPTER 15 Pagination >>> xmen = m.get_single_series(403).data.results.get_characters(limit=5) >>> for xm in xmen.data.results:... print xm.name Archangel Banshee Beast Bishop Black Panther >>> more_xmen = xmen.next() >>> for xm in more_xmen.data.results:... print xm.name Cable Cannonball Colossus Cyclops Emma Frost 39

44 40 Chapter 15. Pagination

45 CHAPTER 16 Contributing Clone the repo at Feel free to log issues in Github or, better yet, submit a Pull Request against the develop branch. 41

46 42 Chapter 16. Contributing

47 CHAPTER 17 Licensing PyMarvel is distributed under the MIT License. genindex modindex search 43

48 44 Chapter 17. Licensing

49 Python Module Index m marvel.core, 11 marvel.marvel, 7 45

50 46 Python Module Index

51 Index A available (marvel.core.list attribute), 13 C code (marvel.core.datawrapper attribute), 12 collectionuri (marvel.core.list attribute), 13 count (marvel.core.datacontainer attribute), 11 D DataContainer (class in marvel.core), 11 DataWrapper (class in marvel.core), 12 E etag (marvel.core.datawrapper attribute), 12 extension (marvel.core.image attribute), 13 G get_character() (marvel.marvel.marvel method), 7 get_characters() (marvel.marvel.marvel method), 7 get_comic() (marvel.marvel.marvel method), 7 get_comics() (marvel.marvel.marvel method), 8 get_creator() (marvel.marvel.marvel method), 8 get_creators() (marvel.marvel.marvel method), 8 get_event() (marvel.marvel.marvel method), 8 get_events() (marvel.marvel.marvel method), 9 get_related_resource() (marvel.core.datacontainer method), 11 get_related_resource() (marvel.core.datawrapper method), 12 get_related_resource() (marvel.core.image method), 13 get_related_resource() (marvel.core.list method), 13 get_related_resource() (marvel.core.marvelobject method), 14 get_related_resource() (marvel.core.summary method), 15 get_related_resource() (marvel.core.textobject method), 15 get_series() (marvel.marvel.marvel method), 9 get_single_series() (marvel.marvel.marvel method), 9 get_stories() (marvel.marvel.marvel method), 9 get_story() (marvel.marvel.marvel method), 10 I Image (class in marvel.core), 13 L language (marvel.core.textobject attribute), 16 limit (marvel.core.datacontainer attribute), 11 List (class in marvel.core), 13 list_to_instance_list() (marvel.core.datacontainer method), 11 list_to_instance_list() (marvel.core.datawrapper method), 12 list_to_instance_list() (marvel.core.image method), 13 list_to_instance_list() (marvel.core.list method), 14 list_to_instance_list() (marvel.core.marvelobject method), 14 list_to_instance_list() (marvel.core.summary method), 15 list_to_instance_list() (marvel.core.textobject method), 16 M Marvel (class in marvel.marvel), 7 marvel.core (module), 11 marvel.marvel (module), 7 MarvelObject (class in marvel.core), 14 N name (marvel.core.summary attribute), 15 O offset (marvel.core.datacontainer attribute), 11 P path (marvel.core.image attribute), 13 R resource_url() (marvel.core.datacontainer method), 11 resource_url() (marvel.core.datawrapper method), 12 47

52 resource_url() (marvel.core.image method), 13 resource_url() (marvel.core.list method), 14 resource_url() (marvel.core.marvelobject class method), 15 resource_url() (marvel.core.summary method), 15 resource_url() (marvel.core.textobject method), 16 resourceuri (marvel.core.summary attribute), 15 result (marvel.core.datacontainer attribute), 11 returned (marvel.core.list attribute), 14 S status (marvel.core.datawrapper attribute), 12 str_to_datetime() (marvel.core.datacontainer method), 12 Summary (class in marvel.core), 15 T text (marvel.core.textobject attribute), 16 TextObject (class in marvel.core), 15 to_dict() (marvel.core.datacontainer method), 12 to_dict() (marvel.core.datawrapper method), 12 to_dict() (marvel.core.image method), 13 to_dict() (marvel.core.list method), 14 to_dict() (marvel.core.marvelobject method), 15 to_dict() (marvel.core.summary method), 15 to_dict() (marvel.core.textobject method), 16 total (marvel.core.datacontainer attribute), 12 type (marvel.core.textobject attribute), Index