Migrating to a devcontainer

Also bumped version.

.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/python
+{
+	"name": "Python 3",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye"
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	// "forwardPorts": [],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	// "postCreateCommand": "pip3 install --user -r requirements.txt",
+
+	// Configure tool-specific properties.
+	// "customizations": {},
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Module",
+            "type": "python",
+            "request": "launch",
+            "module": "renamebycsv.cli",
+            "args": [
+                "${workspaceFolder}/tests/resources/files",
+                "group\\d+-\\w-(\\d+)\\.txt",
+                "${workspaceFolder}/tests/resources/groups.csv",
+                "target",
+                "replaced",
+                "-d",
+                "-e",
+                "abc",
+                "-k"
+            ],
+            "justMyCode": true
+        }
+    ]
+}

Jenkinsfile

@@ -0,0 +1,44 @@
+pipeline {
+    agent {
+        kubernetes {
+            cloud 'rsys-devel'
+            defaultContainer 'pip'
+            inheritFrom 'pip'
+        }
+    }
+    stages {
+        stage("install") {
+            steps {
+                sh 'pip install -r requirements.txt'
+            }
+        }
+        stage("build") {
+            steps {
+                sh 'rm -rf ./dist/*'
+                sh "python -m build"
+            }
+        }
+        stage("test") {
+            steps {
+                sh "pip install dist/*.whl --force-reinstall"
+                sh "renamebycsv -h"
+            }
+        }
+        stage("archive") {
+            steps {
+                archiveArtifacts artifacts: 'dist/*.tar.gz, dist/*.whl', fingerprint: true, followSymlinks: false, onlyIfSuccessful: true
+            }
+        }
+        stage("publish package") {
+            environment {
+                CREDS = credentials('rs-git-package-registry-ydeng')
+            }
+            when {
+                branch '**/master'
+            }
+            steps {
+                sh returnStatus: true, script: 'python -m twine upload --repository-url https://git.reslate.systems/api/packages/${CREDS_USR}/pypi -u ${CREDS_USR} -p ${CREDS_PSW} --non-interactive --disable-progress-bar --verbose dist/*'
+            }
+        }
+    }
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+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.

README.md

@@ -5,5 +5,38 @@ A simple program that renames files by using a spreadsheet in CSV format as a di
 ## Features
 
  - Rename files recursively within a directory to a desired string
+ - Replace only the REGEX match portion
  - Desired string is set by a CSV where one column is the original string, and another column is the string to replace the original string with
  - Uses a REGEX capture group to select file and the portion of the filename to rename
+ - Ability to define file extension
+
+## Installing using `pip`
+
+1. Run `pip install --index-url https://git.reslate.systems/api/packages/ydeng/pypi/simple renamebycsv` in any `python3` enabled terminal.
+
+2. Run `renamebycsv -h` to see the help and confirm installation was successful.
+
+## Advanced Usage: What is REGEX?
+
+This program makes heavy use of REGEX, also known as Regular Expression to give users the flexibility to choose which portion of any given filename should be the portion used by the program to look up in the CSV. It is therefore critical for users of this script to understand how REGEX works. Here are some key pointers to get you started:
+
+ - REGEX works by matching one string to another, this is just like if you used any in-text search function.
+ - Where it differs is the ability to use one REGEX string to match many strings.
+   - i.e, the REGEX "`abc\d+`" will match with "`abc1`", "`abc2`", "`abc12`", but not "`ac12`" or "`abc`".
+ - Many characters can be used as normal and will match a string literally (character for character), but some will be treated as special characters (such as the previously used `\`, which indicates that the letter afterwards should be treated specially, such as a token)
+   - Common tokens to be aware of: `.` for any character, `\d` for single digits, `\w` for word characters, `\s` for space characters (tabs, spaces, linebreaks, etc.). Tokens can be repeated by using `+`, indicating "one or more", `*` indicating "none or more". If you want to match something that is read as a token by default, such as `.`, or `+`, using the `\` in front of it will cause it to match `.` literally, i.e, `1\.2` matches `1.3`, but not `123`, `1a3`, etc.
+ - A capture group is a way of "selecting" a part of a text and is formed by using `(` and `)` around the REGEX that should be selected.
+
+ Now for a few examples:
+
+Let's say we have files `run325-a-1.vcf`, `run326-b-2.vcf`, and `run327-b-3.vcf`. If we know that all that matters is the `1` after the `run[numbers]-[character]-`, we can write `run\d+-\w-(\d)\.vcf` which will match with all 3 of the above examples, and select the last digit. The program can then use a given CSV to look up the selected digits and replace the name with what is given by the CSV.
+
+For learning and testing your own REGEX, checkout [regex101.com](https://regex101.com/), which allows you to write the strings that you're trying to match, and the REGEX. It will show you live which parts of the strings match to what, if any parts match.
+
+## Not Working?
+
+If the program is not working the way you would like it, try running the program in `-v DEBUG` mode which increases verbosity. Typically, files not being renamed can be attributed to one of two problems:
+
+1. It's looking in the wrong directory. The solution would be to double check that the directory it's looking in (printed by the program each run) is correct. If not, try adding quotes around the path in the command line.
+
+2. The provided REGEX pattern isn't matching to any of the files. In this case, test one or two of the files at [regex101.com](https://regex101.com/) with your pattern.

environment.yml

@@ -0,0 +1,12 @@
+name: renamebycsv
+channels:
+  - anaconda
+  - conda-forge
+dependencies:
+  - python-build=0.7
+  - pytest=7.2
+  - python=3.11
+  - setuptools=67.6
+  - twine=4.0
+  - cryptography=38.0.4
+prefix: ./env

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["setuptools", "wheel"]

renamebycsv/cli.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+
+import argparse
+import logging
+
+from renamebycsv.renamer import find_all_candidates, rename_by_csv
+
+
+def run(args):
+    candidates = find_all_candidates(args.input_dir, args.pattern, args.recursive)
+    if len(candidates):
+        rename_by_csv(
+            args.csv,
+            candidates,
+            args.current,
+            args.become,
+            args.dry,
+            args.extension,
+            args.keep_extension,
+        )
+
+
+def main():
+    program_name = "renamebycsv"
+    argparser = argparse.ArgumentParser(
+        program_name, description="Rename all files by using a CSV as a dictionary."
+    )
+    argparser.add_argument(
+        "input_dir",
+        help="The directory containing the items that is to be renamed.",
+        metavar="I",
+    )
+    argparser.add_argument(
+        "pattern",
+        help="The regex to apply to each file name. The first capture group is used to "
+        "perform the replacement.",
+        metavar="R",
+    )
+    argparser.add_argument(
+        "csv",
+        help="The CSV to use as the dictionary for the substitutions in file name.",
+        metavar="C",
+    )
+    argparser.add_argument(
+        "current",
+        help="The column header to look for the text matched by the regex.",
+        metavar="F",
+    )
+    argparser.add_argument(
+        "become", help="The column header to replace the regex match.", metavar="T"
+    )
+    argparser.add_argument(
+        "-r",
+        "--recursive",
+        help="Perform renaming action recursively.",
+        action="store_true",
+    )
+    argparser.add_argument(
+        "-f",
+        "--force",
+        help="Overwrite files if file already exists.",
+        action="store_true",
+    )
+    argparser.add_argument(
+        "-d", "--dry", help="Do not perform any renames", action="store_true"
+    )
+    argparser.add_argument(
+        "-V",
+        "--verbosity",
+        help="Set the logging verbosity.",
+        required=False,
+        type=str,
+        default="INFO",
+    )
+    argparser.add_argument(
+        "-e",
+        "--extension",
+        help='Sets the new file extension after the renaming. Use empty string ("") '
+        "to not add extension. Will use empty string by default.",
+        type=str,
+        default="",
+        required=False,
+    )
+    argparser.add_argument(
+        "-k",
+        "--keep-extension",
+        help="Keeps the OS recognized extension from the original filename. Will "
+        'append to end of argument given by "-e" or "--extension".',
+        action="store_true",
+        default=False,
+        required=False,
+    )
+
+    args = argparser.parse_args()
+    logging.basicConfig(
+        format="[%(filename)s %(asctime)s - %(levelname)s] %(message)s",
+        level=args.verbosity.upper(),
+    )
+    run(args)
+
+
+if __name__ == "__main__":
+    main()

renamebycsv/renamer.py

@@ -1,14 +1,17 @@
-#!/usr/bin/env python3
-
-import argparse
 import csv
+import logging
 import os
 import re
 from typing import Iterable
-import logging
 
 
 def find_all_candidates(input_dir: str, regex: str, recursive: bool):
+    logging.info(
+        'Searching "%s" for files that match "%s" %s',
+        input_dir,
+        regex,
+        "recursively" if recursive else "non-recursively",
+    )
     results = []
     for subitem in os.listdir(input_dir):
         subitem_path = os.path.join(input_dir, subitem)
@@ -22,15 +25,26 @@ def find_all_candidates(input_dir: str, regex: str, recursive: bool):
                 continue
             results.append((subitem_path, subitem, match))
             logging.debug(f'Collecting "{subitem}"...')
+    if len(results) < 1:
+        logging.info(
+            'No results found matching "%s" in "%s". Please double check your REGEX '
+            "pattern and directory being searched.",
+            regex,
+            input_dir,
+        )
+    else:
+        logging.info("Collected %d files to rename.", len(results))
     return results
 
 
-def rename(
+def rename_by_csv(
     csv_path: str,
     candidates: Iterable[tuple[str, str, re.Match]],
     current: str,
     become: str,
     dry: bool,
+    extension: str,
+    keep_extension: bool,
 ):
     replacement_dict = {}
     with open(csv_path, "r") as csv_fd:
@@ -39,6 +53,10 @@ def rename(
         become_col_ind = None
         for row in reader:
             if current_col_ind is None and become_col_ind is None:
+                if current not in row:
+                    logging.error("\"%s\" not in header %s.", current, list(row))
+                if become not in row:
+                    logging.error("\"%s\" not in header %s.", become, list(row))
                 current_col_ind = row.index(current)
                 become_col_ind = row.index(become)
                 continue
@@ -46,18 +64,30 @@ def rename(
                 row[current_col_ind] in replacement_dict
                 and replacement_dict[row[current_col_ind]] != row[become_col_ind]
             ):
+                # Check if there's a duplicate key for different values.
                 raise Exception("Duplicate current key.")
             replacement_dict[row[current_col_ind]] = row[become_col_ind]
     for subitem_path, subitem, match in candidates:
+        if match.group(1) not in replacement_dict:
+            logging.warning(
+                'Group "%s" was not matched to any row in the provided CSV. '
+                "Skipping...",
+                match.group(1),
+            )
+            continue
         original = subitem_path
         objective = os.path.join(
             os.path.dirname(subitem_path),
-            re.sub(match.re, replacement_dict[match.group(1)], subitem),
+            re.sub(match.re, replacement_dict[match.group(1)], subitem.strip()),
         )
+        if extension:
+            objective += ("." if not extension.startswith(".") else "") + extension
+        if keep_extension:
+            objective += os.path.splitext(subitem_path)[1]
         logging.info(f'Will rename "{original}" to "{os.path.basename(objective)}"')
         if os.path.exists(objective):
             logging.error(
-                f'Path at "{objective}" exists, not continuing. '
+                f'Path at "{objective}" already exists, not continuing. '
                 "Use -f to overwrite instead of stopping."
             )
             exit(1)
@@ -65,69 +95,3 @@ def rename(
             os.rename(original, objective)
     if dry:
         logging.info("No file names were modified.")
-
-
-def main():
-    program_name = "renamebycsv"
-    argparser = argparse.ArgumentParser(
-        program_name, "Rename all files by using a CSV as a dictionary."
-    )
-    argparser.add_argument(
-        "input_dir",
-        help="The directory containing the items that is to be renamed.",
-        metavar="I",
-    )
-    argparser.add_argument(
-        "regex",
-        help="The regex to apply to each file name. The first capture group is used to "
-        "perform the replacement.",
-        metavar="R",
-    )
-    argparser.add_argument(
-        "csv",
-        help="The CSV to use as the dictionary for the substitutions in file name.",
-        metavar="C",
-    )
-    argparser.add_argument(
-        "current",
-        help="The column header to look for the text matched by the regex.",
-        metavar="F",
-    )
-    argparser.add_argument(
-        "become", help="The column header to replace the regex match.", metavar="T"
-    )
-    argparser.add_argument(
-        "-r",
-        "--recursive",
-        help="Perform renaming action recursively",
-        action="store_true",
-    )
-    argparser.add_argument(
-        "-f",
-        "--force",
-        help="Overwrite files if file already exists",
-        action="store_true",
-    )
-    argparser.add_argument(
-        "-d", "--dry", help="Do not perform any renames", action="store_true"
-    )
-    argparser.add_argument(
-        "-V",
-        "--verbosity",
-        help="Set the logging verbosity",
-        required=False,
-        type=str,
-        default="INFO",
-    )
-
-    args = argparser.parse_args()
-    logging.basicConfig(
-        format="[%(filename)s %(asctime)s - %(levelname)s] %(message)s",
-        level=args.verbosity.upper(),
-    )
-    candidates = find_all_candidates(args.input_dir, args.regex, args.recursive)
-    rename(args.csv, candidates, args.current, args.become, args.dry)
-
-
-if __name__ == "__main__":
-    main()

requirements.txt

@@ -0,0 +1,5 @@
+build
+pytest
+setuptools
+twine
+cryptography

setup.cfg

@@ -0,0 +1,10 @@
+[metadata]
+name = renamebycsv
+version = 0.0.8
+
+[options]
+packages = renamebycsv
+
+[options.entry_points]
+console_scripts =
+    renamebycsv = renamebycsv.cli:main

setup.py

@@ -0,0 +1,2 @@
+from setuptools import setup
+setup()

tests/resources/files/foo.txt

@@ -0,0 +1 @@
+Text

tests/resources/files/group1-a-12.txt

@@ -0,0 +1,2 @@
+
+Text

tests/resources/files/group1-a-13.txt

@@ -0,0 +1 @@
+Text

tests/resources/files/group1-b-10.txt

@@ -0,0 +1 @@
+Text

tests/resources/files/group1-b-11.txt

@@ -0,0 +1 @@
+Text

tests/resources/files/group1-b-14.txt

@@ -0,0 +1 @@
+Text

tests/resources/files/group1-b-9.txt

@@ -0,0 +1 @@
+Text

tests/resources/groups.csv

@@ -0,0 +1,6 @@
+target,replaced
+9,a
+10,b
+11,c
+12,d
+13,e