sebastian
Repositories
1
 Projects Packages
5
 Public activity Starred repositories

docrename (0.1.0)

Published 2026-10-01 14:47:12 +00:00 by harlequix

Installation

pip install --index-url  docrename

About this package

Document rename tool with structured naming scheme

Document Rename Tool

A CLI tool for renaming documents according to a structured scheme: <date>-<correspondent>-<topic>.<ext>

Features

  • CLI Parameters: Specify date, correspondent, and topic directly via command-line flags
  • Interactive TUI: If information is missing, provides an interactive interface:
    • Date input with defaults
    • Fuzzy search for correspondent (from memory)
    • Fuzzy search for topic (from memory)
  • Memory System: Automatically saves correspondents and topics to ~/.docrename_memory.json for future fuzzy search
  • Non-Interactive Mode: Fails gracefully if information is missing and --non-interactive flag is set
  • Configurable Date Format: Defaults to YYYY-MM-DD but can be customized

Installation

cd ~/docrename
chmod +x docrename.py

# Install with uv
uv pip install -e .

Or install from the package registry:

uv tool install docrename --index https://git.rust.cloud/api/packages/harlequix/pypi/simple

Or run directly with uvx:

uvx --from . docrename ~/document.pdf

Optionally, create a symlink for easier access:

ln -s ~/docrename/docrename.py ~/bin/docrename  # or ~/.local/bin/docrename

Usage

Basic Usage (Interactive)

./docrename.py document.pdf

If date, correspondent, or topic is missing, you'll be prompted interactively.

Full CLI Specification

./docrename.py document.pdf -d 2026-02-11 -c "John Doe" -t "Invoice"
# Renames to: 2026-02-11-John_Doe-Invoice.pdf

Non-Interactive Mode

./docrename.py document.pdf -d 2026-02-11 -c "Acme Corp" -t "Contract" --non-interactive
# Fails if any information is missing

Custom Date Format

./docrename.py document.pdf --date-format "%Y%m%d" -d 20260211 -c "Client" -t "Report"
# Renames to: 20260211-Client-Report.pdf

Command-Line Options

  • filepath: Path to the file to rename (required)
  • -d, --date: Date string (format depends on --date-format)
  • -c, --correspondent: Correspondent name
  • -t, --topic: Topic/description
  • -n, --non-interactive: Non-interactive mode - fail if information is missing
  • --date-format: Date format (default: %Y-%m-%d)

Memory File

The tool stores previously used correspondents and topics in $XDG_CONFIG_HOME/docrename/memory.json (typically ~/.config/docrename/memory.json):

{
  "correspondents": ["Acme Corp", "John Doe", "Tax Office"],
  "topics": ["Contract", "Invoice", "Report"]
}

This enables fuzzy search in interactive mode. New values are automatically added.

Examples

# Interactive mode - will prompt for missing info
./docrename.py ~/Documents/scan.pdf

# Partial info - will only prompt for topic
./docrename.py invoice.pdf -d 2026-02-11 -c "Supplier XYZ"

# Full automation
./docrename.py receipt.pdf -d 2026-02-11 -c "Store" -t "Purchase" -n

# With custom date format (no dashes)
./docrename.py doc.pdf --date-format "%Y%m%d" -d 20260211 -c "Client" -t "Letter"

Requirements

  • Python 3.7+
  • prompt_toolkit (for interactive TUI and fuzzy search)

Requirements

Requires Python: >=3.7
Details
PyPI
2026-10-01 14:47:12 +00:00
0
20 KiB
Assets (2)
docrename-0.1.0-py3-none-any.whl 10 KiB
docrename-0.1.0.tar.gz 9.4 KiB
Versions (1) View all
0.1.0 2026-10-01