trapyze 0.17.4__tar.gz

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 (89) hide show
  1. trapyze-0.17.4/LICENSE +21 -0
  2. trapyze-0.17.4/PKG-INFO +329 -0
  3. trapyze-0.17.4/README.md +289 -0
  4. trapyze-0.17.4/pyproject.toml +57 -0
  5. trapyze-0.17.4/setup.cfg +4 -0
  6. trapyze-0.17.4/src/trapyze/__init__.py +21 -0
  7. trapyze-0.17.4/src/trapyze/__main__.py +5 -0
  8. trapyze-0.17.4/src/trapyze/ai.py +361 -0
  9. trapyze-0.17.4/src/trapyze/apis.py +162 -0
  10. trapyze-0.17.4/src/trapyze/cli.py +506 -0
  11. trapyze-0.17.4/src/trapyze/desktop.py +516 -0
  12. trapyze-0.17.4/src/trapyze/editors.py +105 -0
  13. trapyze-0.17.4/src/trapyze/explain.py +84 -0
  14. trapyze-0.17.4/src/trapyze/freshness.py +104 -0
  15. trapyze-0.17.4/src/trapyze/health.py +180 -0
  16. trapyze-0.17.4/src/trapyze/home.py +210 -0
  17. trapyze-0.17.4/src/trapyze/importer.py +1094 -0
  18. trapyze-0.17.4/src/trapyze/label.py +402 -0
  19. trapyze-0.17.4/src/trapyze/layout.py +363 -0
  20. trapyze-0.17.4/src/trapyze/locks.py +101 -0
  21. trapyze-0.17.4/src/trapyze/packages.py +309 -0
  22. trapyze-0.17.4/src/trapyze/packs.py +92 -0
  23. trapyze-0.17.4/src/trapyze/project.py +13 -0
  24. trapyze-0.17.4/src/trapyze/resources/examples/demo_price_data.py +71 -0
  25. trapyze-0.17.4/src/trapyze/resources/examples/price_report.py +75 -0
  26. trapyze-0.17.4/src/trapyze/resources/examples/say_hello.py +53 -0
  27. trapyze-0.17.4/src/trapyze/resources/helper/trapyze_helper.py +741 -0
  28. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/backup_folder.py +80 -0
  29. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/biggest_files.py +69 -0
  30. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/find_duplicates.py +76 -0
  31. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/rename_files.py +93 -0
  32. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/restore_backup.py +68 -0
  33. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/set_duplicates_aside.py +105 -0
  34. trapyze-0.17.4/src/trapyze/resources/packs/everyday_files/tidy_folder.py +91 -0
  35. trapyze-0.17.4/src/trapyze/resources/packs/home_finance/bank_csv.py +123 -0
  36. trapyze-0.17.4/src/trapyze/resources/packs/home_finance/bank_overview.py +173 -0
  37. trapyze-0.17.4/src/trapyze/resources/packs/home_finance/find_subscriptions.py +87 -0
  38. trapyze-0.17.4/src/trapyze/resources/packs/tables_and_data/check_download.py +100 -0
  39. trapyze-0.17.4/src/trapyze/resources/packs/tables_and_data/csv_to_database.py +118 -0
  40. trapyze-0.17.4/src/trapyze/resources/packs/tables_and_data/export_table.py +76 -0
  41. trapyze-0.17.4/src/trapyze/resources/packs/tables_and_data/merge_csv.py +95 -0
  42. trapyze-0.17.4/src/trapyze/resources/templates/analyse.py +68 -0
  43. trapyze-0.17.4/src/trapyze/resources/templates/app.py +41 -0
  44. trapyze-0.17.4/src/trapyze/resources/templates/collect.py +53 -0
  45. trapyze-0.17.4/src/trapyze/resources/templates/maintain.py +62 -0
  46. trapyze-0.17.4/src/trapyze/resources/templates/share.py +67 -0
  47. trapyze-0.17.4/src/trapyze/review.py +88 -0
  48. trapyze-0.17.4/src/trapyze/runner.py +415 -0
  49. trapyze-0.17.4/src/trapyze/schedule.py +810 -0
  50. trapyze-0.17.4/src/trapyze/share.py +138 -0
  51. trapyze-0.17.4/src/trapyze/store.py +419 -0
  52. trapyze-0.17.4/src/trapyze/templates.py +38 -0
  53. trapyze-0.17.4/src/trapyze/updater.py +284 -0
  54. trapyze-0.17.4/src/trapyze/vault.py +570 -0
  55. trapyze-0.17.4/src/trapyze/versions.py +104 -0
  56. trapyze-0.17.4/src/trapyze/web/__init__.py +0 -0
  57. trapyze-0.17.4/src/trapyze/web/server.py +1738 -0
  58. trapyze-0.17.4/src/trapyze/web/static/app.css +598 -0
  59. trapyze-0.17.4/src/trapyze/web/static/app.js +3058 -0
  60. trapyze-0.17.4/src/trapyze/web/static/favicon.png +0 -0
  61. trapyze-0.17.4/src/trapyze/web/static/favicon.svg +1 -0
  62. trapyze-0.17.4/src/trapyze/web/static/icon.ico +0 -0
  63. trapyze-0.17.4/src/trapyze/web/static/icon.png +0 -0
  64. trapyze-0.17.4/src/trapyze/web/static/index.html +36 -0
  65. trapyze-0.17.4/src/trapyze.egg-info/PKG-INFO +329 -0
  66. trapyze-0.17.4/src/trapyze.egg-info/SOURCES.txt +87 -0
  67. trapyze-0.17.4/src/trapyze.egg-info/dependency_links.txt +1 -0
  68. trapyze-0.17.4/src/trapyze.egg-info/entry_points.txt +5 -0
  69. trapyze-0.17.4/src/trapyze.egg-info/requires.txt +6 -0
  70. trapyze-0.17.4/src/trapyze.egg-info/top_level.txt +1 -0
  71. trapyze-0.17.4/tests/test_ai.py +186 -0
  72. trapyze-0.17.4/tests/test_comfort.py +182 -0
  73. trapyze-0.17.4/tests/test_desktop.py +334 -0
  74. trapyze-0.17.4/tests/test_gateway.py +283 -0
  75. trapyze-0.17.4/tests/test_import.py +323 -0
  76. trapyze-0.17.4/tests/test_layout.py +151 -0
  77. trapyze-0.17.4/tests/test_packages.py +128 -0
  78. trapyze-0.17.4/tests/test_packs.py +271 -0
  79. trapyze-0.17.4/tests/test_prices.py +181 -0
  80. trapyze-0.17.4/tests/test_release.py +257 -0
  81. trapyze-0.17.4/tests/test_renewals.py +87 -0
  82. trapyze-0.17.4/tests/test_review.py +171 -0
  83. trapyze-0.17.4/tests/test_schedule.py +258 -0
  84. trapyze-0.17.4/tests/test_share.py +134 -0
  85. trapyze-0.17.4/tests/test_site.py +35 -0
  86. trapyze-0.17.4/tests/test_suite.py +205 -0
  87. trapyze-0.17.4/tests/test_trapyze.py +448 -0
  88. trapyze-0.17.4/tests/test_vault.py +167 -0
  89. trapyze-0.17.4/tests/test_web.py +198 -0
