np2 1.0.0__py3-none-any.whl

np2/__init__.py

@@ -0,0 +1,215 @@
+"""Offline IMAP reference. Start with import np2; np2.show()."""
+from importlib.resources import files
+import argparse
+import json
+import pydoc
+import sys
+
+__version__ = "1.0.0"
+__all__ = ["show", "commands", "units", "unit", "topics", "notes", "search", "main"]
+
+
+def _json(name):
+    return json.loads(files(__package__).joinpath("data", name + ".json").read_text(encoding="utf-8"))
+
+
+def _output(text, pager=False, return_text=False):
+    if return_text:
+        return text
+    if pager and sys.stdout.isatty():
+        pydoc.pager(text)
+    else:
+        print(text)
+    return None
+
+
+def _unit_number(value):
+    if isinstance(value, bool) or str(value) not in {"1", "2", "3", "4", "5"}:
+        raise ValueError("Unit must be an integer from 1 to 5.")
+    return int(value)
+
+
+def _match(query, *values):
+    return query.casefold() in " ".join(str(v) for v in values).casefold()
+
+
+def commands(group=None, query=None, *, pager=False, return_text=False):
+    """Display command examples and their use cases. Never execute examples."""
+    rows = _json("commands")
+    groups = list(dict.fromkeys(r["group"] for r in rows))
+    aliases = {"pip": "python", "npm": "react", "drf": "django", "postgres": "sql", "aws": "cloud", "ssh": "cloud"}
+    if group:
+        group = aliases.get(str(group).casefold(), str(group).casefold())
+        if group not in groups:
+            raise ValueError("Unknown group. Choose: " + ", ".join(groups))
+        rows = [r for r in rows if r["group"] == group]
+    if query:
+        rows = [r for r in rows if _match(query, r["group"], r["command"], r["use"])]
+    lines = ["SECTION 1 - COMMANDS AND USE CASES", "Examples only; replace <placeholders>. Commands are never executed.",
+             "Shell commands, SQL, ORM expressions and Dockerfile instructions are labelled separately."]
+    previous = None
+    for r in rows:
+        if r["group"] != previous:
+            previous = r["group"]
+            lines += ["", "[" + previous.upper() + "]"]
+        lines += [r["command"], "  Use: " + r["use"]]
+    if not rows:
+        lines.append("No matching commands.")
+    return _output("\n".join(lines), pager, return_text)
+
+
+def units(number=None, query=None, *, pager=False, return_text=False):
+    """Display all concise definitions, optionally filtered to a unit or phrase."""
+    number = _unit_number(number) if number is not None else None
+    rows = _json("definitions")
+    titles = {r["unit"]: r["title"] for r in _json("units")}
+    rows = [r for r in rows if (number is None or r["unit"] == number) and
+            (not query or _match(query, r["term"], r["definition"]))]
+    lines = ["SECTION 2 - UNIT-WISE DEFINITIONS", "Concise revision glossary; use notes() for full source explanations and code."]
+    previous = None
+    for r in rows:
+        if r["unit"] != previous:
+            previous = r["unit"]
+            lines += ["", f"UNIT {previous}: {titles[previous]}"]
+        lines += [r["term"], "  " + r["definition"]]
+    if not rows:
+        lines.append("No matching definitions.")
+    return _output("\n".join(lines), pager, return_text)
+
+
+unit = units
+
+
+def topics(number=None, *, pager=False, return_text=False):
+    """List every numbered source subsection and its original PDF page."""
+    number = _unit_number(number) if number is not None else None
+    rows = [r for r in _json("topics") if number is None or r["unit"] == number]
+    text = "SOURCE TOPICS\n" + "\n".join(f'{r["id"]:5} {r["title"]} (PDF p. {r["page"]})' for r in rows)
+    return _output(text, pager, return_text)
+
+
+def notes(number, *, pager=True, return_text=False):
+    """Display the complete extracted chapter for a unit (including examples).
+
+    Source wording is preserved, not independently fact-checked. PDF extraction
+    can flatten tables/code indentation. Original PDF page numbers are retained.
+    """
+    number = _unit_number(number)
+    text = files(__package__).joinpath("data", f"unit{number}.txt").read_text(encoding="utf-8")
+    header = "FULL SOURCE NOTES - UNIT " + str(number) + "\nPDF text extraction; table/code layout may differ.\n"
+    return _output(header + text, pager, return_text)
+
+
+def search(query, *, full=False, pager=False, return_text=False):
+    """Search commands, definitions and topic headings; full=True adds source lines."""
+    if not isinstance(query, str) or not query.strip():
+        raise ValueError("Provide a non-empty search phrase.")
+    parts = []
+    for r in _json("commands"):
+        if _match(query, r["group"], r["command"], r["use"]):
+            parts.append(f'[command/{r["group"]}] {r["command"]}\n  {r["use"]}')
+    for r in _json("definitions"):
+        if _match(query, r["term"], r["definition"]):
+            parts.append(f'[unit {r["unit"]}] {r["term"]}\n  {r["definition"]}')
+    for r in _json("topics"):
+        if _match(query, r["title"], r["id"]):
+            parts.append(f'[topic {r["id"]}, PDF p. {r["page"]}] {r["title"]}')
+    if full:
+        for number in range(1, 6):
+            page = "?"
+            text = files(__package__).joinpath("data", f"unit{number}.txt").read_text(encoding="utf-8")
+            for line in text.splitlines():
+                if line.startswith("--- PDF page "):
+                    page = line.split()[3]
+                elif _match(query, line):
+                    parts.append(f'[source unit {number}, PDF p. {page}] {line.strip()}')
+    return _output("\n\n".join(parts) if parts else "No matches found.", pager, return_text)
+
+
+def show(section=None, *, unit=None, group=None, query=None, pager=False, return_text=False):
+    """show(): two-section menu; show(1): commands; show(2): definitions.
+
+    Examples: show(1, group='docker'); show(2, unit=3); show('all').
+    """
+    key = str(section).casefold() if section is not None else None
+    if key in {"1", "commands", "command"}:
+        if unit is not None:
+            raise ValueError("Use unit= with section 2; use group= with section 1.")
+        return commands(group, query, pager=pager, return_text=return_text)
+    if key in {"2", "units", "unit", "definitions"} or (key is None and unit is not None):
+        if group is not None:
+            raise ValueError("Use group= with section 1.")
+        return units(unit, query, pager=pager, return_text=return_text)
+    if key == "all":
+        text = commands(group, query, return_text=True) + "\n\n" + units(unit, query, return_text=True)
+        return _output(text, pager, return_text)
+    if key is None and group is not None:
+        return commands(group, query, pager=pager, return_text=return_text)
+    if key is None and query:
+        return search(query, pager=pager, return_text=return_text)
+    if key is not None:
+        raise ValueError("Section must be 1/'commands', 2/'units', or 'all'.")
+    counts = (len(_json("commands")), len(_json("definitions")), len(_json("topics")))
+    menu = f'''NP2 - OFFLINE IMAP REVISION ({__version__})
+{counts[0]} command examples | {counts[1]} definitions | {counts[2]} source topics | 5 units
+
+1. COMMANDS + USE CASES
+   np2.show(1)                         All commands, grouped by tool
+   np2.show(1, group="git")             Git commands
+   np2.show(1, group="docker")          Docker commands
+   np2.show(1, group="compose")         Compose commands
+   np2.show(1, query="migrate")         Filter command examples
+
+2. UNIT-WISE DEFINITIONS
+   np2.show(2)                         Definitions for all five units
+   np2.show(2, unit=1)                  Definitions for Unit 1
+   np2.unit(4)                         Shortcut for Unit 4
+   np2.topics(4)                       Source subsection/page index
+   np2.notes(4)                        Full Unit 4 text and code
+
+   np2.search("promise")               Search both sections
+   np2.search("promise", full=True)    Also search complete unit text
+   np2.show("all", pager=True)         Read both sections with paging
+
+Units: 1 Web/Git | 2 Python/Django | 3 Databases/Cloud | 4 React | 5 Docker
+Use import np2 as NP2 if you prefer NP2.show().
+This is an offline study reference. It does not run the displayed commands.'''
+    return _output(menu, pager, return_text)
+
+
+def main(argv=None):
+    """Command-line interface: np2 commands docker; np2 unit 1; np2 search hooks."""
+    parser = argparse.ArgumentParser(prog="np2", description="Offline IMAP study reference")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--pager", action="store_true", help="Page output in an interactive terminal")
+    sub = parser.add_subparsers(dest="action")
+    cmd = sub.add_parser("commands", help="Section 1: commands with use cases")
+    cmd.add_argument("group", nargs="?")
+    cmd.add_argument("--query")
+    unt = sub.add_parser("unit", aliases=["units"], help="Section 2: unit definitions")
+    unt.add_argument("number", nargs="?", type=int)
+    unt.add_argument("--query")
+    top = sub.add_parser("topics", help="Source subsection index")
+    top.add_argument("number", nargs="?", type=int)
+    note = sub.add_parser("notes", help="Complete source chapter")
+    note.add_argument("number", type=int)
+    find = sub.add_parser("search", help="Search all reference entries")
+    find.add_argument("query")
+    find.add_argument("--full", action="store_true")
+    sub.add_parser("all", help="Show both complete sections")
+    args = parser.parse_args(argv)
+    try:
+        if args.action == "commands":
+            commands(args.group, args.query, pager=args.pager)
+        elif args.action in {"unit", "units"}:
+            units(args.number, args.query, pager=args.pager)
+        elif args.action == "topics":
+            topics(args.number, pager=args.pager)
+        elif args.action == "notes":
+            notes(args.number, pager=args.pager)
+        elif args.action == "search":
+            search(args.query, full=args.full, pager=args.pager)
+        else:
+            show("all" if args.action == "all" else None, pager=args.pager)
+    except ValueError as error:
+        parser.error(str(error))

np2/__main__.py

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