pydfdoi 0.1.1__py3-none-any.whl

pydfdoi/__init__.py

@@ -0,0 +1,57 @@
+"""Tools for DOI-aware PDF metadata and citation-based PDF renaming."""
+
+__version__ = "0.1.1"
+
+from .citation import build_citation_filename, clean_filename_piece
+from .crossref import fetch_crossref_item
+from .doi import normalize_doi
+from .metadata import (
+    DoiMetadata,
+    capture_book_doi,
+    capture_doi_metadata,
+    capture_journal_doi,
+    classify_by_page_count,
+    classify_crossref_type,
+)
+from .page_labels import (
+    ArticlePageRange,
+    PageLabelPlan,
+    align_journal_article_page_labels,
+    build_page_label_plan,
+    parse_crossref_page_range,
+)
+from .pdf import capture_and_write_doi_metadata, count_pdf_pages, extract_doi, write_pdf_metadata
+from .processing import PdfResult, process_journal_page_labels, process_pdf, process_pdf_metadata_only, rename_by_citation
+from .publishers import PUBLISHERS, PublisherInfo, publisher_for_doi, publisher_for_name
+
+__all__ = [
+    "PdfResult",
+    "DoiMetadata",
+    "PUBLISHERS",
+    "ArticlePageRange",
+    "PageLabelPlan",
+    "PublisherInfo",
+    "__version__",
+    "build_citation_filename",
+    "build_page_label_plan",
+    "capture_and_write_doi_metadata",
+    "capture_book_doi",
+    "capture_doi_metadata",
+    "capture_journal_doi",
+    "classify_by_page_count",
+    "classify_crossref_type",
+    "clean_filename_piece",
+    "count_pdf_pages",
+    "extract_doi",
+    "fetch_crossref_item",
+    "align_journal_article_page_labels",
+    "normalize_doi",
+    "parse_crossref_page_range",
+    "process_pdf",
+    "process_journal_page_labels",
+    "process_pdf_metadata_only",
+    "publisher_for_doi",
+    "publisher_for_name",
+    "rename_by_citation",
+    "write_pdf_metadata",
+]

pydfdoi/citation.py

@@ -0,0 +1,56 @@
+"""Citation metadata formatting for filenames."""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import Path
+
+INVALID_FILENAME_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f]')
+WHITESPACE_RE = re.compile(r"\s+")
+
+
+def clean_filename_piece(text: str) -> str:
+    text = unicodedata.normalize("NFKC", text)
+    text = INVALID_FILENAME_CHARS.sub(" ", text)
+    text = WHITESPACE_RE.sub(" ", text)
+    return text.strip(" .")
+
+
+def first_author_label(item: dict) -> str:
+    authors = item.get("author") or []
+    if not authors:
+        return "Unknown"
+    first = authors[0]
+    family = clean_filename_piece(first.get("family") or first.get("name") or "Unknown")
+    return family if len(authors) == 1 else f"{family} et al."
+
+
+def item_year(item: dict) -> str:
+    for key in ("published-print", "published-online", "published", "issued", "created"):
+        parts = ((item.get(key) or {}).get("date-parts") or [])
+        if parts and parts[0]:
+            return str(parts[0][0])
+    return "n.d."
+
+
+def item_title(item: dict) -> str:
+    titles = item.get("title") or []
+    return clean_filename_piece(titles[0] if titles else "Untitled")
+
+
+def build_citation_filename(item: dict, *, extension: str = ".pdf", max_name_chars: int = 180) -> str:
+    filename = clean_filename_piece(f"{first_author_label(item)} {item_year(item)} {item_title(item)}")
+    if len(filename) > max_name_chars:
+        filename = filename[:max_name_chars].rstrip(" .")
+    return f"{filename}{extension}"
+
+
+def unique_path(path: Path) -> Path:
+    if not path.exists():
+        return path
+    for number in range(2, 1000):
+        candidate = path.with_name(f"{path.stem} ({number}){path.suffix}")
+        if not candidate.exists():
+            return candidate
+    raise FileExistsError(f"Could not find an unused filename for {path}")

