pybinbot 0.4.1__py3-none-any.whl

pybinbot/__init__.py

@@ -0,0 +1,160 @@
+"""Public API for the ``pybinbot`` distribution.
+
+This package exposes a flat, convenient API for common types, enums and
+models, while still allowing access to the structured subpackages via
+``pybinbot.shared`` and ``pybinbot.models``.
+"""
+
+from pybinbot.shared.maths import (
+    format_ts,
+    interval_to_millisecs,
+    round_numbers,
+    round_numbers_ceiling,
+    round_numbers_floor,
+    supress_notation,
+    supress_trailling,
+    zero_remainder,
+)
+from pybinbot.shared.timestamps import (
+    ms_to_sec,
+    round_timestamp,
+    sec_to_ms,
+    timestamp,
+    timestamp_to_datetime,
+    ts_to_day,
+    ts_to_humandate,
+)
+from pybinbot.shared.enums import (
+    AutotradeSettingsDocument,
+    BinanceKlineIntervals,
+    BinanceOrderModel,
+    CloseConditions,
+    DealType,
+    ExchangeId,
+    KafkaTopics,
+    KucoinKlineIntervals,
+    MarketDominance,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    QuoteAssets,
+    Status,
+    Strategy,
+    TimeInForce,
+    TrendEnum,
+    UserRoles,
+)
+from pybinbot.shared.indicators import Indicators
+from pybinbot.shared.heikin_ashi import HeikinAshi
+from pybinbot.shared.logging_config import configure_logging
+from pybinbot.shared.types import Amount
+from pybinbot.shared.cache import cache
+from pybinbot.shared.handlers import handle_binance_errors, aio_response_handler
+from pybinbot.models.bot_base import BotBase
+from pybinbot.models.deal import DealBase
+from pybinbot.models.order import OrderBase
+from pybinbot.models.signals import HABollinguerSpread, SignalsConsumer
+from pybinbot.models.routes import StandardResponse
+from pybinbot.apis.binance.base import BinanceApi
+from pybinbot.apis.binbot.base import BinbotApi
+from pybinbot.apis.binbot.exceptions import (
+    BinbotErrors,
+    QuantityTooLow,
+    IsolateBalanceError,
+    DealCreationError,
+    MarginShortError,
+    MarginLoanNotFound,
+    DeleteOrderError,
+    LowBalanceCleanupError,
+    SaveBotError,
+    InsufficientBalance,
+)
+from pybinbot.apis.kucoin.base import KucoinApi
+from pybinbot.apis.kucoin.exceptions import KucoinErrors
+from pybinbot.apis.binance.exceptions import (
+    BinanceErrors,
+    InvalidSymbol,
+    NotEnoughFunds,
+)
+
+
+from . import models, shared
+
+__all__ = [
+    # subpackages
+    "shared",
+    "models",
+    # models
+    "BotBase",
+    "OrderBase",
+    "DealBase",
+    "StandardResponse",
+    "HABollinguerSpread",
+    "SignalsConsumer",
+    # misc
+    "Amount",
+    "configure_logging",
+    "cache",
+    "handle_binance_errors",
+    "aio_response_handler",
+    # maths helpers
+    "supress_trailling",
+    "round_numbers",
+    "round_numbers_ceiling",
+    "round_numbers_floor",
+    "supress_notation",
+    "interval_to_millisecs",
+    "format_ts",
+    "zero_remainder",
+    # timestamp helpers
+    "timestamp",
+    "round_timestamp",
+    "ts_to_day",
+    "ms_to_sec",
+    "sec_to_ms",
+    "ts_to_humandate",
+    "timestamp_to_datetime",
+    # dataframes
+    "Indicators",
+    "HeikinAshi",
+    # enums
+    "CloseConditions",
+    "KafkaTopics",
+    "DealType",
+    "BinanceOrderModel",
+    "Status",
+    "Strategy",
+    "OrderType",
+    "TimeInForce",
+    "OrderSide",
+    "OrderStatus",
+    "TrendEnum",
+    "BinanceKlineIntervals",
+    "KucoinKlineIntervals",
+    "AutotradeSettingsDocument",
+    "UserRoles",
+    "QuoteAssets",
+    "ExchangeId",
+    "HABollinguerSpread",
+    "SignalsConsumer",
+    "MarketDominance",
+    # exchange apis
+    "BinbotApi",
+    "BinanceApi",
+    "KucoinApi",
+    "KucoinErrors",
+    # exceptions
+    "BinanceErrors",
+    "InvalidSymbol",
+    "NotEnoughFunds",
+    "BinbotErrors",
+    "QuantityTooLow",
+    "IsolateBalanceError",
+    "MarginShortError",
+    "MarginLoanNotFound",
+    "DeleteOrderError",
+    "LowBalanceCleanupError",
+    "DealCreationError",
+    "SaveBotError",
+    "InsufficientBalance",
+]

