Skip to content

sok.core.history

Rename history: what each rename did, and how to undo it.

A rename runs inside record(): the file operations report each move (move_file), each folder they create (make_folders) and each poster they save to the active Journal. At the end, the journal becomes an Operation of the HistoryStore, saved in history.json next to the settings.

Undoing puts the files back where they were, but never replaces a file: a file moved or deleted since, or an old place taken by another file, is skipped. A hard link or a copy is deleted when its source is still there. The .backup kept for a replaced file is put back, the posters the rename saved are deleted once all their files are back, and the folders it created are removed when they are empty.

Artworkdataclass

class Artwork(path: str, files: List[str], removed: bool = False)

A poster or cover saved by a rename, and the files it belongs to.

Parameters

NameTypeDefaultDescription
pathstr
filesList[str]
removedboolFalse
Source

Attributes

NameType
filesList[str]
pathstr
removedbool

HistoryStore

class HistoryStore(path: Path)

The operations of the history, newest first, saved in a JSON file.

Parameters

NameTypeDescription
pathPath
Source

Attributes

Name
path

add

def add(operation: Operation) -> None:

Add an operation, dropping the oldest beyond MAX_OPERATIONS.

Parameters

NameTypeDescription
operationOperation
Source

clear

def clear() -> None:
Source

get

def get(operation_id: str) -> Optional[Operation]:

Parameters

NameTypeDescription
operation_idstr
Source

operations

def operations() -> List[Operation]:

The operations, newest first.

Source

undo

def undo(operation_id: str, index: Optional[int] = None) -> UndoReport:

Put the files of an operation back where they were.

Parameters

NameTypeDefaultDescription
operation_idstrThe operation.
indexOptional[int]NoneOne file of it (its position in moves), or None for all. The files that follow it, such as its subtitles, go back too.

Returns

  • UndoReportThe files put back and the ones left in place, with why.
Source

Journal

class Journal()

What a rename does, reported by the file operations as it goes.

Source

Attributes

NameType
artworkList[Artwork]
foldersList[str]
movesList[Move]
operation_idOptional[str]

created_folders

def created_folders(folders: List[str]) -> None:

Parameters

NameTypeDescription
foldersList[str]
Source

moved

def moved(
source: str,
target: str,
backup: Optional[str],
follows: Optional[str] = None,
mode: str = MOVE,
) -> None:

Parameters

NameTypeDefaultDescription
sourcestr
targetstr
backupOptional[str]
followsOptional[str]None
modestrMOVE
Source

saved_artwork

def saved_artwork(path: str, files: List[str]) -> None:

Parameters

NameTypeDescription
pathstr
filesList[str]
Source

Movedataclass

class Move(
source: str,
target: str,
backup: Optional[str] = None,
undone: bool = False,
follows: Optional[str] = None,
mode: str = MOVE,
)

One file of a rename: where it was, where it went.

Parameters

NameTypeDefaultDescription
sourcestr
targetstr
backupOptional[str]None
undoneboolFalse
followsOptional[str]None
modestrMOVE
Source

Attributes

NameType
backupOptional[str]
followsOptional[str]
modestr
sourcestr
targetstr
undonebool

Operationdataclass

class Operation(
id: str,
date: str,
kind: str,
moves: List[Move] = list(),
folders: List[str] = list(),
artwork: List[Artwork] = list(),
)

One rename: all the files of one click on "Rename all".

Parameters

NameTypeDefaultDescription
idstr
datestr
kindstr
movesList[Move]list()
foldersList[str]list()
artworkList[Artwork]list()
Source

Attributes

NameType
artworkList[Artwork]
datestr
foldersList[str]
idstr
kindstr
movesList[Move]

partly_undoneproperty

bool

True when some files, but not all, were put back.

undoneproperty

bool

True when every file was put back.

from_dictclassmethod

def from_dict(data: Dict[str, Any]) -> Operation:

Parameters

NameTypeDescription
dataDict[str, Any]
Source

UndoReportdataclass

class UndoReport(restored: List[Move] = list(), skipped: List[tuple] = list())

What an undo did: the files put back and the files left in place.

Parameters

NameTypeDefaultDescription
restoredList[Move]list()
skippedList[tuple]list()
Source

Attributes

NameType
restoredList[Move]
skippedList[tuple]

Functions

content_kind

def content_kind(media_item: Any) -> str:

The kind of an operation: the ContentType value of its item.

Parameters

NameTypeDescription
media_itemAny
Source

current_journal

def current_journal() -> Optional[Journal]:

The journal of the rename running in this thread, if any.

Source

get_history

def get_history() -> HistoryStore:

The history of the application, in history.json next to the settings.

Source

record

def record(
kind: str,
store: Optional[HistoryStore] = None,
) -> Iterator[Journal]:

Record the rename run in the block as one operation of the history.

Parameters

NameTypeDefaultDescription
kindstrWhat was renamed, a ContentType value such as "movie".
storeOptional[HistoryStore]NoneThe history to add it to (get_history() by default).

Yields

  • JournalThe journal; its operation_id is set at the end when files moved.
Source

Attributes

NameValue
COPY'copy'
FAILED'failed'
FILE_MODES(MOVE, LINK, COPY)
MAX_OPERATIONS100
MISSING'missing'
MOVE'move'
OCCUPIED'occupied'
SYSTEM_FILES{'.DS_Store', 'Thumbs.db', 'desktop.ini'}
loggerlogging.getLogger(__name__)
Built with Kiln