pydfdoi/cli.py

@@ -0,0 +1,102 @@
+"""Command-line interface for pydfdoi."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Iterable
+
+from .processing import process_journal_page_labels, process_pdf, process_pdf_metadata_only
+
+
+def choose_files_with_dialog() -> list[str]:
+    import tkinter as tk
+    from tkinter import filedialog
+
+    root = tk.Tk()
+    root.withdraw()
+    root.attributes("-topmost", True)
+    files = filedialog.askopenfilenames(
+        title="Select PDF files",
+        filetypes=[("PDF files", "*.pdf"), ("All files", "*.*")],
+    )
+    root.destroy()
+    return list(files)
+
+
+def flatten_files(values: Iterable[str]) -> list[Path]:
+    paths: list[Path] = []
+    for value in values:
+        for piece in str(value).splitlines():
+            piece = piece.strip().strip('"')
+            if piece:
+                paths.append(Path(piece))
+    return paths
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="PDF DOI metadata and citation rename tool")
+    parser.add_argument("files", nargs="*", help="PDF files to process")
+    parser.add_argument("--mode", choices=("rename", "metadata-only", "page-labels"), default="rename")
+    parser.add_argument("--max-pages", type=int, default=20, help="pages to scan for DOI")
+    parser.add_argument("--extra-placement", choices=("front", "back", "split"), default="front")
+    parser.add_argument("--skipped-label-prefix", default="skip-")
+    parser.add_argument("--dry-run", action="store_true", help="show actions without writing files")
+    parser.add_argument("--json", action="store_true", help="print machine-readable results")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(list(sys.argv[1:] if argv is None else argv))
+    files = flatten_files(args.files) or flatten_files(choose_files_with_dialog())
+    if not files:
+        print("No files selected.")
+        return 1
+
+    if args.mode == "metadata-only":
+        results = [process_pdf_metadata_only(path, max_pages=args.max_pages, dry_run=args.dry_run) for path in files]
+    elif args.mode == "page-labels":
+        results = [
+            process_journal_page_labels(
+                path,
+                max_pages=args.max_pages,
+                extra_placement=args.extra_placement,
+                skipped_label_prefix=args.skipped_label_prefix,
+                dry_run=args.dry_run,
+            )
+            for path in files
+        ]
+    else:
+        results = [process_pdf(path, rename=True, max_pages=args.max_pages, dry_run=args.dry_run) for path in files]
+
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "path": str(result.path),
+                        "ok": result.ok,
+                        "doi": result.doi,
+                        "renamed_to": str(result.renamed_to) if result.renamed_to else None,
+                        "error": result.error,
+                    }
+                    for result in results
+                ],
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        ok_count = sum(1 for result in results if result.ok)
+        fail_count = len(results) - ok_count
+        for result in results:
+            if not result.ok:
+                print(f"[Failed] {result.path.name}: {result.error}")
+        print(f"Done. Success: {ok_count}, failed: {fail_count}")
+
+    if len(results) == 1:
+        time.sleep(0.2)
+    return 0 if all(result.ok for result in results) else 2

pydfdoi/crossref.py

@@ -0,0 +1,22 @@
+"""Crossref client helpers."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import requests
+
+USER_AGENT = "pydfdoi/0.1.1"
+
+
+def fetch_crossref_item(doi: str, timeout: float = 20.0) -> dict | None:
+    url = f"https://api.crossref.org/works/{quote(doi, safe='')}"
+    headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "application/json",
+    }
+    response = requests.get(url, headers=headers, timeout=timeout)
+    if response.status_code == 404:
+        return None
+    response.raise_for_status()
+    return response.json().get("message")

pydfdoi/doi.py