pybinbot/models/bot_base.py

@@ -0,0 +1,99 @@
+from pydantic import BaseModel, Field, field_validator
+
+from pybinbot.shared.enums import (
+    BinanceKlineIntervals,
+    CloseConditions,
+    QuoteAssets,
+    Status,
+    Strategy,
+)
+from pybinbot.shared.timestamps import timestamp, ts_to_humandate
+from pybinbot.shared.types import Amount
+
+
+class BotBase(BaseModel):
+    pair: str
+    fiat: str = Field(default="USDC")
+    quote_asset: QuoteAssets = Field(default=QuoteAssets.USDC)
+    fiat_order_size: Amount = Field(
+        default=0, ge=0, description="Min Binance 0.0001 BNB approx 15USD"
+    )
+    candlestick_interval: BinanceKlineIntervals = Field(
+        default=BinanceKlineIntervals.fifteen_minutes
+    )
+    close_condition: CloseConditions = Field(default=CloseConditions.dynamic_trailling)
+    cooldown: int = Field(
+        default=0,
+        ge=0,
+        description="cooldown period in minutes before opening next bot with same pair",
+    )
+    created_at: float = Field(default_factory=timestamp)
+    updated_at: float = Field(default_factory=timestamp)
+    dynamic_trailling: bool = Field(default=False)
+    logs: list = Field(default=[])
+    mode: str = Field(default="manual")
+    name: str = Field(
+        default="terminal",
+        description="Algorithm name or 'terminal' if executed from React app",
+    )
+    status: Status = Field(default=Status.inactive)
+    stop_loss: Amount = Field(
+        default=0, ge=-1, le=101, description="If stop_loss > 0, allow for reversal"
+    )
+    margin_short_reversal: bool = Field(
+        default=False,
+        description="Autoswitch from long to short or short to long strategy",
+    )
+    take_profit: Amount = Field(default=0, ge=-1, le=101)
+    trailling: bool = Field(default=False)
+    trailling_deviation: Amount = Field(
+        default=0,
+        ge=-1,
+        le=101,
+        description="Trailling activation (first take profit hit)",
+    )
+    trailling_profit: Amount = Field(default=0, ge=-1, le=101)
+    strategy: Strategy = Field(default=Strategy.long)
+    model_config = {
+        "from_attributes": True,
+        "use_enum_values": True,
+        "json_schema_extra": {
+            "description": "Most fields are optional. Deal and orders fields are generated internally and filled by Exchange",
+            "examples": [
+                {
+                    "pair": "BNBUSDT",
+                    "fiat": "USDC",
+                    "quote_asset": "USDC",
+                    "fiat_order_size": 15,
+                    "candlestick_interval": "15m",
+                    "close_condition": "dynamic_trailling",
+                    "cooldown": 0,
+                    "created_at": 1702999999.0,
+                    "updated_at": 1702999999.0,
+                    "dynamic_trailling": False,
+                    "logs": [],
+                    "mode": "manual",
+                    "name": "Default bot",
+                    "status": "inactive",
+                    "stop_loss": 0,
+                    "take_profit": 2.3,
+                    "trailling": True,
+                    "trailling_deviation": 0.63,
+                    "trailling_profit": 2.3,
+                    "margin_short_reversal": False,
+                    "strategy": "long",
+                }
+            ],
+        },
+    }
+
+    @field_validator("pair")
+    @classmethod
+    def check_pair_not_empty(cls, v):
+        assert v != "", "Pair field must be filled."
+        return v
+
+    def add_log(self, message: str) -> str:
+        timestamped_message = f"[{ts_to_humandate(timestamp())}] {message}"
+        self.logs.append(timestamped_message)
+        return self.logs[-1]

