meaningful-pdf-names 0.1.0__py3-none-any.whl

meaningful_pdf_names/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

meaningful_pdf_names/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

meaningful_pdf_names/cli.py

@@ -0,0 +1,270 @@
+import argparse
+import random
+import string
+import re
+from pathlib import Path
+
+try:
+    from pypdf import PdfReader
+except ImportError:
+    PdfReader = None
+
+try:
+    from transformers import pipeline
+except ImportError:
+    pipeline = None
+
+STOPWORDS = {
+    "the", "and", "for", "with", "that", "this", "from", "into", "onto",
+    "but", "not", "are", "were", "was", "have", "has", "had", "their",
+    "its", "our", "your", "about", "using", "use", "based", "on", "of",
+    "in", "to", "by", "an", "a", "as", "is", "be", "or", "we", "can",
+    "such", "these", "those", "also", "it", "at"
+}
+
+_SUMMARIZER = None
+
+
+def get_summarizer():
+    """
+    Lazy-load a small local HF summarization model, if transformers is installed.
+    """
+    global _SUMMARIZER
+    if _SUMMARIZER is not None:
+        return _SUMMARIZER
+
+    if pipeline is None:
+        return None
+
+    try:
+        _SUMMARIZER = pipeline(
+            "summarization",
+            model="sshleifer/distilbart-cnn-12-6",
+            device=-1,  # CPU; user can change if needed
+        )
+    except Exception:
+        _SUMMARIZER = None
+
+    return _SUMMARIZER
+
+
+def summarize_text(text: str, max_chars: int = 4000) -> str:
+    """
+    Summarize text using a local HF model if available.
+    Falls back to original text on any failure.
+    """
+    text = text.strip()
+    if not text:
+        return ""
+
+    summarizer = get_summarizer()
+    if summarizer is None:
+        return text
+
+    chunk = text[:max_chars]
+    try:
+        out = summarizer(
+            chunk,
+            max_length=80,
+            min_length=20,
+            do_sample=False,
+        )
+        summary = (out[0].get("summary_text") or "").strip()
+        return summary or text
+    except Exception:
+        return text
+
+
+def extract_text_keywords(pdf_path: Path, max_keywords: int = 5):
+    """
+    Extract up to `max_keywords` from ONLY the first page of the PDF.
+    """
+    text = ""
+
+    if PdfReader is not None:
+        try:
+            reader = PdfReader(str(pdf_path))
+            if len(reader.pages) > 0:
+                first_page = reader.pages[0]
+                text = (first_page.extract_text() or "")
+        except Exception:
+            text = ""
+
+    if not text.strip():
+        # fallback: original filename as text source
+        text = pdf_path.stem
+
+    # Clean the text - remove URLs, DOIs, and other noise
+    cleaned_text = clean_extracted_text(text)
+    
+    summarized = summarize_text(cleaned_text) or cleaned_text
+
+    # Basic tokenization on summary
+    tokens = re.findall(r"[A-Za-z][A-Za-z\-]{1,}", summarized.lower())
+    filtered = [
+        t for t in tokens
+        if t not in STOPWORDS and len(t) > 2
+    ]
+
+    if not filtered:
+        # fallback to filename-derived tokens
+        fallback_tokens = re.findall(r"[A-Za-z0-9]+", pdf_path.stem.lower())
+        filtered = [t for t in fallback_tokens if len(t) > 1] or ["paper"]
+
+    # Deduplicate in order
+    seen = set()
+    ordered = []
+    for t in filtered:
+        if t not in seen:
+            seen.add(t)
+            ordered.append(t)
+
+    return ordered[:max_keywords]
+
+
+def clean_extracted_text(text: str) -> str:
+    """
+    Clean extracted PDF text by removing URLs, DOIs, emails, and other noise.
+    """
+    if not text:
+        return ""
+    
+    # Remove URLs
+    text = re.sub(r'https?://[^\s]+', '', text)
+    text = re.sub(r'www\.[^\s]+', '', text)
+    
+    # Remove DOIs
+    text = re.sub(r'doi:[^\s]+', '', text, flags=re.IGNORECASE)
+    text = re.sub(r'10\.\d{4,9}/[-._;()/:A-Z0-9]+', '', text, flags=re.IGNORECASE)
+    
+    # Remove emails
+    text = re.sub(r'\S+@\S+', '', text)
+    
+    # Remove common PDF metadata patterns
+    text = re.sub(r'received:\s*\d{1,2}\s+\w+\s+\d{4}', '', text, flags=re.IGNORECASE)
+    text = re.sub(r'accepted:\s*\d{1,2}\s+\w+\s+\d{4}', '', text, flags=re.IGNORECASE)
+    text = re.sub(r'published:\s*\d{1,2}\s+\w+\s+\d{4}', '', text, flags=re.IGNORECASE)
+    
+    # Remove page numbers and headers/footers
+    text = re.sub(r'\b\d{1,3}\b', '', text)  # Remove standalone numbers (likely page numbers)
+    
+    # Remove excessive whitespace
+    text = re.sub(r'\s+', ' ', text).strip()
+    
+    return text
+
+
+def slugify_keywords(keywords):
+    """
+    Turn keywords into a filesystem-safe slug.
+    """
+    cleaned = []
+    for kw in keywords:
+        kw = re.sub(r"[^a-z0-9\-]+", "-", kw.lower())
+        kw = re.sub(r"-{2,}", "-", kw).strip("-")
+        if kw:
+            cleaned.append(kw)
+    if not cleaned:
+        cleaned = ["paper"]
+    return "-".join(cleaned)
+
+
+def random_suffix(length: int = 3):
+    """
+    Generate a short random suffix to minimize collisions.
+    """
+    alphabet = string.ascii_lowercase + string.digits
+    return "".join(random.choices(alphabet, k=length))
+
+
+def build_new_name(keywords, suffix_len=3, max_len=120):
+    """
+    Build the base part of the new filename (without .pdf).
+    """
+    base_slug = slugify_keywords(keywords)
+
+    # Reserve for "-xyz.pdf"
+    max_base_len = max_len - (1 + suffix_len + 4)
+    if max_base_len < 10:
+        max_base_len = 10
+
+    if len(base_slug) > max_base_len:
+        base_slug = base_slug[:max_base_len].rstrip("-")
+
+    return base_slug
+
+
+def unique_target_path(folder: Path, base_slug: str, suffix_len: int = 3) -> Path:
+    """
+    Generate a unique filename in `folder` using base_slug + random suffix.
+    """
+    while True:
+        suffix = random_suffix(suffix_len)
+        candidate = folder / f"{base_slug}-{suffix}.pdf"
+        if not candidate.exists():
+            return candidate
+
+
+def rename_pdfs(folder: Path, dry_run: bool = False, verbose: bool = True):
+    """
+    Rename all PDFs in the folder using first-page-based keywords.
+    """
+    if not folder.is_dir():
+        raise ValueError(f"{folder} is not a directory")
+
+    pdf_files = sorted(
+        p for p in folder.iterdir()
+        if p.is_file() and p.suffix.lower() == ".pdf"
+    )
+
+    if verbose:
+        print(f"Found {len(pdf_files)} PDF(s) in {folder}")
+
+    for pdf in pdf_files:
+        keywords = extract_text_keywords(pdf)
+        base_slug = build_new_name(keywords)
+        target = unique_target_path(folder, base_slug)
+
+        if target.name == pdf.name:
+            if verbose:
+                print(f"Skip (already well-named): {pdf.name}")
+            continue
+
+        if verbose:
+            print(f"{pdf.name} -> {target.name}")
+
+        if not dry_run:
+            pdf.rename(target)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description=(
+            "Rename PDFs using first-page-derived keywords plus a short suffix "
+            "for clean, meaningful filenames."
+        )
+    )
+    parser.add_argument(
+        "folder",
+        type=str,
+        help="Path to folder containing PDFs."
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show planned renames without changing files."
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Minimal output."
+    )
+
+    args = parser.parse_args()
+    folder = Path(args.folder).expanduser().resolve()
+
+    rename_pdfs(folder, dry_run=args.dry_run, verbose=not args.quiet)
+
+
+if __name__ == "__main__":
+    main()

