NextFreeFileName

NextFreeFileName is a micro-package aiming to simplify the process of finding the next available filename when generating files as part of a large process.

Overview

To understand the purpose of NextFreeFileName, walk thorough an exemplary case.
Let's suppose the following scenario:

• You're generating SVG files using the contents of multiple JSON files
  
• The filename of one of your processed JSON file is: performance_graph.json
  
• You need to generate 3 SVG files using information from this JSON
  
• You want all your generated SVGs to share a common name (usually the name of the source file)
• You want to distinguish the generated SVGs by having a numeric suffix in their file names
  

To find the next free filename, you can execute the following statements:

from NextFreeFileName import NextFreeFileName

src_json = '/tmp/performance_graph.json'
svg_out = NextFreeFileName('/tmp/performance_graph.svg')

If /tmp/performance_graph.svg already exists, svg_out returns the following NextFreeFileName object:
PosixPath('/tmp/performance_graph_0.svg')
Otherwise the original path is returned with no numeric suffix: PosixPath('/tmp/performance_graph.svg').

File names can be dynamically generated using the NextFreeFileName.next() method.

Demo

To demonstrate a real-world use case, let's generate 4 empty .txt files:

from NextFreeFileName import NextFreeFileName

out_txt = NextFreeFileName('/tmp/performance_graph.txt')  # Can be str OR class 'pathlib.*'
i = 0
while i < 4:
    with open(out_txt.next(), 'w') as f:
        f.write('Some text...')
        f.close()
    i += 1

Results:

ls
# performance_graph.txt performance_graph_0.txt performance_graph_1.txt performance_graph_2.txt

API Description

class NextFreeFileName:
    def __init__(self,
                 file_path, glue="_", index=0, ignore_reserved=False, resolve_suffix=True):
        """
        Takes a path to a file and if already exists, a number gets appended to its end.
        If file exists, glue + index gets appended to it.
        If file does not exist, the initial value of file_path gets returned as Path.
        :param file_path: (str | Path) Path to existing or desired output
        :param glue: (str) Character gluing together the `original file name` and the `index`. Default=_ (underscore)
        :param index: (int) Number to start counting from
        :param ignore_reserved: Set to True if you don't want to compare glue's value to reserved character's list
        :param resolve_suffix: Sets index based on the file name's current numeric suffix (if exists)
        """

• To initialize NextFreeFileName, a value must be provided for file_path.
  Accepted types: str or a pathlib-like objects.
  
• By default, filename and the generated integer are glued together with an underscore(_).
  To override it, set the value of glue to any valid unicode character. Exceptions: * / : < > ? \ | ".
• By default, the generated integer starts at 0.
  To override it, set the value of index to any valid integer.
• By default a few characters (see above) are restricted for glue.
  To disable this restriction, set ignore_reserved to True.

Installation

To install NFFN, execute the following steps:

1. Get the latest Release or clone the repository:
   git clone git@github.com:theriverman/NextFreeFileName.git
2. Install to your virtualenv by executing the following command:
   python setup.py install
3. Import the main class to your project:
   from NFFN import NextFreeFileName

PyPI package may be added later.

Compatibility

Python 3.6.0 and above.

This library takes advantage of f-strings PEP 498 and Type Hints PEP 484.

Copyright

MIT License