pybinbot/models/deal.py

@@ -0,0 +1,78 @@
+from pydantic import BaseModel, Field, field_validator
+
+from pybinbot.shared.types import Amount
+
+
+class DealBase(BaseModel):
+    """Operational deal data model with numeric fields."""
+
+    base_order_size: Amount = Field(default=0, gt=-1)
+    current_price: Amount = Field(default=0)
+    take_profit_price: Amount = Field(default=0)
+    trailling_stop_loss_price: Amount = Field(
+        default=0,
+        description=(
+            "take_profit but for trailling, to avoid confusion, "
+            "trailling_profit_price always be > trailling_stop_loss_price"
+        ),
+    )
+    trailling_profit_price: Amount = Field(default=0)
+    stop_loss_price: Amount = Field(default=0)
+    total_interests: float = Field(default=0, gt=-1)
+    total_commissions: float = Field(default=0, gt=-1)
+    margin_loan_id: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Txid from Binance. This is used to check if there is a loan, "
+            "0 means no loan"
+        ),
+    )
+    margin_repay_id: int = Field(
+        default=0, ge=0, description="= 0, it has not been repaid"
+    )
+    opening_price: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous buy_price or short_sell_price/margin_short_sell_price"
+        ),
+    )
+    opening_qty: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous buy_total_qty or short_sell_qty/margin_short_sell_qty"
+        ),
+    )
+    opening_timestamp: int = Field(default=0)
+    closing_price: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous sell_price or short_sell_price/margin_short_sell_price"
+        ),
+    )
+    closing_qty: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous sell_qty or short_sell_qty/margin_short_sell_qty"
+        ),
+    )
+    closing_timestamp: int = Field(
+        default=0,
+        description=("replaces previous buy_timestamp or margin/short_sell timestamps"),
+    )
+
+    @field_validator("margin_loan_id", mode="before")
+    @classmethod
+    def validate_margin_loan_id(cls, value):
+        if isinstance(value, float):
+            return int(value)
+        else:
+            return value
+
+    @field_validator("margin_loan_id", mode="after")
+    @classmethod
+    def cast_float(cls, value):
+        if isinstance(value, float):
+            return int(value)
+        else:
+            return value

pybinbot/models/order.py

