upticks 0.1.5__py3-none-any.whl

upticks/__init__.py

@@ -0,0 +1,213 @@
+"""upticks — price action, honestly.
+
+A causality-first price-action research library. Plain pandas in, plain pandas out.
+Zero trading dependencies.
+
+Created by Nashit Babber <nashit.babber@gmail.com>
+"""
+from __future__ import annotations
+
+# Imports that are not part of the surface are aliased under `_`: `dir(upticks)` must contain
+# nothing public beyond `__all__` and the submodule names.
+import typing as _t
+
+import pandas as _pd
+
+from ._result import Result, ScanResult
+from .config import PRESETS as presets
+from .config import (
+    Preset,
+    ResolvedConfig,
+    defaults_provenance,
+    option_context,
+    options,
+    preset,
+)
+from .core.adjust import AdjustmentTable, adjust, detect_actions, read_adjustments
+from .core.bars import Bars, Capabilities
+from .core.freq import Freq, normalize_freq
+from .core.holidays import HolidayTable
+from .core.holidays import derive_holidays as _derive_holidays
+from .core.hygiene import CheckOutcome, CheckSpec, repair
+from .core.hygiene import checks as _check_registry
+from .core.hygiene import run_checks as _run_checks
+from .core.ingest import capabilities, load, load_benchmark, reattach, scan
+from .core.meta import Meta
+from .core.parts import closing_range, initial_balance, opening_range, session_part
+from .core.resample import resample
+from .core.sessions import SessionShape, SessionTable, infer_sessions
+from .core.tickgrid import TickInference
+from .errors import (
+    AmbiguousBar,
+    ConfigurationError,
+    DataQualityError,
+    DegenerateInputWarning,
+    DependencyMissing,
+    HoldoutLocked,
+    InsufficientBars,
+    LookaheadWarning,
+    MetadataLost,
+    MetadataLostWarning,
+    NonCausalDetector,
+    PerformanceWarning,
+    ProvisionalDataWarning,
+    RepaintingDetector,
+    StructurallyUnavailable,
+    UnknownKey,
+    UpticksError,
+    UpticksWarning,
+)
+from .io.parquet import read_actions, read_parquet, to_parquet
+
+__version__ = "0.1.5"
+__author__ = "Nashit Babber"
+__email__ = "nashit.babber@gmail.com"
+
+#: The curated surface, frozen against `tests/api_snapshot.txt` — adding a name is an API change.
+__all__ = [
+    "AdjustmentTable",
+    "AmbiguousBar",
+    "Bars",
+    "Capabilities",
+    "CheckOutcome",
+    "CheckSpec",
+    "ConfigurationError",
+    "DataQualityError",
+    "DegenerateInputWarning",
+    "DependencyMissing",
+    "Freq",
+    "HoldoutLocked",
+    "HolidayTable",
+    "InsufficientBars",
+    "LookaheadWarning",
+    "Meta",
+    "MetadataLost",
+    "MetadataLostWarning",
+    "NonCausalDetector",
+    "PerformanceWarning",
+    "Preset",
+    "ProvisionalDataWarning",
+    "RepaintingDetector",
+    "ResolvedConfig",
+    "Result",
+    "ScanResult",
+    "SessionShape",
+    "SessionTable",
+    "StructurallyUnavailable",
+    "TickInference",
+    "UnknownKey",
+    "UpticksError",
+    "UpticksWarning",
+    "__version__",
+    "adjust",
+    "banner",
+    "capabilities",
+    "checks",
+    "closing_range",
+    "defaults_provenance",
+    "detect_actions",
+    "holidays",
+    "hygiene",
+    "infer_sessions",
+    "initial_balance",
+    "load",
+    "load_benchmark",
+    "normalize_freq",
+    "opening_range",
+    "option_context",
+    "options",
+    "preset",
+    "presets",
+    "read_actions",
+    "read_adjustments",
+    "read_parquet",
+    "reattach",
+    "render",
+    "repair",
+    "resample",
+    "scan",
+    "session_part",
+    "to_parquet",
+]
+
+
+def _param_text(value: _t.Any) -> str:
+    """Render a check parameter for reading: `8`, `3`, `(2, 0.5, 5)`."""
+    if isinstance(value, float):
+        return f"{value:g}"
+    if isinstance(value, (tuple, list)):
+        return "(" + ", ".join(_param_text(v) for v in value) + ")"
+    return str(value)
+
+
+def checks() -> _pd.DataFrame:
+    """The sixteen hygiene checks as a tidy frame, in canonical report order.
+
+    Columns: `check_id | severity | requires | params | doc`. `params` holds the pinned,
+    overridable defaults rendered as text (`k=8`); every one of them also has a row in
+    `defaults_provenance()`. This is the registry, not a result — it says what *would* run.
+    `hygiene(bars)` runs it.
+    """
+    frame = _check_registry()  # a fresh frame per call, so rewriting a column is safe
+    frame["params"] = [
+        ", ".join(f"{k}={_param_text(v)}" for k, v in params.items()) for params in frame["params"]
+    ]
+    return frame
+
+
+def hygiene(
+    bars_or_df: _t.Any,
+    *,
+    sessions: SessionTable | None = None,
+    tick: TickInference | None = None,
+    params: _t.Mapping[str, _t.Mapping[str, _t.Any]] | None = None,
+    only: _t.Iterable[str] | None = None,
+    skip: _t.Iterable[str] | None = None,
+) -> _pd.DataFrame:
+    """Run the sixteen checks over a `Bars` handle or a bare OHLCV frame. Never mutates its input.
+
+    Public alias of `upticks.core.hygiene.run_checks`; see that function for the full argument and
+    column contract. A `Bars` handle lends its own `SessionTable` when `sessions=` is omitted, so
+    `up.hygiene(bars)` reproduces `bars.quality`.
+    """
+    return _run_checks(
+        bars_or_df, sessions=sessions, tick=tick, params=params, only=only, skip=skip
+    )
+
+
+def holidays(
+    bars_or_sessions: _t.Any,
+    *,
+    min_share: float | None = None,
+    extra: _t.Any = None,
+) -> HolidayTable:
+    """The non-trading days a `Bars` handle or a `SessionTable` implies. Never mutates its input.
+
+    Public alias of `upticks.core.holidays.derive_holidays`, widened to take the handle as well as
+    the table: `up.holidays(bars)` is `derive_holidays(bars.sessions)`. See that function for the
+    derivation, which is a pure function of the sessions given — a day is a holiday because the
+    file has no bars on it, not because a calendar says so, so nothing here consults the future.
+
+    Args:
+        bars_or_sessions: a `Bars` handle carrying sessions, or a `SessionTable`.
+        min_share: weekday threshold; default `options.holiday_min_share` (0.2).
+        extra: a user holiday table merged in — a path, a `DatetimeIndex`, or date-likes.
+    """
+    sessions = bars_or_sessions.sessions if isinstance(bars_or_sessions, Bars) else bars_or_sessions
+    if sessions is None:
+        raise StructurallyUnavailable(
+            "this handle carries no session table, so it implies no calendar.",
+            construct="holidays",
+            reason="sessions were not inferred (the index was not strictly increasing)",
+            remedy="re-load with a sorted, de-duplicated index, or pass a table built by "
+            "up.infer_sessions(df.index)",
+        )
+    return _derive_holidays(sessions, min_share=min_share, extra=extra)
+
+
+# The `__future__` import binds a public module-level name; the surface has no room for it.
+del annotations
+
+from ._banner import banner, render  # noqa: E402
+
+banner()

