空置

basename从&中查找未占用的名称occupied names。

如果你累了写一堆代码来处理unnamed note 02、、pic-03.jpg命名archive.part4.zip问题。这是给你的。

特征

• 基于basename：找到一个与用户想要的一样接近的未被占用的名称，而不是随机的。
• 隔离：纯函数API，没有文件系统或数据库等相关外部环境。
• 稳定：考虑边缘情况并且已经过测试。
• 灵活：库用户可以轻松选择/覆盖命名算法。

用法

基本用法

使用basename和occupied容器（一个可迭代的）来查找一个未被占用的名称：

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'

名称查找器

名称查找器提供了一种算法来查找（或生成）未占用的名称。

让我们尝试更改默认名称查找器：

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'

另一种情况：假设我们需要找到一个未被占用的文件名，但是，我们不希望基本文件名foo.txt变成foo.txt-1. foo-1.txt很合适的名字。试试内置的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'

构建名称查找器

Aname_finder只是一个可调用的接受 2 个参数：( basename, norm_occupied)，所以请随意构建自己的。例如：

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'

或者，使用BaseNameFinder类来构建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'

正如你看到的。BaseNameFinder打包了一些繁琐的工作，例如 for-loop 和无限循环检查。并且有利于提供一些可配置的选项以供进一步使用。

参考

函数未占用（basename，占用，name_finder=NumberNameFinder()，skipbase=False）

找一个无人问津的名字。

• basename: (str) 想要的基本名称。
• occupied: (str of iterable) 名字已经被占用了。

name_finder是带有 2 个参数 ( basename, norm_occupied) 的可调用对象。该函数只有在basename不能直接使用时才调用，应该返回None或字符串。返回None意味着它找不到任何未占用的名称并导致unoccupied()引发UnoccupiedNameNotFound异常。

提示：occupied将转换为frozenset数据类型（我们称之为norm_occupied）并注入到name_finder. 当且仅当您尝试自己构建一个name_finder时，您可能需要知道这一点。

skipbase是一个布尔值。如果True,basename将不会直接返回，无论是否basename已经在occupied。因此，用户可以生成一致的名称系列，例如pic-01，pic-02而没有pic.

类 BaseNameFinder()

这是内置 NameFinder 类的基类。它有 2 种方法可以（但不是必须）被覆盖：

方法 ids_generator(self) -> 可迭代

此方法将创建一系列id并推入self.formatter().

方法格式化程序（self，basename，id）-> str

该方法可以通过任何算法组装basename然后id返回一个字符串。

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

生成一个name_finder以查找一个未占用的名称，其中basename的数字越来越多。

template参数是一个 pythonstr.format()模板。此模板可以包含 2 个关键字参数。{basename}代表原创basename。{num}代表越来越多的数字。

start参数可以定义{num}从什么开始。

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

生成 aname_finder以查找具有已处理文件名且数量不断增加的未占用名称。

template参数是一个 pythonstr.format()模板。此模板可以包含 2 个关键字参数。{base}表示没有扩展名的文件名。{num}代表越来越多的数字。提示：文件扩展名将被自动附加。

start参数可以定义{num}从什么开始。

测试

./setup.py test  # or pytest

安装

pip install unoccupied