openansho 0.1.0__py3-none-any.whl

openansho/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

openansho/__main__.py

@@ -0,0 +1,39 @@
+import sys
+from pathlib import Path
+
+from PySide6.QtGui import QIcon
+from PySide6.QtWidgets import QApplication
+
+from openansho.ui.main_window import MainWindow
+
+
+ICON_FILENAME = "kanji_shou_app_icon.png"
+
+
+def _icon_path() -> Path:
+    # Three layouts to cover: PyInstaller extracts bundled data files (see the
+    # Makefile's --add-data) under sys._MEIPASS; an installed wheel carries the
+    # icon inside the package (see pyproject's force-include); a source checkout
+    # has it at the repo root, which is where the Makefile reads it from.
+    meipass = getattr(sys, "_MEIPASS", None)
+    if meipass:
+        return Path(meipass) / "images" / ICON_FILENAME
+    packaged = Path(__file__).resolve().parent / ICON_FILENAME
+    if packaged.exists():
+        return packaged
+    return Path(__file__).resolve().parent.parent.parent / "images" / ICON_FILENAME
+
+
+def main() -> None:
+    app = QApplication(sys.argv)
+    app.setWindowIcon(QIcon(str(_icon_path())))
+    window = MainWindow()
+    # Start in the built-in tutorial so the app opens onto something codeable;
+    # it's an in-memory project, so it costs the user nothing to abandon.
+    window.open_tutorial_project()
+    window.show()
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

openansho/db.py

