Merge branch 'master' into feature/trailing-stop

Author: Shlomi Kushchi

NOTICE

@@ -0,0 +1,5 @@
+Apache [PRODUCT_NAME]
+Copyright [XXXX-XXXX] The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).

README.md

@@ -6,7 +6,7 @@
 # alpaca-trade-api-python
 
 `alpaca-trade-api-python` is a python library for the [Alpaca Commission Free Trading API](https://alpaca.markets).
-It allows rapid trading algo development easily, with support for the
+It allows rapid trading algo development easily, with support for
 both REST and streaming data interfaces. For details of each API behavior,
 please see the online [API document](https://docs.alpaca.markets).
 
@@ -21,7 +21,7 @@ $ pip3 install alpaca-trade-api
 
 ## Example
 
-In order to call Alpaca's trade API, you need to sign up for a account and obtain API key pairs. Replace <key_id> and <secret_key> with what you get from the web console.
+In order to call Alpaca's trade API, you need to sign up for an account and obtain API key pairs. Replace <key_id> and <secret_key> with what you get from the web console.
 
 ### REST example
 ```python
@@ -42,7 +42,7 @@ The HTTP API document is located at https://docs.alpaca.markets/
 
 ## API Version
 
-API Version now defaults to 'v2', however if you still have a 'v1' account, you may need to specify api_version='v1' to properly use the API until you migrate.
+API Version now defaults to 'v2', however, if you still have a 'v1' account, you may need to specify api_version='v1' to properly use the API until you migrate.
 
 ## Authentication
 
@@ -53,7 +53,7 @@ outlined below.
 
 ## Alpaca Environment Variables
 
-The Alpaca SDK will check the environment for a number of variables which can be used rather than hard-coding these into your scripts.
+The Alpaca SDK will check the environment for a number of variables that can be used rather than hard-coding these into your scripts.
 
 | Environment                      | default                                                                                | Description                                                                                                            |
 | -------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -66,15 +66,14 @@ The Alpaca SDK will check the environment for a number of variables which can be
 | APCA_RETRY_CODES=429,504         | 429,504                                                                                | comma-separated HTTP status code for which retry is attempted                                                          |
 | POLYGON_WS_URL                   | wss://socket.polygon.io/stocks                                                  | Endpoint for streaming polygon data.  You likely don't need to change this unless you want to proxy it for example     |
 | POLYGON_KEY_ID                   |                                                                                        | Your Polygon key, if it's not the same as your Alpaca API key. Most users will not need to set this to access Polygon. |
-| ALPHAVANTAGE_API_KEY=<key_id>    |                                                                                        | Your Alpha Vantage API key. You can get [one for free here](https://www.alphavantage.co/support/#api-key).             |
 
 ## REST
 
 The `REST` class is the entry point for the API request.  The instance of this
 class provides all REST API calls such as account, orders, positions,
 and bars.
 
-Each returned object is wrapped by a subclass of `Entity` class (or a list of it).
+Each returned object is wrapped by a subclass of the `Entity` class (or a list of it).
 This helper class provides property access (the "dot notation") to the
 json object, backed by the original object stored in the `_raw` field.
 It also converts certain types to the appropriate python object.
@@ -88,7 +87,7 @@ account.status
 => 'ACTIVE'
 ```
 
-The `Entity` class also converts timestamp string field to a pandas.Timestamp
+The `Entity` class also converts the timestamp string field to a pandas.Timestamp
 object.  Its `_raw` property returns the original raw primitive data unmarshaled
 from the response JSON text.
 
@@ -221,9 +220,9 @@ exception is raised, and each event handler is called asynchronously
 upon the message arrivals.
 
 The `run` method tries to reconnect to the server in the event of
-connection failure.  In this case you may want to reset your state
+connection failure.  In this case, you may want to reset your state
 which is best in the `connect` event.  The method still raises
-exception in the case any other unknown error happens inside the
+an exception in the case any other unknown error happens inside the
 event loop.
 
 The `msg` object passed to each handler is wrapped by the entity
@@ -285,8 +284,29 @@ same `channel_pat` will overwrite the old handler.
 Deregisters the event handler function that was previously registered via `on` or
 `register` method.
 
+#### Debugging
+Websocket exceptions may occur during execution.
+It will usually happen during the `consume()` method, which basically is the 
+websocket steady-state.<br>
+exceptions during the consume method may occur due to:
+- server disconnections
+- error while handling the response data
+
+We handle the first issue by reconnecting the websocket every time there's a disconnection.
+The second issue, is usually a user's code issue. To help you find it, we added a flag to the 
+StreamConn object called `debug`. It is set to False by default, but you can turn it on to get a more
+verbose logs when this exception happens.
+Turn it on like so `StreamConn(debug=True)`  
+
+## Logging
+You should define a logger in your app in order to make sure you get all the messages from the different components.<br>
+It will help you debug, and make sure you don't miss issues when they occur.<br>
+The simplest way to define a logger, if you have no experience with the python logger - will be something like this:
+```py
+import logging
+logging.basicConfig(format='%(asctime)s %(message)s', level=logging.INFO)
+```
 
----
 # Polygon API Service
 
 Alpaca's API key ID can be used to access Polygon API, the documentation for
@@ -321,7 +341,7 @@ df = api.polygon.historic_agg_v2('AAPL', 1, 'minute', _from=start, to=end).df
 ```
 
 ## polygon/REST
-It is initialized through alpaca `REST` object.
+It is initialized through the alpaca `REST` object.
 
 ### polygon/REST.exchanges()
 Returns a list of `Exchange` entity.
@@ -332,7 +352,7 @@ Returns a `SymbolTypeMap` object.
 ### polygon/REST.historic_trades_v2(symbol, date,timestamp=None, timestamp_limit=None, reverse=None, limit=None)
 Returns a `TradesV2` which is a list of `Trade` entities.
 
-- `date` is a date string such as '2018-2-2'.  The returned quotes are from this day onyl.
+- `date` is a date string such as '2018-2-2'.  The returned quotes are from this day only.
 - `timestamp` is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive.
 - `timestamp_limit` is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results.
 - `limit` is an integer for the number of ticks to return.  Default and max is 50000.
@@ -343,7 +363,7 @@ Returns a pandas DataFrame object with the ticks returned by `historic_trades_v2
 ### polygon/REST.historic_quotes_v2(symbol, date,timestamp=None, timestamp_limit=None, reverse=None, limit=None)
 Returns a `QuotesV2` which is a list of `Quote` entities.
 
-- `date` is a date string such as '2018-2-2'.  The returned quotes are from this day onyl.
+- `date` is a date string such as '2018-2-2'.  The returned quotes are from this day only.
 - `timestamp` is an integer in Unix Epoch nanoseconds as the lower bound filter, exclusive.
 - `timestamp_limit` is an integer in Unix Epoch nanoseconds as the maximum timestamp allowed in the results.
 - `limit` is an integer for the number of ticks to return.  Default and max is 50000.
@@ -358,8 +378,7 @@ object.
 - `multiplier` is an integer affecting the amount of data contained in each Agg object.
 - `timespan` is a string affecting the length of time represented by each Agg object. It is one of the following values:
   - `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`
-- `_from` is an Eastern Time timestamp string/object that filters the result
- for the lower bound, inclusive. we accept the date in these formats: 
+- `_from` is an Eastern Time timestamp string/object that filters the result for the lower bound, inclusive. we accept the date in these formats: 
  datetime.datetime, datetime.date, pd.Timestamp, datetime.timestamp,
   isoformat string (YYYY-MM-DD)
 - `to` is an Eastern Time timestamp string that filters the result for the upper bound, inclusive. we support the same formats as the _from field
@@ -406,72 +425,11 @@ dict[symbol -> `Financials`] if `symbol` is a list of string.
 ### polygon/REST.news(symbol)
 Returns a `NewsList` entity for the symbol.
 
-
----
-# Alpha Vantage API Service
-
-In addition to Polygon is Alpha Vantage, for users without a live account (paper trading) or want to use the unique features of AV data. You can get a free key [here](https://www.alphavantage.co/support/#api-key) and the documentation is [here](https://www.alphavantage.co/documentation/). Premium keys are also available [here](https://www.alphavantage.co/premium/#intro)
-This python SDK wraps their API service and seamlessly integrates it with the Alpaca
-API. `alpaca_trade_api.REST.alpha_vantage` will be the `REST` object for Alpha Vantage.
-
-The example below gives AAPL daily OHLCV data in a DataFrame format.
-
-```py
-import alpaca_trade_api as tradeapi
-
-api = tradeapi.REST()
-aapl = api.alpha_vantage.historic_quotes('AAPL', adjusted=True, output_format='pandas')
-```
-
-## alpha_vantage/REST
-It is initialized through alpaca `REST` object.
-
-### alpha_vantage/REST.get(params=None)
-Customizable endpoint, where you can pass all keywords/paramters from the documentation:https://www.alphavantage.co/documentation/#
-
-Returns the specific customized data.
-
-### alpha_vantage/REST.historic_quotes(symbol, adjusted=False, outputsize='full', cadence='daily', output_format=None)
-Returns a `csv`, `json`, or `pandas` object of historical OHLCV data.
-
-### alpha_vantage/REST.intraday_quotes(symbol, interval='5min', outputsize='full', output_format=None)
-Returns a `csv`, `json`, or `pandas` object of intraday OHLCV data.
-
-### alpha_vantage/REST.current_quote(symbol)
-Returns a `json` object with the current OHLCV data of the selected symbol.
-
-### alpha_vantage/REST.last_quote(symbol)
-Returns a `json` object with the current OHLCV data of the selected symbol (same as `current_quote`).
-
-### alpha_vantage/REST.search_endpoint(keywords, datatype='json')
-Returns a `csv`, `json`, or `pandas` object that contains the best-matching symbols and market information based on keywords of your choice.
-
-### alpha_vantage/REST.company(symbol, datatype='json')
-Same as `search_endpoint`.
-
-### alpha_vantage/REST.historic_fx_quotes(from_symbol, to_symbol, outputsize='full', cadence='daily', output_format=None)
-Returns a `csv`, `json`, or `pandas` object of historical OHLCV data for the currency pair.
-
-### alpha_vantage/REST.intraday_fx_quotes(from_symbol, to_symbol, interval='5min', outputsize='full', output_format=None)
-Returns a `csv`, `json`, or `pandas` object of intraday OHLCV data for the currency pair.
-
-### alpha_vantage/REST.exchange_rate(from_currency, to_currency)
-Returns a `json` object with the current OHLCV data of the selected currency pair (digital or physical)
-
-### alpha_vantage/REST.historic_cryptocurrency_quotes(self, symbol, market, cadence='daily', output_format=None)
-Returns a `csv`, `json`, or `pandas` object of historical OHLCV data for the cryptocurrency pair.
-
-### alpha_vantage/REST.techindicators(self, techindicator='SMA', output_format='json', **kwargs)
-Returns a `csv`, `json`, or `pandas` object with the data from the techindicator of choice.
-
-### alpha_vantage/REST.sector()
-Returns a `json` of the currrency sector performances.
-
 ## Support and Contribution
 
 For technical issues particular to this module, please report the
 issue on this GitHub repository. Any API issues can be reported through
 Alpaca's customer support.
 
-New features, as well as bug fixes, by sending pull request is always
+New features, as well as bug fixes, by sending a pull request is always
 welcomed.

alpaca_trade_api/__init__.py

@@ -1,4 +1,4 @@
 from .rest import REST  # noqa
 from .stream2 import StreamConn  # noqa
 
-__version__ = '0.49.0'
+__version__ = '0.49.1'