Merge pull request #194 from s4w3d0ff/dev

v0.5

.travis.yml

@@ -1,9 +1,15 @@
 language: python
 python:
 - '2.7'
-- '3.3'
-- '3.4'
 - '3.5'
 - '3.6'
 install: python setup.py install
 script: python test.py
+deploy:
+  provider: pypi
+  user: s4w3d0ff
+  password:
+    secure: "wQaQITU9IZBpBkspCPof2W7qDXQkQdMfSmkhdzCqaHEYxdXcIOBekVmG+yME912Hh6UUuDi58Uz55sXo5fe4UctV91kzrbq5VpcaQ7ko+Q7TizZ6EMiHKvaX2570EEKdVkG7iz65Mg0TMPtAHR3xOKNBCFhI7sy85ixYPsHEEHr64gm8Ygtv2nfgQ2ptD0tp7+dORuaxSyYZckb6glsde81T9+9AO/4L08D13pquy1GtEp1PkUGnr/lLXqo6Pbz4/mwURkw30KmgIxGgZUmgOtBp2SyIGpWmcfL7opYlCPwI3fbNkAYBt1pF8aDRN5SxbaGK/I3+bHJrYZtQEZ9HUFkrdte9DxJMuzXU+eIskMkone+gtGMTvkQd614/rWP0IHiRhE+oQHeuNqIC0g015ocTqA8+V74CiGETGDonVfRcyCDdne6rPbVX/lmFoD0kIUb7rJuhsX3Lk8GFkYkUTzphqT6I33aLP66IbOfyve0MeFXVntfsZ8ZiS6kd+aTYgIw6cVIT4LVG4i6Jwjm2/LZN7CqvWHI2RQ15pV9OehXEK1otWFh5FRKy3331kAKGnWNQRbuOvpNnNGMsS/niXL/wALd5hPQuzAALk5XgShoKsN3LwacLaWAm1ZtCcBeKsiQIDU9h0QOyUlbYCeNGV5V7K92ft7EhERZxR5BRzoE="
+  on:
+    tags: true
+  skip_existing: true

README.md