@@ -0,0 +1,363 @@
+"""SQLite-backed data access layer for OpenAnsho projects.
+
+A project is a single .sqlite file containing documents, a codebook
+(codes, possibly nested), and the coded segments linking the two.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS documents (
+    id INTEGER PRIMARY KEY,
+    name TEXT NOT NULL,
+    content TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS codes (
+    id INTEGER PRIMARY KEY,
+    name TEXT NOT NULL,
+    parent_id INTEGER REFERENCES codes(id) ON DELETE CASCADE,
+    color TEXT,
+    color_class TEXT,
+    description TEXT,
+    created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS segments (
+    id INTEGER PRIMARY KEY,
+    document_id INTEGER NOT NULL REFERENCES documents(id) ON DELETE CASCADE,
+    code_id INTEGER NOT NULL REFERENCES codes(id) ON DELETE CASCADE,
+    start_offset INTEGER NOT NULL,
+    end_offset INTEGER NOT NULL,
+    memo TEXT,
+    created_by TEXT,
+    created_at TEXT NOT NULL
+);
+"""
+
+
+@dataclass(frozen=True)
+class Document:
+    id: int
+    name: str
+    content: str
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Code:
+    id: int
+    name: str
+    parent_id: int | None
+    color: str | None
+    color_class: str | None
+    description: str | None
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Segment:
+    id: int
+    document_id: int
+    code_id: int
+    start_offset: int
+    end_offset: int
+    memo: str | None
+    created_by: str | None
+    created_at: str
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def connect(path: str | Path) -> sqlite3.Connection:
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    init_db(conn)
+    return conn
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    conn.executescript(SCHEMA)
+    _migrate(conn)
+    conn.commit()
+
+
+def _migrate(conn: sqlite3.Connection) -> None:
+    """Add columns introduced after a project's initial creation."""
+    columns = {row["name"] for row in conn.execute("PRAGMA table_info(segments)")}
+    if "created_by" not in columns:
+        conn.execute("ALTER TABLE segments ADD COLUMN created_by TEXT")
+
+    code_columns = {row["name"] for row in conn.execute("PRAGMA table_info(codes)")}
+    if "color_class" not in code_columns:
+        conn.execute("ALTER TABLE codes ADD COLUMN color_class TEXT")
+    if "description" not in code_columns:
+        conn.execute("ALTER TABLE codes ADD COLUMN description TEXT")
+
+
+def create_document(conn: sqlite3.Connection, name: str, content: str) -> Document:
+    cur = conn.execute(
+        "INSERT INTO documents (name, content, created_at) VALUES (?, ?, ?)",
+        (name, content, _now()),
+    )
+    conn.commit()
+    return get_document(conn, cur.lastrowid)
+
+
+def get_document(conn: sqlite3.Connection, document_id: int) -> Document | None:
+    row = conn.execute(
+        "SELECT * FROM documents WHERE id = ?", (document_id,)
+    ).fetchone()
+    return Document(**row) if row else None
+
+
+def list_documents(conn: sqlite3.Connection) -> list[Document]:
+    rows = conn.execute("SELECT * FROM documents ORDER BY id").fetchall()
+    return [Document(**row) for row in rows]
+
+
+def get_document_by_name(conn: sqlite3.Connection, name: str) -> Document | None:
+    row = conn.execute(
+        "SELECT * FROM documents WHERE name = ?", (name,)
+    ).fetchone()
+    return Document(**row) if row else None
+
+
+def delete_document(conn: sqlite3.Connection, document_id: int) -> None:
+    conn.execute("DELETE FROM documents WHERE id = ?", (document_id,))
+    conn.commit()
+
+
+def update_document_content(
+    conn: sqlite3.Connection, document_id: int, content: str
+) -> Document:
+    conn.execute(
+        "UPDATE documents SET content = ? WHERE id = ?", (content, document_id)
+    )
+    conn.commit()
+    return get_document(conn, document_id)
+
+
+def create_code(
+    conn: sqlite3.Connection,
+    name: str,
+    parent_id: int | None = None,
+    color: str | None = None,
+    color_class: str | None = None,
+    description: str | None = None,
+) -> Code:
+    cur = conn.execute(
+        "INSERT INTO codes (name, parent_id, color, color_class, description, created_at) "
+        "VALUES (?, ?, ?, ?, ?, ?)",
+        (name, parent_id, color, color_class, description, _now()),
+    )
+    conn.commit()
+    return get_code(conn, cur.lastrowid)
+
+
+def get_code(conn: sqlite3.Connection, code_id: int) -> Code | None:
+    row = conn.execute("SELECT * FROM codes WHERE id = ?", (code_id,)).fetchone()
+    return Code(**row) if row else None
+
+
+def list_codes(conn: sqlite3.Connection) -> list[Code]:
+    rows = conn.execute("SELECT * FROM codes ORDER BY id").fetchall()
+    return [Code(**row) for row in rows]
+
+
+def rename_code(conn: sqlite3.Connection, code_id: int, name: str) -> Code:
+    conn.execute("UPDATE codes SET name = ? WHERE id = ?", (name, code_id))
+    conn.commit()
+    return get_code(conn, code_id)
+
+
+def set_code_description(conn: sqlite3.Connection, code_id: int, description: str | None) -> Code:
+    conn.execute("UPDATE codes SET description = ? WHERE id = ?", (description, code_id))
+    conn.commit()
+    return get_code(conn, code_id)
+
+
+def set_code_parent(conn: sqlite3.Connection, code_id: int, parent_id: int | None) -> Code:
+    conn.execute("UPDATE codes SET parent_id = ? WHERE id = ?", (parent_id, code_id))
+    conn.commit()
+    return get_code(conn, code_id)
+
+
+def set_code_color(
+    conn: sqlite3.Connection, code_id: int, color: str, color_class: str
+) -> Code:
+    conn.execute(
+        "UPDATE codes SET color = ?, color_class = ? WHERE id = ?",
+        (color, color_class, code_id),
+    )
+    conn.commit()
+    return get_code(conn, code_id)
+
+
+def count_codes_by_color_class(conn: sqlite3.Connection) -> dict[str, int]:
+    """Map color_class -> number of codes (root or child) assigned to it."""
+    rows = conn.execute(
+        "SELECT color_class, COUNT(*) AS count FROM codes "
+        "WHERE color_class IS NOT NULL GROUP BY color_class"
+    ).fetchall()
+    return {row["color_class"]: row["count"] for row in rows}
+
+
+def delete_code(conn: sqlite3.Connection, code_id: int) -> None:
+    """Delete a code, re-parenting its children to its own parent (or to root).
+
+    `codes.parent_id` cascades on delete, so children would otherwise be
+    deleted along with their parent; re-pointing them first avoids that.
+    """
+    code = get_code(conn, code_id)
+    if code is None:
+        return
+    conn.execute(
+        "UPDATE codes SET parent_id = ? WHERE parent_id = ?", (code.parent_id, code_id)
+    )
+    conn.execute("DELETE FROM codes WHERE id = ?", (code_id,))
+    conn.commit()
+
+
+def merge_codes(conn: sqlite3.Connection, keep_id: int, merge_id: int) -> None:
+    """Merge `merge_id` into `keep_id`.
+
+    Segments coded with `merge_id` are re-coded to `keep_id`, dropping any
+    that would exactly duplicate a segment `keep_id` already has. Children of
+    `merge_id` are re-parented to `keep_id` before it's deleted, the same
+    cascade-dodging move `delete_code` makes for its own children.
+    """
+    keep_segments = {
+        (s.document_id, s.start_offset, s.end_offset, s.created_by)
+        for s in list_segments_for_code(conn, keep_id)
+    }
+    for segment in list_segments_for_code(conn, merge_id):
+        key = (segment.document_id, segment.start_offset, segment.end_offset, segment.created_by)
+        if key in keep_segments:
+            conn.execute("DELETE FROM segments WHERE id = ?", (segment.id,))
+        else:
+            conn.execute(
+                "UPDATE segments SET code_id = ? WHERE id = ?", (keep_id, segment.id)
+            )
+            keep_segments.add(key)
+    conn.execute(
+        "UPDATE codes SET parent_id = ? WHERE parent_id = ?", (keep_id, merge_id)
+    )
+    conn.execute("DELETE FROM codes WHERE id = ?", (merge_id,))
+    conn.commit()
+
+
+def create_segment(
+    conn: sqlite3.Connection,
+    document_id: int,
+    code_id: int,
+    start_offset: int,
+    end_offset: int,
+    memo: str | None = None,
+    created_by: str | None = None,
+) -> Segment:
+    if end_offset <= start_offset:
+        raise ValueError("end_offset must be greater than start_offset")
+    existing = conn.execute(
+        """
+        SELECT * FROM segments
+        WHERE document_id = ? AND code_id = ? AND start_offset = ? AND end_offset = ?
+            AND created_by IS ?
+        """,
+        (document_id, code_id, start_offset, end_offset, created_by),
+    ).fetchone()
+    if existing is not None:
+        return Segment(**existing)
+    cur = conn.execute(
+        """
+        INSERT INTO segments
+            (document_id, code_id, start_offset, end_offset, memo, created_by, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        """,
+        (document_id, code_id, start_offset, end_offset, memo, created_by, _now()),
+    )
+    conn.commit()
+    return get_segment(conn, cur.lastrowid)
+
+
+def get_segment(conn: sqlite3.Connection, segment_id: int) -> Segment | None:
+    row = conn.execute(
+        "SELECT * FROM segments WHERE id = ?", (segment_id,)
+    ).fetchone()
+    return Segment(**row) if row else None
+
+
+def list_segments_for_document(
+    conn: sqlite3.Connection, document_id: int
+) -> list[Segment]:
+    rows = conn.execute(
+        "SELECT * FROM segments WHERE document_id = ? ORDER BY start_offset",
+        (document_id,),
+    ).fetchall()
+    return [Segment(**row) for row in rows]
+
+
+def list_segments_for_code(conn: sqlite3.Connection, code_id: int) -> list[Segment]:
+    rows = conn.execute(
+        "SELECT * FROM segments WHERE code_id = ? ORDER BY id", (code_id,)
+    ).fetchall()
+    return [Segment(**row) for row in rows]
+
+
+def list_all_segments(conn: sqlite3.Connection) -> list[Segment]:
+    rows = conn.execute("SELECT * FROM segments ORDER BY id").fetchall()
+    return [Segment(**row) for row in rows]
+
+
+def list_distinct_usernames(conn: sqlite3.Connection) -> list[str | None]:
+    """Distinct `segments.created_by` values with at least one segment.
+
+    `None` is included if any segment has no recorded creator.
+    """
+    rows = conn.execute("SELECT DISTINCT created_by FROM segments").fetchall()
+    return [row["created_by"] for row in rows]
+
+
+def count_segments_by_code(
+    conn: sqlite3.Connection, document_id: int | None = None
+) -> dict[int, int]:
+    """Map code_id -> number of segments coded with it.
+
+    Codes with no segments are omitted, so callers should default to 0.
+    """
+    if document_id is None:
+        rows = conn.execute(
+            "SELECT code_id, COUNT(*) AS count FROM segments GROUP BY code_id"
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT code_id, COUNT(*) AS count FROM segments WHERE document_id = ? "
+            "GROUP BY code_id",
+            (document_id,),
+        ).fetchall()
+    return {row["code_id"]: row["count"] for row in rows}
+
+
+def delete_segment(conn: sqlite3.Connection, segment_id: int) -> None:
+    conn.execute("DELETE FROM segments WHERE id = ?", (segment_id,))
+    conn.commit()
+
+
+def update_segment_offsets(
+    conn: sqlite3.Connection, segment_id: int, start_offset: int, end_offset: int
+) -> Segment:
+    conn.execute(
+        "UPDATE segments SET start_offset = ?, end_offset = ? WHERE id = ?",
+        (start_offset, end_offset, segment_id),
+    )
+    conn.commit()
+    return get_segment(conn, segment_id)

