API reference¶
pyimgren
module¶
This module imports pyimgren.pyimgren.Renamer
. It also defines the following constants:
-
pyimgren.
__name__
¶ the name of the package (
pyimgren
)
-
pyimgren.
__version__
¶ the actual version of the package (0.4.1)
pyimgren.pymgren
module¶
Implementation of the package
-
exception
pyimgren.pyimgren.
NamesLogException
(numlig, line)¶ Bases:
pyimgren.pyimgren.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.pyimgren.
PyimgrenException
¶ Bases:
Exception
Base for pyimgren exceptions
-
class
pyimgren.pyimgren.
Renamer
(folder, src_mask='DSCF*.jpg', dst_mask='%Y%m%d_%H%M%S', ext_mask='.jpg', ref_file='names.log', debug=False, dummy=False)¶ 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
- src_mask – a pattern to select the files to be renamed (default “DSCF*.jpg”)
- 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)
- 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
- parameters become attribute of the object with the same name (All) –
-
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() # to convert all files with selected pattern to # "date" names conv.back()
Note
This class requires piexif and Python >= 3.
-
back
(*pictures)¶ 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. Uses load_names to load the names.log file.
-
get_new_name
(name)¶ - 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: RuntimeErrorException
– if all files from a to zz already exist
-
load_names
()¶ 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 (:)
-
rename
(*pictures)¶ Rename pictures in folder (by default the pictures with the src_mask pattern)
Parameters: pictures – an iterable of paths. If a path is a folder, a new Renamer is started in that folder with current parameters to rename all files matching src_mask. If it is a file (that must be in the Renamer folder), that file will be renamed regardless of src_mask. If it contains wildcard characters (* and ?), all files matching that pattern will berenamed. Uses load_names to load the names.log file, and get_new_name to avoid collisions in file names.
-
exception
pyimgren.pyimgren.
UnknownPictureException
(file, renamer)¶ Bases:
pyimgren.pyimgren.PyimgrenException
Raised when trying to rename back a file not registered in the ref_file
-
file
¶ name of the unknown image
-
renamer
¶ the Renamer object that raised the current error
-
-
pyimgren.pyimgren.
exif_dat
(file)¶ Utility function that uses the piexif module to extract the date and time when the picture was taken from the exif tags
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