bfxapi: edit comments for doc generating

bfxapi/rest/bfx_rest.py

@@ -100,6 +100,7 @@ class BfxRest:
         """
         Get all of the public candles between the start and end period.
 
+        # Attributes
         @param symbol symbol string: pair symbol i.e tBTCUSD
         @param secton string: available values: "last", "hist"
         @param start int: millisecond start time
@@ -120,6 +121,7 @@ class BfxRest:
         """
         Get all of the public trades between the start and end period.
 
+        # Attributes
         @param symbol symbol string: pair symbol i.e tBTCUSD
         @param start int: millisecond start time
         @param end int: millisecond end time
@@ -136,6 +138,7 @@ class BfxRest:
         """
         Get the public orderbook for a given symbol.
 
+        # Attributes
         @param symbol symbol string: pair symbol i.e tBTCUSD
         @param precision string: level of price aggregation (P0, P1, P2, P3, P4, R0)
         @param length int: number of price points ("25", "100")
@@ -151,6 +154,7 @@ class BfxRest:
         Get tickers for the given symbol. Tickers shows you the current best bid and ask,
         as well as the last trade price.
 
+        # Attributes
         @param symbols symbol string: pair symbol i.e tBTCUSD
         @return Array [ SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE,
           DAILY_CHANGE_PERC, LAST_PRICE, VOLUME, HIGH, LOW ]
@@ -164,6 +168,7 @@ class BfxRest:
         Get tickers for the given symbols. Tickers shows you the current best bid and ask,
         as well as the last trade price.
 
+        # Attributes
         @param symbols Array<string>: array of symbols i.e [tBTCUSD, tETHUSD]
         @return Array [ SYMBOL, BID, BID_SIZE, ASK, ASK_SIZE, DAILY_CHANGE,  DAILY_CHANGE_PERC,
           LAST_PRICE, VOLUME, HIGH, LOW ]
@@ -176,6 +181,7 @@ class BfxRest:
         """
         Gets platform information for derivative symbol.
 
+        # Attributes
         @param derivativeSymbol string: i.e tBTCF0:USTF0
         @return [KEY/SYMBOL, MTS, PLACEHOLDER, DERIV_PRICE, SPOT_PRICE, PLACEHOLDER, INSURANCE_FUND_BALANCE4,
             PLACEHOLDER, PLACEHOLDER, FUNDING_ACCRUED, FUNDING_STEP, PLACEHOLDER]
@@ -189,6 +195,7 @@ class BfxRest:
         """
         Gets platform information for a collection of derivative symbols.
 
+        # Attributes
         @param derivativeSymbols Array<string>: array of symbols i.e [tBTCF0:USTF0 ...] or ["ALL"]
         @return [KEY/SYMBOL, MTS, PLACEHOLDER, DERIV_PRICE, SPOT_PRICE, PLACEHOLDER, INSURANCE_FUND_BALANCE4,
             PLACEHOLDER, PLACEHOLDER, FUNDING_ACCRUED, FUNDING_STEP, PLACEHOLDER]
@@ -215,6 +222,7 @@ class BfxRest:
         """
         Get all of the active orders associated with API_KEY - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @return Array <models.Order>
         """
@@ -227,6 +235,7 @@ class BfxRest:
         Get all of the orders between the start and end period associated with API_KEY
         - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @param start int: millisecond start time
         @param end int: millisecond end time
@@ -254,6 +263,7 @@ class BfxRest:
         Get all of the trades that have been generated by the given order associated with API_KEY
         - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @param order_id string: id of the order
         @return Array <models.Trade>
@@ -267,6 +277,7 @@ class BfxRest:
         Get all of the trades between the start and end period associated with API_KEY
         - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @param start int: millisecond start time
         @param end int: millisecond end time
@@ -293,6 +304,7 @@ class BfxRest:
         Get all of the funding offers between the start and end period associated with API_KEY
         - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @param start int: millisecond start time
         @param end int: millisecond end time
@@ -319,6 +331,7 @@ class BfxRest:
         Get all of the funding loans between the start and end period associated with API_KEY
         - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @param start int: millisecond start time
         @param end int: millisecond end time
@@ -340,6 +353,7 @@ class BfxRest:
         Get all of the funding credits between the start and end period associated with API_KEY
         - Requires authentication.
 
+        # Attributes
         @param symbol string: pair symbol i.e tBTCUSD
         @param start int: millisecond start time
         @param end int: millisecond end time
@@ -356,6 +370,7 @@ class BfxRest:
         """
         Submits a new funding offer
 