openansho/reporting.py

@@ -0,0 +1,153 @@
+"""Export and aggregate reporting over a project's coded segments.
+
+These functions operate directly on a sqlite3.Connection so they can
+be used from the UI, a future CLI, or tests without any Qt dependency.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import sqlite3
+from pathlib import Path
+
+from openansho import db
+from openansho.db import Code
+
+CSV_FIELDNAMES = [
+    "document",
+    "code",
+    "start_offset",
+    "end_offset",
+    "text",
+    "memo",
+    "username",
+    "created_at",
+]
+
+
+def code_path(codes_by_id: dict[int, Code], code_id: int) -> str:
+    parts = []
+    current = codes_by_id.get(code_id)
+    while current is not None:
+        parts.append(current.name)
+        current = codes_by_id.get(current.parent_id) if current.parent_id else None
+    return " > ".join(reversed(parts))
+
+
+def _segment_rows(conn: sqlite3.Connection) -> list[dict]:
+    codes_by_id = {code.id: code for code in db.list_codes(conn)}
+    documents = db.list_documents(conn)
+
+    rows = []
+    for document in documents:
+        for segment in db.list_segments_for_document(conn, document.id):
+            rows.append(
+                {
+                    "document": document.name,
+                    "code": code_path(codes_by_id, segment.code_id),
+                    "start_offset": segment.start_offset,
+                    "end_offset": segment.end_offset,
+                    "text": document.content[segment.start_offset : segment.end_offset],
+                    "memo": segment.memo or "",
+                    "username": segment.created_by or "",
+                    "created_at": segment.created_at,
+                }
+            )
+    rows.sort(key=lambda row: (row["document"], row["start_offset"]))
+    return rows
+
+
+def export_segments_csv(conn: sqlite3.Connection, path: str | Path) -> int:
+    rows = _segment_rows(conn)
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=CSV_FIELDNAMES)
+        writer.writeheader()
+        writer.writerows(rows)
+    return len(rows)
+
+
+def export_segments_json(conn: sqlite3.Connection, path: str | Path) -> int:
+    rows = _segment_rows(conn)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(rows, f, indent=2)
+    return len(rows)
+
+
+def code_frequency(conn: sqlite3.Connection) -> list[dict]:
+    codes_by_id = {code.id: code for code in db.list_codes(conn)}
+    rows = [
+        {
+            "code_id": code_id,
+            "path": code_path(codes_by_id, code_id),
+            "count": len(db.list_segments_for_code(conn, code_id)),
+        }
+        for code_id in codes_by_id
+    ]
+    rows.sort(key=lambda row: (-row["count"], row["path"]))
+    return rows
+
+
+def code_user_frequency(conn: sqlite3.Connection) -> list[dict]:
+    """One row per (code, user) pair: the code, its parent, the username, and
+    how many segments that user has coded with that code across the dataset."""
+    codes_by_id = {code.id: code for code in db.list_codes(conn)}
+
+    counts: dict[tuple[int, str], int] = {}
+    for code_id in codes_by_id:
+        for segment in db.list_segments_for_code(conn, code_id):
+            key = (code_id, segment.created_by or "")
+            counts[key] = counts.get(key, 0) + 1
+
+    rows = []
+    for (code_id, username), count in counts.items():
+        code = codes_by_id[code_id]
+        parent = codes_by_id.get(code.parent_id) if code.parent_id else None
+        rows.append(
+            {
+                "code": code.name,
+                "parent": parent.name if parent else "",
+                "username": username,
+                "count": count,
+            }
+        )
+    rows.sort(key=lambda row: (row["code"], row["username"]))
+    return rows
+
+
+CODE_FREQUENCY_CSV_FIELDNAMES = ["code", "count"]
+CODE_USER_FREQUENCY_CSV_FIELDNAMES = ["code", "parent", "username", "count"]
+
+
+def export_code_frequency_csv(conn: sqlite3.Connection, path: str | Path) -> int:
+    rows = code_frequency(conn)
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=CODE_FREQUENCY_CSV_FIELDNAMES)
+        writer.writeheader()
+        for row in rows:
+            writer.writerow({"code": row["path"], "count": row["count"]})
+    return len(rows)
+
+
+def export_code_frequency_json(conn: sqlite3.Connection, path: str | Path) -> int:
+    rows = code_frequency(conn)
+    export_rows = [{"code": row["path"], "count": row["count"]} for row in rows]
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(export_rows, f, indent=2)
+    return len(rows)
+
+
+def export_code_user_frequency_csv(conn: sqlite3.Connection, path: str | Path) -> int:
+    rows = code_user_frequency(conn)
+    with open(path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=CODE_USER_FREQUENCY_CSV_FIELDNAMES)
+        writer.writeheader()
+        writer.writerows(rows)
+    return len(rows)
+
+
+def export_code_user_frequency_json(conn: sqlite3.Connection, path: str | Path) -> int:
+    rows = code_user_frequency(conn)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(rows, f, indent=2)
+    return len(rows)

openansho/text_extract.py

@@ -0,0 +1,97 @@
+"""Turn an on-disk document into the plain text OpenAnsho codes against.
+
+Like `db.py` and `reporting.py`, this module has no Qt imports: the UI hands it
+a path and gets back a string (or a `DocumentReadError` carrying a message fit
+for a dialog).
+
+The `.docx` reader is hand-rolled on top of `zipfile`/`xml.etree` rather than
+`python-docx` so the packaged app keeps its single third-party dependency.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+import zipfile
+from pathlib import Path
+
+W_NAMESPACE = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+DOCX_BODY_PART = "word/document.xml"
+
+
+class DocumentReadError(Exception):
+    """A document couldn't be read; the message is shown to the user as-is."""
+
+
+def read_document_text(path: Path) -> str:
+    """Read `path` as plain text, dispatching on its extension."""
+    suffix = path.suffix.lower()
+    if suffix == ".docx":
+        return read_docx_text(path)
+    if suffix == ".doc":
+        raise DocumentReadError(
+            f"{path.name} is a legacy Word document. Open it in Word and save it "
+            "as .docx (or plain text), then import that."
+        )
+    try:
+        return path.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        raise DocumentReadError(f"Could not read {path.name} as UTF-8 text.") from None
+    except OSError as exc:
+        raise DocumentReadError(f"Could not read {path.name}: {exc}") from None
+
+
+def read_docx_text(path: Path) -> str:
+    """Extract the body text of a `.docx` file, one line per paragraph.
+
+    Paragraphs are visited in document order, including those nested inside
+    tables (each table cell's paragraphs become their own lines).
+    """
+    try:
+        with zipfile.ZipFile(path) as archive:
+            try:
+                body_xml = archive.read(DOCX_BODY_PART)
+            except KeyError:
+                raise DocumentReadError(
+                    f"{path.name} is not a valid Word document "
+                    f"(it has no {DOCX_BODY_PART})."
+                ) from None
+    except zipfile.BadZipFile:
+        raise DocumentReadError(
+            f"{path.name} is not a valid Word document (it is not a .docx archive)."
+        ) from None
+    except OSError as exc:
+        raise DocumentReadError(f"Could not read {path.name}: {exc}") from None
+
+    try:
+        root = ET.fromstring(body_xml)
+    except ET.ParseError as exc:
+        raise DocumentReadError(f"Could not parse {path.name}: {exc}") from None
+
+    body = root.find(_w("body"))
+    if body is None:
+        body = root
+    paragraphs = [_paragraph_text(p) for p in body.iter(_w("p"))]
+    return "\n".join(paragraphs)
+
+
+def _w(tag: str) -> str:
+    return f"{{{W_NAMESPACE}}}{tag}"
+
+
+def _paragraph_text(paragraph: ET.Element) -> str:
+    """Flatten one `w:p` into a line of text.
+
+    Only `w:t` runs contribute characters, which conveniently skips field
+    instructions (`w:instrText`) and tracked deletions (`w:delText`); tabs and
+    in-paragraph breaks are preserved as whitespace.
+    """
+    pieces: list[str] = []
+    for node in paragraph.iter():
+        tag = node.tag
+        if tag == _w("t"):
+            pieces.append(node.text or "")
+        elif tag == _w("tab"):
+            pieces.append("\t")
+        elif tag in (_w("br"), _w("cr")):
+            pieces.append("\n")
+    return "".join(pieces)

