lens-qda 0.2.0__tar.gz

lens_qda-0.2.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+> Mirror of the project-root `/LICENSE`. Copy-edits should land in both files
+> (or replace this with `ln -s ../../LICENSE python/LICENSE` so there is one
+> source of truth).
+
+
+
+Copyright (c) 2026 Mark Bouck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lens_qda-0.2.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: lens-qda
+Version: 0.2.0
+Summary: Python utilities for LENS, a local-first qualitative data analysis (QDA) tool.
+Author: LENS contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mabo-du/lens
+Project-URL: Source, https://github.com/mabo-du/lens/tree/main/python
+Project-URL: Issues, https://github.com/mabo-du/lens/issues
+Project-URL: Changelog, https://github.com/mabo-du/lens/blob/main/CHANGELOG.md
+Keywords: qda,qualitative,research,pdf,text-mining
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber==0.11.4
+Dynamic: license-file
+
+# lens-qda
+
+Python utilities for **[LENS](https://github.com/mabo-du/lens)**, a local-first
+qualitative data analysis (QDA) desktop application.
+
+This package bundles the same PDF text-extraction pipeline that the LENS
+desktop app uses to ingest PDF documents, exposing it as a small CLI so it can
+also be used directly from Python or from shell scripts.
+
+## Install
+
+```bash
+pip install lens-qda
+```
+
+Requires Python 3.8+ and the prebuilt wheels for `pdfplumber` and its
+dependencies (`cryptography`, `pillow`, `pdfminer.six`, ...) on PyPI; no
+compiler is needed on supported platforms.
+
+## CLI usage
+
+```bash
+# Print plain text extracted from a PDF (one paragraph per page):
+lens-qda extract path/to/paper.pdf
+
+# Emit the same JSON envelope the LENS desktop sidecar produces:
+lens-qda extract paper.pdf --json
+
+# Save the extracted text to a file:
+lens-qda extract paper.pdf -o paper.txt
+
+# Tune pdfplumber's tolerances (defaults match the sidecar):
+lens-qda extract paper.pdf --x-tolerance 3 --y-tolerance 3
+```
+
+The `--json` schema matches the contract the LENS Tauri sidecar already
+implements:
+
+```json
+{ "success": true, "text": "...all pages, joined by blank lines..." }
+```
+
+On failure:
+
+```json
+{ "success": false, "error": "<exception message>" }
+```
+
+(the process exits with status 1 in that case).
+
+## Programmatic usage
+
+```python
+from pathlib import Path
+import json, subprocess
+
+result = subprocess.run(
+    ["lens-qda", "extract", "paper.pdf", "--json"],
+    capture_output=True, text=True, check=True,
+)
+envelope = json.loads(result.stdout)
+assert envelope["success"], envelope["error"]
+corpus = envelope["text"]
+```
+
+## License
+
+MIT — same as the parent [LENS](https://github.com/mabo-du/lens) project.

lens_qda-0.2.0/README.md

@@ -0,0 +1,68 @@
+# lens-qda
+
+Python utilities for **[LENS](https://github.com/mabo-du/lens)**, a local-first
+qualitative data analysis (QDA) desktop application.
+
+This package bundles the same PDF text-extraction pipeline that the LENS
+desktop app uses to ingest PDF documents, exposing it as a small CLI so it can
+also be used directly from Python or from shell scripts.
+
+## Install
+
+```bash
+pip install lens-qda
+```
+
+Requires Python 3.8+ and the prebuilt wheels for `pdfplumber` and its
+dependencies (`cryptography`, `pillow`, `pdfminer.six`, ...) on PyPI; no
+compiler is needed on supported platforms.
+
+## CLI usage
+
+```bash
+# Print plain text extracted from a PDF (one paragraph per page):
+lens-qda extract path/to/paper.pdf
+
+# Emit the same JSON envelope the LENS desktop sidecar produces:
+lens-qda extract paper.pdf --json
+
+# Save the extracted text to a file:
+lens-qda extract paper.pdf -o paper.txt
+
+# Tune pdfplumber's tolerances (defaults match the sidecar):
+lens-qda extract paper.pdf --x-tolerance 3 --y-tolerance 3
+```
+
+The `--json` schema matches the contract the LENS Tauri sidecar already
+implements:
+
+```json
+{ "success": true, "text": "...all pages, joined by blank lines..." }
+```
+
+On failure:
+
+```json
+{ "success": false, "error": "<exception message>" }
+```
+
+(the process exits with status 1 in that case).
+
+## Programmatic usage
+
+```python
+from pathlib import Path
+import json, subprocess
+
+result = subprocess.run(
+    ["lens-qda", "extract", "paper.pdf", "--json"],
+    capture_output=True, text=True, check=True,
+)
+envelope = json.loads(result.stdout)
+assert envelope["success"], envelope["error"]
+corpus = envelope["text"]
+```
+
+## License
+
+MIT — same as the parent [LENS](https://github.com/mabo-du/lens) project.

lens_qda-0.2.0/lens_qda/__init__.py

@@ -0,0 +1,11 @@
+"""lens-qda: Python utilities for the LENS qualitative data analysis tool.
+
+The version string is set at build time from the git tag by
+``.github/workflows/release.yml`` so PyPI releases stay in lockstep with the
+desktop release.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+__all__ = ["__version__"]

lens_qda-0.2.0/lens_qda/cli.py

@@ -0,0 +1,240 @@
+"""Command-line interface for ``lens-qda``.
+
+Mirrors the JSON-envelope contract of the Tauri PDF sidecar
+(``src-tauri/sidecars/pdfplumber/extract.py``) so the same Rust parser can
+consume output from the ``lens-qda extract --json`` invocation and from the
+bundled executable.
+
+Entry point declared in ``python/pyproject.toml``::
+
+    [project.scripts]
+    lens-qda = "lens_qda.cli:main"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+from lens_qda import __version__
+
+# Default tolerances must match src-tauri/sidecars/pdfplumber/extract.py
+# (the canonical Tauri sidecar) so the two code paths produce identical text.
+DEFAULT_X_TOLERANCE = 3
+DEFAULT_Y_TOLERANCE = 3
+
+
+def _extract_pages(
+    pdf_path: Path, *, x_tolerance: int, y_tolerance: int
+) -> list[str]:
+    # Imported lazily so `lens-qda --version` works without pdfplumber installed.
+    import pdfplumber  # type: ignore
+
+    chunks: list[str] = []
+    with pdfplumber.open(str(pdf_path)) as pdf:
+        for page in pdf.pages:
+            text = page.extract_text(
+                x_tolerance=x_tolerance, y_tolerance=y_tolerance
+            )
+            if text is None:
+                # Fallback matching the Tauri sidecar's resilience logic.
+                text = page.extract_text_simple()
+            if text:
+                chunks.append(text)
+    return chunks
+
+
+def extract_text(
+    pdf_path: Path,
+    *,
+    x_tolerance: int = DEFAULT_X_TOLERANCE,
+    y_tolerance: int = DEFAULT_Y_TOLERANCE,
+) -> str:
+    """Return plain text extracted from *pdf_path*, pages joined by blank lines."""
+    return "\n\n".join(
+        _extract_pages(pdf_path, x_tolerance=x_tolerance, y_tolerance=y_tolerance)
+    )
+
+
+def extract_json(
+    pdf_path: Path,
+    *,
+    x_tolerance: int = DEFAULT_X_TOLERANCE,
+    y_tolerance: int = DEFAULT_Y_TOLERANCE,
+) -> dict[str, object]:
+    """Return the JSON envelope the Tauri sidecar contract uses."""
+    try:
+        return {
+            "success": True,
+            "text": "\n\n".join(
+                _extract_pages(
+                    pdf_path,
+                    x_tolerance=x_tolerance,
+                    y_tolerance=y_tolerance,
+                )
+            ),
+        }
+    except Exception as exc:  # noqa: BLE001 — envelope must capture any failure
+        return {"success": False, "error": str(exc)}
+
+
+def _emit(text: str, output: Optional[Path]) -> None:
+    if output is None:
+        sys.stdout.write(text)
+        if not text.endswith("\n"):
+            sys.stdout.write("\n")
+        return
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text, encoding="utf-8")
+
+
+def _emit_envelope(envelope: dict[str, object], output: Optional[Path]) -> None:
+    """Emit the {success, text|error} JSON envelope consistently.
+
+    Always rendered with ``ensure_ascii=False`` so non-ASCII PDF text
+    round-trips identically in every CLI branch.
+    """
+    _emit(json.dumps(envelope, ensure_ascii=False), output)
+
+
+def cmd_extract(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+
+    # Distinguish a missing path from a non-regular-file path so the JSON
+    # envelope (and the stderr message) actually matches the failure cause.
+    if not path.exists():
+        msg = f"file not found: {path}"
+        if args.json:
+            _emit_envelope({"success": False, "error": msg}, args.output)
+        else:
+            sys.stderr.write(f"lens-qda: {msg}\n")
+        return 1
+    if not path.is_file():
+        msg = f"not a regular file: {path}"
+        if args.json:
+            _emit_envelope({"success": False, "error": msg}, args.output)
+        else:
+            sys.stderr.write(f"lens-qda: {msg}\n")
+        return 1
+
+    # ``extract_json`` always returns a dict (it catches every pdfplumber
+    # failure internally and converts it to ``{"success": False, "error": ...}``)
+    # so there is no exception to handle here — only the success-flag branch.
+    envelope = extract_json(
+        path, x_tolerance=args.x_tolerance, y_tolerance=args.y_tolerance
+    )
+
+    if not envelope["success"]:
+        if args.json:
+            _emit_envelope(envelope, args.output)
+        else:
+            sys.stderr.write(f"lens-qda: {envelope['error']}\n")
+        return 1
+
+    if args.json:
+        _emit_envelope(envelope, args.output)
+    else:
+        _emit(str(envelope["text"]), args.output)
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    # ``args.output`` is only present when the ``version`` *subparser* was used;
+    # ``lens-qda --version`` (top-level) does not populate it. ``getattr`` keeps
+    # both paths working without crashing on missing attributes.
+    _emit(__version__, getattr(args, "output", None))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="lens-qda",
+        description=(
+            "Python utilities for LENS, a local-first qualitative data analysis "
+            "(QDA) tool. Currently exposes a PDF text-extraction command that "
+            "matches the LENS desktop app's bundled sidecar."
+        ),
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="store_true",
+        help="print the lens-qda version and exit",
+    )
+
+    # Top-level defaults ensure `args.output` is always defined on the resulting
+    # Namespace so cmd_version / cmd_extract can safely read it regardless of
+    # whether the top-level parser or a subparser produced the namespace.
+    parser.set_defaults(output=None, version=False)
+
+    sub = parser.add_subparsers(dest="cmd", metavar="COMMAND")
+
+    p_extract = sub.add_parser(
+        "extract",
+        aliases=["x"],
+        help="extract text from a PDF document",
+        description=(
+            "Extract text from a PDF using pdfplumber, with tolerance settings "
+            "matching the LENS desktop sidecar. Print plain text by default; "
+            "pass --json to emit the {success, text|error} envelope consumed "
+            "by the Tauri Rust layer."
+        ),
+    )
+    p_extract.add_argument("path", help="path to a PDF file")
+    p_extract.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="write output to this file instead of stdout",
+    )
+    p_extract.add_argument(
+        "-j",
+        "--json",
+        action="store_true",
+        help="emit the JSON envelope {success, text|error} matching the sidecar",
+    )
+    p_extract.add_argument(
+        "--x-tolerance",
+        type=int,
+        default=DEFAULT_X_TOLERANCE,
+        help=f"horizontal text-clustering tolerance (default: {DEFAULT_X_TOLERANCE})",
+    )
+    p_extract.add_argument(
+        "--y-tolerance",
+        type=int,
+        default=DEFAULT_Y_TOLERANCE,
+        help=f"vertical text-clustering tolerance (default: {DEFAULT_Y_TOLERANCE})",
+    )
+    p_extract.set_defaults(func=cmd_extract)
+
+    p_version = sub.add_parser(
+        "version", help="print lens-qda version and exit"
+    )
+    p_version.add_argument(
+        "-o", "--output", type=Path, help="write version to this file instead of stdout"
+    )
+    p_version.set_defaults(func=cmd_version)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Console-script entry point declared in pyproject.toml."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        return cmd_version(args)
+
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help(sys.stderr)
+        return 1
+    return func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

lens_qda-0.2.0/lens_qda.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: lens-qda
+Version: 0.2.0
+Summary: Python utilities for LENS, a local-first qualitative data analysis (QDA) tool.
+Author: LENS contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mabo-du/lens
+Project-URL: Source, https://github.com/mabo-du/lens/tree/main/python
+Project-URL: Issues, https://github.com/mabo-du/lens/issues
+Project-URL: Changelog, https://github.com/mabo-du/lens/blob/main/CHANGELOG.md
+Keywords: qda,qualitative,research,pdf,text-mining
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber==0.11.4
+Dynamic: license-file
+
+# lens-qda
+
+Python utilities for **[LENS](https://github.com/mabo-du/lens)**, a local-first
+qualitative data analysis (QDA) desktop application.
+
+This package bundles the same PDF text-extraction pipeline that the LENS
+desktop app uses to ingest PDF documents, exposing it as a small CLI so it can
+also be used directly from Python or from shell scripts.
+
+## Install
+
+```bash
+pip install lens-qda
+```
+
+Requires Python 3.8+ and the prebuilt wheels for `pdfplumber` and its
+dependencies (`cryptography`, `pillow`, `pdfminer.six`, ...) on PyPI; no
+compiler is needed on supported platforms.
+
+## CLI usage
+
+```bash
+# Print plain text extracted from a PDF (one paragraph per page):
+lens-qda extract path/to/paper.pdf
+
+# Emit the same JSON envelope the LENS desktop sidecar produces:
+lens-qda extract paper.pdf --json
+
+# Save the extracted text to a file:
+lens-qda extract paper.pdf -o paper.txt
+
+# Tune pdfplumber's tolerances (defaults match the sidecar):
+lens-qda extract paper.pdf --x-tolerance 3 --y-tolerance 3
+```
+
+The `--json` schema matches the contract the LENS Tauri sidecar already
+implements:
+
+```json
+{ "success": true, "text": "...all pages, joined by blank lines..." }
+```
+
+On failure:
+
+```json
+{ "success": false, "error": "<exception message>" }
+```
+
+(the process exits with status 1 in that case).
+
+## Programmatic usage
+
+```python
+from pathlib import Path
+import json, subprocess
+
+result = subprocess.run(
+    ["lens-qda", "extract", "paper.pdf", "--json"],
+    capture_output=True, text=True, check=True,
+)
+envelope = json.loads(result.stdout)
+assert envelope["success"], envelope["error"]
+corpus = envelope["text"]
+```
+
+## License
+
+MIT — same as the parent [LENS](https://github.com/mabo-du/lens) project.

lens_qda-0.2.0/lens_qda.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+lens_qda/__init__.py
+lens_qda/cli.py
+lens_qda.egg-info/PKG-INFO
+lens_qda.egg-info/SOURCES.txt
+lens_qda.egg-info/dependency_links.txt
+lens_qda.egg-info/entry_points.txt
+lens_qda.egg-info/requires.txt
+lens_qda.egg-info/top_level.txt

lens_qda-0.2.0/lens_qda.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lens_qda-0.2.0/lens_qda.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lens-qda = lens_qda.cli:main

lens_qda-0.2.0/lens_qda.egg-info/requires.txt

@@ -0,0 +1 @@
+pdfplumber==0.11.4

lens_qda-0.2.0/lens_qda.egg-info/top_level.txt

@@ -0,0 +1 @@
+lens_qda

lens_qda-0.2.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+# setuptools>=69 so both the SPDX-string `license` field and the PEP 639
+# `[project] license-files = [...]` declaration are accepted by the build
+# validator.
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lens-qda"
+version = "0.2.0"  # dynamically rewritten in .github/workflows/release.yml from $GITHUB_REF_NAME
+description = "Python utilities for LENS, a local-first qualitative data analysis (QDA) tool."
+# `file = …` reads the FILE CONTENTS as the project long description; `text = …`
+# would set the literal 9-character string "README.md" (a footgun). PyPI will
+# render this as the package homepage body, so keep it pointing at the file.
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.8"
+# SPDX identifier form: universally supported by setuptools' validator across
+# versions that recognise PEP 639. Table form ``license = {file = "LICENSE"}``
+# requires a slightly newer validator and would make this package uninstallable
+# on older toolchains. The full text lives in ``python/LICENSE`` (mirror of the
+# project-root ``/LICENSE``; see the sync note in that file) and is listed
+# below via ``license-files`` so PyPI serves the full MIT body alongside the
+# SPDX badge.
+license = "MIT"
+license-files = ["LICENSE"]
+
+keywords = ["qda", "qualitative", "research", "pdf", "text-mining"]
+authors = [{ name = "LENS contributors" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    # No ``License :: ...`` classifier: PEP 639 forbids it when ``license``
+    # is an SPDX expression (which it is — see above).
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+    # Mirrors the canonical pdfplumber pin in
+    # src-tauri/sidecars/pdfplumber/requirements.txt (read by build.rs via the
+    # PDFPLUMBER_VERSION env var and by scripts/build-sidecar.sh). Bump BOTH
+    # consumers in lockstep so the bundled Tauri sidecar and this PyPI package
+    # always speak the same pdfplumber dialect.
+    "pdfplumber==0.11.4",
+]
+
+[project.urls]
+"Homepage"   = "https://github.com/mabo-du/lens"
+"Source"     = "https://github.com/mabo-du/lens/tree/main/python"
+"Issues"     = "https://github.com/mabo-du/lens/issues"
+"Changelog"  = "https://github.com/mabo-du/lens/blob/main/CHANGELOG.md"
+
+[project.scripts]
+lens-qda = "lens_qda.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["lens_qda*"]
+exclude = ["tests*"]

lens_qda-0.2.0/setup.cfg

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