@@ -0,0 +1,112 @@
+from pydantic import BaseModel, Field
+
+from pybinbot.shared.enums import DealType, OrderStatus
+from pybinbot.shared.types import Amount
+
+
+class OrderBase(BaseModel):
+    order_type: str = Field(
+        description=(
+            "Because every exchange has different naming, we should keep it as a "
+            "str rather than OrderType enum"
+        )
+    )
+    time_in_force: str
+    timestamp: int = Field(default=0)
+    order_id: int | str = Field(
+        description=(
+            "Because every exchange has id type, we should keep it as loose as "
+            "possible. Int is for backwards compatibility"
+        )
+    )
+    order_side: str = Field(
+        description=(
+            "Because every exchange has different naming, we should keep it as a "
+            "str rather than OrderType enum"
+        )
+    )
+    pair: str
+    qty: float
+    status: OrderStatus
+    price: float
+    deal_type: DealType
+    model_config = {
+        "from_attributes": True,
+        "use_enum_values": True,
+        "json_schema_extra": {
+            "description": (
+                "Most fields are optional. Deal field is generated internally, "
+                "orders are filled up by Exchange"
+            ),
+            "examples": [
+                {
+                    "order_type": "LIMIT",
+                    "time_in_force": "GTC",
+                    "timestamp": 0,
+                    "order_id": 0,
+                    "order_side": "BUY",
+                    "pair": "",
+                    "qty": 0,
+                    "status": "",
+                    "price": 0,
+                }
+            ],
+        },
+    }
+
+
+class DealModel(BaseModel):
+    base_order_size: Amount = Field(default=0, gt=-1)
+    current_price: Amount = Field(default=0)
+    take_profit_price: Amount = Field(default=0)
+    trailling_stop_loss_price: Amount = Field(
+        default=0,
+        description=(
+            "take_profit but for trailling, to avoid confusion, "
+            "trailling_profit_price always be > trailling_stop_loss_price"
+        ),
+    )
+    trailling_profit_price: Amount = Field(default=0)
+    stop_loss_price: Amount = Field(default=0)
+    total_interests: float = Field(default=0, gt=-1)
+    total_commissions: float = Field(default=0, gt=-1)
+    margin_loan_id: int = Field(
+        default=0,
+        ge=0,
+        description=(
+            "Txid from Binance. This is used to check if there is a loan, "
+            "0 means no loan"
+        ),
+    )
+    margin_repay_id: int = Field(
+        default=0, ge=0, description="= 0, it has not been repaid"
+    )
+    opening_price: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous buy_price or short_sell_price/margin_short_sell_price"
+        ),
+    )
+    opening_qty: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous buy_total_qty or short_sell_qty/margin_short_sell_qty"
+        ),
+    )
+    opening_timestamp: int = Field(default=0)
+    closing_price: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous sell_price or short_sell_price/margin_short_sell_price"
+        ),
+    )
+    closing_qty: Amount = Field(
+        default=0,
+        description=(
+            "replaces previous sell_qty or short_sell_qty/margin_short_sell_qty"
+        ),
+    )
+    closing_timestamp: int = Field(
+        default=0,
+        description=("replaces previous buy_timestamp or margin/short_sell timestamps"),
+    )

pybinbot/models/routes.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel, Field
+
+
+class StandardResponse(BaseModel):
+    message: str
+    error: int = Field(default=0)

pybinbot/models/signals.py

@@ -0,0 +1,46 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class HABollinguerSpread(BaseModel):
+    """Pydantic model for the Bollinguer spread."""
+
+    bb_high: float
+    bb_mid: float
+    bb_low: float
+
+
+class SignalsConsumer(BaseModel):
+    """Pydantic model for the signals consumer."""
+
+    type: str = Field(default="signal")
+    date: str = Field(
+        default_factory=lambda: datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    )
+    spread: Optional[float] = Field(default=0)
+    current_price: Optional[float] = Field(default=0)
+    msg: str
+    symbol: str
+    algo: str
+    bot_strategy: str = Field(default="long")
+    bb_spreads: Optional[HABollinguerSpread]
+    autotrade: bool = Field(default=True, description="If it is in testing mode, False")
+
+    model_config = ConfigDict(
+        extra="allow",
+        use_enum_values=True,
+    )
+
+    @field_validator("spread", "current_price")
+    @classmethod
+    def name_must_contain_space(cls, v):
+        if v is None:
+            return 0
+        elif isinstance(v, str):
+            return float(v)
+        elif isinstance(v, float):
+            return v
+        else:
+            raise ValueError("must be a float or 0")

pybinbot/shared/cache.py

@@ -0,0 +1,32 @@
+import time
+from functools import wraps
+from typing import Any, Callable, Dict, Tuple
+
+
+def cache(
+    ttl_seconds: int = 3600,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Simple in-process TTL cache decorator (per process).
+    Caches function results by args/kwargs for ttl_seconds.
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        store: Dict[
+            Tuple[Tuple[Any, ...], Tuple[Tuple[str, Any], ...]], Tuple[float, Any]
+        ] = {}
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            key = (args, tuple(sorted(kwargs.items())))
+            now = time.monotonic()
+            if key in store:
+                expiry, value = store[key]
+                if now < expiry:
+                    return value
+            value = func(*args, **kwargs)
+            store[key] = (now + max(0, int(ttl_seconds)), value)
+            return value
+
+        return wrapper
+
+    return decorator