Skip to main content

Unoccupied

Find an unoccupied name from basename & occupied names.

If you tired to write a bunch of code to deal unnamed note 02, pic-03.jpg, archive.part4.zip naming problem. It's for you.

Features

  • Based on basename: find an unoccupied name as close as user wanted, not randomly.
  • Isolated: pure function API, no related outer environment like filesystem or DB.
  • Stable: consider edge situations and already be tested.
  • Flexible: library user can choice / overwrite naming algorithm easily.

Usage

Basic Usage

Use basename and occupied container (an iterable) to find a unoccupied name:

from unoccupied import unoccupied

basename = 'foo'



unoccupied(basename, [])  # 'foo' not be occupied
# >>> 'foo'

unoccupied(basename, ['foo'])  # 'foo' already be occupied
# >>> 'foo-1'

unoccupied(basename, ['foo', 'foo-1'])  # 'foo' & 'foo-1' already be occupied
# >>> 'foo-2'

Name Finder

Name finder offer an algorithm to find (or generate) an unoccupied name.

Let's try to change the default name finder:

from unoccupied import unoccupied
from unoccupied import NumberNameFinder  # A built-in name finder generator

# test data
basename = 'foo'
occupied = ['foo', 'bar', 'foo-1']



unoccupied(basename, occupied)  # use defualt name finder
# >>> 'foo-2'

name_finder = NumberNameFinder(template='{basename}-{num:02}')  # <- look here
unoccupied(basename, occupied, name_finder)
# >>> 'foo-01'

Another case: Assume we need to find an unoccupied filename, but, we don't want the base filename foo.txt become foo.txt-1. The foo-1.txt is much suitable name. Try the built-in FileNameFinder().

from unoccupied import unoccupied
from unoccupied import FileNameFinder  # here

# test data
basename = 'pic.jpg'
occupied = ['pic.jpg', 'pic-1.jpg', 'foo']  # may use os.listdir() in real case



unoccupied(basename, occupied, FileNameFinder())  # <- look here
# >>> 'pic-2.jpg'

name_finder = FileNameFinder(template='{base}.{num:02}', start=0)
unoccupied(basename, occupied, name_finder)
# >>> 'pic.00.jpg'

Build a Name Finder

A name_finder is just a callable accept 2 arguments: (basename, norm_occupied), so feel free to build your own. e.g.:

import string
from unoccupied import unoccupied

def alphabet_name_finder(basename, norm_occupied):
    for char in string.ascii_lowercase:
        testing_name = '{}-{}'.format(basename, char)
        if testing_name not in norm_occupied:
            return testing_name

unoccupied('foo', ['foo'], alphabet_name_finder)
# >>> 'foo-a'

Or, using BaseNameFinder class to build a name_finder:

import string
from unoccupied import unoccupied
from unoccupied import BaseNameFinder


class AlphabetNameFinder(BaseNameFinder):
    """Basic alphabet name finder."""
    def ids_generator(self):
        return string.ascii_lowercase

alphabet_name_finder = AlphabetNameFinder()

unoccupied('foo', ['foo'], alphabet_name_finder)
# >>> 'foo-a'


class AlphabetNameFinder2(BaseNameFinder):
    """Configurable alphabet name finder."""
    def __init__(self, template):       # here is a configurable option.
        self.template = template

    def ids_generator(self):
        return string.ascii_lowercase

    def formatter(self, basename, id):  # change formatting algorithm
        return self.template.format(basename=basename, id=id)

alphabet_name_finder2 = AlphabetNameFinder2(template='{basename}.{id}')

unoccupied('foo', ['foo'], alphabet_name_finder2)
# >>> 'foo.a'

As you see. BaseNameFinder packed some tedious work like for-loop & infinite loop checking. And good for offer some configurable options for further usage.

Reference

function unoccupied(basename, occupied, name_finder=NumberNameFinder(), skipbase=False)

Find a unoccupied name.

  • basename: (str) the wanted basename.
  • occupied: (str of iterable) the names already be occupied.

name_finder is a callable with 2 arguments (basename, norm_occupied). This function only be called when basename cannot use directly, and it should return None or string. Return None mean it can't find any unoccupied name and cause unoccupied() raise UnoccupiedNameNotFound exception.

Hint: occupied will be convert to frozenset data type (we call it norm_occupied) and inject to name_finder. If and only if you try to build a name_finder by yourself, you may need to know that.

skipbase is a boolean value. If True, basename will not return directly, no matter the basename already in occupied or not. So user can generate a consistent name series like pic-01, pic-02 and without pic.

class BaseNameFinder()

This is the base class of built-in NameFinder class. It has 2 method which can (but not necessary) be overwrited:

method ids_generator(self) -> Iterable

This method will create a series of id and push into self.formatter().

method formatter(self, basename, id) -> str

This method can assemble basename and id then return a string by any algorithm.

class NumberNameFinder(template='{basename}-{num}', start=1)

Generate a name_finder to find an unoccupied name with basename and an increasing number.

The template argument is a python str.format() template. This template can include 2 keyword params. {basename} represent the original basename. {num} represent an increasing number.

start argument can define what {num} starts from.

class FileNameFinder(template='{base}-{num}', start=1)

Generate a name_finder to find an unoccupied name with processed filename and an increasing number.

The template argument is a python str.format() template. This template can include 2 keyword params. {base} represent the filename without extension. {num} represent an increasing number. Hint: the filename extension will be appended automatically.

start argument can define what {num} starts from.

Test

./setup.py test  # or pytest

Install

pip install unoccupied

Metadata

Release files for unoccupied 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unoccupied 0.2.1
File Size Uploaded Provenance Actions
unoccupied-0.2.1.tar.gz 7.0 kB Without provenance Details for unoccupied-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for unoccupied 0.2.1
File Interpreter ABI Platform Actions
unoccupied-0.2.1-py3-none-any.whl Python 3 none any Details for unoccupied-0.2.1-py3-none-any.whl

Total release size: 12.8 kB

Release files / unoccupied-0.2.1.tar.gz

Download URL unoccupied-0.2.1.tar.gz
Size 7.0 kB
Tags Source
SHA-256 checksum
How to use checksums
d7871168d775e38e04916cfc9d5bc9a190075ff82fd01f3b3e5851673a7c6d8f
BLAKE2b-256 checksum
How to use checksums
d2fdb65cec8089acb4fb2080f237770d55bf4661d2a419a1394eca15ce896a08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / unoccupied-0.2.1-py3-none-any.whl

Download URL unoccupied-0.2.1-py3-none-any.whl
Size 5.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ef801cdba0f837ca25a0d1c4512f8c2b6fc9fa3ad1a70f4699fbb716ebb9665
BLAKE2b-256 checksum
How to use checksums
776f293ced439e67250dbcfb4e4171633a1525c3ab53f871794efbb507ac38ba
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for unoccupied 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page