thuk 1.0.1__tar.gz

thuk-1.0.1/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: thuk
+Version: 1.0.1
+Summary: Offline terminal reference for Unit 2, Unit 5, Django, Docker and Git
+Project-URL: Repository, https://github.com/omparekh54-lgtm/thuk
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Thuk
+
+An offline Python study library with a nested terminal browser for five documents:
+
+1. Unit 2 Theory
+2. Unit 5 Theory
+3. Django Code (complete Unit 2 coding reference)
+4. Docker Commands (complete Unit 5 coding reference)
+5. Git Commands (supplementary cheat sheet)
+
+The full supplied text and all four original PDFs are bundled. No runtime dependencies, API keys or internet access are needed after installation. Code and commands in references are displayed for reading, never executed.
+
+## Install and run
+
+Python 3.9 or newer and Git:
+
+```powershell
+python -m pip install git+https://github.com/omparekh54-lgtm/thuk.git
+python -m thuk
+```
+
+Install while your virtual environment is active if you want to use Thuk inside it. The `thuk` command also works when your Python Scripts directory is on PATH (normally automatic in an active virtual environment).
+
+Without Git, download the repository ZIP, extract it, open a terminal inside the extracted folder, and run `python -m pip install .`.
+
+Not published to PyPI yet.
+
+## Browse
+
+```text
+THUK
+==========================================
+1. Unit 2 Theory
+2. Unit 5 Theory
+3. Django Code
+4. Docker Commands
+5. Git Commands
+0. Exit
+```
+
+Choose a document to see its contents, with main numbered chapters only. Choose a chapter to read it, including all of its subsections. Subsections such as 2.1 and 2.2 are not separate menu options.
+
+After reading, you stay in the same document's contents menu. In an interactive pager, press `q` to finish reading. Choose `0. Back to documents` to return to the five-document menu; `0. Exit` there closes Thuk. Ctrl+C or end-of-input exits cleanly.
+
+A `Document introduction` entry preserves each document's preface and original contents page. PDF extraction can change table spacing; open the original PDF to see diagrams and exact formatting.
+
+## Search within a document
+
+Choose `S. Search this document`, then type a keyword or phrase such as `migrations` or `docker run`. Search is case-insensitive and treats the query literally.
+
+Thuk lists matching sections with match counts and preview lines. Choose a result to open its section. Every matching keyword in that section is highlighted as `[[keyword]]`, which is readable on Windows, Linux and macOS. After reading a search result you return to that document's contents. `0` at search results returns without opening a result; a blank query cancels search.
+
+Search maps each hit to its main chapter and opens that chapter with matching keywords highlighted. Contents-page hits appear under Document introduction.
+
+## Other commands
+
+```powershell
+thuk 1                           # Open Unit 2's contents menu
+thuk 3                           # Open the Django code contents menu
+thuk 3 --topic 2 --plain          # Print topic 2 and exit
+thuk 1 --full --plain             # Print the entire document
+thuk 3 --search migrations        # Interactive document search
+thuk --search Docker             # Print matches across all documents
+thuk 1 --pdf                      # Open the original PDF in your desktop viewer
+thuk 4 --export-pdf docker.pdf    # Save the original PDF
+```
+
+Use `python -m thuk` instead of `thuk` if the executable isn't on PATH. In piped/noninteractive CLI search, results are printed with topic numbers; open one using `--topic NUMBER`. PDF export replaces the destination file if it exists. Git is a text-only reference and has no source PDF.
+
+## Python API
+
+```python
+from thuk import get_text, list_topics, get_topic, search_topics
+
+print(list_topics(1))
+print(get_topic(1, 2))
+print(search_topics('Django', 1))
+print(get_text(1))
+```
+
+## Development
+
+```sh
+python -m pip install .
+python -m unittest discover -s tests -v
+python -m pip wheel --no-deps . -w dist
+```
+
+The topic index is stored in `src/thuk/data/contents.json` using zero-based start and exclusive end line offsets in the bundled text. Update that index whenever reference text line boundaries change. The four original PDFs retain their source authorship.

thuk-1.0.1/README.md

