API reference

pyimgren module

This module imports pyimgren.renamer.Renamer and the function pyimgren.renamer.nls_init(). It also defines the following constants:

pyimgren.__name__

the name of the package (pyimgren)

pyimgren.__version__

the current version of the package (1.0.0)

pyimgren.renamer module

Implementation of the package

pyimgren.renamer.nls_init(reset: bool = False) → str

Initialize the package for i18n

Parameters:

reset – Indicates whether i18n should be setup (if True) or removed (if False)

Returns: the name of the locale currently used by the package

exception pyimgren.renamer.PyimgrenException

Bases: Exception

Base for pyimgren exceptions

exception pyimgren.renamer.NamesLogException(numlig: int, line: str)

Bases: PyimgrenException

Raised when a line in the names.log file cannot be parsed

numlig

line number where the problem occurs

line

content of the offending line

exception pyimgren.renamer.UnknownPictureException(file: str, renamer: Renamer)

Bases: PyimgrenException

Raised when trying to rename back a file not registered in the ref_file

file

name of the unknown image

ref_file

the reference file (names.txt) of the Renamer

folder

the (output) folder of the Renamer

exception pyimgren.renamer.MergeSameDirException(folder: str)

Bases: PyimgrenException

Raised when trying to merge one directory into itself.

folder

name of the directory

class pyimgren.renamer.Renamer(folder, dst_mask='%Y%m%d_%H%M%S', ext_mask='.jpg', ref_file='names.log')

Bases: object

Main class of the module.

A Renamer is used to rename image names provided by a camera (commonly IMGxxxxx.JPG or DSCFyyyy.JPG) into a name based on the time when the photography had been taken (as smartphones do). That time is extracted from the exif tag of the picture. No rename occurs if the picture contains no exif time.

Parameters:

• folder – the folder where pictures will be renamed

• dst_mask – a format containing strftime formatting directives, that will be used for the new name of a picture (default “%Y%m%d_%H%M%S”)

• ext_mask – the extension of the new name

• ref_file – the name of a file that will remember the old names (default names.log)

All parameters become attribute of the object with the same name

delta

a number of minutes to add to the time found in exif data. This is intended to cope with a camera having a wrong time (default 0)

Type:

int

debug

a boolean flag that will cause a line to be printed for each rename when true (default false)

Type:

bool

dummy

a boolean flag that will cause a “dry run”, meaning that the folder will be scanned, and debug info eventually printed but no file will be renamed (default false)

Type:

bool

log: an object respecting a logging.Logger interface. By default,

logging.getLogger("pyimgren")

A file named names.log is created in the folder to store the new names and the original ones, in order to be able to rename them back.

Example:

conv = Renamer(path)
conv.rename(*files)   # to convert all files from the iterable files to
                      #  "date" names
conv.back()

Note

This class requires piexif and Python >= 3.

rename(*pictures, delta: int = 0, debug: bool = False, dummy: bool = False) → None

Rename pictures in folder

Parameters:

• pictures – an iterable of names of files to rename (they must be in the Renamer folder). If a name contains wildcard characters (* and ?), all files matching that pattern will be renamed.

• delta – a number of minutes to add to the time found in exif data. This is intended to cope with a camera having a wrong time

• debug – a boolean flag that will cause a line to be printed for each rename when true

• dummy – a boolean flag that will cause a “dry run”, meaning that the folder will be scanned, and debug info eventually printed but no file will be renamed

Uses load_names to load the names.log file, and get_new_name to avoid collisions in file names.

Raises:

RuntimeErrorException – if for a destination name, all files from a to zz already exist

back(*pictures, delta: int = 0, debug: bool = False, dummy: bool = False) → None

Rename pictures back to their initial name in folder (by default all pictures known in ref file)

Parameters:

• pictures – an iterable of names. If one name exists in the local ref_file, that file will be renamed back. If it contains wildcard characters (* and ?), all files matching that pattern will be processed.

• delta – a number of minutes to add to the time found in exif data. This is intended to cope with a camera having a wrong time

• debug – a boolean flag that will cause a line to be printed for each rename when true

• dummy – a boolean flag that will cause a “dry run”, meaning that the folder will be scanned, and debug info eventually printed but no file will be renamed

Uses load_names to load the names.log file.

merge(*files, src_folder: str = '.', delta: int = 0, debug: bool = False, dummy: bool = False) → None

Merge files from a different folder.

Parameters:

• *files – file names or patterns containing wildcard characters (* or?) defining the files to be copied.

• src_folder – the name of the folder containing the files to merge. It cannot contain wildcard characters.

• delta – a number of minutes to add to the time found in exif data. This is intended to cope with a camera having a wrong time

• debug – a boolean flag that will cause a line to be printed for each rename when true

• dummy – a boolean flag that will cause a “dry run”, meaning that the folder will be scanned, and debug info eventually printed but no file will be renamed

If src_folder is given it is used as a start path component for all relative paths in files.

The files are not moved but remain in their original folder. As usual, the copies receive a name based on their exif timestamp encoded by strftime using dst_mask and dst_ext.

If a name matches a directory, the directory is ignored and a warning is issued.

Raises:

RuntimeErrorException – if all files from a to zz already exist

load_names() → Mapping[str, str]

Load new and original names from a names.log file.

Returns:

the keys of the dict are the new names of the renamed pictures and the values are the original names

Return type:

OrderedDict

Raises:

NamesLogException – the attributes of the NamesLogException are the number of the offending line and its content if a line in names.log contains no colon (:)

get_new_name(name: str) → str

Finds the final name of a picture if a file with that name

already exists.

Parameters:

name – the name (without the extension which shall be ext_mask)

Returns:

a name composed with

• the value of name

• a suffix between a and zz until a file of that name does not exist in the directory

• ext_mask

Return type:

str

Raises:

RuntimeError – if all files from a to zz already exist

pyimgren.renamer.exif_dat(file)

Extract the timestamp of a picture file from the exif tags.

This function is a wrapper around the piexif module to easily find the date and time when the picture was taken. It first tries the time when the camera took the picture, then the time when the file was writen on the memory card.

Parameters:

file – the name of an image file that shall contain an exif tag

Returns:

the date when the picture was taken or stored by the camera found in the exif tag or None if no date could be found.

Return type:

datetime.datetime