manx.py: man pages in BBS style, with ANSI colours and syntax highlighting, using only the Python standard library.

0 downloads

dbbasic-manx/manx.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-manx.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-manx.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-manx.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 Initial commit: BBS-style ANSI man page viewer 9414990 1 year, 1 month ago History
manx.py · 13.7 KB · 397 lines
1#!/usr/bin/env python3
2# manx.py — BBS/ANSI colored "man" viewer with a bundled page for dbbasic-tsv.
3# No dependencies. Works with pydoc.pager/less -R for keyboard navigation.
4# - Arrow keys/PageUp/PageDown in pager
5# - '/' to search in pager
6# - 'q' to quit pager
7import os, sys, re, textwrap, shutil, pydoc
8from datetime import datetime
9
10# ---------- ANSI Palette (respects NO_COLOR) ----------
11NO_COLOR = os.environ.get("NO_COLOR")
12TRUECOLOR = os.environ.get("COLORTERM") == "truecolor"
13def c(code): return "" if NO_COLOR else code
14RESET = c("\x1b[0m")
15BOLD = c("\x1b[1m")
16DIM = c("\x1b[2m")
17ITAL = c("\x1b[3m")
18UNDER = c("\x1b[4m")
19
20# base colors
21FG = {
22 "fg": c("\x1b[38;5;252m"),
23 "muted": c("\x1b[38;5;244m"),
24 "accent": c("\x1b[38;5;178m"), # amber-ish
25 "link": c("\x1b[38;5;111m"),
26 "green": c("\x1b[38;5;77m"),
27 "blue": c("\x1b[38;5;69m"),
28 "yellow": c("\x1b[38;5;220m"),
29 "red": c("\x1b[38;5;203m"),
30 "magenta": c("\x1b[38;5;171m"),
31 "cyan": c("\x1b[38;5;51m"),
32 "white": c("\x1b[97m"),
33 "grey": c("\x1b[90m"),
34}
35BG_HILITE = c("\x1b[48;5;236m")
36BG_YELLOWFADE = c("\x1b[48;5;228m")
37
38# ---------- Text helpers ----------
39def get_term_width():
40 """Get current terminal width, handling pipes and redirects gracefully."""
41 try:
42 size = shutil.get_terminal_size()
43 # If stdout is redirected/piped, default to 100
44 if not sys.stdout.isatty():
45 return 100
46 # Cap at reasonable max for readability, min 60 for narrow terminals
47 return min(120, max(60, size.columns))
48 except:
49 return 100
50
51def wrap(s, width=None, indent=""):
52 w = width or get_term_width()
53 return "\n".join(textwrap.fill(line, width=w, subsequent_indent=indent)
54 if line.strip() and not line.startswith(" ")
55 else line
56 for line in s.splitlines())
57
58def h1(title):
59 title = f" {title.strip()} "
60 width = get_term_width()
61 line = "═" * max(0, (width - len(title) - 2))
62 return (FG["accent"] + "╔" + title + line + "╗" + RESET)
63
64def h2(title):
65 return FG["accent"] + BOLD + f"\n{title}\n" + RESET + FG["muted"] + ("─" * len(title)) + RESET
66
67def code_fence(lang, is_end=False):
68 lang = (lang or "").lower().strip()
69 width = get_term_width()
70 if is_end:
71 line = "─" * max(0, width - 8)
72 return FG["muted"] + "└" + line + "┘" + RESET
73 else:
74 label = f" {lang or 'text'} "
75 line = "─" * max(0, width - len(label) - 3)
76 return FG["muted"] + "┌" + label + line + "┐" + RESET
77
78def code_block(code, lang=""):
79 """Format a code block with syntax highlighting and decorative fencing."""
80 highlighted = colorize_code_block(code, lang)
81 # Indent code slightly for better readability
82 indented = "\n".join(" " + line if line.strip() else line
83 for line in highlighted.splitlines())
84 return f"{code_fence(lang)}\n{indented}\n{code_fence(lang, is_end=True)}"
85
86# ---------- Simple syntax highlighters (no deps) ----------
87KW_PY = r"\b(False|True|None|def|class|return|yield|from|import|as|if|elif|else|for|while|try|except|with|lambda|pass|break|continue|in|is|not|and|or)\b"
88def color_python(line):
89 # Apply highlights in a way that prevents re-highlighting ANSI codes
90 # Mark strings first (greedy, so they take priority)
91 parts = []
92 last_end = 0
93 for m in re.finditer(r"'[^']*'|\"[^\"]*\"", line):
94 # Add unhighlighted part before the string
95 if m.start() > last_end:
96 parts.append(('text', line[last_end:m.start()]))
97 # Add the string (highlighted)
98 parts.append(('string', m.group(0)))
99 last_end = m.end()
100 # Add remaining text
101 if last_end < len(line):
102 parts.append(('text', line[last_end:]))
103
104 # Now process non-string parts
105 result = []
106 for typ, content in parts:
107 if typ == 'string':
108 result.append(FG["green"] + content + RESET)
109 else:
110 # Apply other highlights to non-string content
111 # comments
112 content = re.sub(r"(\s+#.*)$", lambda m: FG["grey"] + m.group(1) + RESET, content)
113 # numbers (but not in ANSI codes)
114 content = re.sub(r"\b(\d+(?:\.\d+)?)\b", lambda m: FG["magenta"] + m.group(1) + RESET, content)
115 # keywords
116 content = re.sub(KW_PY, lambda m: FG["cyan"] + m.group(1) + RESET, content)
117 # decorators
118 content = re.sub(r"^(\s*@\w+)", lambda m: FG["yellow"] + m.group(1) + RESET, content)
119 result.append(content)
120
121 return ''.join(result)
122
123def color_shell(line):
124 # prompt/path dim
125 line = re.sub(r"^(\$)\s*", lambda m: FG["muted"] + m.group(1) + " " + RESET, line)
126 # flags
127 line = re.sub(r"(\s|^)(-\w+|--[\w-]+)", lambda m: m.group(1) + FG["cyan"] + m.group(2) + RESET, line)
128 # env vars
129 line = re.sub(r"\$[A-Z_][A-Z0-9_]*", lambda m: FG["magenta"] + m.group(0) + RESET, line)
130 # quoted args
131 line = re.sub(r"('.*?'|\".*?\")", lambda m: FG["green"] + m.group(1) + RESET, line)
132 return line
133
134def color_http(line):
135 # methods
136 line = re.sub(r"\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b", lambda m: FG["blue"] + m.group(1) + RESET, line)
137 # status codes
138 line = re.sub(r"\b(20\d)\b", lambda m: FG["green"] + m.group(1) + RESET, line)
139 line = re.sub(r"\b(30\d)\b", lambda m: FG["blue"] + m.group(1) + RESET, line)
140 line = re.sub(r"\b(40\d)\b", lambda m: FG["yellow"] + m.group(1) + RESET, line)
141 line = re.sub(r"\b(50\d)\b", lambda m: FG["red"] + m.group(1) + RESET, line)
142 # headers like Key: value
143 line = re.sub(r"^([A-Za-z-]+)(:)", lambda m: FG["cyan"] + m.group(1) + RESET + m.group(2), line)
144 return line
145
146def color_tsv(line, is_header=False):
147 cells = line.split("\t")
148 if is_header:
149 cells = [FG["cyan"] + c + RESET for c in cells]
150 return "\t".join(cells)
151
152def colorize_code_block(block, lang):
153 lines = block.splitlines()
154 if lang == "python":
155 return "\n".join(color_python(l) for l in lines)
156 if lang in ("sh", "bash", "shell", ""):
157 return "\n".join(color_shell(l) for l in lines)
158 if lang in ("http", "headers"):
159 return "\n".join(color_http(l) for l in lines)
160 if lang in ("tsv", "csv"):
161 out = []
162 for i, l in enumerate(lines):
163 out.append(color_tsv(l, is_header=(i==0)))
164 return "\n".join(out)
165 return "\n".join(lines)
166
167# ---------- Minimal markdown-ish to ANSI renderer ----------
168FENCE = re.compile(r"^```(\w+)?\s*$")
169def render_markdownish(md_text):
170 """Supports: # headers, code fences ```lang, bullet lists, bold/italic * _."""
171 out, in_code, lang = [], False, ""
172 for raw in md_text.splitlines():
173 if FENCE.match(raw):
174 if not in_code:
175 in_code = True
176 lang = FENCE.match(raw).group(1) or ""
177 out.append(code_fence(lang))
178 else:
179 in_code = False
180 lang = ""
181 continue
182 if in_code:
183 out.append(colorize_code_block(raw, lang))
184 continue
185 # h1/h2/h3
186 if raw.startswith("# "):
187 out.append(h2(raw[2:].strip()))
188 continue
189 if raw.startswith("## "):
190 out.append(FG["accent"] + BOLD + raw[3:].strip() + RESET)
191 continue
192 # bullets
193 if re.match(r"^\s*[-*]\s+", raw):
194 out.append(FG["muted"] + "• " + RESET + wrap(raw.strip()[2:], indent=" "))
195 continue
196 # inline bold/italic
197 line = raw
198 line = re.sub(r"\*\*(.+?)\*\*", BOLD + r"\1" + RESET, line)
199 line = re.sub(r"_(.+?)_", ITAL + r"\1" + RESET, line)
200 out.append(wrap(line))
201 return "\n".join(out)
202
203# ---------- Bundled MAN page: dbbasic-tsv (from your PyPI details) ----------
204def get_dbbasic_tsv_man():
205 # Pre-build code blocks
206 install_code = code_block("""$ pip install dbbasic-tsv
207# With Rust (optional)
208$ pip install maturin
209$ git clone https://github.com/askrobots/dbbasic-tsv.git
210$ cd dbbasic-tsv
211$ maturin develop --release""", "sh")
212
213 quickstart_code = code_block('''from dbbasic.tsv import TSV
214
215# Create a table
216users = TSV("users", ["id", "name", "email", "created_at"])
217
218# Insert
219users.insert({"id":"123","name":"Alice","email":"alice@example.com","created_at":"2024-01-01"})
220
221# Query
222user = users.query_one(email="alice@example.com")
223print(user)
224
225# Bulk
226users.insert_many([
227 {"id":"124","name":"Bob","email":"bob@example.com"},
228 {"id":"125","name":"Charlie","email":"charlie@example.com"},
229])
230
231# Update
232users.update({"email":"alice@example.com"},{"name":"Alice Smith"})
233
234# Delete
235users.delete(id="123")
236
237# Transactions
238with users.transaction():
239 users.insert({"id":"126","name":"Dave"})
240 users.update({"id":"126"},{"email":"dave@example.com"})''', "python")
241
242 data_format_code = code_block("""id\tname\temail\tcreated_at
243123\tAlice\talice@example.com\t2024-01-01
244124\tBob\tbob@example.com\t2024-01-01
245125\tCharlie\tcharlie@example.com\t2024-01-01""", "tsv")
246
247 indexes_code = code_block("""users = TSV("users", ["id","name","email"], indexes=["email"])
248users.rebuild_indexes()""", "python")
249
250 compaction_code = code_block("""users.compact()""", "python")
251
252 concurrency_code = code_block("""users = TSV("users", ["id","name","email"])
253results = list(users.query(name="Alice")) # works during writes""", "python")
254
255 return f"""{h1("DBBASIC-TSV(1) — DBBasic Manual")}
256
257{FG['muted']}Updated:{RESET} {datetime.now().strftime('%Y-%m-%d')} {FG['muted']}Version:{RESET} 1.0.2 {FG['muted']}License:{RESET} MIT
258
259{BOLD}NAME{RESET}
260 dbbasic-tsv — A pure-Python, filesystem-based database using TSV files
261
262{BOLD}SYNOPSIS{RESET}
263 pip install dbbasic-tsv
264 python -c "from dbbasic.tsv import TSV; print(TSV('users', ['id','name']).all())"
265
266{BOLD}DESCRIPTION{RESET}
267 dbbasic-tsv is a blazing-fast TSV (Tab-Separated Values) database that keeps your data
268 in human-readable text files, versionable with git. It provides ACID transactions,
269 concurrent reads during writes, optional in-memory indexes with persistence, bloom
270 filters (planned), automatic compaction, and thread-safety. Pure Python works
271 everywhere; optional Rust acceleration makes hot paths much faster.
272
273{BOLD}WHY THIS EXISTS{RESET}
274 We built a video platform (YouTube-like) and discovered we didn't need PostgreSQL,
275 Redis, or Elasticsearch for a large class of problems. Text files + good engineering
276 were enough, and often faster to operate and understand.
277
278{BOLD}FEATURES{RESET}
279 • Human-readable TSV you can grep/cat/edit in Excel
280 • Git-friendly: diffs are meaningful
281 • Zero-setup: no server, no migrations
282 • Optional Rust acceleration
283 • ACID transactions (PID-based locking)
284 • Concurrent reads during writes
285 • In-memory indexes; rebuild from disk on startup
286 • Automatic compaction/cleanup
287 • Type-hinted, production/stable
288
289{BOLD}INSTALLATION{RESET}
290{install_code}
291
292{BOLD}QUICK START{RESET}
293{quickstart_code}
294
295{BOLD}DATA FORMAT{RESET}
296{data_format_code}
297
298{BOLD}ADVANCED{RESET}
299
300 Indexes
301 {indexes_code}
302
303 Compaction
304 {compaction_code}
305
306 Concurrency
307 {concurrency_code}
308
309{BOLD}PERFORMANCE NOTE{RESET}
310 Pure Python inserts ~160k/sec on modern hardware; Rust acceleration projects ~600k/sec
311 inserts and ~88k/sec queries (10k sample). SQLite baseline remains very fast in many
312 cases. Choose per workload.
313
314{BOLD}WHEN TO USE{RESET}
315 ✅ Content/config/reference data, catalogs, docs; git-push as deployment
316 ❌ High-concurrency transactional workloads (orders/payments/carts)
317
318{BOLD}ARCHITECTURE OVERVIEW{RESET}
319 • Writes: append-only with fcntl locking
320 • Reads: lock-free
321 • Indexes: in-memory maps + on-disk persistence
322 • Transactions: PID-based lock + rollback journal
323 • Compaction: periodic clean-up of tombstones
324 • Rust: hot-path parse/serialize (optional)
325
326{BOLD}API REFERENCE (TSV){RESET}
327 TSV(name: str, columns: list[str] = None, data_dir: Path = None, indexes: list[str] = None)
328
329 insert(record: dict) -> bool
330 insert_many(records: list[dict]) -> int
331 query(**conditions) -> Iterator[dict]
332 query_one(**conditions) -> dict|None
333 update(conditions: dict, updates: dict) -> int
334 delete(**conditions) -> int
335 all() -> Iterator[dict]
336 count(**conditions) -> int
337 transaction() -> contextmanager
338 compact() -> None
339 rebuild_indexes() -> None
340
341{BOLD}FILES{RESET}
342 ./data/<table>.tsv main data file
343 ./data/.journal/<table>.log transaction journal
344 ./data/.index/<table>/*.idx persisted index shards
345
346{BOLD}ENVIRONMENT{RESET}
347 DBBASIC_DATA_DIR base directory for TSV data (default: ./data)
348
349{BOLD}SEE ALSO{RESET}
350 dbbasic-web(1), dbbasic-queue(1), grep(1), awk(1), rsync(1)
351
352{FG['muted']}"If you can't grep it, you don't own it."{RESET}
353"""
354
355# ---------- Multi-page registry (in-memory) ----------
356PAGES = {
357 "dbbasic-tsv": get_dbbasic_tsv_man,
358}
359
360# ---------- Renderer / Pager ----------
361def to_pager(text):
362 # Ensure ANSI survives in less
363 if not os.environ.get("LESS"):
364 os.environ["LESS"] = "-R"
365 pydoc.pager(text)
366
367def render_page(key):
368 page_fn = PAGES.get(key)
369 if not page_fn:
370 keys = ", ".join(sorted(PAGES))
371 to_pager(f"{h1('MANX(1) — Local Manuals')}\n\nUnknown page: {key}\n\nAvailable: {keys}\n")
372 return
373 # Call the function to generate the page content
374 to_pager(page_fn())
375
376# ---------- Menu ----------
377MENU = f"""{h1("MANX(1) — BBS/ANSI Manual Viewer")}
378
379{BOLD}USAGE{RESET}
380 python manx.py <page>
381 python manx.py dbbasic-tsv
382
383{BOLD}AVAILABLE PAGES{RESET}
384 • dbbasic-tsv
385
386{BOLD}TIPS{RESET}
387 • Use '/' to search, 'n' for next match, 'q' to quit
388 • Set {BOLD}NO_COLOR=1{RESET} to disable ANSI colors
389 • Export to text: python manx.py dbbasic-tsv > out.txt
390"""
391
392# ---------- main ----------
393if __name__ == "__main__":
394 if len(sys.argv) == 1:
395 to_pager(MENU)
396 sys.exit(0)
397 render_page(sys.argv[1].strip().lower())