trading-state 0.0.1__tar.gz

trading_state-0.0.1/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2013 kaelzhang <>, contributors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

trading_state-0.0.1/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: trading-state
+Version: 0.0.1
+Summary: A lightweight Python engine for simulating trading account balances, order states, and exchange-style constraints.
+Author-email: Kael Zhang <i+pypi@kael.me>
+Project-URL: Homepage, https://github.com/kaelzhang/python-trading-state
+Keywords: trading-state
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+[![](https://github.com/kaelzhang/python-trading-state/actions/workflows/python.yml/badge.svg)](https://github.com/kaelzhang/python-trading-state/actions/workflows/python.yml)
+[![](https://codecov.io/gh/kaelzhang/python-trading-state/branch/master/graph/badge.svg)](https://codecov.io/gh/kaelzhang/python-trading-state)
+[![](https://img.shields.io/pypi/v/trading-state.svg)](https://pypi.org/project/trading-state/)
+[![Conda version](https://img.shields.io/conda/vn/conda-forge/trading-state)](https://anaconda.org/conda-forge/trading-state)
+[![](https://img.shields.io/pypi/l/trading-state.svg)](https://github.com/kaelzhang/python-trading-state)
+
+# trading-state
+
+`trading-state` is a small, focused Python library that models the dynamic state of a trading account, including balances, positions, open orders, and PnL, under realistic exchange-like constraints.
+
+It provides configurable rules for price limits, notional and quantity limits, order validation, and order lifecycle transitions (new, partially filled, filled, canceled, rejected), making it easy to plug into backtesting frameworks, execution simulators, or custom quant research tools.
+
+By separating “trading state” from strategy logic, `trading-state` helps you build cleaner, more testable quantitative trading systems.
+
+## Install
+
+```sh
+$ pip install trading-state
+```
+
+## Usage
+
+```py
+from trading_state import TradingState
+```
+
+## License
+
+[MIT](LICENSE)

trading_state-0.0.1/README.md

@@ -0,0 +1,29 @@
+[![](https://github.com/kaelzhang/python-trading-state/actions/workflows/python.yml/badge.svg)](https://github.com/kaelzhang/python-trading-state/actions/workflows/python.yml)
+[![](https://codecov.io/gh/kaelzhang/python-trading-state/branch/master/graph/badge.svg)](https://codecov.io/gh/kaelzhang/python-trading-state)
+[![](https://img.shields.io/pypi/v/trading-state.svg)](https://pypi.org/project/trading-state/)
+[![Conda version](https://img.shields.io/conda/vn/conda-forge/trading-state)](https://anaconda.org/conda-forge/trading-state)
+[![](https://img.shields.io/pypi/l/trading-state.svg)](https://github.com/kaelzhang/python-trading-state)
+
+# trading-state
+
+`trading-state` is a small, focused Python library that models the dynamic state of a trading account, including balances, positions, open orders, and PnL, under realistic exchange-like constraints.
+
+It provides configurable rules for price limits, notional and quantity limits, order validation, and order lifecycle transitions (new, partially filled, filled, canceled, rejected), making it easy to plug into backtesting frameworks, execution simulators, or custom quant research tools.
+
+By separating “trading state” from strategy logic, `trading-state` helps you build cleaner, more testable quantitative trading systems.
+
+## Install
+
+```sh
+$ pip install trading-state
+```
+
+## Usage
+
+```py
+from trading_state import TradingState
+```
+
+## License
+
+[MIT](LICENSE)

trading_state-0.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trading-state"
+authors = [
+    {name = "Kael Zhang", email = "i+pypi@kael.me"}
+]
+description = "A lightweight Python engine for simulating trading account balances, order states, and exchange-style constraints."
+readme = "README.md"
+license-files = ["LICENSE"]
+keywords = ["trading-state"]
+classifiers = [
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+requires-python = ">=3.7"
+dynamic = ['version']
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/kaelzhang/python-trading-state"
+
+[project.optional-dependencies]
+dev = [
+    # "codecov",
+    "coverage",
+    "ruff",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "twine",
+    "mypy",
+    "build"
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "trading_state.__version__"}
+
+[tool.setuptools.package-data]
+trading_state = ["py.typed"]
+
+[tool.mypy]
+warn_return_any = true
+ignore_missing_imports = true
+no_implicit_optional = true
+strict_optional = true

trading_state-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trading_state-0.0.1/test/test_trading_state.py

@@ -0,0 +1,401 @@
+# import asyncio
+import pytest
+
+from trading_state.state import (
+    TraderState,
+
+    # TicketOrderSide
+)
+from trading_state.types import (
+    Balance
+)
+
+BTC = 'BTC'
+USDT = 'USDT'
+SYMBOL = BTC + USDT
+
+
+def set_price(state: TraderState):
+    state.set_price(SYMBOL, 7000.)
+
+
+def set_symbol_info(state: TraderState):
+    state.set_symbol_info(
+        SYMBOL,
+        BTC,
+        USDT,
+
+        '0.01',
+        '1000000',
+        '0.01',
+
+        '0.000001',
+        '9000',
+        '0.000001',
+
+        '10.00000000'
+    )
+
+
+def set_balances(state: TraderState):
+    state.update_balances([
+        Balance(
+            BTC,
+            15.,
+            0.
+        ),
+        Balance(
+            USDT,
+            0.001,
+            0.
+        )
+    ])
+
+
+def set_info(state: TraderState):
+    set_price(state)
+    set_symbol_info(state)
+
+
+def test_support():
+    state = TraderState()
+
+    set_info(state)
+
+    assert state.support_symbol(SYMBOL)
+
+    LTEBTC = 'LTEBTC'
+
+    assert not state.support_symbol(LTEBTC)
+    assert state.create_ticket(
+        LTEBTC,
+        1.,
+        False,
+        None
+    ) == (None, set())
+
+
+def test_non_diff():
+    state = TraderState()
+
+    set_balances(state)
+    set_info(state)
+
+    state.expect(
+        SYMBOL,
+        1.,
+        False,
+        None
+    )
+
+    diffed, to_cancel = state.get_tickets()
+
+    assert not diffed
+    assert not to_cancel
+
+
+def test_specified_price():
+    state = TraderState()
+
+    set_balances(state)
+    set_info(state)
+
+    ticket, to_cancel = state.create_ticket(
+        SYMBOL,
+        0.,
+        False,
+        7000.
+    )
+
+    assert not to_cancel
+    assert ticket is not None
+    assert ticket.price == 7000.
+
+    ticket2, to_cancel2 = state.create_ticket(
+        SYMBOL,
+        0.,
+        False,
+        6000.
+    )
+
+    assert ticket in to_cancel2
+    assert ticket2.price == 6000.
+
+    state.expect(
+        SYMBOL,
+        1.,
+        False,
+        5000.
+    )
+
+    # Different direction, cancel previous ticket
+    # ---------------------------------------------
+
+    tickets, to_cancel = state.get_tickets()
+
+    assert ticket2 in to_cancel
+    assert not tickets
+
+    # get_tickets again, previous ticket already closed
+    # ---------------------------------------------
+
+    tickets, to_cancel = state.get_tickets()
+
+    assert not tickets
+    assert not tickets
+
+    # Update balances should reset diff
+
+    state.update_balances([
+        Balance(
+            USDT,
+            1000.,
+            0.
+        )
+    ])
+
+    tickets, to_cancel = state.get_tickets()
+
+    ticket = tickets[0]
+
+    assert ticket.price == 5000.
+    assert ticket.symbol.name == SYMBOL
+    assert not to_cancel
+
+    # Will remove expectations
+
+    state.create_ticket(
+        SYMBOL,
+        0.,
+        False,
+        None
+    )
+
+    assert not state._expected
+
+
+@pytest.mark.asyncio
+async def test_diff():
+    state = TraderState()
+
+    def expect_sell_all(quantity: float = 15.):
+        # sell all
+        state.expect(
+            SYMBOL,
+            0.,
+            False,
+            None
+        )
+
+        if not state._expected:
+            return
+
+        assert repr(state._expected[SYMBOL]) == '<SymbolPosition BTCUSDT: value: 0.0, asap: False, price: None>'
+
+        diff, _ = state.get_tickets()
+
+        if not diff:
+            return
+
+        ticket = diff[0]
+
+        assert str(ticket.order_side) == 'SELL'
+        assert ticket.symbol.name == SYMBOL
+        assert ticket.price == 7000.
+
+        assert ticket.quantity == '15.000000'
+
+        assert ticket.locked_asset == BTC
+        assert ticket.locked_quantity == quantity
+
+        return ticket
+
+    def expect_all_in():
+        # buy all
+        state.expect(
+            SYMBOL,
+            1.,
+            False,
+            None
+        )
+
+        diff, _ = state.get_tickets()
+
+        if not diff:
+            return
+
+        return diff[0]
+
+    state.expect(
+        SYMBOL,
+        0.,
+        False,
+        None
+    )
+
+    assert not state._expected, 'BTC not supported'
+
+    tickets, to_cancel = state.get_tickets()
+    assert not tickets
+    assert not to_cancel
+
+    assert expect_sell_all() is None, 'symbol info is not set'
+
+    set_symbol_info(state)
+
+    assert repr(state._symbol_infos[SYMBOL]) == '<SymbolInfo BTCUSDT: price_step >= 0.01, quantity_step >= 0.000001>'
+
+    assert expect_sell_all() is None, 'price is not set'
+
+    state.set_price(SYMBOL, 7000.)
+
+    assert expect_sell_all() is None, 'balances are not set'
+
+    state.update_balances([
+        Balance(
+            BTC,
+            15.,
+            0.
+        ),
+        Balance(
+            USDT,
+            0.001,
+            0.
+        )
+    ])
+
+    assert repr(state._balances[BTC]) == '<Balance BTC: free: 15.0, locked: 0.0>'
+
+    ticket0 = expect_sell_all()
+    assert ticket0 is not None
+
+    # Unsolved tickets will be always returned by state.tickets
+
+    tickets, _ = state.get_tickets()
+    assert tickets[0] is ticket0
+
+    # ticket 0 will be closed
+    assert expect_all_in() is None
+
+    ticket1 = expect_sell_all()
+
+    assert ticket1 is not None
+
+    # Test to close ticket duplicately
+    # ------------------------------------------------------
+
+    state.close_ticket(ticket1)
+    state.close_ticket(ticket1)
+
+    # Test to create ticket
+    # ------------------------------------------------------
+
+    ticket_sell, to_cancel = state.create_ticket(
+        SYMBOL,
+        0.,
+        False,
+        None
+    )
+
+    assert ticket_sell.position.value == 0.
+    assert ticket_sell.symbol.name == SYMBOL
+    assert not to_cancel
+
+    # There is already a ticket
+    # ------------------------------------------------------
+
+    ticket_sell2, to_cancel2 = state.create_ticket(
+        SYMBOL,
+        0.,
+        False,
+        None
+    )
+
+    assert ticket_sell2 is None
+    assert not to_cancel2
+
+    ticket_buy, to_cancel = state.create_ticket(
+        SYMBOL,
+        1.,
+        False,
+        None
+    )
+
+    assert ticket_buy is None
+    assert ticket_sell in to_cancel
+
+    assert not state._expected
+
+    state.update_balances([
+        Balance(
+            BTC,
+            0.,
+            0.
+        ),
+        Balance(
+            USDT,
+            70000,
+            0.
+        )
+    ])
+
+    assert expect_all_in() is not None
+    assert expect_sell_all() is None
+
+    # Set quota to 0
+    state.set_quota(BTC, 0.)
+    state.set_quota('ETH', 0.)
+
+    assert expect_all_in() is None, 'not enough quota'
+
+    state.set_quota(BTC, None)
+
+    state.update_balances([
+        Balance(
+            USDT,
+            0.006,
+            0.
+        )
+    ])
+
+    assert expect_all_in() is None, 'min price step'
+
+    state.update_balances([
+        Balance(
+            USDT,
+            9.,
+            0.
+        )
+    ])
+
+    assert expect_all_in() is None, 'min notional'
+
+    state.update_balances([
+        Balance(
+            USDT,
+            15.,
+            0.
+        )
+    ])
+
+    state.set_price(SYMBOL, 70000000.)
+    state.set_price(SYMBOL, 70000000.)
+
+    assert expect_all_in() is None, 'not enough'
+
+    state.set_price(SYMBOL, 7000.)
+
+    ticket2 = expect_all_in()
+
+    assert ticket2 is not None
+
+    assert ticket2.quantity == '0.002142'
+
+    state.clear()
+
+    tickets, to_cancel = state.get_tickets()
+
+    assert not tickets
+    assert not to_cancel
+
+    assert not state._expected

trading_state-0.0.1/test/test_types.py

@@ -0,0 +1,30 @@
+from trading_state.types import (
+    SymbolInfo,
+    Balance
+)
+
+
+def test_float_precision():
+    info = SymbolInfo(
+        'BTCUSDT',
+        'BTC',
+        'USDT',
+
+        '0.010000000000',
+        '1000000',
+        '0.010000000000',
+
+        '0.000001000000',
+        '9000',
+        '0.000001000000',
+
+        '10.00000000'
+    )
+
+    assert info.min_quantity_step_precision == 6
+
+
+def test_balance():
+    balance = Balance('BTCUSDT', 0, 0)
+
+    assert not balance.exists()

trading_state-0.0.1/trading_state/__init__.py

@@ -0,0 +1,2 @@
+# The first alpha version
+__version__ = '0.0.1'