openansho/tutorial.py

@@ -0,0 +1,41 @@
+"""The built-in tutorial project.
+
+The app opens this project at startup so a first-time user has something to
+code without importing anything first. Its database lives in memory rather
+than in a .sqlite file, so whatever codebook the user builds while following
+along is discarded on quit and the tutorial is fresh again on the next launch.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+import sys
+from pathlib import Path
+
+from openansho import db
+
+DOCUMENT_NAME = "tutorial.txt"
+
+
+def tutorial_text_path() -> Path:
+    """Locate the tutorial text, bundled or running from source.
+
+    PyInstaller extracts the bundled copy (see the Makefile's --add-data and
+    OpenAnsho.spec) under sys._MEIPASS at runtime; fall back to the file
+    sitting next to this module when running from a source checkout.
+    """
+    meipass = getattr(sys, "_MEIPASS", None)
+    if meipass:
+        return Path(meipass) / "openansho" / DOCUMENT_NAME
+    return Path(__file__).resolve().with_name(DOCUMENT_NAME)
+
+
+def read_tutorial_text() -> str:
+    return tutorial_text_path().read_text(encoding="utf-8")
+
+
+def open_tutorial_project() -> sqlite3.Connection:
+    """Open a throwaway in-memory project holding just the tutorial document."""
+    conn = db.connect(":memory:")
+    db.create_document(conn, DOCUMENT_NAME, read_tutorial_text())
+    return conn