td-sequential 1.0.0__py3-none-any.whl

td_sequential/__init__.py

@@ -0,0 +1,6 @@
+"""TD Sequential indicator for Python: TD9 setup, countdown 13 and TDST levels."""
+
+from .core import CountdownState, Latest, TdBar, compute, latest
+
+__version__ = "1.0.0"
+__all__ = ["CountdownState", "Latest", "TdBar", "compute", "latest", "__version__"]

td_sequential/core.py

@@ -0,0 +1,260 @@
+"""TD Sequential setup, countdown and support/resistance counter.
+
+Pure Python, no dependencies. Written from SPEC.md: one record per closed bar,
+oldest first. Nothing here is trading advice; a count describes past prices.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Any, Iterable, List, Optional, Tuple
+
+__all__ = ["TdBar", "CountdownState", "Latest", "compute", "latest"]
+
+MAX_LEVELS = 20
+IDLE = 14  # cancellation / "no countdown in progress" value
+
+# Attribute / key names accepted for each bar field, first match wins.
+_NAMES = {
+    "t": ("t", "time", "timestamp"),
+    "o": ("o", "open"),
+    "h": ("h", "high"),
+    "l": ("l", "low"),
+    "c": ("c", "close"),
+}
+
+
+@dataclass(frozen=True)
+class TdBar:
+    """One output record per input bar (SPEC.md, section 4)."""
+
+    t: Any
+    buy_setup: int
+    sell_setup: int
+    buy_countdown: int
+    sell_countdown: int
+    resistance: Optional[float]
+    support: Optional[float]
+    buy_deferred: bool
+    sell_deferred: bool
+    buy_perfected: bool
+    sell_perfected: bool
+    bullish_flip: bool
+    bearish_flip: bool
+
+
+@dataclass(frozen=True)
+class CountdownState:
+    """A countdown in progress: `count` of 13, `paused` when the last bar did not qualify."""
+
+    count: int
+    paused: bool
+
+
+@dataclass(frozen=True)
+class Latest:
+    """Summary of the final bar of a `compute()` result."""
+
+    t: Any
+    buy_setup: int
+    sell_setup: int
+    buy_countdown: Optional[CountdownState]
+    sell_countdown: Optional[CountdownState]
+    buy_completed_13_now: bool
+    sell_completed_13_now: bool
+    last_buy_setup_9: Any
+    last_sell_setup_9: Any
+    last_buy_countdown_13: Any
+    last_sell_countdown_13: Any
+    resistance: Optional[float]
+    support: Optional[float]
+
+
+def _field(bar: Any, key: str, index: int) -> Any:
+    names = _NAMES[key]
+    if isinstance(bar, dict):
+        for name in names:
+            if name in bar:
+                return bar[name]
+    else:
+        for name in names:
+            if hasattr(bar, name):
+                return getattr(bar, name)
+    raise ValueError(f"bar {index}: missing field '{names[0]}' (also accepted: {', '.join(names[1:]) or 'none'})")
+
+
+def _price(value: Any, key: str, index: int) -> float:
+    if isinstance(value, bool):
+        raise TypeError(f"bar {index}: '{key}' must be a number, got bool")
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        raise TypeError(f"bar {index}: '{key}' must be a number, got {type(value).__name__}") from None
+    if math.isnan(number):
+        raise ValueError(f"bar {index}: '{key}' is NaN")
+    return number
+
+
+def _normalize(bars: Iterable[Any]) -> List[Tuple[Any, float, float, float]]:
+    """Return (t, high, low, close) per bar. Accepts dicts, (t,o,h,l,c) tuples or objects."""
+    rows: List[Tuple[Any, float, float, float]] = []
+    for i, bar in enumerate(bars):
+        if isinstance(bar, (tuple, list)):
+            if len(bar) != 5:
+                raise ValueError(f"bar {i}: a tuple bar must be (t, o, h, l, c), got {len(bar)} items")
+            t, o, h, l, c = bar
+        else:
+            t, o, h, l, c = (_field(bar, k, i) for k in ("t", "o", "h", "l", "c"))
+        _price(o, "o", i)
+        rows.append((t, _price(h, "h", i), _price(l, "l", i), _price(c, "c", i)))
+    return rows
+
+
+class _Countdown:
+    """State of one side's countdown (SPEC.md, section 3)."""
+
+    def __init__(self) -> None:
+        self.value = 0
+        self.eight_close = math.nan
+
+    def step(self, own9: bool, other9: bool, level_active: bool, qualifies: bool, test: bool, close: float) -> Tuple[int, bool]:
+        prev = self.value
+        deferred = False
+        if own9:
+            value = 1 if qualifies else 0
+        elif other9 or not level_active:
+            value = IDLE
+        elif abs(prev) == 12 and qualifies and not test:
+            value, deferred = -12, True
+        elif qualifies:
+            value = abs(prev) + 1
+        else:
+            value = 0 if prev == 0 else -abs(prev)
+        if value == 8:  # only a transition to +8 gets here
+            self.eight_close = close
+        self.value = value
+        return value, deferred
+
+
+class _Level:
+    __slots__ = ("price", "active")
+
+    def __init__(self, price: float) -> None:
+        self.price = price
+        self.active = True
+
+
+def _add_level(levels: List[_Level], price: float) -> None:
+    if not price > 0 or any(x.active and x.price == price for x in levels):
+        return
+    levels.append(_Level(price))
+    if len(levels) > MAX_LEVELS:
+        levels.pop(0)
+
+
+def _reported(levels: List[_Level]) -> Optional[float]:
+    if levels and levels[-1].active:
+        return levels[-1].price
+    return None
+
+
+def compute(bars: Iterable[Any]) -> List[TdBar]:
+    """Compute one `TdBar` per input bar.
+
+    `bars` is ordered oldest first and holds closed bars only. Each bar is a dict
+    with keys t, o, h, l, c (long names such as "close" also work), a
+    (t, o, h, l, c) tuple, or an object with those attributes.
+    """
+    rows = _normalize(bars)
+    out: List[TdBar] = []
+    resistances: List[_Level] = []
+    supports: List[_Level] = []
+    buy = _Countdown()
+    sell = _Countdown()
+    buy_setup = 0
+    sell_setup = 0
+
+    for i, (t, h, l, c) in enumerate(rows):
+        buy_setup = buy_setup + 1 if i >= 4 and c < rows[i - 4][3] else 0
+        sell_setup = sell_setup + 1 if i >= 4 and c > rows[i - 4][3] else 0
+        buy9 = buy_setup == 9
+        sell9 = sell_setup == 9
+
+        if buy9:
+            _add_level(resistances, max(r[1] for r in rows[i - 8 : i + 1]))
+        if sell9:
+            _add_level(supports, min(r[2] for r in rows[i - 8 : i + 1]))
+        for r in resistances:
+            if r.active and (c > r.price or l > r.price):
+                r.active = False
+        for s in supports:
+            if s.active and (c < s.price or h < s.price):
+                s.active = False
+        resistance = _reported(resistances)
+        support = _reported(supports)
+
+        l2 = rows[i - 2][2] if i >= 2 else math.nan
+        h2 = rows[i - 2][1] if i >= 2 else math.nan
+        b_value, b_deferred = buy.step(buy9, sell9, resistance is not None, i >= 2 and c <= l2, l <= buy.eight_close, c)
+        s_value, s_deferred = sell.step(sell9, buy9, support is not None, i >= 2 and c >= h2, h >= sell.eight_close, c)
+
+        # Information only: perfection on the setup-9 bar, and price flips.
+        buy_perfected = buy9 and min(rows[i - 1][2], l) < min(rows[i - 3][2], rows[i - 2][2])
+        sell_perfected = sell9 and max(rows[i - 1][1], h) > max(rows[i - 3][1], rows[i - 2][1])
+        bullish_flip = i >= 5 and rows[i - 1][3] < rows[i - 5][3] and c > rows[i - 4][3]
+        bearish_flip = i >= 5 and rows[i - 1][3] > rows[i - 5][3] and c < rows[i - 4][3]
+
+        out.append(
+            TdBar(
+                t=t,
+                buy_setup=buy_setup,
+                sell_setup=sell_setup,
+                buy_countdown=b_value,
+                sell_countdown=s_value,
+                resistance=resistance,
+                support=support,
+                buy_deferred=b_deferred,
+                sell_deferred=s_deferred,
+                buy_perfected=buy_perfected,
+                sell_perfected=sell_perfected,
+                bullish_flip=bullish_flip,
+                bearish_flip=bearish_flip,
+            )
+        )
+    return out
+
+
+def _last_where(result: List[TdBar], predicate: Any) -> Any:
+    for record in reversed(result):
+        if predicate(record):
+            return record.t
+    return None
+
+
+def _countdown_state(value: int) -> Optional[CountdownState]:
+    if value != 0 and abs(value) < 13:
+        return CountdownState(count=abs(value), paused=value < 0)
+    return None
+
+
+def latest(result: List[TdBar]) -> Optional[Latest]:
+    """Summary of the final bar of a `compute()` result, or None for an empty result."""
+    if not result:
+        return None
+    last = result[-1]
+    return Latest(
+        t=last.t,
+        buy_setup=last.buy_setup,
+        sell_setup=last.sell_setup,
+        buy_countdown=_countdown_state(last.buy_countdown),
+        sell_countdown=_countdown_state(last.sell_countdown),
+        buy_completed_13_now=last.buy_countdown == 13,
+        sell_completed_13_now=last.sell_countdown == 13,
+        last_buy_setup_9=_last_where(result, lambda r: r.buy_setup == 9),
+        last_sell_setup_9=_last_where(result, lambda r: r.sell_setup == 9),
+        last_buy_countdown_13=_last_where(result, lambda r: r.buy_countdown == 13),
+        last_sell_countdown_13=_last_where(result, lambda r: r.sell_countdown == 13),
+        resistance=last.resistance,
+        support=last.support,
+    )