upticks/_banner.py

@@ -0,0 +1,110 @@
+"""Import banner. Cosmetic only — never affects library behaviour.
+
+Shown once per process on an interactive import. Automatically silent where a
+banner would corrupt output: piped stdout, pytest, CI, or UPTICKS_NO_BANNER=1.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import Protocol
+
+__all__ = ["banner", "render"]
+
+
+class _TextSink(Protocol):
+    """The whole of what the banner asks of a stream: somewhere to put text.
+
+    Deliberately narrower than `typing.TextIO`. The display rules probe `isatty` through
+    `getattr`, so a stream without one is legal, and every write happens inside the fail-open
+    handler, so a stream whose methods raise is legal too. `sys.stderr` is only the default.
+    """
+
+    def write(self, text: str, /) -> object: ...
+
+    def flush(self) -> object: ...
+
+
+_SHOWN = False
+
+AUTHOR = "Nashit Babber"
+EMAIL = "nashit.babber@gmail.com"
+TAGLINE = "price action, honestly"
+
+_LOGO = r"""
+   ██╗   ██╗██████╗ ████████╗██╗ ██████╗██╗  ██╗███████╗
+   ██║   ██║██╔══██╗╚══██╔══╝██║██╔════╝██║ ██╔╝██╔════╝
+   ██║   ██║██████╔╝   ██║   ██║██║     █████╔╝ ███████╗
+   ██║   ██║██╔═══╝    ██║   ██║██║     ██╔═██╗ ╚════██║
+   ╚██████╔╝██║        ██║   ██║╚██████╗██║  ██╗███████║
+    ╚═════╝ ╚═╝        ╚═╝   ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝
+"""
+
+# An ascending candlestick strip: wick, body, wick.
+_CHART = [
+    "                                                  ╷      ",
+    "                                        ╷    ╷   ▐█▌     ",
+    "                              ╷    ╷   ▐█▌  ▐█▌   ╵      ",
+    "                    ╷   ╷    ▐█▌  ▐█▌   ╵    ╵           ",
+    "     ╷    ╷   ╷    ▐█▌ ▐█▌    ╵    ╵                     ",
+    "    ▐█▌  ▐█▌ ▐█▌    ╵   ╵                                ",
+    "     ╵    ╵   ╵                                          ",
+]
+
+_RESET, _DIM, _BOLD = "\033[0m", "\033[2m", "\033[1m"
+_GREEN, _CYAN, _WHITE = "\033[38;5;42m", "\033[38;5;51m", "\033[38;5;255m"
+
+
+def _supports_color(stream: _TextSink) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    if not hasattr(stream, "isatty") or not stream.isatty():
+        return False
+    return os.environ.get("TERM", "") not in ("", "dumb")
+
+
+def _should_show(stream: _TextSink) -> bool:
+    """Silent wherever a banner would corrupt output or spam a log."""
+    if os.environ.get("UPTICKS_NO_BANNER"):
+        return False
+    if "pytest" in sys.modules or "PYTEST_CURRENT_TEST" in os.environ:
+        return False
+    if os.environ.get("CI") or os.environ.get("GITHUB_ACTIONS"):
+        return False
+    return bool(getattr(stream, "isatty", lambda: False)())
+
+
+def render(color: bool = True) -> str:
+    """The banner as a string. Always available, regardless of display rules."""
+    c = (lambda s, code: f"{code}{s}{_RESET}") if color else (lambda s, code: s)
+    out = [c(line, _CYAN + _BOLD) for line in _LOGO.strip("\n").split("\n")]
+    out += [c(line, _GREEN) for line in _CHART]
+    width = 57
+    out.append(c("   " + "─" * (width - 3), _DIM))
+    out.append(
+        c("   " + TAGLINE.ljust(26), _WHITE)
+        + c("created by ", _DIM)
+        + c(AUTHOR, _WHITE + _BOLD)
+    )
+    out.append(c("   " + " " * 26 + "connect    ", _DIM) + c(EMAIL, _CYAN))
+    return "\n".join(out) + "\n"
+
+
+def banner(force: bool = False, stream: _TextSink | None = None) -> None:
+    """Print the banner. Called once on import; safe to call again with force.
+
+    `stream` defaults to `sys.stderr` and needs only `write`; anything it raises is swallowed.
+    """
+    global _SHOWN
+    stream = stream or sys.stderr
+    if not force:
+        if _SHOWN or not _should_show(stream):
+            return
+    _SHOWN = True
+    try:
+        stream.write("\n" + render(color=_supports_color(stream)) + "\n")
+        stream.flush()
+    except Exception:
+        pass  # a cosmetic banner must never break an import

upticks/_logging.py

@@ -0,0 +1,40 @@
+"""Logger namespace.
+
+One flat tree under `upticks`: a `logging.NullHandler` is attached to the root at import
+and nothing else — no formatter, no level, `propagate` left at its default so an
+application's own logging configuration stays in charge. DEBUG records internal
+decisions, INFO user-visible phase transitions.
+"""
+from __future__ import annotations
+
+import logging
+
+__all__ = ["ROOT", "get_logger"]
+
+ROOT = "upticks"
+
+_root = logging.getLogger(ROOT)
+if not any(isinstance(h, logging.NullHandler) for h in _root.handlers):
+    _root.addHandler(logging.NullHandler())
+
+
+def _child(name: str) -> str:
+    """Map any module path onto `upticks` | `upticks.<sub>`.
+
+    Only the last dotted segment is kept, so `upticks.core.ingest` and `upticks.ingest`
+    are the same logger — the tree is one level deep by design, and a caller cannot
+    accidentally configure a logger outside the package namespace.
+    """
+    sub = name.rsplit(".", 1)[-1].strip()
+    if not sub or sub in (ROOT, "__init__", "__main__"):
+        return ROOT
+    return f"{ROOT}.{sub}"
+
+
+def get_logger(name: str = ROOT) -> logging.Logger:
+    """Return the `upticks` logger, or its `upticks.<sub>` child for `name`.
+
+    Pass `__name__`. Children used in A1: `upticks.ingest`, `upticks.hygiene`,
+    `upticks.sessions`, `upticks.config`.
+    """
+    return logging.getLogger(_child(name))