thuk 1.0.1__py3-none-any.whl

thuk/__init__.py

@@ -0,0 +1,4 @@
+"""Thuk: offline study documents with contents and keyword search."""
+from .reference import SECTIONS, get_text, search, list_topics, get_topic, search_topics
+__version__ = '1.0.1'
+__all__ = ['SECTIONS', 'get_text', 'search', 'list_topics', 'get_topic', 'search_topics']

thuk/__main__.py

@@ -0,0 +1,2 @@
+from .cli import main
+raise SystemExit(main())

thuk/cli.py

@@ -0,0 +1,152 @@
+"""Nested document browser and keyword search."""
+import argparse
+import pydoc
+import re
+import subprocess
+import sys
+from . import __version__
+from .reference import SECTIONS, get_text, get_topic, list_topics, search_topics, export_pdf, open_pdf
+
+
+def highlight(text, keyword, color=False):
+    if not keyword:
+        return text
+    pattern = re.compile(re.escape(keyword), re.IGNORECASE)
+    return pattern.sub(lambda m: ('\033[1;33m' + m[0] + '\033[0m') if color else '[[' + m[0] + ']]', text)
+
+
+def display(section, topic=None, plain=False, keyword=None):
+    title = SECTIONS[section][0]
+    body = get_text(section) if topic is None else get_topic(section, topic)
+    if topic is not None:
+        title += ' / ' + list_topics(section)[topic - 1]['title']
+    # Markers remain visible even in Windows pagers that strip ANSI escapes.
+    text = title + '\n' + '=' * 60 + '\n\n' + highlight(body, keyword)
+    if keyword:
+        text = f'Search: {keyword} (matches marked with [[...]]).\n\n' + text
+    if plain or not sys.stdout.isatty():
+        print(text)
+    else:
+        pydoc.pager(text)
+
+
+def ask(prompt):
+    return input(prompt).strip()
+
+
+def search_menu(section, plain=False, query=None):
+    if query is None:
+        query = ask('Keyword (blank to cancel): ')
+    if not query.strip():
+        return
+    results = search_topics(query, section)
+    if not results:
+        print('No matches found in this document.')
+        return
+    while True:
+        print(f'\nSearch results in {SECTIONS[section][0]} for "{query}"')
+        for i, result in enumerate(results, 1):
+            print(f"{i}. {result['title']} ({len(result['matches'])} matching lines)")
+            for line, snippet in result['matches'][:2]:
+                print(f'   Line {line}: {highlight(snippet, query)}')
+        print('0. Back to document contents')
+        choice = ask('Open result: ')
+        if choice == '0':
+            return
+        if choice.isdigit() and 1 <= int(choice) <= len(results):
+            display(section, results[int(choice) - 1]['topic'], plain, query)
+            return
+        else:
+            print('Choose a result number or 0.')
+
+
+def document_menu(section, plain=False):
+    topics = list_topics(section)
+    while True:
+        print('\n' + SECTIONS[section][0] + ' - Contents\n' + '=' * 60)
+        for number, item in enumerate(topics, 1):
+            indent = '  ' if item['level'] == 2 else ''
+            print(f"{number}. {indent}{item['title']}")
+        print('S. Search this document')
+        print('0. Back to documents')
+        choice = ask('Select a section or S to search: ').lower()
+        if choice == '0':
+            return
+        if choice == 's':
+            search_menu(section, plain)
+        elif choice.isdigit() and 1 <= int(choice) <= len(topics):
+            display(section, int(choice), plain)
+        else:
+            print('Choose a section number, S, or 0.')
+
+
+def menu(plain=False, pdf=False):
+    while True:
+        print('\nTHUK\n' + '=' * 42)
+        for number, (title, _) in SECTIONS.items():
+            print(f'{number}. {title}')
+        print('0. Exit\n' + '=' * 42)
+        choice = ask('Select a document (1-5): ')
+        if choice == '0':
+            return 0
+        if choice not in {str(n) for n in SECTIONS}:
+            print('Choose a document from 1 to 5, or 0 to exit.')
+            continue
+        if pdf:
+            try:
+                print(f'Opened: {open_pdf(int(choice))}')
+            except (ValueError, OSError, subprocess.CalledProcessError) as exc:
+                print(f'Cannot open PDF: {exc}')
+        else:
+            document_menu(int(choice), plain)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description='Thuk offline document browser')
+    parser.add_argument('section', nargs='?', type=int, choices=SECTIONS, help='document number (1-5)')
+    parser.add_argument('--topic', type=int, help='read one topic by its contents-menu number')
+    parser.add_argument('--version', action='version', version=f'Thuk {__version__}')
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument('--pdf', action='store_true', help='open the original PDF')
+    group.add_argument('--export-pdf', metavar='PATH', help='save the original PDF')
+    group.add_argument('--search', metavar='TEXT', help='search the selected document, or all documents')
+    group.add_argument('--full', action='store_true', help='print the complete document')
+    parser.add_argument('--plain', action='store_true', help='disable the interactive pager')
+    args = parser.parse_args(argv)
+    if (args.topic is not None or args.export_pdf or args.full) and args.section is None:
+        parser.error('--topic, --export-pdf and --full require a document number')
+    if args.topic is not None and (args.pdf or args.export_pdf or args.full or args.search is not None):
+        parser.error('--topic cannot be combined with PDF, full-document or search options')
+    try:
+        if args.search is not None:
+            if not args.search.strip():
+                raise ValueError('Enter a non-empty search query.')
+            if args.section is not None and sys.stdin.isatty():
+                search_menu(args.section, args.plain, args.search)
+                document_menu(args.section, args.plain)
+            else:
+                found = False
+                for section in ([args.section] if args.section else SECTIONS):
+                    for result in search_topics(args.search, section):
+                        found = True
+                        print(f"{SECTIONS[section][0]} / {result['title']} (topic {result['topic']})")
+                        for line, snippet in result['matches']:
+                            print(f'  {line}: {highlight(snippet, args.search)}')
+                if not found:
+                    print('No matches found.')
+        elif args.section is None:
+            return menu(args.plain, args.pdf)
+        elif args.export_pdf:
+            print(export_pdf(args.section, args.export_pdf))
+        elif args.pdf:
+            print(f'Opened: {open_pdf(args.section)}')
+        elif args.topic is not None or args.full:
+            display(args.section, args.topic, args.plain)
+        else:
+            document_menu(args.section, args.plain)
+        return 0
+    except (EOFError, KeyboardInterrupt, BrokenPipeError):
+        return 0
+    except (ValueError, OSError, subprocess.CalledProcessError) as exc:
+        print(f'Thuk: {exc}', file=sys.stderr)
+        return 1

