Metadata-Version: 2.4
Name: thuk
Version: 1.1.0
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
6. Answer a question
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.

## Answer a question (offline)

Choose `6. Answer a question` in the main menu to ask across all five documents.
Inside a document, choose `A. Answer a question from this document` to restrict
answers to that document. Type a question, for example `What is the difference
between containers and virtual machines?` or `Explain MVT`.

Thuk ranks passages using words from your question, simple plural matching and
common acronyms. It returns up to three **exact excerpts** with document, main
chapter, topic number and source line references. It requires no AI model, API
key, internet or extra dependencies. This is extractive retrieval: it does not
write a new explanation, solve exercises, or reliably understand every paraphrase.
Matching passages may be incomplete; check the cited chapter for full context.
Questions whose significant terms do not all match a passage get a clear no-match
message; rephrase using words from your notes if needed.

After each answer you can ask another question. Enter `0` or a blank question to
return to the menu you opened it from. Existing reading and search navigation is
preserved.

```powershell
thuk --ask "What is the difference between containers and virtual machines?"
thuk 1 --ask "Explain MVT" --plain
```

The Python API is `answer_question(question, section=None, limit=3)`. It returns
`question`, `found`, `answer` and `sources`; each source includes `section`,
`document`, `topic`, `title`, `line_start`, `line_end` and `excerpt`.

## 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.
