Move to async-only library for version>=12 (#299)

* Move to async-only library for version>=12

For a long time this library was mostly sync, with the streamers being
the exception. PR #168 added async endpoints on top of the existing
endpoints, which gave users more flexibility. With this change, I
propose that version 12+ be async-only.

There are a few reasons for this. First of all, having both sync and
async versions of everything resulted in a ton of code duplication
(check out how many lines are removed in this commit!). Second, both
streamers are (and always have been) async, meaning that almost all
users are already implementing at least *some* async code, so having the
separate sync versions makes less sense. Finally, this change allows us
to support Trio and clean up the streamer implementation which was hard
to reason about and prone to bugs.

Summary of important changes:

- `httpx-ws` library replaces `websockets`, allowing for Trio support.
  As a consequence of this, reconnect and disconnect functionality is
  gone (however, this is almost certainly better handled on the user
  side anyways).

- Python 3.10 support is dropped as we're now using `ExceptionGroup`s.
  This would likely have happened soon anyways as the official support
  lifecycle only goes through October 2026.

- All previous sync endpoints are now async. All previous async
  endpoints have been removed (so instead of having endpoints named
  `Account.a_get` for async and `Account.get` for sync, we have a single
  endpoint named `Account.get`, which is async).

- Session token refreshing is smarter: Instead of making users check and
  refresh themselves, they will auto-refresh before any request if
  they're close to expiry. Sessions also have an optional async context
  manager which can be used to ensure cleanup happens.

- Streamers now use `httpx-ws` websockets and structured concurrency,
  making them much simpler and easier to reason about (which implies a
  lower chance of bugs in the future). We also get to use the helpful
  `send_json` and `receive_json` functions instead of wrapping
  everything in `json.dumps`/`json.loads`.

- `tastytrade.dxfeed.Quote` events now have helpful `mid_price` and
  `micro_price` properties calculated from its bid/ask prices.

- `tastytrade.order.OrderAction` has a `multiplier` property which is
  `-1` when it's a "Sell" leg and `1` when it's a "Buy" leg.

- Test suite now runs on both asyncio and Trio.

* update docs

* bump min pydantic version for 3.14 support

Author: Graeme22

.github/pull_request_template.md

@@ -5,8 +5,8 @@ Fixes ...
 
 ## Pre-merge checklist
 - [ ] Code formatted correctly (check with `make lint`)
-- [ ] Code implemented for both sync and async
 - [ ] Passing tests locally (check with `make test`, make sure you have `TT_REFRESH`, `TT_SECRET`, and `TT_ACCOUNT` environment variables set)
 - [ ] New tests added (if applicable)
+- [ ] Docs updated (if applicable)
 
 Please note that, in order to pass the tests, you'll need to set up your Tastytrade credentials as repository secrets on your local fork. Read more at CONTRIBUTING.md.

.github/workflows/python-app.yml

@@ -13,7 +13,6 @@ jobs:
       max-parallel: 1
       matrix:
         python-version:
-          - "3.10"
           - "3.11"
           - "3.12"
           - "3.13"
@@ -39,7 +38,7 @@ jobs:
         uv run mypy tastytrade/
     - name: Test with pytest
       run: |
-        uv run pytest --cov=tastytrade --cov-report=term-missing tests/ --cov-fail-under=95
+        uv run pytest --cov=tastytrade --cov-report=term-missing tests/ --cov-fail-under=95 -v
       env:
         TT_REFRESH_SANDBOX: ${{ secrets.TT_REFRESH_SANDBOX }}
         TT_SECRET_SANDBOX: ${{ secrets.TT_SECRET_SANDBOX }}

.python-version

@@ -1 +1 @@
-3.10
+3.11

Makefile

@@ -11,7 +11,7 @@ lint:
 	uv run mypy tastytrade/
 
 test:
-	uv run pytest --cov=tastytrade --cov-report=term-missing tests/ --cov-fail-under=95
+	uv run pytest --cov=tastytrade --cov-report=term-missing tests/ --cov-fail-under=95 -v
 
 docs:
 	uv run -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs/ docs/_build/

README.md

@@ -10,8 +10,7 @@ A simple, reverse-engineered SDK for Tastytrade built on their (now mostly publi
 ## Features
 
 - Up to 10x less code than using the API directly
-- Sync/async functions for all endpoints
-- Powerful websocket implementation for account alerts and data streaming, with support for auto-reconnection and reconnection callbacks
+- Powerful websocket implementation for account alerts and data streaming
 - 100% typed, with Pydantic models for all JSON responses from the API
 - 95%+ unit test coverage
 - Comprehensive documentation
@@ -65,27 +64,15 @@ Note that this is asynchronous code, so you can't run it as is unless you're usi
 ```python
 from tastytrade import Account
 
-account = Account.get(session)[0]
-positions = account.get_positions(session)
+account = (await Account.get(session))[0]
+positions = await account.get_positions(session)
 print(positions[0])
 ```
 
 ```python
 >>> CurrentPosition(account_number='5WX01234', symbol='IAU', instrument_type=<InstrumentType.EQUITY: 'Equity'>, underlying_symbol='IAU', quantity=Decimal('20'), quantity_direction='Long', close_price=Decimal('37.09'), average_open_price=Decimal('37.51'), average_yearly_market_close_price=Decimal('37.51'), average_daily_market_close_price=Decimal('37.51'), multiplier=1, cost_effect=<PriceEffect.CREDIT: 'Credit'>, is_suppressed=False, is_frozen=False, realized_day_gain=Decimal('7.888'), realized_day_gain_date=datetime.date(2023, 5, 19), realized_today=Decimal('-0.512'), realized_today_date=datetime.date(2023, 5, 19), created_at=datetime.datetime(2023, 3, 31, 14, 38, 32, 58000, tzinfo=datetime.timezone.utc), updated_at=datetime.datetime(2023, 5, 19, 16, 56, 51, 920000, tzinfo=datetime.timezone.utc), mark=None, mark_price=None, restricted_quantity=Decimal('0'), expires_at=None, fixing_price=None, deliverable_type=None)
 ```
 
-## Sync/async wrappers
-
-The code from above can be rewritten asynchronously:
-
-```python
-from tastytrade import Account
-
-account = (await Account.a_get(session))[0]
-positions = await account.a_get_positions(session)
-print(positions[0])
-```
-
 ## Placing an order
 
 ```python
@@ -94,8 +81,8 @@ from tastytrade import Account
 from tastytrade.instruments import Equity
 from tastytrade.order import NewOrder, OrderAction, OrderTimeInForce, OrderType
 
-account = Account.get(session, '5WX01234')
-symbol = Equity.get(session, 'USO')
+account = await Account.get(session, '5WX01234')
+symbol = await Equity.get(session, 'USO')
 leg = symbol.build_leg(Decimal('5'), OrderAction.BUY_TO_OPEN)  # buy to open 5 shares
 
 order = NewOrder(
@@ -104,7 +91,7 @@ order = NewOrder(
     legs=[leg],  # you can have multiple legs in an order
     price=Decimal('-10')  # limit price, $10/share debit for a total value of $50
 )
-response = account.place_order(session, order, dry_run=True)  # a test order
+response = await account.place_order(session, order, dry_run=True)  # a test order
 print(response)
 ```
 
@@ -120,7 +107,7 @@ from tastytrade.dxfeed import Greeks
 from tastytrade.instruments import get_option_chain
 from tastytrade.utils import get_tasty_monthly
 
-chain = get_option_chain(session, 'SPLG')
+chain = await get_option_chain(session, 'SPLG')
 exp = get_tasty_monthly()  # 45 DTE expiration!
 subs_list = [chain[exp][0].streamer_symbol]
 

docs/account-streamer.rst

@@ -14,10 +14,6 @@ Here's an example of setting up an account streamer to continuously wait for eve
     from tastytrade import Account, AlertStreamer, Watchlist
 
     async with AlertStreamer(session) as streamer:
-        accounts = Account.get(session)
-
-        # updates to balances, orders, and positions
-        await streamer.subscribe_accounts(accounts)
         # changes in public watchlists
         await streamer.subscribe_public_watchlists()
         # quote alerts configured by the user
@@ -33,50 +29,31 @@ Probably the most important information the account streamer handles is order fi
     from tastytrade.order import PlacedOrder
 
     async with AlertStreamer(session) as streamer:
-        accounts = Account.get(session)
+        # updates to balances, orders, and positions
+        accounts = await Account.get(session)
         await streamer.subscribe_accounts(accounts)
 
         async for order in streamer.listen(PlacedOrder):
             print(order)
 
-Disconnect callback
--------------------
+Auto-retries
+------------
 
-The disconnect callback can be used to run arbitrary code when the websocket connection has been disconnected.
-This is useful for notification purposes in your application when you need high availability.
-The callback function should look something like this:
+Often, account streamer connections should be long-lived and persistent. While the SDK doesn't provide this functionality itself, it's pretty trivial to build with just a few lines of code:
 
 .. code-block:: python
 
-    async def disconnect_callback(streamer: AlertStreamer):
-        print("Disconnected!")
-
-The requirements are that the first parameter be the `AlertStreamer` instance, and the function should be asynchronous.
-This callback can then be used when creating the streamer:
-
-.. code-block:: python
-
-    async with AlertStreamer(session, disconnect_fn=disconnect_callback) as streamer:
-        # ...
-
-Retry callback
---------------
-
-The account streamer has a special "callback" function which can be used to execute arbitrary code whenever the websocket reconnects. This is useful for re-subscribing to whatever alerts you wanted to subscribe to initially (in fact, you can probably use the same function/code you use when initializing the connection).
-The callback function should look something like this:
-
-.. code-block:: python
-
-    async def reconnect_callback(streamer: AlertStreamer, arg1, arg2):
-        await streamer.subscribe_quote_alerts()
-
-The requirements are that the first parameter be the `AlertStreamer` instance, and the function should be asynchronous. Other than that, you have the flexibility to decide what arguments you want to use.
-This callback can then be used when creating the streamer:
-
-.. code-block:: python
+    from anyio import sleep
+    from httpx_ws import HTTPXWSException
 
-    async with AlertStreamer(session, reconnect_fn=reconnect_callback, reconnect_args=(arg1, arg2)) as streamer:
-        # ...
+    tries, max_tries = 0, 3
+    while (tries := tries + 1) <= max_tries:
+        try:
+            async with AlertStreamer(session) as streamer:
+                print("Yay! Connected!")
+                ...
+        except* HTTPXWSException:
+            print("Oh no! Disconnected!")
+            await sleep(tries ** 2)
 
-The reconnection uses `websockets`' exponential backoff algorithm, which can be configured through environment variables `here <https://websockets.readthedocs.io/en/14.1/reference/variables.html>`_.
-The difference between the disconnect and reconnect callbacks is that the disconnect will be called immediately when the connection is broken, whereas the reconnect callback will only be called once the connection is re-established.
+Now we have persistence, exponential backoff, and disconnect/reconnect hooks--easy!

docs/accounts.rst

@@ -8,19 +8,19 @@ The easiest way to get an account is to grab all accounts associated with a spec
 .. code-block:: python
 
    from tastytrade import Account
-   accounts = Account.get(session)
+   accounts = await Account.get(session)
 
 You can also get a specific account by its unique ID:
 
 .. code-block:: python
 
-   account = Account.get(session, '5WX01234')
+   account = await Account.get(session, '5WX01234')
 
 The ``get_balances`` function can be used to obtain information about the current buying power and cash balance:
 
 .. code-block:: python
 
-   balance = account.get_balances(session)
+   balance = await account.get_balances(session)
    print(balance)
 
 >>> AccountBalance(account_number='5WX01234', cash_balance=Decimal('87.055'), long_equity_value=Decimal('4046.05'), short_equity_value=Decimal('0.0'), long_derivative_value=Decimal('0.0'), short_derivative_value=Decimal('0.0'), long_futures_value=Decimal('0.0'), short_futures_value=Decimal('0.0'), long_futures_derivative_value=Decimal('0.0'), short_futures_derivative_value=Decimal('0.0'), long_margineable_value=Decimal('0.0'), short_margineable_value=Decimal('0.0'), margin_equity=Decimal('4133.105'), equity_buying_power=Decimal('87.055'), derivative_buying_power=Decimal('87.055'), day_trading_buying_power=Decimal('0.0'), futures_margin_requirement=Decimal('0.0'), available_trading_funds=Decimal('0.0'), maintenance_requirement=Decimal('4048.85'), maintenance_call_value=Decimal('0.0'), reg_t_call_value=Decimal('0.0'), day_trading_call_value=Decimal('0.0'), day_equity_call_value=Decimal('0.0'), net_liquidating_value=Decimal('4133.105'), cash_available_to_withdraw=Decimal('87.06'), day_trade_excess=Decimal('87.06'), pending_cash=Decimal('0.0'), pending_cash_effect=<PriceEffect.NONE: 'None'>, long_cryptocurrency_value=Decimal('0.0'), short_cryptocurrency_value=Decimal('0.0'), cryptocurrency_margin_requirement=Decimal('0.0'), unsettled_cryptocurrency_fiat_amount=Decimal('0.0'), unsettled_cryptocurrency_fiat_effect=<PriceEffect.NONE: 'None'>, closed_loop_available_balance=Decimal('87.06'), equity_offering_margin_requirement=Decimal('0.0'), long_bond_value=Decimal('0.0'), bond_margin_requirement=Decimal('0.0'), snapshot_date=datetime.date(2023, 11, 28), reg_t_margin_requirement=Decimal('4048.85'), futures_overnight_margin_requirement=Decimal('0.0'), futures_intraday_margin_requirement=Decimal('0.0'), maintenance_excess=Decimal('87.055'), pending_margin_interest=Decimal('0.0'), effective_cryptocurrency_buying_power=Decimal('87.055'), updated_at=datetime.datetime(2023, 11, 28, 20, 54, 33, 556000, tzinfo=datetime.timezone.utc), apex_starting_day_margin_equity=None, buying_power_adjustment=None, buying_power_adjustment_effect=None, time_of_day=None)
@@ -29,7 +29,7 @@ To obtain information about current positions:
 
 .. code-block:: python
 
-   positions = account.get_positions(session)
+   positions = await account.get_positions(session)
    print(positions[0])
 
 >>> CurrentPosition(account_number='5WX01234', symbol='BRK/B', instrument_type=<InstrumentType.EQUITY: 'Equity'>, underlying_symbol='BRK/B', quantity=Decimal('10'), quantity_direction='Long', close_price=Decimal('361.34'), average_open_price=Decimal('339.63'), multiplier=1, cost_effect='Credit', is_suppressed=False, is_frozen=False, realized_day_gain=Decimal('18.5'), realized_today=Decimal('279.15'), created_at=datetime.datetime(2023, 3, 31, 14, 35, 40, 138000, tzinfo=datetime.timezone.utc), updated_at=datetime.datetime(2023, 8, 10, 15, 42, 7, 482000, tzinfo=datetime.timezone.utc), mark=None, mark_price=None, restricted_quantity=Decimal('0'), expires_at=None, fixing_price=None, deliverable_type=None, average_yearly_market_close_price=Decimal('339.63'), average_daily_market_close_price=Decimal('361.34'), realized_day_gain_effect=<PriceEffect.CREDIT: 'Credit'>, realized_day_gain_date=datetime.date(2023, 8, 10), realized_today_effect=<PriceEffect.CREDIT: 'Credit'>, realized_today_date=datetime.date(2023, 8, 10))
@@ -38,7 +38,7 @@ To fetch a list of past transactions:
 
 .. code-block:: python
 
-   history = account.get_history(session, start_date=date(2024, 1, 1))
+   history = await account.get_history(session, start_date=date(2024, 1, 1))
    print(history[-1])
 
 >>> Transaction(id=280070508, account_number='5WX01234', transaction_type='Trade', transaction_sub_type='Sell to Close', description='Sold 10 BRK/B @ 384.04', executed_at=datetime.datetime(2024, 1, 26, 15, 51, 53, 685000, tzinfo=datetime.timezone.utc), transaction_date=datetime.date(2024, 1, 26), value=Decimal('3840.4'), value_effect=<PriceEffect.CREDIT: 'Credit'>, net_value=Decimal('3840.35'), net_value_effect=<PriceEffect.CREDIT: 'Credit'>, is_estimated_fee=True, symbol='BRK/B', instrument_type=<InstrumentType.EQUITY: 'Equity'>, underlying_symbol='BRK/B', action='Sell to Close', quantity=Decimal('10.0'), price=Decimal('384.04'), regulatory_fees=Decimal('0.042'), regulatory_fees_effect=<PriceEffect.DEBIT: 'Debit'>, clearing_fees=Decimal('0.008'), clearing_fees_effect=<PriceEffect.DEBIT: 'Debit'>, commission=Decimal('0.0'), commission_effect=<PriceEffect.NONE: 'None'>, proprietary_index_option_fees=Decimal('0.0'), proprietary_index_option_fees_effect=<PriceEffect.NONE: 'None'>, ext_exchange_order_number='12271026815307', ext_global_order_number=2857, ext_group_id='0', ext_group_fill_id='0', ext_exec_id='0', exec_id='123_40126000126350300000', exchange='JNS', order_id=305250635, exchange_affiliation_identifier='', leg_count=1, destination_venue='JANE_STREET_EQUITIES_A', other_charge=None, other_charge_effect=None, other_charge_description=None, reverses_id=None, cost_basis_reconciliation_date=None, lots=None, agency_price=None, principal_price=None)
@@ -48,7 +48,7 @@ We can also view portfolio P/L over time (and even plot it!):
 .. code-block:: python
 
    import matplotlib.pyplot as plt
-   nl = account.get_net_liquidating_value_history(session, time_back='1m')  # past 1 month
+   nl = await account.get_net_liquidating_value_history(session, time_back='1m')  # past 1 month
    plt.plot([n.time for n in nl], [n.close for n in nl])
    plt.show()