meaningful_pdf_names-0.1.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: meaningful-pdf-names
+Version: 0.1.0
+Summary: Offline-friendly PDF renamer that generates meaningful, keyword-rich filenames from first-page content.
+Author-email: Nishant Kumar <abcnishant007@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/abcnishant007/meaningful-pdf-names
+Project-URL: Source, https://github.com/abcnishant007/meaningful-pdf-names
+Project-URL: Issues, https://github.com/abcnishant007/meaningful-pdf-names/issues
+Keywords: pdf,rename,keywords,offline,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pypdf>=5.0.0
+Provides-Extra: summarizer
+Requires-Dist: transformers>=4.45.0; extra == "summarizer"
+Requires-Dist: torch>=2.0.0; extra == "summarizer"
+Dynamic: license-file
+
+# meaningful-pdf-names
+
+Offline-friendly CLI to turn your messy paper filenames into **compact, keyword-rich names** based on the PDF's first page.
+
+Example:
+
+`final_v3_really_final.pdf` → `urban-resilience-transport-inequality-policy-a9f.pdf`
+
+## Features
+
+- Uses only the **first page** (title, authors, abstract region) for speed.
+- Up to **5 meaningful keywords** per file.
+- Adds a **3-character [a-z0-9] suffix** to avoid collisions.
+- Works fully **offline** with `pypdf`.
+- Optional: use a small local Hugging Face summarizer
+  (`sshleifer/distilbart-cnn-12-6`) via `transformers` + `torch`.
+
+## Install
+
+From source / Git:
+
+```bash
+pip install git+https://github.com/yourname/meaningful-pdf-names.git
+```
+
+(When published to PyPI:)
+
+```bash
+pip install meaningful-pdf-names
+```
+
+With optional local summarizer:
+
+```bash
+pip install "meaningful-pdf-names[summarizer]"
+```
+
+## Usage
+
+```bash
+meaningful-pdf-names /path/to/pdfs
+meaningful-pdf-names /path/to/pdfs --dry-run
+mpn /path/to/pdfs
+```
+
+## Why not existing tools?
+
+Other tools often:
+
+* Depend on **OpenAI / web APIs**.
+* Require DOIs or external metadata.
+* Use long `Author - Title - Year` patterns.
+
+`meaningful-pdf-names` is:
+
+* **Local-only** (no API keys, no network).
+* **Fast** (first-page only).
+* **Slug-based**: short, grep- and git-friendly names.
+
+## License
+
+MIT