trapyze-0.17.4/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kapistyn and the traPYze contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,329 @@
1
+ Metadata-Version: 2.4
2
+ Name: trapyze
3
+ Version: 0.17.4
4
+ Summary: Run your Python tools without the technical bits.
5
+ Author: traPYze contributors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://kapistyn.github.io/trapyze/
8
+ Project-URL: Guide, https://kapistyn.github.io/trapyze/guide.html
9
+ Project-URL: Download, https://github.com/Kapistyn/trapyze/releases/latest
10
+ Project-URL: Source, https://github.com/Kapistyn/trapyze
11
+ Project-URL: Issues, https://github.com/Kapistyn/trapyze/issues
12
+ Project-URL: Changelog, https://kapistyn.github.io/trapyze/changelog.html
13
+ Keywords: python scripts,script launcher,scheduler,desktop,no-code,automation,pep 723,uv
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Web Environment
16
+ Classifier: Environment :: Win32 (MS Windows)
17
+ Classifier: Environment :: MacOS X
18
+ Classifier: Intended Audience :: End Users/Desktop
19
+ Classifier: Intended Audience :: Financial and Insurance Industry
20
+ Classifier: Intended Audience :: Science/Research
21
+ Classifier: Operating System :: Microsoft :: Windows
22
+ Classifier: Operating System :: MacOS
23
+ Classifier: Operating System :: POSIX :: Linux
24
+ Classifier: Programming Language :: Python :: 3
25
+ Classifier: Programming Language :: Python :: 3.11
26
+ Classifier: Programming Language :: Python :: 3.12
27
+ Classifier: Programming Language :: Python :: 3.13
28
+ Classifier: Topic :: Desktop Environment
29
+ Classifier: Topic :: Office/Business
30
+ Classifier: Topic :: Utilities
31
+ Requires-Python: >=3.11
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ Requires-Dist: cryptography>=42
35
+ Provides-Extra: desktop
36
+ Requires-Dist: pywebview>=5; extra == "desktop"
37
+ Requires-Dist: pystray>=0.19; extra == "desktop"
38
+ Requires-Dist: Pillow>=10; extra == "desktop"
39
+ Dynamic: license-file
40
+
41
+ <p align="center">
42
+ <img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/logo.png" width="88" alt="">
43
+ </p>
44
+
45
+ <h1 align="center">traPYze</h1>
46
+
47
+ <p align="center">
48
+ <b>Run your Python tools without the technical bits.</b><br>
49
+ A friendly desktop for the scripts you, a colleague or an AI wrote:
50
+ tiles, settings windows, schedules and a vault. No terminal needed.
51
+ </p>
52
+
53
+ <p align="center">
54
+ <a href="https://github.com/kapistyn/trapyze/releases/latest"><img src="https://img.shields.io/github/v/release/kapistyn/trapyze?label=download&color=2a4bd7" alt="Newest version"></a>
55
+ <a href="https://github.com/kapistyn/trapyze/actions/workflows/tests.yml"><img src="https://github.com/kapistyn/trapyze/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
56
+ <img src="https://img.shields.io/badge/Windows%20%C2%B7%20macOS%20%C2%B7%20Linux-supported-1d9a8c" alt="Windows, macOS and Linux">
57
+ <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="Python 3.11 or newer">
58
+ <a href="https://github.com/Kapistyn/trapyze/blob/v0.17.4/LICENSE"><img src="https://img.shields.io/github/license/kapistyn/trapyze?color=555" alt="MIT licence"></a>
59
+ </p>
60
+
61
+ <p align="center">
62
+ <a href="#install"><b>Install</b></a> ·
63
+ <a href="#a-quick-tour">Tour</a> ·
64
+ <a href="#make-your-own-tool">Make a tool</a> ·
65
+ <a href="https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md">Full guide</a> ·
66
+ <a href="#questions">Questions</a>
67
+ </p>
68
+
69
+ <p align="center">
70
+ <img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/desktop.png" alt="The traPYze desktop: tools on shelves, a Today strip, favourites and a tool running" width="900">
71
+ </p>
72
+
73
+ ## Why traPYze?
74
+
75
+ Python is the easiest way to automate the boring parts of life: fetch prices, tidy
76
+ a folder, turn a bank export into a summary, mail yourself a report. AI chats
77
+ write such scripts in seconds. **Running them is the hard part:** a terminal,
78
+ packages that must be installed, settings changed inside the code, passwords
79
+ typed into the script, and scheduled runs that need cron or Task Scheduler.
80
+
81
+ traPYze takes all of that away.
82
+
83
+ | Without traPYze | With traPYze |
84
+ |---|---|
85
+ | Open a terminal, find the folder, type the command | Click a tile |
86
+ | Change values inside the code before each run | A settings window, made from the script's own label |
87
+ | `pip install` and broken environments | Each tool gets exactly the packages it needs, invisibly, pinned and tested |
88
+ | API keys and passwords typed into the script | A PIN-protected vault; tools get only the keys you allowed |
89
+ | Cron or Task Scheduler for daily runs | Plans like "every weekday at 07:30", also while you're logged out |
90
+ | Results scattered over folders | Every run with its files, settings and log, newest first |
91
+ | "What does this script do? Why did it fail?" | A health check, and Ask AI with any chat site |
92
+
93
+ **Who it's for:** anyone with a few useful scripts and no wish to babysit them:
94
+ hobbyists, analysts and traders, small businesses, teachers, researchers, and
95
+ everyone who got a script from ChatGPT, Copilot, Gemini or Claude.
96
+
97
+ <p align="center">
98
+ <img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/run-a-tool.gif" alt="Running a tool: open its tile, press Run, watch the progress, open the result" width="800">
99
+ </p>
100
+
101
+ ## Install
102
+
103
+ **Windows:** download **[traPYze-Setup.exe](https://github.com/kapistyn/trapyze/releases/latest/download/traPYze-Setup.exe)** and open it. Or paste this into PowerShell:
104
+
105
+ ```powershell
106
+ irm https://github.com/kapistyn/trapyze/releases/latest/download/install.ps1 | iex
107
+ ```
108
+
109
+ **macOS and Linux:** paste this into a terminal:
110
+
111
+ ```sh
112
+ curl -LsSf https://github.com/kapistyn/trapyze/releases/latest/download/install.sh | sh
113
+ ```
114
+
115
+ **Already use [uv](https://docs.astral.sh/uv/)?** traPYze is also [on PyPI](https://pypi.org/project/trapyze/):
116
+
117
+ ```sh
118
+ uv tool install "trapyze[desktop]"
119
+ trapyze shortcut
120
+ ```
121
+
122
+ You don't need Python: the installer adds [uv](https://docs.astral.sh/uv/), which
123
+ fetches and runs Python for traPYze. No administrator needed. traPYze opens when
124
+ it's done, with three example tools, and adds a shortcut to your desktop, Start
125
+ menu or Applications. It updates itself: when there's a new version, it says so
126
+ and installs it with one click.
127
+
128
+ ## A quick tour
129
+
130
+ ### Tools on shelves, sorted for you
131
+ Tools sit on shelves by what they do: **Collect**, **Analyse**, **Share**,
132
+ **Maintain** and **Apps**. traPYze sorts them itself from what each script does;
133
+ drag them anywhere you like after that. Star your daily tools, filter by topic,
134
+ and see at a glance what's running, what's next and what needs a look.
135
+ Prefer a table? Switch to the List view.
136
+
137
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/list.png" width="820" alt="The List view"></p>
138
+
139
+ ### A settings window for every script, and live progress
140
+ The settings come from a few lines at the top of the script (its *label*), so
141
+ every tool explains itself. Press **Run** and keep working: traPYze shows the
142
+ progress and tells you when it's done.
143
+
144
+ <table>
145
+ <tr>
146
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/settings.png" alt="A tool's settings window"></td>
147
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/progress.png" alt="A tool running, with its progress"></td>
148
+ </tr>
149
+ </table>
150
+
151
+ ### Everything it made, in one place
152
+ Every run with its files, the settings it used and its log, newest first.
153
+ "Run again with these settings" is one click; a run that failed says why in
154
+ plain words.
155
+
156
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/outputs.png" width="820" alt="Outputs: every run with its files"></p>
157
+
158
+ ### Plans that run by themselves, and a vault for your keys
159
+ "Every weekday at 07:30", "Sundays at 20:00". Plans use your computer's own
160
+ scheduler, so they run even when traPYze is closed; missed runs catch up.
161
+ Chain tools together: fetch, then analyse, then mail. Keys and logins live
162
+ encrypted behind your PIN and only reach the tools you allowed.
163
+
164
+ <table>
165
+ <tr>
166
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/schedule.png" alt="Plans on the Schedule screen"></td>
167
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/vault.png" alt="Connections in the vault"></td>
168
+ </tr>
169
+ </table>
170
+
171
+ ### Import anything, even a whole program
172
+ Point traPYze at a script, a folder, a .zip or a folder in WSL. It finds the
173
+ main script, turns its command-line options into settings, works out the
174
+ packages it needs, offers `.env` keys to the vault, and keeps the helper
175
+ scripts out of sight. Your original is never changed.
176
+
177
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/import.png" width="820" alt="Importing a program folder"></p>
178
+
179
+ ### A health check, and AI help that shows its work
180
+ The health check reads a script offline: will it start, are packages missing,
181
+ is a key typed into the code, are there risky lines? **Ask AI** explains a
182
+ script, says why a run failed, or changes it, with a free chat site (Copilot,
183
+ Gemini, ChatGPT, Claude) or your own key. Secrets are masked first, and you see
184
+ every change before it's saved.
185
+
186
+ <table>
187
+ <tr>
188
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/health.png" alt="The health check finds a token typed into the code"></td>
189
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/ask-ai.png" alt="Ask AI proposes a fix, shown as changes"></td>
190
+ </tr>
191
+ </table>
192
+
193
+ ### Every change kept, and new tools in a minute
194
+ traPYze keeps a copy each time a script changes, whether by you, your editor or
195
+ an AI, and goes back with one click. **Edit** opens a script in VS Code,
196
+ PyCharm, Notepad++ or whichever editor you use. **New tool** gives you a small
197
+ working script to start from.
198
+
199
+ <table>
200
+ <tr>
201
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/changes.png" alt="Changes: every version, with going back"></td>
202
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/new-tool.png" alt="A new tool from a template"></td>
203
+ </tr>
204
+ </table>
205
+
206
+ ### Light or dark, your colours, its own window
207
+ Its own window with a tray icon (or your browser), light and dark themes,
208
+ accent colours, compact or comfortable, and your own icon per tool.
209
+
210
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/desktop-dark.png" width="820" alt="The desktop in dark"></p>
211
+
212
+ ## Ready-made tools
213
+
214
+ New to Python tools? **Get tools** adds packs that come with traPYze. They work
215
+ without the internet and need nothing installed:
216
+
217
+ | Pack | Tools |
218
+ |---|---|
219
+ | **Everyday files** | Tidy a folder · Find duplicate files · Set duplicates aside · Back up a folder · Restore a backup · Rename files · What takes the space? |
220
+ | **Home finance** | Bank statement overview by category and month · Find subscriptions |
221
+ | **Tables and data** | Check a download · Merge CSV files · CSV into a database · Database table to CSV |
222
+
223
+ Tools that change files show you a list first and never delete or overwrite your
224
+ files; your bank statement never leaves your computer.
225
+
226
+ ## Make your own tool
227
+
228
+ Any Python script works. A few comment lines at the top make it a proper
229
+ traPYze tool with its own settings window:
230
+
231
+ ```python
232
+ # /// script
233
+ # dependencies = ["requests"]
234
+ #
235
+ # [tool.trapyze]
236
+ # name = "Exchange rates"
237
+ # description = "Fetches today's euro exchange rates."
238
+ # icon = "coin"
239
+ #
240
+ # [[tool.trapyze.settings]]
241
+ # key = "currencies"
242
+ # label = "Currencies"
243
+ # type = "text"
244
+ # default = "USD, GBP, JPY"
245
+ # ///
246
+ import requests
247
+ import trapyze_helper as tz
248
+
249
+ s = tz.settings() # what the user chose in the window
250
+ tz.progress(0.5, "Asking the central bank")
251
+ ...
252
+ tz.output_path("rates.csv").write_text(csv_text) # shows up under Outputs
253
+ ```
254
+
255
+ The top block is the standard [PEP 723](https://peps.python.org/pep-0723/)
256
+ format, so the script still runs anywhere else too. Don't want to write it
257
+ yourself? **New tool, Have an AI write it**: describe what you want, and traPYze
258
+ tells the AI how its tools work, so the script arrives ready. The same
259
+ [prompt](https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md#prompt-for-ai-written-tools) works in any AI chat, and
260
+ **Ask AI, Make it traPYze-ready** adds the label to a script you already have.
261
+
262
+ ## How it works
263
+
264
+ ```mermaid
265
+ flowchart LR
266
+ A[Your script<br/>with its label] --> B[traPYze reads<br/>the label]
267
+ B --> C[Settings window]
268
+ C --> D[uv runs it with<br/>exactly its packages]
269
+ V[(Vault)] -. only allowed keys .-> D
270
+ P[Plans] --> D
271
+ D --> E[Progress, results<br/>and history]
272
+ ```
273
+
274
+ - **The engine is [uv](https://docs.astral.sh/uv/)**: each tool runs with its
275
+ own packages, pinned per tool, so tools never break each other.
276
+ - **Everything stays on your computer.** traPYze listens only on 127.0.0.1
277
+ with a fresh key per session. Nothing is sent anywhere unless a tool does
278
+ so, or you use Ask AI; traPYze itself only looks for newer packages and a
279
+ newer traPYze, once a day.
280
+ - **Your scripts stay yours**: plain .py files in your Trapyze folder,
281
+ working with or without traPYze.
282
+
283
+ ## Questions
284
+
285
+ **Is it free?** Yes, free and open source under the MIT licence, with no ads
286
+ and no tracking.
287
+
288
+ **Do I need to know Python?** No, to use tools. A little, to write your own,
289
+ and Ask AI helps with that.
290
+
291
+ **Is it safe?** traPYze keeps your keys encrypted and away from scripts that
292
+ weren't allowed to use them, and a tool you imported or an AI wrote shows what
293
+ it can do before its first run. But a tool is a program that can do anything you
294
+ can: only run tools from people you trust.
295
+ See [SECURITY.md](https://github.com/Kapistyn/trapyze/blob/v0.17.4/SECURITY.md).
296
+
297
+ **Does it work offline?** Yes. Only installing a tool's packages the first
298
+ time, tools that fetch data, Ask AI and the update check need the internet.
299
+
300
+ **Where are my things?** In the `Trapyze` folder in your home folder:
301
+ `scripts`, `outputs` and `data`. Back it up like any other folder.
302
+
303
+ **Can I run a tool from the terminal too?** Yes: `trapyze run "exchange rates"
304
+ --set currencies=USD`. See [the guide](https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md#from-the-terminal).
305
+
306
+ ## Helping
307
+
308
+ traPYze is free and stays free. The best ways to help:
309
+
310
+ - ⭐ **Star the project** on GitHub, so more people find it
311
+ - [Report a problem or share an idea](https://github.com/kapistyn/trapyze/issues)
312
+ - Share a tool you made (see [CONTRIBUTING.md](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CONTRIBUTING.md))
313
+
314
+ ## Documentation
315
+
316
+ - **[The full guide](https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md)**: every screen and option, step by step
317
+ - [Changelog](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CHANGELOG.md) · [Contributing](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CONTRIBUTING.md) · [Security](https://github.com/Kapistyn/trapyze/blob/v0.17.4/SECURITY.md)
318
+
319
+ ## Running the tests
320
+
321
+ ```
322
+ uv run --with pytest --with pandas python -m pytest -q
323
+ ```
324
+
325
+ No internet needed. See [CONTRIBUTING.md](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CONTRIBUTING.md) for more.
326
+
327
+ ## Licence
328
+
329
+ MIT, see LICENSE.
@@ -0,0 +1,289 @@
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/logo.png" width="88" alt="">
3
+ </p>
4
+
5
+ <h1 align="center">traPYze</h1>
6
+
7
+ <p align="center">
8
+ <b>Run your Python tools without the technical bits.</b><br>
9
+ A friendly desktop for the scripts you, a colleague or an AI wrote:
10
+ tiles, settings windows, schedules and a vault. No terminal needed.
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://github.com/kapistyn/trapyze/releases/latest"><img src="https://img.shields.io/github/v/release/kapistyn/trapyze?label=download&color=2a4bd7" alt="Newest version"></a>
15
+ <a href="https://github.com/kapistyn/trapyze/actions/workflows/tests.yml"><img src="https://github.com/kapistyn/trapyze/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
16
+ <img src="https://img.shields.io/badge/Windows%20%C2%B7%20macOS%20%C2%B7%20Linux-supported-1d9a8c" alt="Windows, macOS and Linux">
17
+ <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="Python 3.11 or newer">
18
+ <a href="https://github.com/Kapistyn/trapyze/blob/v0.17.4/LICENSE"><img src="https://img.shields.io/github/license/kapistyn/trapyze?color=555" alt="MIT licence"></a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <a href="#install"><b>Install</b></a> ·
23
+ <a href="#a-quick-tour">Tour</a> ·
24
+ <a href="#make-your-own-tool">Make a tool</a> ·
25
+ <a href="https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md">Full guide</a> ·
26
+ <a href="#questions">Questions</a>
27
+ </p>
28
+
29
+ <p align="center">
30
+ <img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/desktop.png" alt="The traPYze desktop: tools on shelves, a Today strip, favourites and a tool running" width="900">
31
+ </p>
32
+
33
+ ## Why traPYze?
34
+
35
+ Python is the easiest way to automate the boring parts of life: fetch prices, tidy
36
+ a folder, turn a bank export into a summary, mail yourself a report. AI chats
37
+ write such scripts in seconds. **Running them is the hard part:** a terminal,
38
+ packages that must be installed, settings changed inside the code, passwords
39
+ typed into the script, and scheduled runs that need cron or Task Scheduler.
40
+
41
+ traPYze takes all of that away.
42
+
43
+ | Without traPYze | With traPYze |
44
+ |---|---|
45
+ | Open a terminal, find the folder, type the command | Click a tile |
46
+ | Change values inside the code before each run | A settings window, made from the script's own label |
47
+ | `pip install` and broken environments | Each tool gets exactly the packages it needs, invisibly, pinned and tested |
48
+ | API keys and passwords typed into the script | A PIN-protected vault; tools get only the keys you allowed |
49
+ | Cron or Task Scheduler for daily runs | Plans like "every weekday at 07:30", also while you're logged out |
50
+ | Results scattered over folders | Every run with its files, settings and log, newest first |
51
+ | "What does this script do? Why did it fail?" | A health check, and Ask AI with any chat site |
52
+
53
+ **Who it's for:** anyone with a few useful scripts and no wish to babysit them:
54
+ hobbyists, analysts and traders, small businesses, teachers, researchers, and
55
+ everyone who got a script from ChatGPT, Copilot, Gemini or Claude.
56
+
57
+ <p align="center">
58
+ <img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/run-a-tool.gif" alt="Running a tool: open its tile, press Run, watch the progress, open the result" width="800">
59
+ </p>
60
+
61
+ ## Install
62
+
63
+ **Windows:** download **[traPYze-Setup.exe](https://github.com/kapistyn/trapyze/releases/latest/download/traPYze-Setup.exe)** and open it. Or paste this into PowerShell:
64
+
65
+ ```powershell
66
+ irm https://github.com/kapistyn/trapyze/releases/latest/download/install.ps1 | iex
67
+ ```
68
+
69
+ **macOS and Linux:** paste this into a terminal:
70
+
71
+ ```sh
72
+ curl -LsSf https://github.com/kapistyn/trapyze/releases/latest/download/install.sh | sh
73
+ ```
74
+
75
+ **Already use [uv](https://docs.astral.sh/uv/)?** traPYze is also [on PyPI](https://pypi.org/project/trapyze/):
76
+
77
+ ```sh
78
+ uv tool install "trapyze[desktop]"
79
+ trapyze shortcut
80
+ ```
81
+
82
+ You don't need Python: the installer adds [uv](https://docs.astral.sh/uv/), which
83
+ fetches and runs Python for traPYze. No administrator needed. traPYze opens when
84
+ it's done, with three example tools, and adds a shortcut to your desktop, Start
85
+ menu or Applications. It updates itself: when there's a new version, it says so
86
+ and installs it with one click.
87
+
88
+ ## A quick tour
89
+
90
+ ### Tools on shelves, sorted for you
91
+ Tools sit on shelves by what they do: **Collect**, **Analyse**, **Share**,
92
+ **Maintain** and **Apps**. traPYze sorts them itself from what each script does;
93
+ drag them anywhere you like after that. Star your daily tools, filter by topic,
94
+ and see at a glance what's running, what's next and what needs a look.
95
+ Prefer a table? Switch to the List view.
96
+
97
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/list.png" width="820" alt="The List view"></p>
98
+
99
+ ### A settings window for every script, and live progress
100
+ The settings come from a few lines at the top of the script (its *label*), so
101
+ every tool explains itself. Press **Run** and keep working: traPYze shows the
102
+ progress and tells you when it's done.
103
+
104
+ <table>
105
+ <tr>
106
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/settings.png" alt="A tool's settings window"></td>
107
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/progress.png" alt="A tool running, with its progress"></td>
108
+ </tr>
109
+ </table>
110
+
111
+ ### Everything it made, in one place
112
+ Every run with its files, the settings it used and its log, newest first.
113
+ "Run again with these settings" is one click; a run that failed says why in
114
+ plain words.
115
+
116
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/outputs.png" width="820" alt="Outputs: every run with its files"></p>
117
+
118
+ ### Plans that run by themselves, and a vault for your keys
119
+ "Every weekday at 07:30", "Sundays at 20:00". Plans use your computer's own
120
+ scheduler, so they run even when traPYze is closed; missed runs catch up.
121
+ Chain tools together: fetch, then analyse, then mail. Keys and logins live
122
+ encrypted behind your PIN and only reach the tools you allowed.
123
+
124
+ <table>
125
+ <tr>
126
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/schedule.png" alt="Plans on the Schedule screen"></td>
127
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/vault.png" alt="Connections in the vault"></td>
128
+ </tr>
129
+ </table>
130
+
131
+ ### Import anything, even a whole program
132
+ Point traPYze at a script, a folder, a .zip or a folder in WSL. It finds the
133
+ main script, turns its command-line options into settings, works out the
134
+ packages it needs, offers `.env` keys to the vault, and keeps the helper
135
+ scripts out of sight. Your original is never changed.
136
+
137
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/import.png" width="820" alt="Importing a program folder"></p>
138
+
139
+ ### A health check, and AI help that shows its work
140
+ The health check reads a script offline: will it start, are packages missing,
141
+ is a key typed into the code, are there risky lines? **Ask AI** explains a
142
+ script, says why a run failed, or changes it, with a free chat site (Copilot,
143
+ Gemini, ChatGPT, Claude) or your own key. Secrets are masked first, and you see
144
+ every change before it's saved.
145
+
146
+ <table>
147
+ <tr>
148
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/health.png" alt="The health check finds a token typed into the code"></td>
149
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/ask-ai.png" alt="Ask AI proposes a fix, shown as changes"></td>
150
+ </tr>
151
+ </table>
152
+
153
+ ### Every change kept, and new tools in a minute
154
+ traPYze keeps a copy each time a script changes, whether by you, your editor or
155
+ an AI, and goes back with one click. **Edit** opens a script in VS Code,
156
+ PyCharm, Notepad++ or whichever editor you use. **New tool** gives you a small
157
+ working script to start from.
158
+
159
+ <table>
160
+ <tr>
161
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/changes.png" alt="Changes: every version, with going back"></td>
162
+ <td width="50%"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/new-tool.png" alt="A new tool from a template"></td>
163
+ </tr>
164
+ </table>
165
+
166
+ ### Light or dark, your colours, its own window
167
+ Its own window with a tray icon (or your browser), light and dark themes,
168
+ accent colours, compact or comfortable, and your own icon per tool.
169
+
170
+ <p align="center"><img src="https://raw.githubusercontent.com/Kapistyn/trapyze/v0.17.4/docs/images/desktop-dark.png" width="820" alt="The desktop in dark"></p>
171
+
172
+ ## Ready-made tools
173
+
174
+ New to Python tools? **Get tools** adds packs that come with traPYze. They work
175
+ without the internet and need nothing installed:
176
+
177
+ | Pack | Tools |
178
+ |---|---|
179
+ | **Everyday files** | Tidy a folder · Find duplicate files · Set duplicates aside · Back up a folder · Restore a backup · Rename files · What takes the space? |
180
+ | **Home finance** | Bank statement overview by category and month · Find subscriptions |
181
+ | **Tables and data** | Check a download · Merge CSV files · CSV into a database · Database table to CSV |
182
+
183
+ Tools that change files show you a list first and never delete or overwrite your
184
+ files; your bank statement never leaves your computer.
185
+
186
+ ## Make your own tool
187
+
188
+ Any Python script works. A few comment lines at the top make it a proper
189
+ traPYze tool with its own settings window:
190
+
191
+ ```python
192
+ # /// script
193
+ # dependencies = ["requests"]
194
+ #
195
+ # [tool.trapyze]
196
+ # name = "Exchange rates"
197
+ # description = "Fetches today's euro exchange rates."
198
+ # icon = "coin"
199
+ #
200
+ # [[tool.trapyze.settings]]
201
+ # key = "currencies"
202
+ # label = "Currencies"
203
+ # type = "text"
204
+ # default = "USD, GBP, JPY"
205
+ # ///
206
+ import requests
207
+ import trapyze_helper as tz
208
+
209
+ s = tz.settings() # what the user chose in the window
210
+ tz.progress(0.5, "Asking the central bank")
211
+ ...
212
+ tz.output_path("rates.csv").write_text(csv_text) # shows up under Outputs
213
+ ```
214
+
215
+ The top block is the standard [PEP 723](https://peps.python.org/pep-0723/)
216
+ format, so the script still runs anywhere else too. Don't want to write it
217
+ yourself? **New tool, Have an AI write it**: describe what you want, and traPYze
218
+ tells the AI how its tools work, so the script arrives ready. The same
219
+ [prompt](https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md#prompt-for-ai-written-tools) works in any AI chat, and
220
+ **Ask AI, Make it traPYze-ready** adds the label to a script you already have.
221
+
222
+ ## How it works
223
+
224
+ ```mermaid
225
+ flowchart LR
226
+ A[Your script<br/>with its label] --> B[traPYze reads<br/>the label]
227
+ B --> C[Settings window]
228
+ C --> D[uv runs it with<br/>exactly its packages]
229
+ V[(Vault)] -. only allowed keys .-> D
230
+ P[Plans] --> D
231
+ D --> E[Progress, results<br/>and history]
232
+ ```
233
+
234
+ - **The engine is [uv](https://docs.astral.sh/uv/)**: each tool runs with its
235
+ own packages, pinned per tool, so tools never break each other.
236
+ - **Everything stays on your computer.** traPYze listens only on 127.0.0.1
237
+ with a fresh key per session. Nothing is sent anywhere unless a tool does
238
+ so, or you use Ask AI; traPYze itself only looks for newer packages and a
239
+ newer traPYze, once a day.
240
+ - **Your scripts stay yours**: plain .py files in your Trapyze folder,
241
+ working with or without traPYze.
242
+
243
+ ## Questions
244
+
245
+ **Is it free?** Yes, free and open source under the MIT licence, with no ads
246
+ and no tracking.
247
+
248
+ **Do I need to know Python?** No, to use tools. A little, to write your own,
249
+ and Ask AI helps with that.
250
+
251
+ **Is it safe?** traPYze keeps your keys encrypted and away from scripts that
252
+ weren't allowed to use them, and a tool you imported or an AI wrote shows what
253
+ it can do before its first run. But a tool is a program that can do anything you
254
+ can: only run tools from people you trust.
255
+ See [SECURITY.md](https://github.com/Kapistyn/trapyze/blob/v0.17.4/SECURITY.md).
256
+
257
+ **Does it work offline?** Yes. Only installing a tool's packages the first
258
+ time, tools that fetch data, Ask AI and the update check need the internet.
259
+
260
+ **Where are my things?** In the `Trapyze` folder in your home folder:
261
+ `scripts`, `outputs` and `data`. Back it up like any other folder.
262
+
263
+ **Can I run a tool from the terminal too?** Yes: `trapyze run "exchange rates"
264
+ --set currencies=USD`. See [the guide](https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md#from-the-terminal).
265
+
266
+ ## Helping
267
+
268
+ traPYze is free and stays free. The best ways to help:
269
+
270
+ - ⭐ **Star the project** on GitHub, so more people find it
271
+ - [Report a problem or share an idea](https://github.com/kapistyn/trapyze/issues)
272
+ - Share a tool you made (see [CONTRIBUTING.md](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CONTRIBUTING.md))
273
+
274
+ ## Documentation
275
+
276
+ - **[The full guide](https://github.com/Kapistyn/trapyze/blob/v0.17.4/docs/guide.md)**: every screen and option, step by step
277
+ - [Changelog](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CHANGELOG.md) · [Contributing](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CONTRIBUTING.md) · [Security](https://github.com/Kapistyn/trapyze/blob/v0.17.4/SECURITY.md)
278
+
279
+ ## Running the tests
280
+
281
+ ```
282
+ uv run --with pytest --with pandas python -m pytest -q
283
+ ```
284
+
285
+ No internet needed. See [CONTRIBUTING.md](https://github.com/Kapistyn/trapyze/blob/v0.17.4/CONTRIBUTING.md) for more.
286
+
287
+ ## Licence
288
+
289
+ MIT, see LICENSE.