trapyze 0.17.4__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.
Files changed (65) hide show
  1. trapyze/__init__.py +21 -0
  2. trapyze/__main__.py +5 -0
  3. trapyze/ai.py +361 -0
  4. trapyze/apis.py +162 -0
  5. trapyze/cli.py +506 -0
  6. trapyze/desktop.py +516 -0
  7. trapyze/editors.py +105 -0
  8. trapyze/explain.py +84 -0
  9. trapyze/freshness.py +104 -0
  10. trapyze/health.py +180 -0
  11. trapyze/home.py +210 -0
  12. trapyze/importer.py +1094 -0
  13. trapyze/label.py +402 -0
  14. trapyze/layout.py +363 -0
  15. trapyze/locks.py +101 -0
  16. trapyze/packages.py +309 -0
  17. trapyze/packs.py +92 -0
  18. trapyze/project.py +13 -0
  19. trapyze/resources/examples/demo_price_data.py +71 -0
  20. trapyze/resources/examples/price_report.py +75 -0
  21. trapyze/resources/examples/say_hello.py +53 -0
  22. trapyze/resources/helper/trapyze_helper.py +741 -0
  23. trapyze/resources/packs/everyday_files/backup_folder.py +80 -0
  24. trapyze/resources/packs/everyday_files/biggest_files.py +69 -0
  25. trapyze/resources/packs/everyday_files/find_duplicates.py +76 -0
  26. trapyze/resources/packs/everyday_files/rename_files.py +93 -0
  27. trapyze/resources/packs/everyday_files/restore_backup.py +68 -0
  28. trapyze/resources/packs/everyday_files/set_duplicates_aside.py +105 -0
  29. trapyze/resources/packs/everyday_files/tidy_folder.py +91 -0
  30. trapyze/resources/packs/home_finance/bank_csv.py +123 -0
  31. trapyze/resources/packs/home_finance/bank_overview.py +173 -0
  32. trapyze/resources/packs/home_finance/find_subscriptions.py +87 -0
  33. trapyze/resources/packs/tables_and_data/check_download.py +100 -0
  34. trapyze/resources/packs/tables_and_data/csv_to_database.py +118 -0
  35. trapyze/resources/packs/tables_and_data/export_table.py +76 -0
  36. trapyze/resources/packs/tables_and_data/merge_csv.py +95 -0
  37. trapyze/resources/templates/analyse.py +68 -0
  38. trapyze/resources/templates/app.py +41 -0
  39. trapyze/resources/templates/collect.py +53 -0
  40. trapyze/resources/templates/maintain.py +62 -0
  41. trapyze/resources/templates/share.py +67 -0
  42. trapyze/review.py +88 -0
  43. trapyze/runner.py +415 -0
  44. trapyze/schedule.py +810 -0
  45. trapyze/share.py +138 -0
  46. trapyze/store.py +419 -0
  47. trapyze/templates.py +38 -0
  48. trapyze/updater.py +284 -0
  49. trapyze/vault.py +570 -0
  50. trapyze/versions.py +104 -0
  51. trapyze/web/__init__.py +0 -0
  52. trapyze/web/server.py +1738 -0
  53. trapyze/web/static/app.css +598 -0
  54. trapyze/web/static/app.js +3058 -0
  55. trapyze/web/static/favicon.png +0 -0
  56. trapyze/web/static/favicon.svg +1 -0
  57. trapyze/web/static/icon.ico +0 -0
  58. trapyze/web/static/icon.png +0 -0
  59. trapyze/web/static/index.html +36 -0
  60. trapyze-0.17.4.dist-info/METADATA +329 -0
  61. trapyze-0.17.4.dist-info/RECORD +65 -0
  62. trapyze-0.17.4.dist-info/WHEEL +5 -0
  63. trapyze-0.17.4.dist-info/entry_points.txt +5 -0
  64. trapyze-0.17.4.dist-info/licenses/LICENSE +21 -0
  65. trapyze-0.17.4.dist-info/top_level.txt +1 -0
