Generate unoccupied name.
Project description
# Unoccupied
Find an unoccupied name from basename & occupied names.
## Usage
### Basic Usage
Use `basename` and `occupied` container (an iterable) to find a unoccupied name:
```python3
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:
```python3
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()`.
```python3
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`, `occupied`), so feel free to build your own. e.g.:
```python3
import string
from unoccupied import unoccupied
def alphabet_name_finder(basename, occupied):
for char in string.ascii_lowercase:
testing_name = '{}-{}'.format(basename, char)
if testing_name not in occupied:
return testing_name
unoccupied('foo', ['foo'], alphabet_name_finder)
# >>> 'foo-a'
```
## Reference
### unoccupied(basename, occupied, name_finder=NumberNameFinder(), nobase=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`, `occupied`). This function only be called when `basename` cannot use directly, and it should return `None` or `str`. Return `None` mean cannot find any unoccupied name and cause `unoccupied()` raise `UnoccupiedNameNotFound` exception.
> Hint: Before call the `name_finder`, `occupied` will be convert to `set` type internally. If and only if you try to build a name_finder by youself, you may need to know that.
`nobase` is a boolean value. It request do not use `basename` as return directly, no matter `basename` already in `occupied` or not.
### 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.
### 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
```sh
./setup.py test # or pytest
```
## Install
```sh
pip install unoccupied
```
Find an unoccupied name from basename & occupied names.
## Usage
### Basic Usage
Use `basename` and `occupied` container (an iterable) to find a unoccupied name:
```python3
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:
```python3
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()`.
```python3
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`, `occupied`), so feel free to build your own. e.g.:
```python3
import string
from unoccupied import unoccupied
def alphabet_name_finder(basename, occupied):
for char in string.ascii_lowercase:
testing_name = '{}-{}'.format(basename, char)
if testing_name not in occupied:
return testing_name
unoccupied('foo', ['foo'], alphabet_name_finder)
# >>> 'foo-a'
```
## Reference
### unoccupied(basename, occupied, name_finder=NumberNameFinder(), nobase=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`, `occupied`). This function only be called when `basename` cannot use directly, and it should return `None` or `str`. Return `None` mean cannot find any unoccupied name and cause `unoccupied()` raise `UnoccupiedNameNotFound` exception.
> Hint: Before call the `name_finder`, `occupied` will be convert to `set` type internally. If and only if you try to build a name_finder by youself, you may need to know that.
`nobase` is a boolean value. It request do not use `basename` as return directly, no matter `basename` already in `occupied` or not.
### 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.
### 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
```sh
./setup.py test # or pytest
```
## Install
```sh
pip install unoccupied
```
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
unoccupied-0.1.0.tar.gz
(5.6 kB
view hashes)
Built Distribution
Close
Hashes for unoccupied-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 70a2b7646a3b1f6f6ff4007e6b25cbe07b408f841bbbe8fafbf742ed690792aa |
|
MD5 | c147bc277ec3e8a96c122f6af11d0965 |
|
BLAKE2b-256 | 2df5844d9c93266d2bc15751a1d37d66ec2f7a21d56702740e71048c8849c482 |