A command-line utility for copying files based on pattern matching, with support for filtering by modification time, plus a helper function for selecting uniquely matched files.

Filesmith is a Python utility that helps you copy files from one directory to another based on regular expression patterns. It's particularly useful for selective file copying, backup operations, and automated file management tasks.

It also includes get_target_file, a reliable helper for retrieving a single uniquely identified file by substring and optional extension filter.

You can install filesmith using pip:

pip install filesmith

filesmith <origin> <destination> <pattern> [options]

• origin: The source directory.
• destination: The destination directory.
• pattern: The regex pattern to match filenames against.

• --newermt <file_or_isodate>: Only copy files newer than a reference file's modification time or a given ISO date/datetime.
• -n, --dry-run: Show which files would be copied without actually copying them.
• -q, --quiet: Suppress output for successfully copied files.

1. Copy all .txt files from source to dest:

   filesmith /path/to/source /path/to/dest ".*\.txt$"

2. Perform a dry run to see which .jpg files would be copied:

   filesmith /path/to/source /path/to/dest ".*\.jpg$" --dry-run

3. Copy .log files newer than a specific date:

   filesmith /path/to/logs /path/to/backup ".*\.log$" --newermt 2023-10-27T10:00:00

4. Copy .py files that are newer than main.py:

   filesmith /path/to/src /path/to/old_src ".*\.py$" --newermt /path/to/src/main.py

Filesmith includes a small but powerful helper function to locate exactly one matching file in a directory.

from filesmith import get_target_file

file_path = get_target_file("/path/to/dir", "report", ".xlsx")
print(file_path)

• Ensures exactly one match.
• Raises ValueError if:
  • No files match.
  • More than one file matches.
• Optional extension filtering:

  get_target_file("data", "2024", ".csv")

This is ideal when processing pipelines rely on single expected inputs, such as weekly exports or naming‑convention‑based file detection.

• Added get_target_file utility.
• Improved copy_files:
  • Switched from print to structured logging.
  • More robust handling of ISO datetime / file-based --newermt filtering.
• Extended full test coverage (pytest).

• Added new CLI: filesmith-find-move
• Integrated core.copy_files with the new engine (finder / transfer / FindMoveJob)