tickwire-cli 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- tickwire_cli/__init__.py +4 -0
- tickwire_cli/__main__.py +14 -0
- tickwire_cli/_version.py +1 -0
- tickwire_cli/app.py +174 -0
- tickwire_cli/commands/__init__.py +11 -0
- tickwire_cli/commands/accounts.py +51 -0
- tickwire_cli/commands/login.py +81 -0
- tickwire_cli/commands/logs.py +272 -0
- tickwire_cli/commands/sandbox.py +74 -0
- tickwire_cli/commands/trade.py +153 -0
- tickwire_cli/commands/trigger.py +44 -0
- tickwire_cli/commands/webhooks_listen.py +112 -0
- tickwire_cli/credentials.py +259 -0
- tickwire_cli/errors.py +6 -0
- tickwire_cli/output.py +96 -0
- tickwire_cli-0.1.0.dist-info/METADATA +93 -0
- tickwire_cli-0.1.0.dist-info/RECORD +21 -0
- tickwire_cli-0.1.0.dist-info/WHEEL +5 -0
- tickwire_cli-0.1.0.dist-info/entry_points.txt +2 -0
- tickwire_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
- tickwire_cli-0.1.0.dist-info/top_level.txt +1 -0
tickwire_cli/__init__.py
ADDED
tickwire_cli/__main__.py
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""``python -m tickwire_cli`` and the ``tickwire`` console script."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import sys
|
|
5
|
+
|
|
6
|
+
from .app import run
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def main() -> None:
|
|
10
|
+
raise SystemExit(run(sys.argv[1:]))
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
if __name__ == "__main__":
|
|
14
|
+
main()
|
tickwire_cli/_version.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|
tickwire_cli/app.py
ADDED
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
"""Argument parsing, the shared context, and error handling for every command.
|
|
2
|
+
|
|
3
|
+
Exit codes:
|
|
4
|
+
|
|
5
|
+
==== ==========================================================
|
|
6
|
+
0 done (for ``trade``: ``applied`` or ``no_change``)
|
|
7
|
+
1 the API answered with an error, or the request failed
|
|
8
|
+
2 usage or configuration problem (no login, bad flags)
|
|
9
|
+
3 ``trade``: ``rejected`` (not executed)
|
|
10
|
+
4 ``trade``: ``held`` by a pre-trade hook, awaiting a decision
|
|
11
|
+
5 ``trade``: ``unknown``: it MAY have executed; never re-sent
|
|
12
|
+
130 interrupted (Ctrl-C)
|
|
13
|
+
==== ==========================================================
|
|
14
|
+
"""
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import argparse
|
|
18
|
+
import getpass as _getpass
|
|
19
|
+
import os
|
|
20
|
+
import sys
|
|
21
|
+
import time
|
|
22
|
+
from collections.abc import Callable, Mapping
|
|
23
|
+
from dataclasses import dataclass, field
|
|
24
|
+
from typing import Any, TextIO
|
|
25
|
+
from urllib.parse import urlsplit
|
|
26
|
+
|
|
27
|
+
import httpx
|
|
28
|
+
from tickwire import ConfigError, Tickwire, TickwireError
|
|
29
|
+
from tickwire.config import ENV_API_KEY, ENV_API_URL, ENV_SANDBOX_URL
|
|
30
|
+
|
|
31
|
+
from ._version import __version__
|
|
32
|
+
from .commands import COMMANDS
|
|
33
|
+
from .credentials import DEFAULT_PROFILE, SANDBOX_PROFILE, CredentialError, CredentialStore
|
|
34
|
+
from .errors import UsageError
|
|
35
|
+
from .output import Output
|
|
36
|
+
|
|
37
|
+
EXIT_OK, EXIT_ERROR, EXIT_USAGE = 0, 1, 2
|
|
38
|
+
ACTOR = "tickwire-cli"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def check_api_url(url: str) -> None:
|
|
45
|
+
"""https:// always; plain http:// only to this machine (a local stack), because the
|
|
46
|
+
API key travels in every request."""
|
|
47
|
+
parts = urlsplit(url)
|
|
48
|
+
host = (parts.hostname or "").lower()
|
|
49
|
+
if parts.scheme == "https" and host:
|
|
50
|
+
return
|
|
51
|
+
if parts.scheme == "http" and host in LOCAL_HOSTS:
|
|
52
|
+
return
|
|
53
|
+
raise UsageError(f"the API URL must be https://… (http:// is allowed only for localhost, 127.0.0.1 "
|
|
54
|
+
f"or [::1]); got {url!r}")
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass
|
|
58
|
+
class Ctx:
|
|
59
|
+
args: argparse.Namespace
|
|
60
|
+
out: Output
|
|
61
|
+
store: CredentialStore
|
|
62
|
+
env: Mapping[str, str]
|
|
63
|
+
stdin: TextIO
|
|
64
|
+
transport: httpx.BaseTransport | None = None # API calls (tests inject one)
|
|
65
|
+
forward_transport: httpx.BaseTransport | None = None # listen --forward-to (tests inject one)
|
|
66
|
+
getpass: Callable[[str], str] = _getpass.getpass
|
|
67
|
+
sleep: Callable[[float], Any] = time.sleep
|
|
68
|
+
_client: Tickwire | None = field(default=None, repr=False)
|
|
69
|
+
|
|
70
|
+
# ---- which profile, URL and key
|
|
71
|
+
@property
|
|
72
|
+
def sandbox(self) -> bool:
|
|
73
|
+
return bool(getattr(self.args, "sandbox", False))
|
|
74
|
+
|
|
75
|
+
@property
|
|
76
|
+
def profile_name(self) -> str:
|
|
77
|
+
name = getattr(self.args, "profile", None) or self.env.get("TICKWIRE_PROFILE")
|
|
78
|
+
return name or (SANDBOX_PROFILE if self.sandbox else DEFAULT_PROFILE)
|
|
79
|
+
|
|
80
|
+
def api_url(self, *, sandbox: bool | None = None, required: bool = True) -> str:
|
|
81
|
+
sandbox = self.sandbox if sandbox is None else sandbox
|
|
82
|
+
url = getattr(self.args, "api_url", None) or self.env.get(ENV_SANDBOX_URL if sandbox else ENV_API_URL, "")
|
|
83
|
+
if not url:
|
|
84
|
+
p = self.store.profile(self.profile_name)
|
|
85
|
+
url = p.api_url if p else ""
|
|
86
|
+
url = (url or "").strip().rstrip("/")
|
|
87
|
+
if required and not url:
|
|
88
|
+
env = ENV_SANDBOX_URL if sandbox else ENV_API_URL
|
|
89
|
+
raise UsageError(f"no API URL: pass --api-url or set {env}")
|
|
90
|
+
if url:
|
|
91
|
+
check_api_url(url)
|
|
92
|
+
return url
|
|
93
|
+
|
|
94
|
+
def client(self) -> Tickwire:
|
|
95
|
+
if self._client is not None:
|
|
96
|
+
return self._client
|
|
97
|
+
name = self.profile_name
|
|
98
|
+
profile = self.store.profile(name)
|
|
99
|
+
if self.sandbox and profile is not None and not profile.sandbox:
|
|
100
|
+
raise UsageError(f"profile {name!r} is a live profile, but --sandbox was given")
|
|
101
|
+
key = self.env.get(ENV_API_KEY, "").strip()
|
|
102
|
+
if not key:
|
|
103
|
+
key = self.store.key(name) or ""
|
|
104
|
+
if not key:
|
|
105
|
+
hint = " --sandbox" if self.sandbox else ""
|
|
106
|
+
raise UsageError(f"not logged in (profile {name!r}): run `tickwire login{hint}` "
|
|
107
|
+
f"or set {ENV_API_KEY}")
|
|
108
|
+
sandbox = self.sandbox or bool(profile and profile.sandbox)
|
|
109
|
+
self._client = Tickwire(base_url=self.api_url(sandbox=sandbox), token=key, actor=ACTOR,
|
|
110
|
+
transport=self.transport)
|
|
111
|
+
return self._client
|
|
112
|
+
|
|
113
|
+
def close(self) -> None:
|
|
114
|
+
if self._client is not None:
|
|
115
|
+
self._client.close()
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def _global_options(p: argparse.ArgumentParser, *, suppress: bool) -> None:
|
|
119
|
+
d = {"default": argparse.SUPPRESS} if suppress else {}
|
|
120
|
+
p.add_argument("--json", action="store_true", help="machine-readable JSON output", **d)
|
|
121
|
+
p.add_argument("--profile", help="credential profile (default: 'default', or 'sandbox' with --sandbox)", **d)
|
|
122
|
+
p.add_argument("--sandbox", action="store_true", help="use the sandbox (TICKWIRE_SANDBOX_URL)", **d)
|
|
123
|
+
p.add_argument("--api-url", help="API base URL (else TICKWIRE_API_URL / TICKWIRE_SANDBOX_URL "
|
|
124
|
+
"or the profile's)", **d)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
128
|
+
parser = argparse.ArgumentParser(prog="tickwire", description="The Tickwire MT4/MT5 cloud API from your terminal.")
|
|
129
|
+
parser.add_argument("--version", action="version", version=f"tickwire-cli {__version__}")
|
|
130
|
+
_global_options(parser, suppress=False)
|
|
131
|
+
common = argparse.ArgumentParser(add_help=False)
|
|
132
|
+
_global_options(common, suppress=True) # the same flags also work after the command
|
|
133
|
+
sub = parser.add_subparsers(dest="command", metavar="<command>")
|
|
134
|
+
sub.required = True
|
|
135
|
+
for module in COMMANDS:
|
|
136
|
+
module.register(sub, common)
|
|
137
|
+
return parser
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def run(argv: list[str], *, env: Mapping[str, str] | None = None, stdin: TextIO | None = None,
|
|
141
|
+
stdout: TextIO | None = None, stderr: TextIO | None = None,
|
|
142
|
+
transport: httpx.BaseTransport | None = None, forward_transport: httpx.BaseTransport | None = None,
|
|
143
|
+
getpass: Callable[[str], str] | None = None, sleep: Callable[[float], Any] | None = None,
|
|
144
|
+
store: CredentialStore | None = None) -> int:
|
|
145
|
+
env = os.environ if env is None else env
|
|
146
|
+
parser = build_parser()
|
|
147
|
+
try:
|
|
148
|
+
args = parser.parse_args(argv)
|
|
149
|
+
except SystemExit as e: # --help, --version, bad usage
|
|
150
|
+
return int(e.code or 0)
|
|
151
|
+
out = Output(bool(getattr(args, "json", False)), stdout, stderr)
|
|
152
|
+
ctx = Ctx(args=args, out=out, store=store or CredentialStore(env=env), env=env,
|
|
153
|
+
stdin=stdin or sys.stdin, transport=transport, forward_transport=forward_transport,
|
|
154
|
+
getpass=getpass or _getpass.getpass, sleep=sleep or time.sleep)
|
|
155
|
+
try:
|
|
156
|
+
return int(args.func(ctx) or 0)
|
|
157
|
+
except UsageError as e:
|
|
158
|
+
out.error("usage", str(e))
|
|
159
|
+
return EXIT_USAGE
|
|
160
|
+
except (CredentialError, ConfigError) as e:
|
|
161
|
+
out.error("config", getattr(e, "message", None) or str(e))
|
|
162
|
+
return EXIT_USAGE
|
|
163
|
+
except TickwireError as e:
|
|
164
|
+
extra = {"status": e.status} if e.status is not None else {}
|
|
165
|
+
rid = e.body.get("requestId") if isinstance(e.body, dict) else None
|
|
166
|
+
if rid:
|
|
167
|
+
extra["requestId"] = rid
|
|
168
|
+
out.error(e.code or type(e).__name__, e.message, **extra)
|
|
169
|
+
return EXIT_ERROR
|
|
170
|
+
except KeyboardInterrupt:
|
|
171
|
+
out.note("interrupted")
|
|
172
|
+
return 130
|
|
173
|
+
finally:
|
|
174
|
+
ctx.close()
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""The ``tickwire`` commands. Each module has ``register(subparsers, common)``,
|
|
2
|
+
which adds its parser(s) with ``parents=[common]`` (the global flags) and sets
|
|
3
|
+
``func(ctx) -> exit code``.
|
|
4
|
+
|
|
5
|
+
To add a command, add a module here and list it in :data:`COMMANDS`.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from . import accounts, login, logs, sandbox, trade, trigger, webhooks_listen
|
|
10
|
+
|
|
11
|
+
COMMANDS = [login, sandbox, accounts, trade, webhooks_listen, trigger, logs]
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""``tickwire accounts list`` and ``tickwire accounts get <id> [--health]``."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
from ..output import table
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
def register(sub, common) -> None:
|
|
8
|
+
p = sub.add_parser("accounts", parents=[common], help="your trading accounts")
|
|
9
|
+
ss = p.add_subparsers(dest="accounts_command", metavar="<subcommand>")
|
|
10
|
+
ss.required = True
|
|
11
|
+
ls = ss.add_parser("list", parents=[common], help="list accounts")
|
|
12
|
+
ls.set_defaults(func=list_accounts)
|
|
13
|
+
g = ss.add_parser("get", parents=[common], help="one account")
|
|
14
|
+
g.add_argument("account_id")
|
|
15
|
+
g.add_argument("--health", action="store_true", help="also read the account's truthful health")
|
|
16
|
+
g.set_defaults(func=get_account)
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def _row(a: dict) -> list:
|
|
20
|
+
return [a.get("id"), a.get("platform"), a.get("login"), a.get("server"), a.get("status"),
|
|
21
|
+
"yes" if a.get("sandbox") else ""]
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
HEADERS = ["ID", "PLATFORM", "LOGIN", "SERVER", "STATUS", "SANDBOX"]
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def list_accounts(ctx) -> int:
|
|
28
|
+
accounts = ctx.client().list_accounts() or []
|
|
29
|
+
ctx.out.result(accounts, lambda: table([_row(a) for a in accounts], HEADERS) if accounts
|
|
30
|
+
else "No accounts.")
|
|
31
|
+
return 0
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def get_account(ctx) -> int:
|
|
35
|
+
tw = ctx.client()
|
|
36
|
+
account = tw.get_account(ctx.args.account_id)
|
|
37
|
+
if ctx.args.health:
|
|
38
|
+
account = {**account, "health": tw.account(ctx.args.account_id).health()}
|
|
39
|
+
|
|
40
|
+
def human() -> str:
|
|
41
|
+
lines = [table([_row(account)], HEADERS)]
|
|
42
|
+
if account.get("error"):
|
|
43
|
+
lines.append(f"error: {account['error']}")
|
|
44
|
+
h = account.get("health")
|
|
45
|
+
if isinstance(h, dict):
|
|
46
|
+
reasons = ", ".join(h.get("reasons") or []) or "none"
|
|
47
|
+
lines.append(f"health: {h.get('status')} (reasons: {reasons}; checked {h.get('checked_at')})")
|
|
48
|
+
return "\n".join(lines)
|
|
49
|
+
|
|
50
|
+
ctx.out.result(account, human)
|
|
51
|
+
return 0
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"""``tickwire login`` / ``tickwire logout``: store or remove an API key.
|
|
2
|
+
|
|
3
|
+
The key is never a command-line argument (it would land in shell history and
|
|
4
|
+
the process list) and is never printed: it is read with a hidden prompt, or
|
|
5
|
+
from standard input (``--key-stdin``, or any non-terminal stdin), then checked
|
|
6
|
+
against the API and stored in the OS keychain or a ``0600`` file.
|
|
7
|
+
"""
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from tickwire import Tickwire
|
|
11
|
+
|
|
12
|
+
from ..credentials import SANDBOX_PROFILE
|
|
13
|
+
from ..errors import UsageError
|
|
14
|
+
|
|
15
|
+
SANDBOX_PREFIX = "twsk_"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def register(sub, common) -> None:
|
|
19
|
+
p = sub.add_parser("login", parents=[common], help="store an API key (hidden prompt or stdin)",
|
|
20
|
+
description=__doc__.split("\n\n")[1] if __doc__ else None)
|
|
21
|
+
p.add_argument("--key-stdin", action="store_true", help="read the key from standard input")
|
|
22
|
+
p.add_argument("--no-keyring", action="store_true", help="store in the 0600 file even if a keychain exists")
|
|
23
|
+
p.add_argument("--no-verify", action="store_true", help="store without checking the key against the API")
|
|
24
|
+
p.set_defaults(func=login)
|
|
25
|
+
|
|
26
|
+
q = sub.add_parser("logout", parents=[common], help="forget the stored key of a profile")
|
|
27
|
+
q.set_defaults(func=logout)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _read_key(ctx) -> str:
|
|
31
|
+
stdin = ctx.stdin
|
|
32
|
+
if getattr(ctx.args, "key_stdin", False) or not _isatty(stdin):
|
|
33
|
+
key = stdin.readline()
|
|
34
|
+
else:
|
|
35
|
+
key = ctx.getpass("Tickwire API key (input hidden): ")
|
|
36
|
+
key = (key or "").strip()
|
|
37
|
+
if not key:
|
|
38
|
+
raise UsageError("no key given")
|
|
39
|
+
if any(c.isspace() for c in key) or not key.isprintable():
|
|
40
|
+
raise UsageError("that does not look like an API key (it contains spaces or control characters)")
|
|
41
|
+
return key
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _isatty(stream) -> bool:
|
|
45
|
+
try:
|
|
46
|
+
return bool(stream.isatty())
|
|
47
|
+
except (AttributeError, ValueError):
|
|
48
|
+
return False
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def login(ctx) -> int:
|
|
52
|
+
name = ctx.profile_name
|
|
53
|
+
existing = ctx.store.profile(name)
|
|
54
|
+
sandbox = ctx.sandbox or (name == SANDBOX_PROFILE) or bool(existing and existing.sandbox)
|
|
55
|
+
url = ctx.api_url(sandbox=sandbox)
|
|
56
|
+
key = _read_key(ctx)
|
|
57
|
+
if sandbox and not key.startswith(SANDBOX_PREFIX):
|
|
58
|
+
raise UsageError(f"--sandbox needs a sandbox key ({SANDBOX_PREFIX}…); this looks like a live key")
|
|
59
|
+
if not sandbox and key.startswith(SANDBOX_PREFIX):
|
|
60
|
+
raise UsageError("this is a sandbox key: run `tickwire login --sandbox`")
|
|
61
|
+
verified = False
|
|
62
|
+
if not ctx.args.no_verify:
|
|
63
|
+
with Tickwire(base_url=url, token=key, actor="tickwire-cli", transport=ctx.transport) as tw:
|
|
64
|
+
tw.list_accounts() # 401 raises: nothing is stored
|
|
65
|
+
verified = True
|
|
66
|
+
profile = ctx.store.save(name, key, api_url=url, sandbox=sandbox, use_keyring=not ctx.args.no_keyring)
|
|
67
|
+
where = ("the OS keychain" if profile.storage == "keyring"
|
|
68
|
+
else f"{ctx.store.dir / 'credentials.json'} (mode 600)")
|
|
69
|
+
data = {**profile.public(), "verified": verified}
|
|
70
|
+
ctx.out.result(data, f"Logged in: profile {name!r}, {'sandbox' if sandbox else 'live'} API at {url}.\n"
|
|
71
|
+
f"Key {profile.key_hint} stored in {where}"
|
|
72
|
+
+ ("" if verified else " (not verified: --no-verify)") + ".")
|
|
73
|
+
return 0
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def logout(ctx) -> int:
|
|
77
|
+
name = ctx.profile_name
|
|
78
|
+
removed = ctx.store.delete(name)
|
|
79
|
+
ctx.out.result({"profile": name, "removed": removed},
|
|
80
|
+
f"Removed the key of profile {name!r}." if removed else f"No profile {name!r}.")
|
|
81
|
+
return 0
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
"""``tickwire logs tail``: your request log (``GET /v1/request-logs``) in the terminal.
|
|
2
|
+
|
|
3
|
+
Prints the most recent calls your organisation's keys made, oldest first, one
|
|
4
|
+
line per request (``--json``: one JSON object per line). ``--follow`` keeps
|
|
5
|
+
polling and prints new calls as the gateway records them; Ctrl-C stops it.
|
|
6
|
+
|
|
7
|
+
How it works (``docs/public/cli.md`` has the full story):
|
|
8
|
+
|
|
9
|
+
* The list is newest first and paginated with an opaque cursor
|
|
10
|
+
(``nextCursor``/``hasMore``). The CLI never decodes the cursor; it passes it
|
|
11
|
+
back unchanged, with the same filters, as the API requires.
|
|
12
|
+
* ``--follow`` polls the first page every ``--interval`` seconds and walks
|
|
13
|
+
back until it reaches a call it already printed, so a call that is recorded
|
|
14
|
+
late is still shown once. If more than ``MAX_POLL_ROWS`` calls arrived
|
|
15
|
+
between two polls, it prints the newest and says how many pages it skipped.
|
|
16
|
+
* ``--bodies`` fetches ``GET /v1/request-logs/{id}`` for failed calls
|
|
17
|
+
(status >= 400; only those keep excerpts) and prints the redacted
|
|
18
|
+
``requestBody``/``responseBody`` exactly as the API returned them. Nothing is
|
|
19
|
+
printed when the API returns none. A credential that may not see bodies
|
|
20
|
+
(``excerptsHidden: true`` or ``403``) gets metadata only, with one note.
|
|
21
|
+
* ``429``: the CLI waits for ``Retry-After`` (or backs off exponentially when
|
|
22
|
+
there is none) and tries again: forever with ``--follow``, a few times
|
|
23
|
+
otherwise. Timeouts and 502/503/504 are handled the same way.
|
|
24
|
+
"""
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
import re
|
|
28
|
+
from collections import OrderedDict
|
|
29
|
+
from datetime import datetime, timedelta, timezone
|
|
30
|
+
from urllib.parse import quote
|
|
31
|
+
|
|
32
|
+
from tickwire import Backoff, TickwireError, TransportError
|
|
33
|
+
from tickwire.errors import Forbidden, NotFound, RateLimited
|
|
34
|
+
|
|
35
|
+
from ..errors import UsageError
|
|
36
|
+
from ..output import clean
|
|
37
|
+
|
|
38
|
+
PAGE_MAX = 200 # the API's largest page
|
|
39
|
+
POLL_PAGE = 100 # page size while following
|
|
40
|
+
MAX_POLL_ROWS = 2000 # new calls walked per poll before we say we skipped some
|
|
41
|
+
MAX_LIMIT = 1000
|
|
42
|
+
SEEN_MAX = 10_000 # ids remembered to avoid printing a call twice
|
|
43
|
+
RETRY_STATUS = frozenset({408, 429, 502, 503, 504})
|
|
44
|
+
ONE_SHOT_RETRIES = 3
|
|
45
|
+
BACKOFF_BASE_S, BACKOFF_CAP_S = 1.0, 60.0
|
|
46
|
+
_REL = re.compile(r"^(\d+)\s*([smhd])$")
|
|
47
|
+
_UNITS = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days"}
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def register(sub, common) -> None:
|
|
51
|
+
p = sub.add_parser("logs", parents=[common], help="your request log",
|
|
52
|
+
description="Read your organisation's request log (GET /v1/request-logs).")
|
|
53
|
+
lsub = p.add_subparsers(dest="logs_command", metavar="<subcommand>")
|
|
54
|
+
lsub.required = True
|
|
55
|
+
t = lsub.add_parser("tail", parents=[common], help="print recent API calls; --follow for new ones",
|
|
56
|
+
description=__doc__.split("\n\n")[1] if __doc__ else None)
|
|
57
|
+
t.add_argument("-f", "--follow", action="store_true", help="keep polling and print new calls (Ctrl-C stops)")
|
|
58
|
+
t.add_argument("-n", "--limit", type=int, default=20,
|
|
59
|
+
help=f"how many recent calls to print first (default 20, at most {MAX_LIMIT}; "
|
|
60
|
+
f"0 with --follow prints only new ones)")
|
|
61
|
+
t.add_argument("--since", help="only calls at or after this time: ISO 8601, or relative (30s, 15m, 2h, 7d)")
|
|
62
|
+
t.add_argument("--until", help="only calls before this time (ISO 8601 or relative); not with --follow")
|
|
63
|
+
t.add_argument("--status", help="404, 4xx, 5xx, errors (>= 400) or aborted")
|
|
64
|
+
t.add_argument("--method", help="GET, POST, …")
|
|
65
|
+
t.add_argument("--route", "--path", dest="route", help="part of the path or of its template")
|
|
66
|
+
t.add_argument("--error-code", help="e.g. validation_error")
|
|
67
|
+
t.add_argument("--account", help="trading account id")
|
|
68
|
+
t.add_argument("--key-id", help="API key id (never the key itself)")
|
|
69
|
+
t.add_argument("--request-id", help="an X-Request-ID")
|
|
70
|
+
t.add_argument("--bodies", action="store_true",
|
|
71
|
+
help="also print the redacted request/response excerpts of failed calls "
|
|
72
|
+
"(full-access key with the writer role only)")
|
|
73
|
+
t.add_argument("--interval", type=float, default=2.0, help="seconds between polls with --follow (default 2)")
|
|
74
|
+
t.set_defaults(func=tail)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
# --------------------------------------------------------------------------- helpers
|
|
78
|
+
def _now() -> datetime:
|
|
79
|
+
return datetime.now(timezone.utc)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def parse_time(value: str | None, flag: str) -> str | None:
|
|
83
|
+
"""``--since``/``--until``: ISO 8601 (kept as given, UTC when no zone) or ``<n>[smhd]`` ago."""
|
|
84
|
+
if value is None or not value.strip():
|
|
85
|
+
return None
|
|
86
|
+
v = value.strip()
|
|
87
|
+
m = _REL.match(v.lower())
|
|
88
|
+
if m:
|
|
89
|
+
dt = _now() - timedelta(**{_UNITS[m.group(2)]: int(m.group(1))})
|
|
90
|
+
else:
|
|
91
|
+
try:
|
|
92
|
+
dt = datetime.fromisoformat(v.replace("Z", "+00:00").replace("z", "+00:00"))
|
|
93
|
+
except ValueError:
|
|
94
|
+
raise UsageError(f"{flag} must be an ISO 8601 time (2026-09-28T10:00:00Z) or relative "
|
|
95
|
+
f"(30s, 15m, 2h, 7d); got {value!r}") from None
|
|
96
|
+
if dt.tzinfo is None:
|
|
97
|
+
dt = dt.replace(tzinfo=timezone.utc)
|
|
98
|
+
return dt.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _latency(ms) -> str:
|
|
102
|
+
if ms is None:
|
|
103
|
+
return "-"
|
|
104
|
+
return f"{ms} ms" if ms < 10_000 else f"{ms / 1000:.1f} s"
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def human_line(row: dict) -> str:
|
|
108
|
+
parts = [str(row.get("createdAt") or "-"), f"{row.get('method') or '-':<6}", str(row.get("status") or "-"),
|
|
109
|
+
f"{_latency(row.get('latencyMs')):>8}", str(row.get("path") or "-")]
|
|
110
|
+
if row.get("errorCode"):
|
|
111
|
+
parts.append(str(row["errorCode"]))
|
|
112
|
+
if row.get("outcome") == "aborted":
|
|
113
|
+
parts.append("[aborted]")
|
|
114
|
+
if row.get("kind") == "websocket":
|
|
115
|
+
parts.append("[websocket]")
|
|
116
|
+
if row.get("accountId"):
|
|
117
|
+
parts.append(f"account={row['accountId']}")
|
|
118
|
+
parts.append(str(row.get("requestId") or row.get("id") or ""))
|
|
119
|
+
return " ".join(p for p in parts if p)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
class _Tail:
|
|
123
|
+
def __init__(self, ctx) -> None:
|
|
124
|
+
self.ctx = ctx
|
|
125
|
+
a = ctx.args
|
|
126
|
+
self.a = a
|
|
127
|
+
self.tw = ctx.client()
|
|
128
|
+
# The CLI owns retries here: it honours Retry-After in full (the SDK caps its wait) and,
|
|
129
|
+
# with --follow, keeps going. One attempt per SDK call.
|
|
130
|
+
self.tw.opts.backoff = Backoff(max_attempts=1)
|
|
131
|
+
self.filters = {"status": a.status, "method": a.method, "route": a.route, "errorCode": a.error_code,
|
|
132
|
+
"accountId": a.account, "keyId": a.key_id, "requestId": a.request_id,
|
|
133
|
+
"since": parse_time(a.since, "--since"), "until": parse_time(a.until, "--until")}
|
|
134
|
+
self.seen: OrderedDict[str, None] = OrderedDict()
|
|
135
|
+
self.bodies = bool(a.bodies)
|
|
136
|
+
self.shown = 0
|
|
137
|
+
|
|
138
|
+
# ---- one API call, with the retry policy
|
|
139
|
+
def call(self, path: str, params: dict | None = None):
|
|
140
|
+
failures = 0
|
|
141
|
+
while True:
|
|
142
|
+
try:
|
|
143
|
+
return self.tw.request("GET", path, control=True, params=params)
|
|
144
|
+
except TickwireError as e:
|
|
145
|
+
retryable = isinstance(e, (RateLimited, TransportError)) or e.status in RETRY_STATUS
|
|
146
|
+
if not retryable or (not self.a.follow and failures >= ONE_SHOT_RETRIES):
|
|
147
|
+
raise
|
|
148
|
+
failures += 1
|
|
149
|
+
backoff = min(BACKOFF_CAP_S, BACKOFF_BASE_S * 2 ** (failures - 1))
|
|
150
|
+
retry_after = getattr(e, "retry_after", None)
|
|
151
|
+
wait = max(float(retry_after), backoff) if retry_after is not None else backoff
|
|
152
|
+
what = "rate limited (429)" if isinstance(e, RateLimited) else (
|
|
153
|
+
f"HTTP {e.status}" if e.status else "no answer")
|
|
154
|
+
self.ctx.out.note(f"{what}: retrying in {wait:g} s"
|
|
155
|
+
+ (" (Retry-After)" if retry_after is not None else ""))
|
|
156
|
+
self.ctx.sleep(wait)
|
|
157
|
+
|
|
158
|
+
def page(self, limit: int, cursor: str | None) -> dict:
|
|
159
|
+
page = self.call("/request-logs", {**self.filters, "limit": limit, "cursor": cursor})
|
|
160
|
+
if not isinstance(page, dict) or not isinstance(page.get("data"), list):
|
|
161
|
+
raise TickwireError("unexpected answer from GET /v1/request-logs (no data list)")
|
|
162
|
+
return page
|
|
163
|
+
|
|
164
|
+
# ---- the rows
|
|
165
|
+
def newest(self, n: int) -> list[dict]:
|
|
166
|
+
"""The ``n`` newest calls, newest first."""
|
|
167
|
+
rows: list[dict] = []
|
|
168
|
+
cursor = None
|
|
169
|
+
while len(rows) < n:
|
|
170
|
+
page = self.page(min(PAGE_MAX, n - len(rows)), cursor)
|
|
171
|
+
rows += page["data"]
|
|
172
|
+
cursor = page.get("nextCursor")
|
|
173
|
+
if not (page.get("hasMore") and cursor):
|
|
174
|
+
break
|
|
175
|
+
return rows[:n]
|
|
176
|
+
|
|
177
|
+
def new_since_last_poll(self) -> list[dict]:
|
|
178
|
+
"""Calls not printed yet, newest first. Walks back until a call already seen."""
|
|
179
|
+
rows: list[dict] = []
|
|
180
|
+
cursor = None
|
|
181
|
+
while True:
|
|
182
|
+
page = self.page(POLL_PAGE, cursor)
|
|
183
|
+
for row in page["data"]:
|
|
184
|
+
if row.get("id") in self.seen:
|
|
185
|
+
return rows
|
|
186
|
+
rows.append(row)
|
|
187
|
+
cursor = page.get("nextCursor")
|
|
188
|
+
if not (page.get("hasMore") and cursor):
|
|
189
|
+
return rows
|
|
190
|
+
if len(rows) >= MAX_POLL_ROWS:
|
|
191
|
+
self.ctx.out.note(f"warning: more than {MAX_POLL_ROWS} new calls since the last poll; "
|
|
192
|
+
f"showing the newest {len(rows)}, older ones in between were skipped "
|
|
193
|
+
f"(narrow the filters or use a shorter --interval)")
|
|
194
|
+
return rows
|
|
195
|
+
|
|
196
|
+
def remember(self, row: dict) -> None:
|
|
197
|
+
rid = row.get("id")
|
|
198
|
+
if rid is None:
|
|
199
|
+
return
|
|
200
|
+
self.seen[rid] = None
|
|
201
|
+
while len(self.seen) > SEEN_MAX:
|
|
202
|
+
self.seen.popitem(last=False)
|
|
203
|
+
|
|
204
|
+
# ---- --bodies
|
|
205
|
+
def detail(self, row: dict) -> dict:
|
|
206
|
+
"""The row plus the excerpts the API returned for it (errors only), or the row alone."""
|
|
207
|
+
if not self.bodies or not isinstance(row.get("status"), int) or row["status"] < 400 or not row.get("id"):
|
|
208
|
+
return row
|
|
209
|
+
try:
|
|
210
|
+
d = self.call(f"/request-logs/{quote(str(row['id']), safe='')}")
|
|
211
|
+
except Forbidden as e:
|
|
212
|
+
self._no_bodies(clean(f"403 {e.code or 'forbidden'}"))
|
|
213
|
+
return row
|
|
214
|
+
except NotFound: # pruned between the list and the detail: metadata only
|
|
215
|
+
return row
|
|
216
|
+
if not isinstance(d, dict):
|
|
217
|
+
return row
|
|
218
|
+
if d.get("excerptsHidden"):
|
|
219
|
+
self._no_bodies("the API hides them from this credential")
|
|
220
|
+
return {**row, "excerptsHidden": True}
|
|
221
|
+
out = dict(row)
|
|
222
|
+
for k in ("requestBody", "responseBody"):
|
|
223
|
+
if d.get(k) is not None: # only what the API returned
|
|
224
|
+
out[k] = d[k]
|
|
225
|
+
return out
|
|
226
|
+
|
|
227
|
+
def _no_bodies(self, why: str) -> None:
|
|
228
|
+
self.bodies = False
|
|
229
|
+
self.ctx.out.note(f"note: request/response bodies are not shown ({why}). Only a full-access key "
|
|
230
|
+
f"with the writer role, not limited to some accounts or applications, may read "
|
|
231
|
+
f"them; printing metadata only.")
|
|
232
|
+
|
|
233
|
+
def emit(self, rows_newest_first: list[dict]) -> None:
|
|
234
|
+
for row in reversed(rows_newest_first):
|
|
235
|
+
if row.get("id") in self.seen:
|
|
236
|
+
continue
|
|
237
|
+
row = self.detail(row)
|
|
238
|
+
lines = [human_line(row)] # each line is made terminal-safe by Output.line
|
|
239
|
+
for k, label in (("requestBody", "request "), ("responseBody", "response")):
|
|
240
|
+
if row.get(k) is not None:
|
|
241
|
+
lines.append(f" {label}: {row[k]}")
|
|
242
|
+
self.ctx.out.line(row, lines)
|
|
243
|
+
self.remember(row)
|
|
244
|
+
self.shown += 1
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def tail(ctx) -> int:
|
|
248
|
+
a = ctx.args
|
|
249
|
+
if a.limit < 0 or a.limit > MAX_LIMIT or (a.limit == 0 and not a.follow):
|
|
250
|
+
raise UsageError(f"--limit must be 1 to {MAX_LIMIT} (0 is allowed with --follow)")
|
|
251
|
+
if a.follow and a.until:
|
|
252
|
+
raise UsageError("--until cannot be combined with --follow")
|
|
253
|
+
if a.interval <= 0:
|
|
254
|
+
raise UsageError("--interval must be positive")
|
|
255
|
+
t = _Tail(ctx)
|
|
256
|
+
try:
|
|
257
|
+
if a.limit:
|
|
258
|
+
t.emit(t.newest(a.limit))
|
|
259
|
+
elif a.follow:
|
|
260
|
+
for row in t.newest(1): # start from the current head, print nothing old
|
|
261
|
+
t.remember(row)
|
|
262
|
+
if not a.follow:
|
|
263
|
+
if not t.shown:
|
|
264
|
+
ctx.out.note("no matching calls in the request log (kept 14 days)")
|
|
265
|
+
return 0
|
|
266
|
+
ctx.out.note("following the request log; Ctrl-C to stop")
|
|
267
|
+
while True:
|
|
268
|
+
ctx.sleep(a.interval)
|
|
269
|
+
t.emit(t.new_since_last_poll())
|
|
270
|
+
except KeyboardInterrupt:
|
|
271
|
+
ctx.out.note(f"stopped ({t.shown} call{'s' if t.shown != 1 else ''} shown)")
|
|
272
|
+
return 130
|