thuk/data/contents.json

@@ -0,0 +1,330 @@
+{
+  "1": [
+    {
+      "title": "Document introduction",
+      "start": 0,
+      "end": 4,
+      "level": 1
+    },
+    {
+      "title": "1. Course Orientation",
+      "start": 4,
+      "end": 30,
+      "level": 1
+    },
+    {
+      "title": "2. Python Core",
+      "start": 30,
+      "end": 246,
+      "level": 1
+    },
+    {
+      "title": "3. Networking and Files",
+      "start": 246,
+      "end": 423,
+      "level": 1
+    },
+    {
+      "title": "4. Django MVT",
+      "start": 423,
+      "end": 685,
+      "level": 1
+    },
+    {
+      "title": "5. Auth and Sessions",
+      "start": 685,
+      "end": 773,
+      "level": 1
+    },
+    {
+      "title": "6. Database Connectivity",
+      "start": 773,
+      "end": 880,
+      "level": 1
+    },
+    {
+      "title": "7. APIs with Django REST Framework",
+      "start": 880,
+      "end": 1011,
+      "level": 1
+    },
+    {
+      "title": "8. Machine Learning Model Integration",
+      "start": 1011,
+      "end": 1120,
+      "level": 1
+    },
+    {
+      "title": "9. Quick Recap",
+      "start": 1120,
+      "end": 1161,
+      "level": 1
+    }
+  ],
+  "2": [
+    {
+      "title": "Document introduction",
+      "start": 0,
+      "end": 25,
+      "level": 1
+    },
+    {
+      "title": "1. Course Orientation",
+      "start": 25,
+      "end": 40,
+      "level": 1
+    },
+    {
+      "title": "2. Why Docker Exists",
+      "start": 40,
+      "end": 120,
+      "level": 1
+    },
+    {
+      "title": "3. Containers vs Virtual Machines",
+      "start": 120,
+      "end": 161,
+      "level": 1
+    },
+    {
+      "title": "4. Docker Architecture",
+      "start": 161,
+      "end": 211,
+      "level": 1
+    },
+    {
+      "title": "5. Images and the Dockerfile",
+      "start": 211,
+      "end": 308,
+      "level": 1
+    },
+    {
+      "title": "6. Containers, Storage and Networking",
+      "start": 308,
+      "end": 422,
+      "level": 1
+    },
+    {
+      "title": "7. Docker Compose",
+      "start": 422,
+      "end": 468,
+      "level": 1
+    },
+    {
+      "title": "8. Integrating Django with Docker",
+      "start": 468,
+      "end": 500,
+      "level": 1
+    },
+    {
+      "title": "9. Deployment and Security",
+      "start": 500,
+      "end": 595,
+      "level": 1
+    },
+    {
+      "title": "10. Best Practice and Debugging",
+      "start": 595,
+      "end": 661,
+      "level": 1
+    },
+    {
+      "title": "11. Quick Recap",
+      "start": 661,
+      "end": 691,
+      "level": 1
+    }
+  ],
+  "3": [
+    {
+      "title": "Document introduction",
+      "start": 0,
+      "end": 7,
+      "level": 1
+    },
+    {
+      "title": "1. Python Core",
+      "start": 7,
+      "end": 127,
+      "level": 1
+    },
+    {
+      "title": "2. Networking and Files",
+      "start": 127,
+      "end": 237,
+      "level": 1
+    },
+    {
+      "title": "3. Django Project Setup",
+      "start": 237,
+      "end": 264,
+      "level": 1
+    },
+    {
+      "title": "4. Django MVT",
+      "start": 264,
+      "end": 414,
+      "level": 1
+    },
+    {
+      "title": "5. Auth and Sessions",
+      "start": 414,
+      "end": 516,
+      "level": 1
+    },
+    {
+      "title": "6. Database Connectivity",
+      "start": 516,
+      "end": 589,
+      "level": 1
+    },
+    {
+      "title": "7. Django REST Framework",
+      "start": 589,
+      "end": 687,
+      "level": 1
+    },
+    {
+      "title": "8. Machine Learning Model Integration",
+      "start": 687,
+      "end": 782,
+      "level": 1
+    },
+    {
+      "title": "9. Common Errors and Fixes",
+      "start": 782,
+      "end": 828,
+      "level": 1
+    },
+    {
+      "title": "10. Command Sheet",
+      "start": 828,
+      "end": 847,
+      "level": 1
+    }
+  ],
+  "4": [
+    {
+      "title": "Document introduction",
+      "start": 0,
+      "end": 36,
+      "level": 1
+    },
+    {
+      "title": "1. Setup",
+      "start": 36,
+      "end": 65,
+      "level": 1
+    },
+    {
+      "title": "2. Images",
+      "start": 65,
+      "end": 107,
+      "level": 1
+    },
+    {
+      "title": "3. Containers",
+      "start": 107,
+      "end": 167,
+      "level": 1
+    },
+    {
+      "title": "4. The Dockerfile",
+      "start": 167,
+      "end": 293,
+      "level": 1
+    },
+    {
+      "title": "5. Preparing Django for Docker",
+      "start": 293,
+      "end": 350,
+      "level": 1
+    },
+    {
+      "title": "6. Volumes and Networks",
+      "start": 350,
+      "end": 394,
+      "level": 1
+    },
+    {
+      "title": "7. Docker Compose",
+      "start": 394,
+      "end": 529,
+      "level": 1
+    },
+    {
+      "title": "8. Registries and Deployment",
+      "start": 529,
+      "end": 596,
+      "level": 1
+    },
+    {
+      "title": "9. Debugging and Clean Up",
+      "start": 596,
+      "end": 660,
+      "level": 1
+    }
+  ],
+  "5": [
+    {
+      "title": "Document introduction",
+      "start": 0,
+      "end": 6,
+      "level": 1
+    },
+    {
+      "title": "SETUP",
+      "start": 6,
+      "end": 11,
+      "level": 1
+    },
+    {
+      "title": "START A REPOSITORY",
+      "start": 11,
+      "end": 15,
+      "level": 1
+    },
+    {
+      "title": "DAILY WORK",
+      "start": 15,
+      "end": 25,
+      "level": 1
+    },
+    {
+      "title": "BRANCHES",
+      "start": 25,
+      "end": 32,
+      "level": 1
+    },
+    {
+      "title": "REMOTES",
+      "start": 32,
+      "end": 40,
+      "level": 1
+    },
+    {
+      "title": "TEMPORARY WORK",
+      "start": 40,
+      "end": 47,
+      "level": 1
+    },
+    {
+      "title": "UNDO",
+      "start": 47,
+      "end": 53,
+      "level": 1
+    },
+    {
+      "title": "CONFLICTS",
+      "start": 53,
+      "end": 60,
+      "level": 1
+    },
+    {
+      "title": "TAGS AND IGNORE RULES",
+      "start": 60,
+      "end": 65,
+      "level": 1
+    }
+  ]
+}