Merge pull request #97 from dmadisetti/master

Cleanup and landscape.io + Readme

.landscape.yaml

@@ -0,0 +1,14 @@
+doc-warnings: true
+test-warnings: false
+max-line-length: 120
+autodetect: true
+requirements:
+  - requirements.txt
+ignore-paths:
+  - proto
+  - POGOProtos
+ignore-patterns:
+  - ^.*_pb2\.py$
+python-targets:
+  - 2
+  - 3

README.md

@@ -1,64 +1,84 @@
 # Pokemon Go API for Python
+[![Code Health](https://landscape.io/github/dmadisetti/pokemongo-api/master/landscape.svg?style=flat)](https://landscape.io/github/dmadisetti/pokemongo-api/master)
+## Why use this API?
 
-## Installation
-
-We do not yet have this installable as a pip package,
-though some headway has been made.
-Clone this or use this however you like.
-
-*Important note*: `libencrypt.so` or `encrypt.dll` is needed in order for this to work.
-
-## Features
+This is arguably one of the cleanest python API's out there. It is our hope that this codebase is easily understood and very readable. We actively stay away from reflection, because actively managed calls provide a nicer experience than digging through protobufs. Development is currently active, so feel free to contribute any requests or functionality you think is missing.
 
-Our current implementaion covers most of the basics of gameplay. The following methods are availible:
+*Important note*: `libencrypt.so` or `encrypt.dll` is needed in order for complete functionality. Minor calls such as getProfile will still work without this. We do not provide this library due to copyright issues. However, if you know where to look, you should be able to be able to find either the binaries or the source. 
 
-```
-# Get profile
-def getProfile(self):
+## Installation
 
-# Get Location
-def getMapObjects(self, radius=10):
+Install this package via pip i.e
+`pip install git+git://github.com/rubenvereecken/pokemongo-api@master`
+Alternatively, clone this and use `pip install .`
 
-# Spin a pokestop
-def getFortSearch(self, fort):
+To get newest, run `pip install git+git://github.com/rubenvereecken/pokemongo-api@master --upgrade`
 
-# Get encounter
-def encounterPokemon(self, pokemon):
+## Implementation
 
-# Upon Encounter, try and catch
-def catchPokemon(self, pokemon, pokeball=1):
+Trainer is a general purpose class meant to encapsulate basic functons. We recommend that you inherit from this class to provide your specific usecase. We understand that `Trainer` is not as fully flushed out as it could be- it is meant to be a stub for building more complex logic. e.g.
+```
+class Map(Trainer):
+    """My beautiful map implementation"""
+
+    def fillWebSocketsForRealtimeStuffOrSomethingLikeThat(self):
+        """Fill websockets with profile data or something.
+        I don't know. The world is your oyster."""
+        profile = self.session.getProfile()
+        ...
+```
 
-# Evolve Pokemon
-def evolvePokemon(self, pokemon):
+or
 
-# Transfer Pokemon
-def releasePokemon(self, pokemon):
+```
+class Bot(Trainer):
+    """Such bot, much cheat."""
 
-# Throw away items
-def recycleItem(self, item_id, count):
+    def catchAllThePokemonOrSomething(self):
+        """Whatever it is botters do"""
+        ...
+```
 
-# set an Egg into an incubator
-def setEgg(self, item, pokemon):
+Feel free to also ignore trainer and call session functions directly.
 
-# Get Eggs
-def getEggs(self):
+## Features
 
-# Get Inventory
-def getInventory(self):
+Our current implementaion covers most of the basics of gameplay. The following methods are availible:
 
-# Get Badges
-def getBadges(self):
 
-# Get Settings
-def getDownloadSettings(self):
-```
-Every method has been tested. Pull requests are encouraged.
+| Description                                      | function      |
+| ------------------                               |:-------------:|
+| Get Profile (Avatar, team etc..)                 | getProfile() |
+| Get Eggs                                         | getEggs() |
+| Get Inventory                                    | getInventory() |
+| Get Badges                                       | getBadges() |
+| Get Settings                                     | getDownloadSettings() |
+| Get Location                                     | getMapObjects(radius=10, bothDirections=True) |
+| Get Location                                     | getFortSearch(fort) |
+| Get details about fort (image, text etc..)       | getFortDetails(fort) |
+| Get encounter (akin to tapping a pokemon)        | encounterPokemon(pokemon) |
+| Upon Encounter, try and catch                    | catchPokemon(pokemon, pokeball=items.POKE_BALL, normalized_reticle_size=1.950, hit_pokemon=True, spin_modifier=0.850, normalized_hit_position=1.0)|
+| Use a razz berry or the like                     | useItemCapture(item_id, pokemon) |
+| Use a Potion (Hyper potion, super, etc..)        | useItemPotion(item_id, pokemon) |
+| Use a Revive (Max revive etc as well)            | useItemRevive(item_id, pokemon) |
+| Evolve Pokemon (check for candies first)         | evolvePokemon(pokemon) |
+| 'Transfers' a pokemon. Pr. Willow is probably eating them| releasePokemon(pokemon) |
+| Check for level up and apply                     | getLevelUp(newLevel) |
+| Use a lucky egg                                  | useXpBoost() |
+| Throw away items                                 | recycleItem(item_id, count) |
+| set an Egg into an incubator                     | setEgg(item, pokemon) |
+| Set the name of a given pokemon                  | nicknamePokemon(pokemon, nickname) |
+| Set Pokemon as favorite                          | setFavoritePokemon(pokemon, is_favorite) |
+| Upgrade a Pokemon's CP                           | upgradePokemon(pokemon) |
+| Choose player's team - `BLUE`,`RED`, or `YELLOW`.| setPlayerTeam(team) |
+
+Every method has been tested locally. Automated units tests are needed. Pull requests are encouraged.
 
 ## Demo
 `demo.py` includes a demo of the API.
 
 ```
-➜  python demo.py -a "google" -u "[email protected]" -p "thepassword" -l "The Atlantic Ocean"
+➜  python demo.py -a "google" -u "[email protected]" -p "thepassword" -l "The Atlantic Ocean" -e"libencrypt.so"
 
 2016-07-17 16:26:59,947 - INFO - Creating Google session for [email protected]
 2016-07-17 16:26:59,953 - INFO - Starting new HTTPS connection (1): android.clients.google.com

demo.py

@@ -64,7 +64,7 @@
         trainer.checkInventory()
 
         # Things we need GPS for
-        if args.location:
+        if args.location and args.encrypt_lib:
             # We need a solid sleep to get over rate limting
             # Goodnight cow jumping over the moon.
             time.sleep(10)

pogo/__init__.py

@@ -1 +0,0 @@
-import POGOProtos as POGOProtos

pogo/api.py

@@ -88,7 +88,7 @@ def createPogoSession(
         # determine location
         location = None
         if noop:
-            location = Location.noop()
+            location = Location.Noop()
         elif session:
             location = session.location
         elif locationLookup:

pogo/inventory.py

@@ -45,7 +45,7 @@ class Inventory(object):
     """ Inventory class to hold response from inventory"""
 
     # Split from inventory since everything is bundled
-    def __init__(self, items):
+    def __init__(self, inventory):
         # Reset inventory
         # Assuming sincetimestamp = 0
         # Otherwise have to associate time state,
@@ -57,7 +57,7 @@ def __init__(self, items):
         self.party = []
         self.eggs = []
         self.bag = {}
-        for item in items:
+        for item in inventory:
             data = item.inventory_item_data
 
             if data.HasField("player_stats"):

pogo/location.py

@@ -47,7 +47,7 @@ def getLatLongIndex(latitude, longitude):
         ).id()
 
     @staticmethod
-    def noop():
+    def Noop():
         return Location(None, None, noop=True)
 
     def setLocation(self, search):

pogo/session.py

@@ -117,7 +117,7 @@ def getFortSearch(self, fort):
         # Return everything
         return self._state.fortSearch
 
-    # set an Egg into an incubator
+    # get details about fort (image, text etc..)
     def getFortDetails(self, fort):
 
         # Create request
@@ -139,7 +139,7 @@ def getFortDetails(self, fort):
         # Return everything
         return self._state.fortDetails
 
-    # Get encounter
+    # Get encounter (akin to tapping a pokemon)
     def encounterPokemon(self, pokemon):
 
         # Create request
@@ -213,7 +213,7 @@ def useItemCapture(self, item_id, pokemon):
         # Return everything
         return self._state.itemCapture
 
-    # Use a Potion
+    # Use a Potion (Hyper potion, super, etc..)
     def useItemPotion(self, item_id, pokemon):
 
         # Create Request
@@ -255,7 +255,7 @@ def useItemRevive(self, item_id, pokemon):
         # Return everything
         return self._state.itemRevive
 
-    # Evolve Pokemon
+    # Evolve Pokemon (check for candies first)
     def evolvePokemon(self, pokemon):
 
         payload = [Request.Request(
@@ -274,6 +274,8 @@ def evolvePokemon(self, pokemon):
         # Return everything
         return self._state.evolve
 
+    # 'Transfers' a pokemon.
+    # We all secretly know Pr. Willow is probably eating them
     def releasePokemon(self, pokemon):
 
         payload = [Request.Request(
@@ -292,6 +294,7 @@ def releasePokemon(self, pokemon):
         # Return everything
         return self._state.release
 
+    # Check for level up and apply
     def getLevelUp(self, newLevel):
 
         payload = [Request.Request(
@@ -310,6 +313,7 @@ def getLevelUp(self, newLevel):
         # Return everything
         return self._state.levelUp
 
+    # Use a lucky egg
     def useXpBoost(self):
 
         payload = [Request.Request(
@@ -431,7 +435,7 @@ def upgradePokemon(self, pokemon):
         # Return everything
         return self._state.upgradePokemon
 
-    # Choose player's team: "BLUE","RED", or "YELLOW".
+    # Choose player's team- "BLUE","RED", or "YELLOW".
     def setPlayerTeam(self, team):
 
         # Create request

pogo/session_bare.py

@@ -77,7 +77,7 @@ def __init__(self, authSession, location, old=None):
         # Set up Inventory
         if old is not None:
             self._inventory = old.inventory
-            self._state = old._state
+            self._state = old.state
 
         # Start fresh
         else:
@@ -129,6 +129,10 @@ def accessToken(self):
     def authProvider(self):
         return self._authSession.provider
 
+    @property
+    def state(self):
+        return self._state
+
     # Properties for defaults
     # Check, so we don't have to start another request
     def _verifyInventory(self, attribute):
@@ -273,11 +277,11 @@ def request(self, req, url=None):
         try:
             return self.requestOrThrow(req, url)
         except DecodeError as e:
-            raise PogoResponseException(ERROR_RESPONSE)
             logging.error(e)
+            raise PogoResponseException(ERROR_RESPONSE)
         except Exception as e:
-            raise PogoServerException(ERROR_SERVER)
             logging.error(e)
+            raise PogoServerException(ERROR_SERVER)
 
     def wrapAndRequest(self, payload, defaults=True):
         res = self.request(self.wrapInRequest(payload, defaults=defaults))