@@ -1,54 +1,117 @@
-[![python](https://img.shields.io/badge/python-2.7%20%26%203-blue.svg)![licence](https://img.shields.io/badge/licence-GPL%20v2-blue.svg)](https://github.com/s4w3d0ff/python-poloniex/blob/master/LICENSE) [![release](https://img.shields.io/github/release/s4w3d0ff/python-poloniex.svg)![release build](https://travis-ci.org/s4w3d0ff/python-poloniex.svg?branch=v0.4.7)](https://github.com/s4w3d0ff/python-poloniex/releases)  
+[![python](https://img.shields.io/badge/python-2.7%20%26%203-blue.svg)![licence](https://img.shields.io/badge/licence-GPL%20v2-blue.svg)](https://github.com/s4w3d0ff/python-poloniex/blob/master/LICENSE) [![release](https://img.shields.io/github/release/s4w3d0ff/python-poloniex.svg)![release build](https://travis-ci.org/s4w3d0ff/python-poloniex.svg?branch=v0.5.4)](https://github.com/s4w3d0ff/python-poloniex/releases)  
 [![master](https://img.shields.io/badge/branch-master-blue.svg)![master build](https://api.travis-ci.org/s4w3d0ff/python-poloniex.svg?branch=master)](https://github.com/s4w3d0ff/python-poloniex/tree/master) [![dev](https://img.shields.io/badge/branch-dev-blue.svg)![dev build](https://api.travis-ci.org/s4w3d0ff/python-poloniex.svg?branch=dev)](https://github.com/s4w3d0ff/python-poloniex/tree/dev)  
 Inspired by [this](http://pastebin.com/8fBVpjaj) wrapper written by 'oipminer'  
-> I (s4w3d0ff) am not affiliated with, nor paid by [Poloniex](https://poloniex.com). I have been an active trader there since 2014 and love python. I found the linked python wrapper on the poloniex support page to be incomplete and buggy so I decided to write this wrapper and create this git repository. If you wish to contribute to this repository please read [CONTRIBUTING.md](https://github.com/s4w3d0ff/python-poloniex/blob/master/CONTRIBUTING.md). All and any help is appreciated.
-## Install latest release:
-Python 2:
-```
-pip install https://github.com/s4w3d0ff/python-poloniex/archive/v0.4.7.zip
-```
+> I (s4w3d0ff) am not affiliated with, nor paid by [Poloniex](https://poloniex.com). I found the linked python wrapper on the poloniex support page to be incomplete and buggy so I decided to write this wrapper and create a git repository. If you wish to contribute to the repository please read [CONTRIBUTING.md](https://github.com/s4w3d0ff/python-poloniex/blob/master/CONTRIBUTING.md). All and any help is appreciated.
+#### Features:
+- [x] Python 2.7 and 3.5+
+- [x] Pypi
+- [x] Travis
+- [x] Websocket api support
+- [x] Minimal amount of dependencies
+- [x] Internal checks to reduce external api errors
+- [x] Rate limiter to keep from going over call limits
+- [x] Retries failed api calls during connection issues
 
-Python 3:
+### Install:
 ```
-pip3 install https://github.com/s4w3d0ff/python-poloniex/archive/v0.4.7.zip
+pip install --upgrade poloniexapi
 ```
 
-## Usage:
+### Usage:
 See the [wiki](https://github.com/s4w3d0ff/python-poloniex/wiki) or `help(poloniex)` for more.
-#### Basic Public Setup (no api Key/Secret):
+
+All api calls are done through an instance of `poloniex.Poloniex`. You can use the instance as follows:
 ```python
+# import this package
 from poloniex import Poloniex
+# make an instance of poloniex.Poloniex
 polo = Poloniex()
+# show the ticker
+print(polo('returnTicker'))
 ```
-Ticker
+Using the instances `__call__` method (shown above) you can pass the command string as the first argument to make an api call. The `poloniex.Poloniex` class also has 'helper' methods for each command that will help 'sanitize' the commands arguments. For example, `Poloniex.returnChartData('USDT_BTC', period=777)` will raise `PoloniexError("777 invalid candle period")`.
+
 ```python
-print(polo('returnTicker')['BTC_ETH'])
-# or
-print(polo.returnTicker()['BTC_ETH'])
-```
-**Public** trade history:
-```python
-print(polo.marketTradeHist('BTC_ETH'))
+# using a 'helper' method
+print(polo.returnChartData(currencyPair='BTC_LTC', period=900))
+# bypassing 'helper'
+print(polo(command='returnChartData', args={'currencyPair': 'BTC_LTC',
+                                            'period': 900}))
 ```
+Almost every api command can be called this way. This wrapper also checks that the command you pass to the `command` arg is a valid command to send to poloniex, this helps reduce api errors due to typos.
+
+#### Private Commands:
+To use the private api commands you first need an api key and secret (supplied by poloniex). When creating the instance of `poloniex.Poloniex` you can pass your api key and secret to the object like so:
 
-#### Basic Private Setup (Api key/secret required):
 ```python
 import poloniex
-polo = poloniex.Poloniex('your-Api-Key-Here-xxxx','yourSecretKeyHere123456789')
-# or
+polo = poloniex.Poloniex(key='your-Api-Key-Here-xxxx', secret='yourSecretKeyHere123456789')
+# or this works
 polo.key = 'your-Api-Key-Here-xxxx'
 polo.secret = 'yourSecretKeyHere123456789'
-```
-Get all your balances
-```python
+# get your balances
 balance = polo.returnBalances()
 print("I have %s ETH!" % balance['ETH'])
 # or
 balance = polo('returnBalances')
 print("I have %s BTC!" % balance['BTC'])
 ```
+#### Trade History:
+Poloniex has two api commands with the same name `returnTradeHistory`. To work around this without splitting up the commands or having to specify 'public' or 'private' we use the helper method `Poloniex.marketTradeHist` for public trade history and `Poloniex.returnTradeHistory` for private trades. If you try to bypass the helper method using `Poloniex.__call__`, it will call the private command.
+
+**Public** trade history:
+```python
+print(polo.marketTradeHist('BTC_ETH'))
+```
 **Private** trade history:
 ```python
 print(polo.returnTradeHistory('BTC_ETH'))
 ```
-**Examples of WAMP applications using the websocket push API can be found [here](https://github.com/s4w3d0ff/python-poloniex/tree/master/examples).**
+
+#### Websocket Usage:
+Right now, the easiest way to use the websocket api is making a child class like so:
+```python
+import logging
+
+logging.basicConfig()
+
+class MySocket(poloniex.Poloniex):
+
+    def on_heartbeat(self, msg):
+        """
+        Triggers whenever we get a heartbeat message
+        """
+        print(msg)
+
+    def on_volume(self, msg):
+        """
+        Triggers whenever we get a ticker message
+        """
+        print(msg)
+
+    def on_ticker(self, msg):
+        """
+        Triggers whenever we get a 24hvolume message
+        """
+        print(msg)
+
+    def on_market(self, msg):
+        """
+        Triggers whenever we get a market ('currencyPair') message
+        """
+        print(msg)
+
+    def on_account(self, msg):
+        """
+        Triggers whenever we get an account message
+        """
+        print(msg)
+
+sock = MySocket()
+# helps show what is going on
+sock.logger.setLevel(logging.DEBUG)
+# start the websocket thread and subsribe to '24hvolume'
+sock.startws(subscribe=['24hvolume'])
+```
+
+**More examples of how to use websocket push API can be found [here](https://github.com/s4w3d0ff/python-poloniex/tree/master/examples).**

examples/README.md

@@ -1,24 +1,25 @@
 # Examples
+#### _Examples require [this poloniex module](https://github.com/s4w3d0ff/python-poloniex) to be installed._
 
-#### _Most examples require this poloniex module and/or autobahn installed._
-
-## WAMP Push Api Setup 
-See http://autobahn.ws/python/installation.html for more details on other systems.
-### From fresh Ubuntu install (14.04, 16.04):
-##### Python 2.7
-```
-sudo apt-get install build-essential libssl-dev python-pip python-dev libffi-dev git
-sudo bash -c 'apt-get update && apt-get upgrade'
-pip install service_identity
-pip install autobahn[twisted]
-```
-##### Python 3
+## Chart:
+Saves chart data in a mongodb collection and returns a pandas dataframe with basic indicators.
+### Requirements:
+pip:
 ```
-sudo apt-get install build-essential libssl-dev python3-pip python3-dev libffi-dev git
-sudo bash -c 'apt-get update && apt-get upgrade'
-pip3 install service_identity
-pip3 install autobahn[twisted]
+pandas
+numpy
+pymongo
 ```
+Chart examples require [mongod](https://www.mongodb.com/) running locally.
+
+## Loanbot:
+Helps your loan offers get filled and keeps them from going 'stale'
+### Requirements:
+Just [this git repository](https://github.com/s4w3d0ff/python-poloniex).
+
 
->NOTE: There is also another wonderful api wrapper that wraps the WAMP polo api using asyncio:  
->[https://github.com/absortium/poloniex-api](https://github.com/absortium/poloniex-api)
+## Websocket:
+Examples of how to use the websocket api to create tickers, stoplimits, etc.
+### Requirements:
+Just [this git repository](https://github.com/s4w3d0ff/python-poloniex) v0.5+.
+`mongoTicker.py` requires pymongo and mongod running.