trapyze/__init__.py ADDED
@@ -0,0 +1,21 @@
1
+ """traPYze: run your Python tools without the technical bits."""
2
+
3
+ __version__ = "0.17.4"
4
+
5
+ from .home import Home # noqa: E402
6
+ from .label import LabelError, Setting, SettingError, Tool, read_tool # noqa: E402
7
+ from .runner import Event, Run, RunResult, history, run_tool # noqa: E402
8
+
9
+ __all__ = [
10
+ "Event",
11
+ "Home",
12
+ "LabelError",
13
+ "Run",
14
+ "RunResult",
15
+ "Setting",
16
+ "SettingError",
17
+ "Tool",
18
+ "history",
19
+ "read_tool",
20
+ "run_tool",
21
+ ]
trapyze/__main__.py ADDED
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
trapyze/ai.py ADDED
@@ -0,0 +1,361 @@
1
+ """AI help: explain a script, say why a run failed, make a script traPYze-ready, or change it.
2
+
3
+ Two ways, both optional:
4
+ - copy and paste: traPYze writes the full question, you paste it into any AI chat
5
+ (Copilot, Gemini, ChatGPT, Claude …) and paste the answer back. Free, no setup.
6
+ - built in: with a key in the vault for Google Gemini, OpenRouter, Anthropic or
7
+ OpenAI, traPYze asks the AI itself.
8
+
9
+ Either way, keys and passwords are masked before anything leaves the computer, and
10
+ a changed script is only written after you have seen the differences; the old
11
+ version is kept (see versions.py).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import re
18
+ import threading
19
+ import urllib.error
20
+ import urllib.request
21
+ from pathlib import Path
22
+ from typing import Any, Callable
23
+
24
+ from .health import KEY_NAME, PLACEHOLDER, SECRET_NAME, SECRET_PATTERNS
25
+ from .label import LabelError, read_tool
26
+ from .store import _read, _write
27
+
28
+ MASK = "••••"
29
+ MAX_SCRIPT = 150_000
30
+
31
+ PROVIDERS: dict[str, dict[str, Any]] = {
32
+ "gemini": {"name": "Google Gemini", "api": "openai", "base": "https://generativelanguage.googleapis.com/v1beta/openai",
33
+ "keys": "https://aistudio.google.com/apikey",
34
+ "hint": "Free key from Google AI Studio, no card needed. Free use has daily limits, and Google may use "
35
+ "what you send to improve its products."},
36
+ "openrouter": {"name": "OpenRouter", "api": "openai", "base": "https://openrouter.ai/api/v1",
37
+ "keys": "https://openrouter.ai/keys",
38
+ "hint": "One key for the models of many companies. Free models (ending in :free) have low daily "
39
+ "limits; others are paid per use from credit you add."},
40
+ "anthropic": {"name": "Anthropic (Claude)", "api": "anthropic", "base": "https://api.anthropic.com/v1",
41
+ "keys": "https://console.anthropic.com/settings/keys", "hint": "Paid per use from credit you add."},
42
+ "openai": {"name": "OpenAI (ChatGPT)", "api": "openai", "base": "https://api.openai.com/v1",
43
+ "keys": "https://platform.openai.com/api-keys", "hint": "Paid per use from credit you add."},
44
+ }
45
+ CHAT_SITES = {
46
+ "copilot": ("Microsoft Copilot", "https://copilot.microsoft.com/"),
47
+ "gemini": ("Google Gemini", "https://gemini.google.com/app"),
48
+ "aimode": ("Google AI Mode", "https://www.google.com/search?udm=50"),
49
+ "chatgpt": ("ChatGPT", "https://chatgpt.com/"),
50
+ "claude": ("Claude", "https://claude.ai/new"),
51
+ }
52
+ TASKS = {
53
+ "explain": "Explain this script",
54
+ "why": "Why did it fail?",
55
+ "ready": "Make it traPYze-ready",
56
+ "change": "Change it",
57
+ }
58
+ CHANGES_CODE = {"ready", "change", "why"}
59
+
60
+ RULES = """You help someone who is not a programmer with a Python script that runs in traPYze, a desktop
61
+ launcher for Python tools. Answer in plain, friendly English; explain any technical word you use.
62
+
63
+ How a traPYze tool works:
64
+ - The file starts with a PEP 723 block (`# /// script` … `# ///`) listing `requires-python` and all
65
+ `dependencies`, plus a `[tool.trapyze]` section with `name`, `description`, `version`, and one
66
+ `[[tool.trapyze.settings]]` entry per option the user may change (`key`, `label`, `type` = text, int,
67
+ float, bool, choice, date, file or folder, `default`, and `min`/`max`/`options` where they apply).
68
+ - In the code: `import trapyze_helper as tz`; read options with `tz.settings()`; report progress with
69
+ `tz.progress(fraction, "what it's doing in plain words")`; save results with `tz.output_path(name)`;
70
+ shared data files go in `tz.data_path(name)` and are listed as `writes = [...]` in the label.
71
+ - For stock, index, fund, currency or futures prices use `tz.prices(ticker, start=..., interval="1d")`
72
+ (Yahoo tickers; needs `yfinance` and `pandas` under `dependencies`). It returns a pandas table and keeps
73
+ one shared copy for all tools, so only missing bars are downloaded. Don't list it under `writes`.
74
+ - Never use `input()`. Never hard-code paths or keys. Keys come from the vault: list the connection
75
+ name under `connections = [...]` in the label and read it from `os.environ`, or call a web service
76
+ with `tz.api(name, path, params={...})`, which adds the key.
77
+ - Values shown as •••• were masked by traPYze because they are secret. Never invent them; read them
78
+ from the environment instead.
79
+ """
80
+ CODE_RULE = """
81
+ If the script needs to change: first list what you changed in at most five short bullet points, then
82
+ give the COMPLETE new script in one ```python block. Keep everything that already works, keep the label
83
+ valid, and change nothing that wasn't asked for."""
84
+
85
+
86
+ NEW_RULE = """
87
+ Write a new tool as ONE Python file. First say in two or three sentences what it does and what the
88
+ user must set up (for example a key under Connections), then give the COMPLETE script in one
89
+ ```python block. Use only packages that are really needed and list every one under `dependencies`.
90
+ Put a clear `name` and `description` in the label, and choose an `icon` (one of: chart, table, mail,
91
+ cloud, coin, trend, archive, bell, globe, photo, gauge, target, rocket, heart, cube, database) and a
92
+ `color` (one of: blue, teal, purple, orange, rose, slate)."""
93
+
94
+
95
+ def write_prompt() -> str:
96
+ """The text to paste into any AI chat, before describing the tool you want."""
97
+ return (RULES + NEW_RULE).strip() + "\n\nThe tool I want:"
98
+
99
+
100
+ def build_new(description: str) -> dict[str, Any]:
101
+ description = str(description or "").strip()
102
+ if len(description) < 8:
103
+ raise AIError("Describe in a sentence or two what the tool should do.")
104
+ if len(description) > 6000:
105
+ raise AIError("That description is very long. Keep it to the main points.")
106
+ system = RULES + NEW_RULE
107
+ return {"system": system, "user": "The tool I want:\n" + description, "text": write_prompt() + "\n" + description, "masked": 0}
108
+
109
+
110
+ def check_new(code: str, scratch: Path) -> tuple[Any, list[str]]:
111
+ """(the tool as read from its label, or None; plain-English problems) for a script that isn't saved yet."""
112
+ problems = []
113
+ try:
114
+ compile(code, "new_tool.py", "exec")
115
+ except SyntaxError as exc:
116
+ problems.append(f"Python can't read it (line {exc.lineno}: {exc.msg}). Ask the AI to fix that line.")
117
+ scratch.mkdir(parents=True, exist_ok=True)
118
+ tmp = scratch / "new_tool.py"
119
+ tmp.write_text(code, encoding="utf-8")
120
+ tool = None
121
+ try:
122
+ tool = read_tool(tmp)
123
+ except LabelError as exc:
124
+ problems.append(f"Its label has a problem: {exc}")
125
+ except (OSError, ValueError) as exc:
126
+ problems.append(f"Its label couldn't be read: {exc}")
127
+ if "# [tool.trapyze]" not in code:
128
+ problems.append("It has no traPYze label, so it would get no settings window. Ask the AI to add the label.")
129
+ return tool, problems
130
+
131
+
132
+ class AIError(Exception):
133
+ """A plain-English problem with the AI service."""
134
+
135
+
136
+ class AISettings:
137
+ def __init__(self, internal: Path):
138
+ self.path = internal / "ai.json"
139
+
140
+ def get(self) -> dict[str, Any]:
141
+ data = {"chat_site": "copilot", "provider": "", "model": "", "connection": ""}
142
+ stored = _read(self.path, {})
143
+ if isinstance(stored, dict):
144
+ data.update({k: v for k, v in stored.items() if k in data})
145
+ return data
146
+
147
+ def update(self, **changes: Any) -> dict[str, Any]:
148
+ data = self.get()
149
+ if "chat_site" in changes and changes["chat_site"] not in CHAT_SITES:
150
+ raise AIError("Unknown chat site.")
151
+ if changes.get("provider") and changes["provider"] not in PROVIDERS:
152
+ raise AIError("Unknown AI service.")
153
+ data.update({k: str(v or "") for k, v in changes.items() if k in data})
154
+ _write(self.path, data)
155
+ return data
156
+
157
+
158
+ # Masking ----------------------------------------------------------------------
159
+ def mask(text: str, secrets: list[str]) -> tuple[str, int]:
160
+ """Text with vault values and anything that looks like a key replaced by ••••."""
161
+ count = 0
162
+ for value in sorted({s for s in secrets if s and len(s) >= 4}, key=len, reverse=True):
163
+ if value in text:
164
+ count += text.count(value)
165
+ text = text.replace(value, MASK)
166
+ for rx, _ in SECRET_PATTERNS:
167
+ text, n = rx.subn(MASK, text)
168
+ count += n
169
+
170
+ def hide(m: re.Match) -> str:
171
+ nonlocal count
172
+ if PLACEHOLDER.match(m.group(3)) or m.group(3) == MASK:
173
+ return m.group(0)
174
+ count += 1
175
+ return m.group(0).replace(m.group(3), MASK)
176
+ for rx in (SECRET_NAME, KEY_NAME):
177
+ text = rx.sub(hide, text)
178
+ return text, count
179
+
180
+
181
+ # Prompts ----------------------------------------------------------------------
182
+ def build(task: str, tool: Any, source: str, request: str = "", run: dict[str, Any] | None = None,
183
+ log: str = "", secrets: list[str] | None = None) -> dict[str, Any]:
184
+ """The question for the AI: {"system", "user", "text" (both together, for pasting), "masked"}."""
185
+ if task not in TASKS:
186
+ raise AIError("Unknown kind of help.")
187
+ if len(source) > MAX_SCRIPT:
188
+ raise AIError("This script is too long to send in one go.")
189
+ script, masked = mask(source, secrets or [])
190
+ parts = [f"Tool: {tool.name} ({tool.path.name})"]
191
+ if task == "explain":
192
+ ask = ("Explain what this script does, step by step: what it needs (settings, data files, connections, "
193
+ "packages), what it produces, and anything risky or surprising. Don't change the code.")
194
+ elif task == "why":
195
+ if not run:
196
+ raise AIError("Pick a run that went wrong first.")
197
+ log_text, n = mask(log or "", secrets or [])
198
+ settings_text, m = mask(json.dumps(run.get("settings", {}), indent=1), secrets or [])
199
+ masked += n + m
200
+ parts.append(f"The run of {run.get('started', '?')} ended with status '{run.get('status')}'"
201
+ + (f" (exit code {run.get('exit_code')})" if run.get("exit_code") is not None else "") + ".")
202
+ if run.get("cause"):
203
+ parts.append(f"traPYze's own explanation: {run['cause']} {run.get('action', '')}".strip())
204
+ parts.append(f"Settings used:\n{settings_text}")
205
+ parts.append(f"The last lines of its log:\n```\n{log_text[-12000:]}\n```")
206
+ ask = ("Explain in plain words why it failed and what to do about it. If it is something outside the "
207
+ "script (a missing file, a key, the internet), say what to do in traPYze or on the computer.")
208
+ elif task == "ready":
209
+ ask = ("Make this script a proper traPYze tool. Add or complete the label at the top: name, description, "
210
+ "dependencies for every package it imports, and a setting for every value a user would want to "
211
+ "change. Replace input() and hard-coded options with tz.settings(), and add tz.progress() at the "
212
+ "main steps. Keep the calculations exactly as they are.")
213
+ else:
214
+ request = " ".join(str(request or "").split())
215
+ if not request:
216
+ raise AIError("Say what should change.")
217
+ ask = f"Change the script as follows: {request}"
218
+ user = "\n\n".join([ask, *parts, f"The script:\n```python\n{script}\n```"])
219
+ system = RULES + (CODE_RULE if task in CHANGES_CODE else "\nDon't rewrite the script; just explain.")
220
+ text = f"{system.strip()}\n\n---\n\n{user}"
221
+ return {"system": system, "user": user, "text": text, "masked": masked}
222
+
223
+
224
+ # Answers ----------------------------------------------------------------------
225
+ FENCE = re.compile(r"```(?:python|py)?[ \t]*\r?\n(.*?)```", re.S)
226
+
227
+
228
+ def extract_code(answer: str) -> str | None:
229
+ blocks = [b for b in FENCE.findall(answer or "") if b.strip()]
230
+ if not blocks:
231
+ return None
232
+ code = max(blocks, key=len)
233
+ return code if code.endswith("\n") else code + "\n"
234
+
235
+
236
+ def check_proposal(code: str, tool: Any, scratch: Path) -> list[str]:
237
+ """Plain-English problems with a proposed script; empty when it's fine to use."""
238
+ problems = []
239
+ try:
240
+ compile(code, tool.path.name, "exec")
241
+ except SyntaxError as exc:
242
+ problems.append(f"Python can't read it (line {exc.lineno}: {exc.msg}). Ask again, or fix it after saving.")
243
+ scratch.mkdir(parents=True, exist_ok=True)
244
+ tmp = scratch / tool.path.name
245
+ tmp.write_text(code, encoding="utf-8")
246
+ try:
247
+ read_tool(tmp)
248
+ except LabelError as exc:
249
+ problems.append(f"Its label has a problem: {exc}")
250
+ except (OSError, ValueError) as exc:
251
+ problems.append(f"Its label couldn't be read: {exc}")
252
+ finally:
253
+ tmp.unlink(missing_ok=True)
254
+ if MASK in code:
255
+ problems.append("It has •••• where a secret was. Move that key to the vault first (the health check shows "
256
+ "where), or put the real value back yourself after saving.")
257
+ return problems
258
+
259
+
260
+ # Calling a service -----------------------------------------------------------
261
+ def _request(url: str, headers: dict[str, str], body: dict | None, timeout: float, opener: Callable | None = None) -> dict:
262
+ data = json.dumps(body).encode() if body is not None else None
263
+ req = urllib.request.Request(url, data=data, headers={"Content-Type": "application/json", "User-Agent": "traPYze", **headers},
264
+ method="POST" if body is not None else "GET")
265
+ try:
266
+ with (opener or urllib.request.urlopen)(req, timeout=timeout) as resp:
267
+ return json.loads(resp.read().decode("utf-8"))
268
+ except urllib.error.HTTPError as exc:
269
+ detail = ""
270
+ try:
271
+ payload = json.loads(exc.read().decode("utf-8", "replace"))
272
+ err = payload.get("error", payload)
273
+ detail = (err.get("message") if isinstance(err, dict) else str(err)) or ""
274
+ except (ValueError, AttributeError):
275
+ pass
276
+ raise AIError(_plain(exc.code, detail)) from None
277
+ except urllib.error.URLError as exc:
278
+ raise AIError(f"Couldn't reach the AI service ({exc.reason}). Check the internet connection.") from None
279
+ except TimeoutError:
280
+ raise AIError("The AI service took too long to answer. Try again, or pick a faster model.") from None
281
+
282
+
283
+ def _plain(status: int, detail: str) -> str:
284
+ short = detail[:240]
285
+ if status in (401, 403):
286
+ return f"The AI service refused the key. Check it, or make a new one. ({short})"
287
+ if status == 402:
288
+ return "The AI service wants credit on the account before it answers."
289
+ if status == 404:
290
+ return f"The AI service doesn't know that model. Pick another one under Look and feel, AI help. ({short})"
291
+ if status == 429:
292
+ return "The limit for now is reached (free use has limits per minute and per day). Try again later, or pick another model."
293
+ if status >= 500:
294
+ return "The AI service has a problem on its side. Try again in a minute."
295
+ return f"The AI service said no ({status}): {short}"
296
+
297
+
298
+ def _headers(provider: str, key: str) -> dict[str, str]:
299
+ if PROVIDERS[provider]["api"] == "anthropic":
300
+ return {"x-api-key": key, "anthropic-version": "2023-06-01"}
301
+ headers = {"Authorization": f"Bearer {key}"}
302
+ if provider == "openrouter":
303
+ headers.update({"HTTP-Referer": "https://github.com/trapyze/trapyze", "X-Title": "traPYze"})
304
+ return headers
305
+
306
+
307
+ def models(provider: str, key: str, opener: Callable | None = None) -> list[str]:
308
+ data = _request(PROVIDERS[provider]["base"] + "/models", _headers(provider, key), None, 30, opener)
309
+ ids = [str(m.get("id", "")).removeprefix("models/") for m in data.get("data", []) if m.get("id")]
310
+ skip = re.compile(r"embed|tts|audio|image|vision-only|whisper|dall|moderation|realtime|transcribe|search|veo|imagen|live", re.I)
311
+ return sorted({i for i in ids if not skip.search(i)})
312
+
313
+
314
+ def _version(model_id: str) -> tuple:
315
+ return tuple(int(n) for n in re.findall(r"\d+", model_id)[:3])
316
+
317
+
318
+ def pick_model(provider: str, ids: list[str]) -> str:
319
+ """A sensible default from the provider's current list (names change too often to fix them here)."""
320
+ if not ids:
321
+ return ""
322
+ if provider == "openrouter":
323
+ return "openrouter/free" if "openrouter/free" in ids else next((i for i in ids if i.endswith(":free")), ids[0])
324
+ if provider == "gemini":
325
+ flash = [i for i in ids if "flash" in i and not re.search(r"lite|preview|exp|thinking", i)] or [i for i in ids if "flash" in i]
326
+ return max(flash or ids, key=lambda i: (_version(i), "latest" not in i))
327
+ if provider == "anthropic":
328
+ sonnet = [i for i in ids if "sonnet" in i] or ids
329
+ return max(sonnet, key=_version)
330
+ if "chat-latest" in ids:
331
+ return "chat-latest"
332
+ gpt = [i for i in ids if i.startswith("gpt-") and not re.search(r"nano|instruct|-0\d{3}|preview", i)] or ids
333
+ return max(gpt, key=lambda i: (_version(i), "mini" not in i))
334
+
335
+
336
+ def ask(provider: str, key: str, model: str, system: str, user: str, timeout: float = 180,
337
+ opener: Callable | None = None) -> str:
338
+ if provider not in PROVIDERS:
339
+ raise AIError("Choose an AI service first, under Look and feel, AI help.")
340
+ if not model:
341
+ raise AIError("Choose a model first, under Look and feel, AI help.")
342
+ p = PROVIDERS[provider]
343
+ if p["api"] == "anthropic":
344
+ data = _request(p["base"] + "/messages", _headers(provider, key),
345
+ {"model": model, "max_tokens": 16000, "system": system, "messages": [{"role": "user", "content": user}]},
346
+ timeout, opener)
347
+ text = "".join(part.get("text", "") for part in data.get("content", []) if part.get("type") == "text")
348
+ else:
349
+ data = _request(p["base"] + "/chat/completions", _headers(provider, key),
350
+ {"model": model, "messages": [{"role": "system", "content": system}, {"role": "user", "content": user}]},
351
+ timeout, opener)
352
+ try:
353
+ text = data["choices"][0]["message"]["content"] or ""
354
+ except (KeyError, IndexError, TypeError):
355
+ raise AIError("The AI service sent an answer traPYze couldn't read.") from None
356
+ if not text.strip():
357
+ raise AIError("The AI service sent an empty answer. Try again, or pick another model.")
358
+ return text
359
+
360
+
361
+ _busy = threading.Semaphore(2) # at most two questions at once
trapyze/apis.py ADDED
@@ -0,0 +1,162 @@
1
+ """Web-service settings for the shared API gateway (tz.api in the helper).
2
+
3
+ A connection can carry an "api" block: where the service lives, where the key
4
+ goes and the shared limits. The limits below are the free plans' as published
5
+ in November 2026; people on a paid plan change them under Connections.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import importlib.util
11
+ import re
12
+ import sys
13
+ from importlib import resources
14
+ from pathlib import Path
15
+ from types import ModuleType
16
+ from typing import Any
17
+
18
+ from .vault import VaultError
19
+
20
+ PRESETS: dict[str, dict[str, Any]] = {
21
+ "fmp": {
22
+ "label": "Financial Modeling Prep", "base": "https://financialmodelingprep.com/stable",
23
+ "key_in": "query", "key_name": "apikey", "per_minute": 0, "per_day": 250, "cache_minutes": 60,
24
+ "test": "quote?symbol=AAPL", "example": 'tz.api("{name}", "quote", params={{"symbol": "AAPL"}})',
25
+ "note": "Free plan: 250 calls a day. Paid plans: no daily limit, 300 or more a minute.",
26
+ },
27
+ "alphavantage": {
28
+ "label": "Alpha Vantage", "base": "https://www.alphavantage.co",
29
+ "key_in": "query", "key_name": "apikey", "per_minute": 5, "per_day": 25, "cache_minutes": 60,
30
+ "error_keys": ["Error Message", "Information", "Note"],
31
+ "test": "query?function=GLOBAL_QUOTE&symbol=IBM",
32
+ "example": 'tz.api("{name}", "query", params={{"function": "GLOBAL_QUOTE", "symbol": "IBM"}})',
33
+ "note": "Free plan: 25 calls a day, 5 a minute. Paid plans: no daily limit.",
34
+ },
35
+ "twelvedata": {
36
+ "label": "Twelve Data", "base": "https://api.twelvedata.com",
37
+ "key_in": "query", "key_name": "apikey", "per_minute": 8, "per_day": 800, "cache_minutes": 15,
38
+ "error_match": {"status": "error"}, "test": "quote?symbol=AAPL",
39
+ "example": 'tz.api("{name}", "quote", params={{"symbol": "AAPL"}})',
40
+ "note": "Free plan: 8 credits a minute, 800 a day. Some requests cost more than one credit: pass cost=.",
41
+ },
42
+ "finnhub": {
43
+ "label": "Finnhub", "base": "https://finnhub.io/api/v1",
44
+ "key_in": "header", "key_name": "X-Finnhub-Token", "per_minute": 60, "per_day": 0, "cache_minutes": 5,
45
+ "test": "quote?symbol=AAPL", "example": 'tz.api("{name}", "quote", params={{"symbol": "AAPL"}})',
46
+ "note": "Free plan: 60 calls a minute.",
47
+ },
48
+ "eodhd": {
49
+ "label": "EODHD", "base": "https://eodhd.com/api",
50
+ "key_in": "query", "key_name": "api_token", "per_minute": 1000, "per_day": 20, "cache_minutes": 60,
51
+ "headers": {}, "test": "user?fmt=json",
52
+ "example": 'tz.api("{name}", "eod/AAPL.US", params={{"fmt": "json"}})',
53
+ "note": "Free plan: 20 calls a day. Paid plans: 100,000 a day. The test uses the free account check.",
54
+ },
55
+ "massive": {
56
+ "label": "Massive (formerly Polygon.io)", "base": "https://api.polygon.io",
57
+ "key_in": "query", "key_name": "apiKey", "per_minute": 5, "per_day": 0, "cache_minutes": 60,
58
+ "test": "v2/aggs/ticker/AAPL/prev", "example": 'tz.api("{name}", "v2/aggs/ticker/AAPL/prev")',
59
+ "note": "Free plan: 5 calls a minute. Paid plans: no limit (set 0).",
60
+ },
61
+ "tiingo": {
62
+ "label": "Tiingo", "base": "https://api.tiingo.com",
63
+ "key_in": "query", "key_name": "token", "per_minute": 1, "per_day": 900, "cache_minutes": 60,
64
+ "test": "api/test", "example": 'tz.api("{name}", "tiingo/daily/aapl/prices", params={{"startDate": "2024-01-02"}})',
65
+ "note": "Free plan: about 50 calls an hour and 1,000 a day, so one a minute keeps every tool safe.",
66
+ },
67
+ "hfdata": {
68
+ "label": "HF Data Library", "base": "https://api.hfdatalibrary.com/v1",
69
+ "key_in": "header", "key_name": "X-API-Key", "per_minute": 100, "per_day": 0, "cache_minutes": 0,
70
+ "test": "symbols", "example": 'tz.api("{name}", "bars/AAPL", params={{"version": "clean"}})',
71
+ "renew_days": 30,
72
+ "note": "Free key, 100 downloads a minute. The key expires every 30 days: traPYze reminds you 5 days before.",
73
+ },
74
+ "github": {
75
+ "label": "GitHub", "base": "https://api.github.com",
76
+ "key_in": "header", "key_name": "Authorization", "key_prefix": "Bearer ", "per_minute": 60, "per_day": 0,
77
+ "cache_minutes": 0, "test": "rate_limit", "example": 'tz.api("{name}", "repos/you/repo/contents/README.md")',
78
+ "note": "Use a fine-grained token for only the repository it needs, with only the permissions it needs.",
79
+ },
80
+ "other": {
81
+ "label": "Another service", "base": "", "key_in": "query", "key_name": "apikey",
82
+ "per_minute": 0, "per_day": 0, "cache_minutes": 15, "test": "",
83
+ "example": 'tz.api("{name}", "path/from/their/docs", params={{...}})',
84
+ "note": "Look in the service's documentation for its address and where the key goes.",
85
+ },
86
+ }
87
+
88
+ _NAME = re.compile(r"^[A-Za-z0-9_.-]{1,64}$")
89
+ _LOCAL = re.compile(r"^http://(127\.0\.0\.1|localhost)(:\d+)?(/|$)")
90
+ FIELDS = ("preset", "base", "key_in", "key_name", "key_prefix", "key_var", "per_minute", "per_day",
91
+ "cache_minutes", "error_keys", "error_match", "headers", "test")
92
+
93
+
94
+ def check_api(api: dict[str, Any] | None, variables: list[str]) -> dict[str, Any] | None:
95
+ """Validate an api block from the Connections screen. Returns the cleaned block."""
96
+ if not api:
97
+ return None
98
+ preset = str(api.get("preset") or "other")
99
+ if preset not in PRESETS:
100
+ raise VaultError("Unknown kind of web service.")
101
+ base = PRESETS[preset]
102
+ out: dict[str, Any] = {"preset": preset}
103
+ url = str(api.get("base", base["base"]) or "").strip().rstrip("/")
104
+ if not (url.startswith("https://") or _LOCAL.match(url)) or " " in url:
105
+ raise VaultError("The web address must start with https://, for example https://api.example.com/v1.")
106
+ out["base"] = url
107
+ key_in = str(api.get("key_in", base["key_in"]))
108
+ if key_in not in ("query", "header", "none"):
109
+ raise VaultError("Choose where the key goes: in the address, in a header, or not needed.")
110
+ out["key_in"] = key_in
111
+ if key_in != "none":
112
+ key_name = str(api.get("key_name", base["key_name"]) or "").strip()
113
+ if not _NAME.match(key_name):
114
+ raise VaultError("The key's name (for example apikey or X-Api-Key) uses letters, digits, - and _.")
115
+ out["key_name"] = key_name
116
+ out["key_prefix"] = str(api.get("key_prefix", base.get("key_prefix", "")) or "")[:20]
117
+ key_var = str(api.get("key_var") or "")
118
+ if key_var not in variables:
119
+ raise VaultError("Choose which of this connection's values is the key.")
120
+ out["key_var"] = key_var
121
+ for field, label in (("per_minute", "calls a minute"), ("per_day", "calls a day"), ("cache_minutes", "minutes to keep answers")):
122
+ try:
123
+ value = int(api.get(field, base[field]) or 0)
124
+ except (TypeError, ValueError):
125
+ raise VaultError(f"Use a whole number for {label} (0 means no limit).") from None
126
+ if value < 0 or value > 10_000_000:
127
+ raise VaultError(f"Use a number from 0 up for {label}.")
128
+ out[field] = value
129
+ if out["cache_minutes"] > 7 * 24 * 60:
130
+ raise VaultError("Keep answers for at most a week (10080 minutes).")
131
+ for field in ("error_keys", "error_match", "headers"):
132
+ if field in base:
133
+ out[field] = base[field]
134
+ out["test"] = str(api.get("test", base.get("test", "")) or "")[:300]
135
+ return out
136
+
137
+
138
+ def run_config(api: dict[str, Any]) -> dict[str, Any]:
139
+ """What a run gets in TRAPYZE_API_<NAME>: no secrets, only where to send and the limits."""
140
+ return {k: api[k] for k in FIELDS if k in api and k != "test"}
141
+
142
+
143
+ def env_name(connection: str) -> str:
144
+ return "TRAPYZE_API_" + re.sub(r"[^A-Z0-9]", "_", connection.upper())
145
+
146
+
147
+ _helper: ModuleType | None = None
148
+
149
+
150
+ def helper() -> ModuleType:
151
+ """The packaged trapyze_helper, so traPYze and the tools share one gateway."""
152
+ global _helper
153
+ if _helper is None:
154
+ source = resources.files("trapyze") / "resources" / "helper" / "trapyze_helper.py"
155
+ with resources.as_file(source) as path:
156
+ spec = importlib.util.spec_from_file_location("trapyze._gateway", Path(path))
157
+ assert spec and spec.loader
158
+ module = importlib.util.module_from_spec(spec)
159
+ sys.modules["trapyze._gateway"] = module
160
+ spec.loader.exec_module(module)
161
+ _helper = module
162
+ return _helper