meaningful_pdf_names-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+meaningful_pdf_names/__init__.py,sha256=tXbRXsO0NE_UV1kIHiZTTQQH0fj0U2KoxxNusu_gzrM,48
+meaningful_pdf_names/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+meaningful_pdf_names/cli.py,sha256=C5eYS9ZTBfkf9urzKrN8G85b9-Kt0JN8qabs0CizWAs,7236
+meaningful_pdf_names-0.1.0.dist-info/licenses/LICENSE,sha256=OphKV48tcMv6ep-7j-8T6nycykPT0g8ZlMJ9zbGvdPs,1066
+meaningful_pdf_names-0.1.0.dist-info/METADATA,sha256=cIZjWGIsHtS-bkAf6tOL_J7YnwOXFit7_pytGZqt0q4,2365
+meaningful_pdf_names-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+meaningful_pdf_names-0.1.0.dist-info/entry_points.txt,sha256=EtPEkZe_yMNP99BJDtBPI2DL20GO3E5ELmOm2F4aPO4,107
+meaningful_pdf_names-0.1.0.dist-info/top_level.txt,sha256=TD_BuniRNpBdNggGi-6B8WQ4CxkYxzEgTSm2DfY4khw,21
+meaningful_pdf_names-0.1.0.dist-info/RECORD,,

meaningful_pdf_names-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

meaningful_pdf_names-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+meaningful-pdf-names = meaningful_pdf_names.cli:main
+mpn = meaningful_pdf_names.cli:main

meaningful_pdf_names-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+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.

meaningful_pdf_names-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+meaningful_pdf_names