+        # Attributes
         @param symbol string: pair symbol i.e fUSD
         @param amount float: funding size
         @param rate float: percentage rate to charge per a day
@@ -379,6 +394,7 @@ class BfxRest:
         """
         Cancel a funding offer
 
+        # Attributes
         @param fundingId int: the id of the funding offer
         """
         endpoint = "auth/w/funding/offer/cancel"
@@ -389,6 +405,7 @@ class BfxRest:
         """
         Transfer funds between wallets
 
+        # Attributes
         @param from_wallet string: wallet name to transfer from i.e margin, exchange
         @param to_wallet string: wallet name to transfer to i.e margin, exchange
         @param from_currency string: currency symbol to tranfer from i.e BTC, USD
@@ -410,6 +427,7 @@ class BfxRest:
         """
         Get the deposit address for the given wallet and protocol
 
+        # Attributes
         @param wallet string: wallet name i.e margin, exchange
         @param method string: transfer protocol i.e bitcoin
         """
@@ -427,6 +445,7 @@ class BfxRest:
         Creates a new deposit address for the given wallet and protocol.
         Previously generated addresses remain linked.
 
+        # Attributes
         @param wallet string: wallet name i.e margin, exchange
         @param method string: transfer protocol i.e bitcoin
         """
@@ -434,7 +453,13 @@ class BfxRest:
 
     async def submit_wallet_withdraw(self, wallet, method, amount, address):
         """
-        `/v2/auth/w/withdraw` (params: `wallet`, `method`, `amount`, `address
+        Submits a request to withdraw crypto funds to an external wallet.
+
+        # Attributes
+        @param wallet string: wallet name i.e margin, exchange
+        @param method string: transfer protocol i.e bitcoin
+        @param amount float: amount of funds to withdraw
+        @param address string: external address to withdraw to
         """
         endpoint = "auth/w/withdraw"
         payload = {
@@ -471,6 +496,7 @@ class BfxRest:
         """
         Submit a new order
 
+        # Attributes
         @param gid: assign the order to a group identifier
         @param symbol: the name of the symbol i.e 'tBTCUSD
         @param price: the price you want to buy/sell at (must be positive)
@@ -523,6 +549,7 @@ class BfxRest:
         """
         Cancel an existing open order
 
+        # Attributes
         @param orderId: the id of the order that you want to update
         """
         endpoint = "auth/w/order/cancel"
@@ -535,6 +562,7 @@ class BfxRest:
         """
         Update an existing order
 
+        # Attributes
         @param orderId: the id of the order that you want to update
         @param price: the price you want to buy/sell at (must be positive)
         @param amount: order size: how much you want to buy/sell,
@@ -581,6 +609,7 @@ class BfxRest:
         """
         Update the amount of callateral used to back a derivative position.
 
+        # Attributes
         @param symbol of the derivative i.e 'tBTCF0:USTF0'
         @param collateral: amount of collateral/value to apply to the open position
         """

bfxapi/websockets/bfx_websocket.py

@@ -88,6 +88,38 @@ class BfxWebsocket(GenericWebsocket):
     More complex websocket that heavily relies on the btfxwss module.
     This websocket requires authentication and is capable of handling orders.
     https://github.com/Crypto-toolbox/btfxwss
+
+    ### Subscribable events:
+    - `all` (array|json): listen for all messages coming through
+    - `connected:` () called when a connection is made
+    - `disconnected`: () called when a connection is ended (A reconnect attempt may follow)
+    - `stopped`: () called when max amount of connection retries is met and the socket is closed
+    - `authenticated` (): called when the websocket passes authentication
+    - `notification` (Notification): incoming account notification
+    - `error` (array): error from the websocket
+    - `order_closed` (Order, Trade): when an order has been closed
+    - `order_new` (Order, Trade): when an order has been created but not closed. Note: will not be called if order is executed and filled instantly
+    - `order_confirmed` (Order, Trade): When an order has been submitted and received
+    - `wallet_snapshot` (array[Wallet]): Initial wallet balances (Fired once)
+    - `order_snapshot` (array[Order]): Initial open orders (Fired once)
+    - `positions_snapshot` (array): Initial open positions (Fired once)
+    - `wallet_update` (Wallet): changes to the balance of wallets
+    - `status_update` (json): new platform status info
+    - `seed_candle` (json): initial past candle to prime strategy
+    - `seed_trade` (json): initial past trade to prime strategy
+    - `funding_offer_snapshot` (array): opening funding offer balances
+    - `funding_loan_snapshot` (array): opening funding loan balances
+    - `funding_credit_snapshot` (array): opening funding credit balances
+    - `balance_update` (array): when the state of a balance is changed
+    - `new_trade` (array): a new trade on the market has been executed
+    - `trade_update` (array): a trade on the market has been updated
+    - `new_candle` (array): a new candle has been produced
+    - `margin_info_updates` (array): new margin information has been broadcasted
+    - `funding_info_updates` (array): new funding information has been broadcasted
+    - `order_book_snapshot` (array): initial snapshot of the order book on connection
+    - `order_book_update` (array): a new order has been placed into the ordebrook
+    - `subscribed` (Subscription): a new channel has been subscribed to
+    - `unsubscribed` (Subscription): a channel has been un-subscribed
     """
 
     ERRORS = {
@@ -461,6 +493,12 @@ class BfxWebsocket(GenericWebsocket):
         return total
 
     async def enable_flag(self, flag):
+        """
+        Enable flag on websocket connection
+
+        # Attributes
+        flag (int): int flag value
+        """
         payload = {
             "event": 'conf',
             "flags": flag
@@ -471,50 +509,185 @@ class BfxWebsocket(GenericWebsocket):
                 await socket.ws.send(json.dumps(payload))
 
     async def subscribe_order_book(self, symbol):
+        """
+        Subscribe to an orderbook data feed
+
+        # Attributes
+        @param symbol: the trading symbol i.e 'tBTCUSD'
+        """
         return await self.subscribe('book', symbol)
 
     async def subscribe_candles(self, symbol, timeframe):
+        """
+        Subscribe to a candle data feed
+
+        # Attributes
+        @param symbol: the trading symbol i.e 'tBTCUSD'
+        """
         return await self.subscribe('candles', symbol, timeframe=timeframe)
 
     async def subscribe_trades(self, symbol):
+        """
+        Subscribe to a trades data feed
+
+        # Attributes
+        @param symbol: the trading symbol i.e 'tBTCUSD'
+        """
         return await self.subscribe('trades', symbol)
 
     async def subscribe_ticker(self, symbol):
+        """
+        Subscribe to a ticker data feed
+
+        # Attributes
+        @param symbol: the trading symbol i.e 'tBTCUSD'
+        """
         return await self.subscribe('ticker', symbol)
 
     async def subscribe_derivative_status(self, symbol):
+        """
+        Subscribe to a status data feed
+
+        # Attributes
+        @param symbol: the trading symbol i.e 'tBTCUSD'
+        """
         key = 'deriv:{}'.format(symbol)
         return await self.subscribe('status', symbol, key=key)
 
     async def subscribe(self, *args, **kwargs):
+        """
+        Subscribe to a new channel
+
+        # Attributes
+        @param channel_name: the name of the channel i.e 'books', 'candles'
+        @param symbol: the trading symbol i.e 'tBTCUSD'
+        @param timeframe: sepecifies the data timeframe between each candle (only required
+          for the candles channel)
+        """
         return await self.subscriptionManager.subscribe(*args, **kwargs)
 
     async def unsubscribe(self, *args, **kwargs):
+        """
+        Unsubscribe from the channel with the given chanId
+
+        # Attributes
+        @param onComplete: function called when the bitfinex websocket resoponds with
+          a signal that confirms the subscription has been unsubscribed to
+        """
         return await self.subscriptionManager.unsubscribe(*args, **kwargs)
 
     async def resubscribe(self, *args, **kwargs):
+        """
+        Unsubscribes and then subscribes to the channel with the given Id
+
+        This function is mostly used to force the channel to produce a fresh snapshot.
+        """
         return await self.subscriptionManager.resubscribe(*args, **kwargs)
 
     async def unsubscribe_all(self, *args, **kwargs):
+        """
+        Unsubscribe from all channels.
+        """
         return await self.subscriptionManager.unsubscribe_all(*args, **kwargs)
 
     async def resubscribe_all(self, *args, **kwargs):
+        """
+        Unsubscribe and then subscribe to all channels
+        """
         return await self.subscriptionManager.resubscribe_all(*args, **kwargs)
 
     async def submit_order(self, *args, **kwargs):
+        """
+        Submit a new order
+
+        # Attributes
+        @param gid: assign the order to a group identifier
+        @param symbol: the name of the symbol i.e 'tBTCUSD
+        @param price: the price you want to buy/sell at (must be positive)
+        @param amount: order size: how much you want to buy/sell,
+          a negative amount indicates a sell order and positive a buy order
+        @param market_type	Order.Type: please see Order.Type enum
+          amount	decimal string	Positive for buy, Negative for sell
+        @param hidden: if True, order should be hidden from orderbooks
+        @param price_trailing:	decimal trailing price
+        @param price_aux_limit:	decimal	auxiliary Limit price (only for STOP LIMIT)
+        @param oco_stop_price: set the oco stop price (requires oco = True)
+        @param close: if True, close position if position present
+        @param reduce_only: if True, ensures that the executed order does not flip the opened position
+        @param post_only: if True, ensures the limit order will be added to the order book and not
+          match with a pre-existing order
+        @param oco: cancels other order option allows you to place a pair of orders stipulating
+          that if one order is executed fully or partially, then the other is automatically canceled
+
+        @param time_in_force:	datetime for automatic order cancellation ie. 2020-01-01 10:45:23
+        @param leverage: the amount of leverage to apply to the order as an integer
+        @param onConfirm: function called when the bitfinex websocket receives signal that the order
+          was confirmed
+        @param onClose: function called when the bitfinex websocket receives signal that the order
+          was closed due to being filled or cancelled
+        """
         return await self.orderManager.submit_order(*args, **kwargs)
 
     async def update_order(self, *args, **kwargs):
+        """
+        Update an existing order
+
+        # Attributes
+        @param orderId: the id of the order that you want to update
+        @param price: the price you want to buy/sell at (must be positive)
+        @param amount: order size: how much you want to buy/sell,
+          a negative amount indicates a sell order and positive a buy order
+        @param delta:	change of amount
+        @param price_trailing:	decimal trailing price
+        @param price_aux_limit:	decimal	auxiliary Limit price (only for STOP LIMIT)
+        @param hidden: if True, order should be hidden from orderbooks
+        @param close: if True, close position if position present
+        @param reduce_only: if True, ensures that the executed order does not flip the opened position
+        @param post_only: if True, ensures the limit order will be added to the order book and not
+          match with a pre-existing order
+        @param time_in_force: datetime for automatic order cancellation ie. 2020-01-01 10:45:23
+        @param leverage: the amount of leverage to apply to the order as an integer
+        @param onConfirm: function called when the bitfinex websocket receives signal that the order
+          was confirmed
+        @param onClose: function called when the bitfinex websocket receives signal that the order
+          was closed due to being filled or cancelled
+        """
         return await self.orderManager.update_order(*args, **kwargs)
 
     async def cancel_order(self, *args, **kwargs):
+        """
+        Cancel an existing open order
+
+        # Attributes
+        @param orderId: the id of the order that you want to update
+        @param onConfirm: function called when the bitfinex websocket receives signal that the
+                          order
+          was confirmed
+        @param onClose: function called when the bitfinex websocket receives signal that the order
+          was closed due to being filled or cancelled
+        """
         return await self.orderManager.cancel_order(*args, **kwargs)
 
     async def cancel_order_group(self, *args, **kwargs):
+        """
+        Cancel a set of orders using a single group id.
+        """
         return await self.orderManager.cancel_order_group(*args, **kwargs)
 
     async def cancel_all_orders(self, *args, **kwargs):
+        """
+        Cancel all existing open orders
+
+        This function closes all open orders.
+        """
         return await self.orderManager.cancel_all_orders(*args, **kwargs)
 
     async def cancel_order_multi(self, *args, **kwargs):
+        """
+        Cancel existing open orders as a batch
+
+        # Attributes
+        @param ids: an array of order ids
+        @param gids: an array of group ids
+        """
         return await self.orderManager.cancel_order_multi(*args, **kwargs)