reny 1.0.0__tar.gz

reny-1.0.0/LICENSE

@@ -0,0 +1,11 @@
+## Copyright (c) 2026 Arseniy Kuznetsov
+##
+## This program is free software; you can redistribute it and/or
+## modify it under the terms of the GNU General Public License
+## as published by the Free Software Foundation; either version 2
+## of the License, or (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.

reny-1.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: reny
+Version: 1.0.0
+Summary: A lightweight, powerful batch renaming and filesystem organizing CLI tool.
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygtrie
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+# Reny
+A lightweight, fast, and safe batch renaming and filesystem organization tool.
+
+## Background
+`reny` was originally created as the `renamer` component inside the larger [`batchmp`](https://github.com/akpw/batch-mp-tools) (Batch Media Processing) suite. It was spun off into its own standalone package to provide for an ultra-lightweight, safe, pure-filesystem organizing tool without FFmpeg / Mutagen media dependencies. 
+
+If you need advanced media operations (like denoising, cover-art extraction, or format transcoding), check out the original [`batchmp`](https://github.com/akpw/batch-mp-tools) project. If you just need to safely organize your files with surgical precision, `reny` is all you need.
+
+## Installation
+You can install `reny` globally using pipx:
+```bash
+pipx install .
+```
+
+## Features
+- **Virtual Views:** Preview how a directory structure would look when reorganised by type, size, or date without moving or changing anything
+- **Indexing:** Multi-level indexing across nested directories, supporting multiple indexing schemes
+- **Padding:** Automatically pad existing numbers in filenames with leading zeros to fix sorting orders
+- **Flattening:** Safely collapse nested directory structures into a single folder
+- **Regex Replacement:** Powerful batch renaming using standard regular expressions
+- **Dry-Run by Default:** `reny` will always visualize targeted changes and ask for confirmation before it ever touches your files
+
+## Examples
+
+### Basic Operations
+**Print current directory structure:**
+```bash
+reny
+```
+*(Without arguments, `reny` defaults to the `print` command)*
+
+**Add a sequential index to all `.txt` files recursively:**
+```bash
+reny -r -in '*.txt' index
+```
+
+**Pad existing numbers with leading zeros (e.g., `2 kms.png` becomes `02 kms.png`):**
+```bash
+reny pad -md 2
+```
+
+**Regex Replace:**
+Change spaces to underscores in all filenames:
+```bash
+reny replace -fs ' ' -rs '_'
+```
+
+### Advanced Operations & Virtual Views
+**Flattening nested directories:**
+Collapse all sub-directories and bring their files up to the current folder level:
+```bash
+reny flatten
+```
+
+**Organize by File Type:**
+Move files into sub-directories grouped by their file extension (e.g., `png/`, `pdf/`):
+```bash
+reny organize -b type
+```
+
+**Virtual Views (Dry-Run Preview):**
+Preview how files would look if organized by year and month, *without actually moving any files on your drive*:
+```bash
+reny print -b date --date-format "%Y/%m"
+```
+```text
+Virtual view by date:
+~/Downloads
+  |- 2025/
+    |- 01/
+      |- document.pdf
+    |- 02/
+      |- image.png
+```
+
+## Documentation & Tutorials
+Although `reny` is a standalone project, its core organizing logic is inherited directly from [`batchmp`](https://github.com/akpw/batch-mp-tools). You can find detailed tutorials and deep-dives on how to master its capabilities in the original blog posts:
+- [Renamer Organize & Virtual Views](https://akpw.github.io/articles/2025/09/22/Print-and-Organize.html) – *Highly recommended reading for mastering virtual directory views*
+- [BatchMP Tools Tutorial, Part II: renaming files with renamer](https://akpw.github.io/articles/2015/04/11/batchmp-tutorial-part-ii.html)
+- [Practical BatchMP Series](https://akpw.github.io//tags.html#BatchMP+Tools)
+
+## Usage
+Run `reny --help` to see all available filesystem operations!
+
+## Development
+To set up the project for development:
+
+1. Clone the repository and navigate into it:
+   ```bash
+   git clone https://github.com/akpw/reny.git
+   cd reny
+   ```
+2. Create and activate a virtual environment:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+3. Install the project in editable mode along with testing dependencies:
+   ```bash
+   pip install -e ".[test]"
+   ```
+
+## Running Tests
+The project uses `pytest` for its test suite. Because `reny` performs real filesystem operations, the tests are designed to dynamically create and clean up safe temporary sandbox folders during execution.
+
+To run the full test suite:
+```bash
+pytest -v --tb=short tests/
+```
+
+To run a specific test file:
+```bash
+pytest tests/fs/test_fs_organize.py
+```

reny-1.0.0/README.md

@@ -0,0 +1,114 @@
+# Reny
+A lightweight, fast, and safe batch renaming and filesystem organization tool.
+
+## Background
+`reny` was originally created as the `renamer` component inside the larger [`batchmp`](https://github.com/akpw/batch-mp-tools) (Batch Media Processing) suite. It was spun off into its own standalone package to provide for an ultra-lightweight, safe, pure-filesystem organizing tool without FFmpeg / Mutagen media dependencies. 
+
+If you need advanced media operations (like denoising, cover-art extraction, or format transcoding), check out the original [`batchmp`](https://github.com/akpw/batch-mp-tools) project. If you just need to safely organize your files with surgical precision, `reny` is all you need.
+
+## Installation
+You can install `reny` globally using pipx:
+```bash
+pipx install .
+```
+
+## Features
+- **Virtual Views:** Preview how a directory structure would look when reorganised by type, size, or date without moving or changing anything
+- **Indexing:** Multi-level indexing across nested directories, supporting multiple indexing schemes
+- **Padding:** Automatically pad existing numbers in filenames with leading zeros to fix sorting orders
+- **Flattening:** Safely collapse nested directory structures into a single folder
+- **Regex Replacement:** Powerful batch renaming using standard regular expressions
+- **Dry-Run by Default:** `reny` will always visualize targeted changes and ask for confirmation before it ever touches your files
+
+## Examples
+
+### Basic Operations
+**Print current directory structure:**
+```bash
+reny
+```
+*(Without arguments, `reny` defaults to the `print` command)*
+
+**Add a sequential index to all `.txt` files recursively:**
+```bash
+reny -r -in '*.txt' index
+```
+
+**Pad existing numbers with leading zeros (e.g., `2 kms.png` becomes `02 kms.png`):**
+```bash
+reny pad -md 2
+```
+
+**Regex Replace:**
+Change spaces to underscores in all filenames:
+```bash
+reny replace -fs ' ' -rs '_'
+```
+
+### Advanced Operations & Virtual Views
+**Flattening nested directories:**
+Collapse all sub-directories and bring their files up to the current folder level:
+```bash
+reny flatten
+```
+
+**Organize by File Type:**
+Move files into sub-directories grouped by their file extension (e.g., `png/`, `pdf/`):
+```bash
+reny organize -b type
+```
+
+**Virtual Views (Dry-Run Preview):**
+Preview how files would look if organized by year and month, *without actually moving any files on your drive*:
+```bash
+reny print -b date --date-format "%Y/%m"
+```
+```text
+Virtual view by date:
+~/Downloads
+  |- 2025/
+    |- 01/
+      |- document.pdf
+    |- 02/
+      |- image.png
+```
+
+## Documentation & Tutorials
+Although `reny` is a standalone project, its core organizing logic is inherited directly from [`batchmp`](https://github.com/akpw/batch-mp-tools). You can find detailed tutorials and deep-dives on how to master its capabilities in the original blog posts:
+- [Renamer Organize & Virtual Views](https://akpw.github.io/articles/2025/09/22/Print-and-Organize.html) – *Highly recommended reading for mastering virtual directory views*
+- [BatchMP Tools Tutorial, Part II: renaming files with renamer](https://akpw.github.io/articles/2015/04/11/batchmp-tutorial-part-ii.html)
+- [Practical BatchMP Series](https://akpw.github.io//tags.html#BatchMP+Tools)
+
+## Usage
+Run `reny --help` to see all available filesystem operations!
+
+## Development
+To set up the project for development:
+
+1. Clone the repository and navigate into it:
+   ```bash
+   git clone https://github.com/akpw/reny.git
+   cd reny
+   ```
+2. Create and activate a virtual environment:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+3. Install the project in editable mode along with testing dependencies:
+   ```bash
+   pip install -e ".[test]"
+   ```
+
+## Running Tests
+The project uses `pytest` for its test suite. Because `reny` performs real filesystem operations, the tests are designed to dynamically create and clean up safe temporary sandbox folders during execution.
+
+To run the full test suite:
+```bash
+pytest -v --tb=short tests/
+```
+
+To run a specific test file:
+```bash
+pytest tests/fs/test_fs_organize.py
+```

reny-1.0.0/pyproject.toml

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

reny-1.0.0/reny/cli/base/bmp_dispatch.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python
+# coding=utf8
+## Copyright (c) 2014 Arseniy Kuznetsov
+##
+## This program is free software; you can redistribute it and/or
+## modify it under the terms of the GNU General Public License
+## as published by the Free Software Foundation; either version 2
+## of the License, or (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+
+from importlib import metadata
+import reny.cli.base.vchk
+from reny.cli.base.bmp_options import BatchMPArgParser, BatchMPBaseCommands
+
+
+class BatchMPDispatcher:
+    ''' Base BatchMP Commands Dispatcher
+    '''
+    def __init__(self):
+        self.option_parser = BatchMPArgParser()
+
+    # Dispatcher
+    def dispatch(self):
+        args = self.option_parser.parse_options()
+
+        if args['sub_cmd'] == BatchMPBaseCommands.VERSION:
+            self.print_version()
+
+        elif args['sub_cmd'] == BatchMPBaseCommands.INFO:
+            self.print_info()
+
+        else:
+            # nothing to dispatch
+            return False
+
+        return True
+
+    # Dispatched methods
+    def print_version(self):
+        ''' Prints BatchMP version info
+        '''
+        version = metadata.version("reny")
+        print('BatchMP tools version {}'.format(version))
+
+    def print_info(self):
+        print('\nBatch Media Processing Tools: {}'.format(self.option_parser.script_name))
+        print(self.option_parser.description)
+
+def main():
+    ''' BatchMP entry point
+    '''
+    BatchMPDispatcher().dispatch()
+
+if __name__ == '__main__':
+    main()
+

reny-1.0.0/reny/cli/base/bmp_options.py

@@ -0,0 +1,342 @@
+#!/usr/bin/env python
+# coding=utf8
+## Copyright (c) 2014 Arseniy Kuznetsov
+##
+## This program is free software; you can redistribute it and/or
+## modify it under the terms of the GNU General Public License
+## as published by the Free Software Foundation; either version 2
+## of the License, or (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+
+
+""" Global options parsing:
+        [-r, --recursive]           Recurse into nested folders
+        [-el, --end-level]          End level for recursion into nested folders
+
+        [-in, --include]            Include names pattern (Unix style)
+        [-ex, --exclude]            Exclude names pattern (Unix style)
+                                      (excludes hidden files by default)
+        [-ad, --all-dirs]           Prevent using Include/Exclude patterns on directories
+        [-af, --all-files]          Prevent using Include/Exclude patterns on files
+                                      (shows hidden files excluded by default)
+
+        [-s, --sort]{na|nd|sa|sd}   Sort order for files / folders (name | date, asc | desc)
+        [-ni, nested-indent]        Indent for printing nested directories
+        [-q, --quiet]               Do not visualise changes / show messages during processing
+"""
+
+import os, sys, string
+from argparse import ArgumentParser, HelpFormatter
+from reny.commons.utils import strtobool
+from urllib.parse import urlparse
+from reny.commons.utils import MiscHelpers
+from reny.fstools.fsutils import FSH
+from reny.fstools.builders.fsentry import FSEntry, FSEntryDefaults
+
+
+
+class BatchMPBaseCommands:
+    VERSION = 'version'
+    INFO = 'info'
+    PRINT = 'print'
+
+    @classmethod
+    def commands_meta(cls):
+        return ''.join(('{',
+                        '{}, '.format(cls.INFO),
+                        '{}'.format(cls.VERSION),
+                        '}'))
+
+class BatchMPArgParser:
+    def __init__(self):
+        self._script_name = 'Reny'
+        self._description = '''
+    Reny provides management of files, directories, etc...
+
+    Reny tools consist of three main command-line utilities.
+    For more information, run:
+        $ renamer -h
+        $ tagger -h
+        $ bmfp -h
+    '''
+
+    @property
+    def description(self):
+        return self._description
+
+    @property
+    def script_name(self):
+        return self._script_name
+
+    # Args parsing
+    def parse_options(self):
+        ''' Common workflow for parsing options
+        '''
+        parser = ArgumentParser(prog = self._script_name, description = self._description,
+                                                                formatter_class=BatchMPHelpFormatter)
+
+        self.parse_global_options(parser)
+
+        self.parse_commands(parser)
+
+        args = vars(parser.parse_args())
+
+        self.check_args(args, parser)
+
+        return args
+
+    def parse_global_options(self, parser):
+        ''' Parses global options
+        '''
+        source_mode_group = parser.add_argument_group('Input source mode')
+        source_mode_group.add_argument("-d", "--dir", dest = "dir",
+                    type = lambda d: self._is_valid_dir_path(parser, d),
+                    help = "Source directory (default is current directory)",
+                    default = os.curdir)
+        source_mode_group.add_argument("-f", "--file", dest = "file",
+                    type = lambda f: self._is_valid_file_path(parser, f),
+                    help = "File to process")
+
+        recursive_mode_group = parser.add_argument_group('Recursion mode')
+        recursive_mode_group.add_argument("-r", "--recursive", dest = "recursive",
+                    help = "Recurse into nested folders",
+                    action = 'store_true')
+        recursive_mode_group.add_argument("-el", "--end-level", dest = "end_level",
+                    help = "End level for recursion into nested folders",
+                    type = int,
+                    default = 0)
+
+        include_mode_group = parser.add_argument_group('Filter files or folders')
+        include_mode_group.add_argument("-in", "--include", dest = "include",
+                    help = "Include: Unix-style name patterns separated by ';'",
+                    type = str,
+                    default =  FSEntryDefaults.DEFAULT_INCLUDE)
+        include_mode_group.add_argument("-ex", "--exclude", dest = "exclude",
+                    help = "Exclude: Unix-style name patterns separated by ';' (excludes hidden files by default)",
+                    type = str,
+                    default =  FSEntryDefaults.DEFAULT_EXCLUDE)
+        include_mode_group.add_argument("-ad", "--all-dirs", dest = "all_dirs",
+                    help = "Disable Include/Exclude patterns on directories",
+                    action = 'store_true')
+        include_mode_group.add_argument("-af", "--all-files", dest = "all_files",
+                    help = "Disable Include/Exclude patterns on files (shows hidden files excluded by default)",
+                    action = 'store_true')
+
+        media_types_group = parser.add_argument_group('File media types')
+        media_types_group.add_argument("-ft", "--file-type", dest = "file_type",
+                    help = "File Media Type",
+                    type = str,
+                    choices = ['image', 'video', 'audio', 'media', 'nonmedia', 'playable', 'nonplayable', 'any'],
+                    default =  FSEntryDefaults.DEFAULT_FILE_TYPE)
+        media_types_group.add_argument("-ms", "--media-scan", dest = "media_scan",
+                    help = "Scan for media types, instead of using file extensions (can take a long time)",
+                    action = 'store_true')
+
+
+        # Add Default Miscellaneous Group
+        self._add_arg_misc_group(parser)
+
+    def parse_commands(self, parser):
+        ''' Specific commands parsing
+        '''
+        subparsers = parser.add_subparsers(dest = 'sub_cmd',
+                                            title = 'BatchMP commands',
+                                                metavar = BatchMPBaseCommands.commands_meta())
+        self._add_version(subparsers)
+        self._add_info(subparsers)
+
+    # Args checking
+    def check_cmd_args(self, args, parser,
+                        show_help = False,
+                        exit = False):
+        if not args.get('sub_cmd'):
+            if show_help:
+                parser.print_help()
+            if exit:
+                sys.exit(1)
+
+            # if not exiting, need to default
+            self.default_command(args, parser)
+
+    def default_command(self, args, parser):
+        args['sub_cmd'] = BatchMPBaseCommands.INFO
+
+    def check_args(self, args, parser):
+        ''' Validation of supplied CLI arguments
+        '''
+        # check if there is a cmd to execute
+        self.check_cmd_args(args, parser)
+
+        # if input source is a file, need to adjust
+        if args['file']:
+            args['dir'] = os.path.dirname(args['file'])
+            args['include'] = os.path.basename(args['file'])
+            args['exclude'] = ''
+            args['end_level'] = 0
+            args['all_files'] = False
+            args['all_dirs'] = False
+
+        # check recursion
+        if args['recursive'] and args['end_level'] == 0:
+            args['end_level'] = sys.maxsize
+
+
+        if args['media_scan']:
+            pass
+
+        if args['sub_cmd'] == BatchMPBaseCommands.PRINT:
+            if args['start_level'] != 0:
+                if args['file']:
+                    print ('Start Level parameter requires a source directory\n Ignoring requested Start Level...')
+                    args['start_level'] = 0
+                elif args['end_level'] < args['start_level']:
+                    ''' print ('Start Level should be greater than or equal to the Recursion End Level Global Option\n'
+                           '... Adjusting End Level to: {}'.format(args['start_level']))
+                    '''
+                    args['end_level'] = args['start_level']
+
+    # Internal Helpers
+    @staticmethod
+    def _is_valid_dir_path(parser, path_arg):
+        """ Checks if path_arg is a valid dir path
+        """
+        path_arg = FSH.full_path(path_arg)
+        if not (os.path.exists(path_arg) and os.path.isdir(path_arg)):
+            parser.error('"{}" does not seem to be an existing directory path'.format(path_arg))
+        else:
+            return path_arg
+
+    @staticmethod
+    def _is_valid_file_path(parser, path_arg):
+        """ Checks if path_arg is a valid file path
+        """
+        path_arg = FSH.full_path(path_arg)
+        if not (os.path.exists(path_arg) and os.path.isfile(path_arg)):
+            parser.error('"{}" does not seem to be an existing file path'.format(path_arg))
+        else:
+            return path_arg
+
+    @staticmethod
+    def _is_boolean(parser, bool_arg):
+        """ Checks if bool_arg can be interpreted as a boolean value
+        """
+        try:
+            bool_arg = True if strtobool(bool_arg) else False
+        except ValueError:
+            parser.error('"{}": Please enter a boolean value'.format(bool_arg))
+            return False
+
+    @staticmethod
+    def _is_valid_url(parser, url_arg):
+        url_parts = urlparse(url_arg)
+
+        def _parser_error():
+            parser.error('"{}": Please enter a valid URL'.format(url_arg))
+
+        if url_parts.scheme in (None, '') and url_parts.netloc in (None, ''):
+            _parser_error()
+
+        if url_parts.scheme == 'file':
+            if url_parts.netloc == '~':
+                fpath = '~{}'.format(url_parts.path)
+            else:
+                fpath = url_parts.path
+            return BatchMPArgParser._is_valid_file_path(parser, fpath)
+
+        if not set(url_parts.netloc).issubset(set(string.ascii_letters + string.digits + '-.')):
+            _parser_error()
+
+        if not url_parts.scheme in ['http', 'https', 'ftp', 'file']:
+            _parser_error()
+
+        return url_arg
+
+    @staticmethod
+    def _is_valid_url_or_file_path(parser, url_or_file_path_arg):
+        url_parts = urlparse(url_or_file_path_arg)
+        if url_parts.scheme in (None, '') and url_parts.netloc in (None, ''):
+            return BatchMPArgParser._is_valid_file_path(parser, url_or_file_path_arg)
+        else:
+            return BatchMPArgParser._is_valid_url(parser, url_or_file_path_arg)
+
+    @staticmethod
+    def _is_timedelta(parser, td_arg):
+        try:
+            td = MiscHelpers.time_delta(td_arg)
+        except ValueError:
+            parser.error('"{}": Please enter a valid value, ' \
+                         'in seconds or in the "hh:mm:ss[.xxx]" format'.format(td_arg))
+        return  td
+
+    # Processing mode for relevant commands
+    @staticmethod
+    def _add_arg_display_curent_state_mode(parser):
+        parser.add_argument('-dc', '--display-current', dest = 'display_current',
+                help ='Unless in quiet mode, display current (pre-processing) state in the confirmation propmt',
+                action = 'store_true')
+
+    @staticmethod
+    def _add_arg_misc_group(parser):
+        misc_group = parser.add_argument_group('Miscellaneous')
+        misc_group.add_argument('-s', '--sort', dest = 'sort',
+                    help = "Sorting for files ('na', i.e. by name ascending by default)",
+                    type = str,
+                    choices = ['na', 'nd', 'sa', 'sd'],
+                    default = FSEntryDefaults.DEFAULT_SORT)
+        misc_group.add_argument('-ni', '--nested_indent', dest = 'nested_indent',
+                    help = "Indent for printing  nested directories",
+                    type = str,
+                    default = '  ')
+        misc_group.add_argument("-q", "--quiet", dest = 'quiet',
+                    help = "Disable visualising changes & displaying info messages during processing",
+                    action = 'store_true')
+
+    @staticmethod
+    def _add_version(parser):
+        ''' Adds the version command
+        '''
+        parser.add_parser(BatchMPBaseCommands.VERSION,
+                                description = 'Displays BatchMP version info',
+                                        formatter_class=BatchMPHelpFormatter)
+
+    @staticmethod
+    def _add_info(parser):
+        ''' Adds the info command
+        '''
+        parser.add_parser(BatchMPBaseCommands.INFO,
+                                description = 'Displays BatchMP info',
+                                        formatter_class=BatchMPHelpFormatter)
+
+
+
+class BatchMPHelpFormatter(HelpFormatter):
+    ''' Custom ArgumentParser formatter
+        Disables double metavar display, showing it only for long-named options
+    '''
+    def _format_action_invocation(self, action):
+        if not action.option_strings:
+            metavar, = self._metavar_formatter(action, action.dest)(1)
+            return metavar
+        else:
+            parts = []
+            # if the Optional doesn't take a value, format is:
+            #    -s, --long
+            if action.nargs == 0:
+                parts.extend(action.option_strings)
+
+            # if the Optional takes a value, format is:
+            #    -s ARGS, --long ARGS
+            # change to
+            #    -s, --long ARGS
+            else:
+                default = action.dest.upper()
+                args_string = self._format_args(action, default)
+                for option_string in action.option_strings:
+                    #parts.append('%s %s' % (option_string, args_string))
+                    parts.append('%s' % option_string)
+                parts[-1] += ' %s'%args_string
+            return ', '.join(parts)