@@ -0,0 +1,36 @@
+"""DOI normalization and extraction helpers."""
+
+from __future__ import annotations
+
+import re
+
+DOI_RE = re.compile(r"\b10\.\d{4,9}/[-._;()/:A-Z0-9]+", re.IGNORECASE)
+
+
+def normalize_doi(raw: str | None) -> str | None:
+    """Return a bare DOI string from common DOI spellings and URLs."""
+    if not raw:
+        return None
+    text = raw.strip()
+    text = re.sub(r"^(?:doi\s*:?\s*|https?://(?:dx\.)?doi\.org/)", "", text, flags=re.I)
+    text = re.sub(r"\s*([./:_;()-])\s*", r"\1", text)
+    text = re.sub(r"\s+", "", text)
+    text = text.strip().strip(".,;:)])}>")
+    text = text.replace("\u200b", "")
+    return text or None
+
+
+def find_doi(text: str | None) -> str | None:
+    """Find and normalize a DOI in text, tolerating simple PDF spacing noise."""
+    if not text:
+        return None
+    collapsed = re.sub(r"\s+", " ", text)
+    match = DOI_RE.search(collapsed)
+    if match:
+        return normalize_doi(match.group(0))
+
+    compact_punctuation = re.sub(r"\s*([./:_;()-])\s*", r"\1", collapsed)
+    match = DOI_RE.search(compact_punctuation)
+    if match:
+        return normalize_doi(match.group(0))
+    return None

pydfdoi/metadata.py

