# ``pm-td-ameritrade-api``: A wrapper for the TD Ameritrade API Spec
## **What's new???**
* ``Pydantic Models`` for nearly everything (Orders, Rest and streaming endpoints, etc.)
* More dynamic functionality (e.g. auth flow, logging, ``QueryInitializer``)
* True sync or async for streaming api
* Config module
Take a look at ``samples/`` to see use cases for REST endpoints and ``samples/stream_client`` for streaming services.
## How to install
```python
pip install pm-td-ameritrade-api
```
This project takes inspiration from two other API wrappers for the [TDA API Spec](https://developer.tdameritrade.com/apis):
* The original version I edited, which was the main inspiration for the code structure: [https://github.com/areed1192/td-ameritrade-api](https://github.com/areed1192/td-ameritrade-api)
* Another version I used at least for base orders classes: [https://github.com/alexgolec/tda-api](https://github.com/alexgolec/tda-api)
## Detailed Changes
1) ``Authentication and Configuration:`` Now handled automatically through a config file specified with an environment variable, **TD_API_CONFIG_PATH**, this config file automates the login/auth process using Selenium all done through a new Config.py module, as well as information for various other modules.
Here's an example of what it looks like:
found in samples/z-config-example.ini
```ini
[app_info]
app_name = meep
client_id = meepmeep
redirect_uri = https://127.0.0.1:XXXX
[credentials]
username = meepmeepmeep
account_password = meepmeepmeepmeepmeep
secretquestion0 = General
secretanswer0 = Kenobi
secretquestion1 = Secret to life
secretanswer1 = 42
secretquestion2 = Favorite color
secretanswer2 = Blue! No..wait-AHHHHHHHHH!
secretquestion3 = Should you revenge trade
secretanswer3 = No
[accounts]
default = 123456789
ROTH_IRA = 123456789
TRADITIONAL_IRA = 123456789
CASH = 123456789
MARGIN = 123456789
[logging]
log_root_path = C://Users//meep//OneDrive//Desktop//meep//td-ameritrade-api//logs
use_bulk_app_name_logging = True
[symbols]
tda_futures_path = .../tda-futures.csv
actively_traded_equities_path = .../tda-actively-traded-equities.csv
[data_paths]
equity_data_base_path = .../tda-data/equity
futures_data_base_path = .../tda-data/future
```
So now in terms of the login flow/process, if the environment variable is specified, you can just do this:
```python
td_client = TdAmeritradeClient()
```
instead of...
```python
# Initialize the Parser.
config = ConfigParser()
# Read the file.
config.read('config/config.ini')
# Get the specified credentials.
client_id = config.get('main', 'client_id')
redirect_uri = config.get('main', 'redirect_uri')
# Intialize our `Credentials` object.
td_credentials = TdCredentials(
client_id=client_id,
redirect_uri=redirect_uri,
credential_file='config/td_credentials.json'
)
# Initalize the `TdAmeritradeClient`
td_client = TdAmeritradeClient(
credentials=td_credentials
)
```
2) ``Added Logging:`` Colored logging is now done to the console, and, if specified, to a logging directory from the config.ini file. In the config file, ``use_bulk_app_name_logging``, dictates whether, in addition to module-level logging, all logging is written to the log file specified by app_name.
Also, for logging, I added variables to the client for whether you want to log sent/received messages. I have log sent True and log received as fault for both REST api and streaming api by default.
`td_client = TdAmeritradeClient(log_sent_messages=True, log_received_messages=True)`
Debug logging - Program will look for the environment variable, ``TD_API_DEBUG``, set to True or False.
3) ``Pydantic Models for dataclasses and validation - REST / Orders:`` In td/models I added a variety of models for various things in the api. For the REST endpoints, I have a decorator called ``QueryInitializer``, that specifies the model for the function in a specific service (e.g. Price History service, price_history.py, has a get_price_history function, decorated with "@QueryInitializer(PriceHistoryQuery)" that allows three different calling methods:
```python
1. Population by field names specified in `PriceHistoryQuery`
>>> price_history_service = td_client.price_history()
>>> price_history = price_history_service.get_price_history(
symbol="MSFT",
frequency_type=FrequencyType.DAILY,
frequency=1,
period_type=PeriodType.MONTH,
period=1,
extended_hours_needed=False,
)
2. Pass a dictionary with field names specified in `PriceHistoryQuery`
>>> price_history = price_history_service.get_price_history({
"symbol": "MSFT",
"frequency_type": FrequencyType.DAILY,
"frequency": 1,
"period_type": PeriodType.MONTH,
"period": 1,
"extended_hours_needed": False,
})
3. Pass an `PriceHistoryQuery` object directly
>>> price_history_query = PriceHistoryQuery(**{
"symbol": "MSFT",
"frequency_type": FrequencyType.DAILY,
"frequency": 1,
"period_type": PeriodType.MONTH,
"period": 1,
"extended_hours_needed": False,
})
>>> price_history = price_history_service.get_price_history(price_history_query)
```
Orders has a recursive model defined in orders.py along with a builder class, builder.py, and various builder helper functions in equities.py and options.py
4) ``Pydantic Models for dataclasses and validation - Streaming:`` The streaming messages, with the exception of order activity, all have formal Pydantic models defined. Take a look at ``samples/example_handlers.py`` for how to use them. In general, there's a BaseDataMessageHandler that acts as a dynamic initializer. There are also, BaseChartHistoryHandler, and BaseActivesHandler..
5) ``Synchronous or Asynchronous asyncio usage of streaming API:`` See samples/stream_client/use_synchronously.py vs something like samples/stream_client/quotes/use_level_one.py
6) ``Ability to use camelCase or snake_case for Pydantic models:`` All models have an alias generator for camelCase so they can use either. This is also used in sending a payload. Although the data classes have snake_case, sending a request with by_alias=True, allows conversion into what the API endpoints expect.
```python
res = self.session.make_request(
method="get",
endpoint=f"marketdata/{movers_query.index}/movers",
params=movers_query.model_dump(mode="json", by_alias=True),
)
```
7) ``Various other touch-ups and reworking of the code:`` Like reviewing documentation, touching up and making sure enums were correct, consolidating helper functions, etc.
``Future:`` Who knows how much the API will change with the Schwab merger/acquisition. I plan to update the API further when the Schwab spec is available.
1) ``Testing``: All testing is currently done by manually calling the sample files. This isn't nearly robust enough and a testing strategy needs to be developed. I'm largely waiting for Schwab's new spec before writing tests though.
2) ``ACCT_ACTIVITY``: Handling this service and parsing the XML from there and converting that into Pydantic models is a task I wasn't ready to tackle yet, especially since this process may change.
3) ``Saved Orders / Watchlists``: In addition, for now, I don't have the code for watchlists or saved_orders since Schwab plans to remove them. If someone wants to add that code back in I'd be happy to review a PR and merge. I did not spend the time since I currently don't use them and they're being removed by Schwab.
4) ``Expand Order Types and Examples``: Add more types of orders and examples (e.g. stop loss orders)
5) ``Sync/async of REST endpoints:`` I plan to do this same type of interface of having an event loop running in the background for the main REST endpoints and also allow those to be async/sync soon. So using aiohttp in the future, maybe do asynchronous logging at the same time as well as look at where else async can be used.
6) ``Better documentation of validation for rest endpoints:`` Although using Pydantic and QueryInitializer is neat, convenient, and concise, when hovering over a function definition, it just says it takes the model but doesn't specify exactly what it expects. This could use some work. Not sure how to go about that at this point.
7) ``Event-based trading architecture:`` Potential changes to make the project "pluggable" into such an architecture.
**Discord:**
I made a discord if anyone is interested. [Join Discord](https://discord.gg/a3eHnNhF)
Raw data
{
"_id": null,
"home_page": "https://github.com/primalmachinai/pm-td-ameritrade-api",
"name": "pm-td-ameritrade-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "finance,td ameritrade,api",
"author": "primalmachinai",
"author_email": "primalmachinai@gmail.com",
"download_url": "",
"platform": null,
"description": "# ``pm-td-ameritrade-api``: A wrapper for the TD Ameritrade API Spec\n\n## **What's new???**\n* ``Pydantic Models`` for nearly everything (Orders, Rest and streaming endpoints, etc.)\n* More dynamic functionality (e.g. auth flow, logging, ``QueryInitializer``)\n* True sync or async for streaming api\n* Config module\n\nTake a look at ``samples/`` to see use cases for REST endpoints and ``samples/stream_client`` for streaming services.\n\n## How to install\n\n```python\npip install pm-td-ameritrade-api\n```\n\n\nThis project takes inspiration from two other API wrappers for the [TDA API Spec](https://developer.tdameritrade.com/apis):\n* The original version I edited, which was the main inspiration for the code structure: [https://github.com/areed1192/td-ameritrade-api](https://github.com/areed1192/td-ameritrade-api)\n* Another version I used at least for base orders classes: [https://github.com/alexgolec/tda-api](https://github.com/alexgolec/tda-api)\n\n## Detailed Changes\n1) ``Authentication and Configuration:`` Now handled automatically through a config file specified with an environment variable, **TD_API_CONFIG_PATH**, this config file automates the login/auth process using Selenium all done through a new Config.py module, as well as information for various other modules.\nHere's an example of what it looks like:\n\nfound in samples/z-config-example.ini\n\n```ini\n[app_info]\napp_name = meep\nclient_id = meepmeep\nredirect_uri = https://127.0.0.1:XXXX\n[credentials]\nusername = meepmeepmeep\naccount_password = meepmeepmeepmeepmeep\nsecretquestion0 = General\nsecretanswer0 = Kenobi\nsecretquestion1 = Secret to life\nsecretanswer1 = 42\nsecretquestion2 = Favorite color\nsecretanswer2 = Blue! No..wait-AHHHHHHHHH!\nsecretquestion3 = Should you revenge trade\nsecretanswer3 = No\n[accounts]\ndefault = 123456789\nROTH_IRA = 123456789\nTRADITIONAL_IRA = 123456789\nCASH = 123456789\nMARGIN = 123456789\n[logging]\nlog_root_path = C://Users//meep//OneDrive//Desktop//meep//td-ameritrade-api//logs\nuse_bulk_app_name_logging = True\n[symbols]\ntda_futures_path = .../tda-futures.csv\nactively_traded_equities_path = .../tda-actively-traded-equities.csv\n[data_paths]\nequity_data_base_path = .../tda-data/equity\nfutures_data_base_path = .../tda-data/future\n```\n\nSo now in terms of the login flow/process, if the environment variable is specified, you can just do this:\n\n```python\ntd_client = TdAmeritradeClient()\n```\n\ninstead of...\n\n```python\n# Initialize the Parser.\nconfig = ConfigParser()\n# Read the file.\nconfig.read('config/config.ini')\n# Get the specified credentials.\nclient_id = config.get('main', 'client_id')\nredirect_uri = config.get('main', 'redirect_uri')\n# Intialize our `Credentials` object.\ntd_credentials = TdCredentials(\nclient_id=client_id,\nredirect_uri=redirect_uri,\ncredential_file='config/td_credentials.json'\n)\n# Initalize the `TdAmeritradeClient`\ntd_client = TdAmeritradeClient(\ncredentials=td_credentials\n)\n```\n\n2) ``Added Logging:`` Colored logging is now done to the console, and, if specified, to a logging directory from the config.ini file. In the config file, ``use_bulk_app_name_logging``, dictates whether, in addition to module-level logging, all logging is written to the log file specified by app_name.\nAlso, for logging, I added variables to the client for whether you want to log sent/received messages. I have log sent True and log received as fault for both REST api and streaming api by default.\n`td_client = TdAmeritradeClient(log_sent_messages=True, log_received_messages=True)`\nDebug logging - Program will look for the environment variable, ``TD_API_DEBUG``, set to True or False.\n\n3) ``Pydantic Models for dataclasses and validation - REST / Orders:`` In td/models I added a variety of models for various things in the api. For the REST endpoints, I have a decorator called ``QueryInitializer``, that specifies the model for the function in a specific service (e.g. Price History service, price_history.py, has a get_price_history function, decorated with \"@QueryInitializer(PriceHistoryQuery)\" that allows three different calling methods:\n\n```python\n 1. Population by field names specified in `PriceHistoryQuery`\n >>> price_history_service = td_client.price_history()\n >>> price_history = price_history_service.get_price_history(\n symbol=\"MSFT\",\n frequency_type=FrequencyType.DAILY,\n frequency=1,\n period_type=PeriodType.MONTH,\n period=1,\n extended_hours_needed=False,\n )\n 2. Pass a dictionary with field names specified in `PriceHistoryQuery`\n >>> price_history = price_history_service.get_price_history({\n \"symbol\": \"MSFT\",\n \"frequency_type\": FrequencyType.DAILY,\n \"frequency\": 1,\n \"period_type\": PeriodType.MONTH,\n \"period\": 1,\n \"extended_hours_needed\": False,\n })\n\n 3. Pass an `PriceHistoryQuery` object directly\n >>> price_history_query = PriceHistoryQuery(**{\n \"symbol\": \"MSFT\",\n \"frequency_type\": FrequencyType.DAILY,\n \"frequency\": 1,\n \"period_type\": PeriodType.MONTH,\n \"period\": 1,\n \"extended_hours_needed\": False,\n })\n >>> price_history = price_history_service.get_price_history(price_history_query)\n```\n\nOrders has a recursive model defined in orders.py along with a builder class, builder.py, and various builder helper functions in equities.py and options.py\n\n4) ``Pydantic Models for dataclasses and validation - Streaming:`` The streaming messages, with the exception of order activity, all have formal Pydantic models defined. Take a look at ``samples/example_handlers.py`` for how to use them. In general, there's a BaseDataMessageHandler that acts as a dynamic initializer. There are also, BaseChartHistoryHandler, and BaseActivesHandler..\n\n5) ``Synchronous or Asynchronous asyncio usage of streaming API:`` See samples/stream_client/use_synchronously.py vs something like samples/stream_client/quotes/use_level_one.py\n\n6) ``Ability to use camelCase or snake_case for Pydantic models:`` All models have an alias generator for camelCase so they can use either. This is also used in sending a payload. Although the data classes have snake_case, sending a request with by_alias=True, allows conversion into what the API endpoints expect.\n\n```python\nres = self.session.make_request(\n method=\"get\",\n endpoint=f\"marketdata/{movers_query.index}/movers\",\n params=movers_query.model_dump(mode=\"json\", by_alias=True),\n )\n ```\n\n7) ``Various other touch-ups and reworking of the code:`` Like reviewing documentation, touching up and making sure enums were correct, consolidating helper functions, etc.\n\n``Future:`` Who knows how much the API will change with the Schwab merger/acquisition. I plan to update the API further when the Schwab spec is available.\n\n1) ``Testing``: All testing is currently done by manually calling the sample files. This isn't nearly robust enough and a testing strategy needs to be developed. I'm largely waiting for Schwab's new spec before writing tests though.\n2) ``ACCT_ACTIVITY``: Handling this service and parsing the XML from there and converting that into Pydantic models is a task I wasn't ready to tackle yet, especially since this process may change. \n3) ``Saved Orders / Watchlists``: In addition, for now, I don't have the code for watchlists or saved_orders since Schwab plans to remove them. If someone wants to add that code back in I'd be happy to review a PR and merge. I did not spend the time since I currently don't use them and they're being removed by Schwab.\n4) ``Expand Order Types and Examples``: Add more types of orders and examples (e.g. stop loss orders)\n5) ``Sync/async of REST endpoints:`` I plan to do this same type of interface of having an event loop running in the background for the main REST endpoints and also allow those to be async/sync soon. So using aiohttp in the future, maybe do asynchronous logging at the same time as well as look at where else async can be used.\n6) ``Better documentation of validation for rest endpoints:`` Although using Pydantic and QueryInitializer is neat, convenient, and concise, when hovering over a function definition, it just says it takes the model but doesn't specify exactly what it expects. This could use some work. Not sure how to go about that at this point.\n7) ``Event-based trading architecture:`` Potential changes to make the project \"pluggable\" into such an architecture.\n\n**Discord:**\n\nI made a discord if anyone is interested. [Join Discord](https://discord.gg/a3eHnNhF)\n",
"bugtrack_url": null,
"license": "",
"summary": "A python client library for the TD Ameritrade API.",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/primalmachinai/pm-td-ameritrade-api"
},
"split_keywords": [
"finance",
"td ameritrade",
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e8cdc16504ff0524baf57e61df52ebaa6e98b818352dc884dd18f97d196bf543",
"md5": "4a2cdafe0cb426e0abf6fa4804461bee",
"sha256": "79f10e68ea381b4aa6890f93e9ba44e84fbcdaaeb358adfb7c30ddc7b9246065"
},
"downloads": -1,
"filename": "pm_td_ameritrade_api-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a2cdafe0cb426e0abf6fa4804461bee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 6151,
"upload_time": "2024-01-18T12:14:30",
"upload_time_iso_8601": "2024-01-18T12:14:30.828877Z",
"url": "https://files.pythonhosted.org/packages/e8/cd/c16504ff0524baf57e61df52ebaa6e98b818352dc884dd18f97d196bf543/pm_td_ameritrade_api-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 12:14:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "primalmachinai",
"github_project": "pm-td-ameritrade-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "aiofiles",
"specs": [
[
">=",
"23.2.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.4.2"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.6.0"
]
]
},
{
"name": "websockets",
"specs": [
[
">=",
"11.0.3"
]
]
},
{
"name": "colorlog",
"specs": [
[
">=",
"6.7.0"
]
]
},
{
"name": "selenium",
"specs": [
[
">=",
"4.14.0"
]
]
},
{
"name": "requests",
"specs": []
},
{
"name": "webdriver_manager",
"specs": []
}
],
"lcname": "pm-td-ameritrade-api"
}
JSON