td_sequential/pandas.py

@@ -0,0 +1,50 @@
+"""Optional pandas helper. Install with `pip install td-sequential[pandas]`."""
+
+from __future__ import annotations
+
+from dataclasses import fields
+from typing import Any
+
+from .core import TdBar, compute
+
+__all__ = ["add_td_sequential"]
+
+_COLUMNS = [f.name for f in fields(TdBar) if f.name != "t"]
+_REQUIRED = ("open", "high", "low", "close")
+
+
+def add_td_sequential(df: Any, prefix: str = "td_") -> Any:
+    """Return a copy of `df` with the TD Sequential columns added.
+
+    `df` needs `open`, `high`, `low` and `close` columns (case-insensitive), one
+    closed bar per row, oldest first; the index is used as the bar time. Added
+    columns are `<prefix>buy_setup`, `<prefix>sell_setup`, `<prefix>buy_countdown`,
+    `<prefix>sell_countdown`, `<prefix>resistance`, `<prefix>support` (NaN when
+    there is no active level), `<prefix>buy_deferred`, `<prefix>sell_deferred`,
+    `<prefix>buy_perfected`, `<prefix>sell_perfected`, `<prefix>bullish_flip`
+    and `<prefix>bearish_flip`.
+    """
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise ImportError("add_td_sequential needs pandas: pip install td-sequential[pandas]") from exc
+
+    lookup = {str(name).lower(): name for name in df.columns}
+    missing = [name for name in _REQUIRED if name not in lookup]
+    if missing:
+        raise KeyError(f"DataFrame is missing column(s): {', '.join(missing)}")
+
+    bars = (
+        (idx, o, h, l, c)
+        for idx, o, h, l, c in zip(df.index, *(df[lookup[name]] for name in _REQUIRED))
+    )
+    records = compute(bars)
+
+    out = df.copy()
+    for name in _COLUMNS:
+        values = [getattr(r, name) for r in records]
+        if name in ("resistance", "support"):
+            out[prefix + name] = pd.Series(values, index=df.index, dtype="float64")
+        else:
+            out[prefix + name] = pd.Series(values, index=df.index)
+    return out