@@ -0,0 +1,182 @@
+"""DOI metadata capture for journal articles and books."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .crossref import fetch_crossref_item
+from .pdf import count_pdf_pages, extract_doi
+from .publishers import PublisherInfo, publisher_for_doi, publisher_for_name
+
+JOURNAL_TYPES = frozenset({"journal-article", "journal-issue", "journal-volume"})
+BOOK_TYPES = frozenset({"book", "book-chapter", "book-part", "book-section", "edited-book", "monograph", "reference-book"})
+ARTICLE_PAGE_LIMIT = 80
+BOOK_MAX_PAGES = 20
+
+
+@dataclass
+class DoiMetadata:
+    doi: str
+    source_path: Path
+    requested_kind: str
+    inferred_kind: str | None = None
+    classification_source: str | None = None
+    page_count: int | None = None
+    work_type: str | None = None
+    title: str | None = None
+    publisher: str | None = None
+    publisher_abbreviation: str | None = None
+    publisher_doi_prefixes: tuple[str, ...] = ()
+    crossref_item: dict | None = field(default=None, repr=False)
+
+
+def _first_text(value: object) -> str | None:
+    if isinstance(value, list) and value:
+        return str(value[0])
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def _publisher_hint(doi: str, item: dict | None) -> PublisherInfo | None:
+    if item:
+        matched = publisher_for_name(item.get("publisher"))
+        if matched:
+            return matched
+    return publisher_for_doi(doi)
+
+
+def classify_by_page_count(page_count: int | None, *, article_page_limit: int = ARTICLE_PAGE_LIMIT) -> str | None:
+    """Guess whether a PDF is article-like or book-like from its page count."""
+    if page_count is None:
+        return None
+    return "journal" if page_count <= article_page_limit else "book"
+
+
+def classify_crossref_type(work_type: str | None) -> str | None:
+    """Map a Crossref work type to the package's journal/book categories."""
+    if work_type in JOURNAL_TYPES:
+        return "journal"
+    if work_type in BOOK_TYPES:
+        return "book"
+    return None
+
+
+def _safe_page_count(path: Path) -> int | None:
+    try:
+        return count_pdf_pages(path)
+    except Exception:
+        return None
+
+
+def _capture(
+    path: Path | str,
+    *,
+    requested_kind: str,
+    allowed_types: frozenset[str] | None,
+    max_pages: int,
+    query_crossref: bool,
+    use_page_guess: bool,
+    article_page_limit: int,
+    strict_type: bool,
+) -> DoiMetadata | None:
+    source_path = Path(path)
+    page_count = _safe_page_count(source_path) if use_page_guess else None
+    page_kind = classify_by_page_count(page_count, article_page_limit=article_page_limit)
+    doi = extract_doi(source_path, max_pages=max_pages)
+    if not doi:
+        return None
+
+    item = fetch_crossref_item(doi) if query_crossref else None
+    work_type = item.get("type") if item else None
+    crossref_kind = classify_crossref_type(work_type)
+    inferred_kind = crossref_kind or page_kind
+    classification_source = "crossref" if crossref_kind else ("page-count" if page_kind else None)
+    if allowed_types and work_type and work_type not in allowed_types:
+        if strict_type or crossref_kind is not None or page_kind != requested_kind:
+            return None
+
+    publisher = _publisher_hint(doi, item)
+    return DoiMetadata(
+        doi=doi,
+        source_path=source_path,
+        requested_kind=requested_kind,
+        inferred_kind=inferred_kind,
+        classification_source=classification_source,
+        page_count=page_count,
+        work_type=work_type,
+        title=_first_text(item.get("title")) if item else None,
+        publisher=item.get("publisher") if item else (publisher.name if publisher else None),
+        publisher_abbreviation=publisher.abbreviation if publisher else None,
+        publisher_doi_prefixes=publisher.doi_prefixes if publisher else (),
+        crossref_item=item,
+    )
+
+
+def capture_journal_doi(path: Path | str, *, max_pages: int = 3, query_crossref: bool = True) -> DoiMetadata | None:
+    """Capture DOI metadata for a journal-like Crossref work."""
+    return _capture(
+        path,
+        requested_kind="journal",
+        allowed_types=JOURNAL_TYPES,
+        max_pages=max_pages,
+        query_crossref=query_crossref,
+        use_page_guess=False,
+        article_page_limit=ARTICLE_PAGE_LIMIT,
+        strict_type=True,
+    )
+
+
+def capture_book_doi(
+    path: Path | str,
+    *,
+    max_pages: int = BOOK_MAX_PAGES,
+    query_crossref: bool = True,
+    article_page_limit: int = ARTICLE_PAGE_LIMIT,
+    strict_type: bool = False,
+) -> DoiMetadata | None:
+    """Capture DOI metadata for a book-like work.
+
+    Books often place DOI information after the cover and title pages, so this
+    function scans more pages than the journal helper by default. When
+    `strict_type` is false, an unknown Crossref type can still be accepted if
+    the page-count heuristic says the PDF is book-like.
+    """
+    return _capture(
+        path,
+        requested_kind="book",
+        allowed_types=BOOK_TYPES,
+        max_pages=max_pages,
+        query_crossref=query_crossref,
+        use_page_guess=True,
+        article_page_limit=article_page_limit,
+        strict_type=strict_type,
+    )
+
+
+def capture_doi_metadata(
+    path: Path | str,
+    *,
+    max_pages: int = 3,
+    query_crossref: bool = True,
+    use_page_guess: bool = True,
+    article_page_limit: int = ARTICLE_PAGE_LIMIT,
+) -> DoiMetadata | None:
+    """Capture DOI metadata and infer whether the work is article-like or book-like.
+
+    The general classifier first makes a coarse page-count guess when enabled:
+    PDFs with `article_page_limit` pages or fewer are treated as journal-like,
+    and longer PDFs are treated as book-like. If Crossref is queried and returns
+    a known work type, the Crossref type overrides that page-count guess.
+    """
+    return _capture(
+        path,
+        requested_kind="any",
+        allowed_types=None,
+        max_pages=max_pages,
+        query_crossref=query_crossref,
+        use_page_guess=use_page_guess,
+        article_page_limit=article_page_limit,
+        strict_type=False,
+    )