@@ -0,0 +1,89 @@
+# Thuk
+
+An offline Python study library with a nested terminal browser for five documents:
+
+1. Unit 2 Theory
+2. Unit 5 Theory
+3. Django Code (complete Unit 2 coding reference)
+4. Docker Commands (complete Unit 5 coding reference)
+5. Git Commands (supplementary cheat sheet)
+
+The full supplied text and all four original PDFs are bundled. No runtime dependencies, API keys or internet access are needed after installation. Code and commands in references are displayed for reading, never executed.
+
+## Install and run
+
+Python 3.9 or newer and Git:
+
+```powershell
+python -m pip install git+https://github.com/omparekh54-lgtm/thuk.git
+python -m thuk
+```
+
+Install while your virtual environment is active if you want to use Thuk inside it. The `thuk` command also works when your Python Scripts directory is on PATH (normally automatic in an active virtual environment).
+
+Without Git, download the repository ZIP, extract it, open a terminal inside the extracted folder, and run `python -m pip install .`.
+
+Not published to PyPI yet.
+
+## Browse
+
+```text
+THUK
+==========================================
+1. Unit 2 Theory
+2. Unit 5 Theory
+3. Django Code
+4. Docker Commands
+5. Git Commands
+0. Exit
+```
+
+Choose a document to see its contents, with main numbered chapters only. Choose a chapter to read it, including all of its subsections. Subsections such as 2.1 and 2.2 are not separate menu options.
+
+After reading, you stay in the same document's contents menu. In an interactive pager, press `q` to finish reading. Choose `0. Back to documents` to return to the five-document menu; `0. Exit` there closes Thuk. Ctrl+C or end-of-input exits cleanly.
+
+A `Document introduction` entry preserves each document's preface and original contents page. PDF extraction can change table spacing; open the original PDF to see diagrams and exact formatting.
+
+## Search within a document
+
+Choose `S. Search this document`, then type a keyword or phrase such as `migrations` or `docker run`. Search is case-insensitive and treats the query literally.
+
+Thuk lists matching sections with match counts and preview lines. Choose a result to open its section. Every matching keyword in that section is highlighted as `[[keyword]]`, which is readable on Windows, Linux and macOS. After reading a search result you return to that document's contents. `0` at search results returns without opening a result; a blank query cancels search.
+
+Search maps each hit to its main chapter and opens that chapter with matching keywords highlighted. Contents-page hits appear under Document introduction.
+
+## Other commands
+
+```powershell
+thuk 1                           # Open Unit 2's contents menu
+thuk 3                           # Open the Django code contents menu
+thuk 3 --topic 2 --plain          # Print topic 2 and exit
+thuk 1 --full --plain             # Print the entire document
+thuk 3 --search migrations        # Interactive document search
+thuk --search Docker             # Print matches across all documents
+thuk 1 --pdf                      # Open the original PDF in your desktop viewer
+thuk 4 --export-pdf docker.pdf    # Save the original PDF
+```
+
+Use `python -m thuk` instead of `thuk` if the executable isn't on PATH. In piped/noninteractive CLI search, results are printed with topic numbers; open one using `--topic NUMBER`. PDF export replaces the destination file if it exists. Git is a text-only reference and has no source PDF.
+
+## Python API
+
+```python
+from thuk import get_text, list_topics, get_topic, search_topics
+
+print(list_topics(1))
+print(get_topic(1, 2))
+print(search_topics('Django', 1))
+print(get_text(1))
+```
+
+## Development
+
+```sh
+python -m pip install .
+python -m unittest discover -s tests -v
+python -m pip wheel --no-deps . -w dist
+```
+
+The topic index is stored in `src/thuk/data/contents.json` using zero-based start and exclusive end line offsets in the bundled text. Update that index whenever reference text line boundaries change. The four original PDFs retain their source authorship.

thuk-1.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "thuk"
+version = "1.0.1"
+description = "Offline terminal reference for Unit 2, Unit 5, Django, Docker and Git"
+readme = "README.md"
+requires-python = ">=3.9"
+classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent", "Topic :: Education"]
+
+[project.urls]
+Repository = "https://github.com/omparekh54-lgtm/thuk"
+
+[project.scripts]
+thuk = "thuk.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+thuk = ["data/*.txt", "data/*.pdf", "data/*.json"]

thuk-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

thuk-1.0.1/src/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-1.0.1/src/thuk/__main__.py

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

thuk-1.0.1/src/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