td_sequential-1.0.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: td-sequential
+Version: 1.0.0
+Summary: TD Sequential indicator for Python: TD9 setup, countdown 13 and TDST levels on OHLC candles. Tested, zero dependencies.
+Project-URL: Homepage, https://moolish.com/tools/td-sequential-counter/
+Project-URL: Documentation, https://moolish.com/learn/td-sequential/
+Project-URL: Source, https://github.com/moolish-com/td-sequential-python
+Project-URL: Issues, https://github.com/moolish-com/td-sequential-python/issues
+Project-URL: Changelog, https://github.com/moolish-com/td-sequential-python/blob/main/CHANGELOG.md
+Author-email: Moolish <support@moolish.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crypto,forex,indicator,ohlc,pandas,stocks,td-countdown,td-sequential,td-setup,td9,tdsequential,tdst,technical-analysis,tom-demark,trading
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Provides-Extra: test
+Requires-Dist: pandas>=1.5; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# TD Sequential indicator for Python
+
+[![test](https://github.com/moolish-com/td-sequential-python/actions/workflows/test.yml/badge.svg)](https://github.com/moolish-com/td-sequential-python/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/td-sequential.svg)](https://pypi.org/project/td-sequential/)
+[![Python](https://img.shields.io/pypi/pyversions/td-sequential.svg)](https://pypi.org/project/td-sequential/)
+[![Downloads](https://img.shields.io/pypi/dm/td-sequential.svg)](https://pypi.org/project/td-sequential/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`td-sequential` computes the TD Sequential indicator in Python on a list of OHLC candles: the TD Setup (the 1 to 9 count, often called TD9), the TD Countdown (1 to 13), the TDST support and resistance levels left by completed setups, and the information-only perfection and price flip flags. It works on crypto, stocks and forex candles of any timeframe, has no dependencies, supports Python 3.9 and later, and has an optional pandas helper.
+
+It follows the plain-English rules in [SPEC.md](SPEC.md) and matches the reference output bar for bar. The free [TD Sequential counter](https://moolish.com/tools/td-sequential-counter/) on moolish.com shows the current count on a crypto pair without installing anything.
+
+## Install
+
+```bash
+pip install td-sequential
+pip install "td-sequential[pandas]"   # optional DataFrame helper
+```
+
+## Usage
+
+```python
+from td_sequential import compute, latest
+
+# Closed bars only, oldest first. Drop the candle that is still forming.
+bars = [
+    {"t": 1750032000000, "o": 105594.02, "h": 108952.38, "l": 104980.37, "c": 106794.53},
+    # ...
+]
+
+result = compute(bars)   # one TdBar record per input bar
+now = latest(result)     # summary of the last bar
+
+last = result[-1]
+if last.buy_setup == 9:
+    print("TD Setup 9 (buy) on", last.t, "resistance", last.resistance)
+if last.sell_countdown == 13:
+    print("TD Countdown 13 (sell) completed on", last.t)
+```
+
+A bar can be a dict with keys `t, o, h, l, c` (the long names `time, open, high, low, close` also work), a `(t, o, h, l, c)` tuple, or any object with those attributes, for example a named tuple or a dataclass. Missing fields and non-numeric prices raise a clear `ValueError` or `TypeError` that names the bar.
+
+### pandas
+
+```python
+import pandas as pd
+from td_sequential.pandas import add_td_sequential
+
+df = pd.read_csv("btcusdt-1d.csv", index_col="time", parse_dates=True)  # open, high, low, close columns
+out = add_td_sequential(df)   # returns a copy with td_* columns added
+print(out[out["td_buy_setup"] == 9])
+```
+
+Column names are case-insensitive on input. Output columns carry the prefix `td_` (change it with `prefix=`). `td_resistance` and `td_support` are `NaN` when there is no active level.
+
+## Output fields
+
+`compute()` returns a list of frozen `TdBar` dataclasses, one per input bar, in input order.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `t` | any | The bar's timestamp, copied from the input |
+| `buy_setup` | int | Buy TD Setup counter (0 or more; exactly 9 marks a setup 9) |
+| `sell_setup` | int | Sell TD Setup counter, same meaning |
+| `buy_countdown` | int | Signed buy countdown; 13 means just completed; 14 or more means no countdown in progress; negative means paused |
+| `sell_countdown` | int | Signed sell countdown, same meaning |
+| `resistance` | float or None | Price of the active latest TDST resistance level (plain highest high of the 9 setup bars) |
+| `support` | float or None | Price of the active latest TDST support level (plain lowest low of the 9 setup bars) |
+| `buy_deferred` | bool | The 13th buy countdown bar was held back by the 13-versus-8 test |
+| `sell_deferred` | bool | Same for the sell countdown |
+| `buy_perfected` | bool | Buy setup 9 whose bar 8 or 9 low is strictly below the lows of bars 6 and 7 (information only) |
+| `sell_perfected` | bool | Sell setup 9 whose bar 8 or 9 high is strictly above the highs of bars 6 and 7 (information only) |
+| `bullish_flip` | bool | Price flip: close crosses above the close 4 bars earlier after being below it (information only) |
+| `bearish_flip` | bool | The mirror price flip (information only) |
+
+The four information-only fields never change a setup, countdown or level value.
+
+`latest(result)` returns a `Latest` dataclass: the current setup counts, the countdown in progress per side (`CountdownState(count, paused)` or `None`), whether a 13 just completed, the time of the last completed setup 9 and countdown 13 per side, and the active resistance and support. It returns `None` for an empty result.
+
+## Rules in short
+
+- Setup: a bar counts when its close is lower (buy) or higher (sell) than the close 4 bars earlier. Any bar that does not qualify resets the counter to 0. Counting does not stop at 9.
+- Levels: a buy setup 9 records the highest high of its 9 bars as resistance, a sell setup 9 the lowest low as support (the "TDST levels", using the plain 9-bar high and low). A level is dropped when price closes beyond it or a whole bar sits beyond it.
+- Countdown: starts on the setup 9 bar; a bar counts when its close is at or beyond the low (buy) or high (sell) of the bar 2 bars earlier. It needs an active level, is cancelled by the opposite setup 9, and the 13th bar must pass the 13-versus-8 test.
+
+The full, unambiguous version is in [SPEC.md](SPEC.md).
+
+## Verified against reference data
+
+The test suite replays eight real candle histories (crypto pairs on 4-hour, daily and weekly timeframes, about 500 bars each) and requires every counting field to match the stored reference output on every bar. It also compares all twelve fields with the JavaScript implementation of the same rules on the same bars, and has unit cases for setup, levels, countdown, the 13-versus-8 deferral, perfection and price flips. Run it with `pip install -e ".[test]"` then `pytest`.
+
+## What is TD Sequential?
+
+TD Sequential is Tom DeMark's method for spotting a stretched run of closes. A TD Setup counts consecutive bars that close beyond the close four bars earlier, and a completed 9 can start a countdown that needs 13 qualifying bars. A 9 or a 13 describes past prices and gives no direction on its own; the [TD Sequential guide](https://moolish.com/learn/td-sequential/) explains the method, [TDST](https://moolish.com/learn/td-sequential/tdst/) and [perfected setups](https://moolish.com/learn/td-sequential/perfected-setup/).
+
+## Related
+
+- [td-sequential](https://github.com/moolish-com/td-sequential) - JavaScript and TypeScript (npm)
+- [td-sequential-pine-script](https://github.com/moolish-com/td-sequential-pine-script) - TradingView Pine Script v6
+- [td-sequential-screener](https://github.com/moolish-com/td-sequential-screener) - command-line screener
+- [Free TD Sequential counter](https://moolish.com/tools/td-sequential-counter/) - check a crypto pair in the browser
+
+## Attribution and disclaimer
+
+Moolish is not affiliated with, endorsed by or sponsored by Tom DeMark or DeMARK Analytics. TD Sequential is a method created by Tom DeMark, and DeMARK is a trademark of DeMARK Analytics.
+
+This is educational software, not financial advice. A count describes past prices; it is not a prediction.
+
+## Licence
+
+[MIT](LICENSE) - Copyright (c) 2026 Moolish

td_sequential-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+td_sequential/__init__.py,sha256=63ZR6eIVYhKJhMd1en8TahrXL1osRSe9xWI6-et0e9k,256
+td_sequential/core.py,sha256=BxB8vXYLPceI_m7I0OW36G2ElNoBxF1JeCuvsXQJY0I,8705
+td_sequential/pandas.py,sha256=bgM1QWPE4VXKMS1ZRHwN3v2Chj3lpxld-wSJRf53NdY,1929
+td_sequential/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+td_sequential-1.0.0.dist-info/METADATA,sha256=qkJh7KUGFTkfp_pGMaa6ZTYFqwBB0XOtviTePj5Zb5Y,9028
+td_sequential-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+td_sequential-1.0.0.dist-info/licenses/LICENSE,sha256=FmHIfCx4AmcR7l4FIRxNMGlVcrO_WP6SBj3CAoCJxxs,1064
+td_sequential-1.0.0.dist-info/RECORD,,

td_sequential-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

td_sequential-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moolish
+
+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.