Skip to content

sok.file_operations.book_operations

File operations for electronic books.

This module handles:

  • Detection and extraction of information from ebook file names
  • Reading metadata (EPUB, MOBI, PDF)
  • Automatic renaming
  • Organization by author/series

BookFileOperations

class BookFileOperations

Bases: FileOperations, FileParsingMixin, FileValidationMixin, FileListOrganizerMixin

File operations for electronic books.

Provides methods to extract metadata from ebook filenames, read embedded metadata (EPUB, MOBI, PDF), organize by author/series, and rename according to book conventions.

Source

supported_extensionsproperty

List[str]

Return list of supported ebook file extensions.

extract_info_from_filename

def extract_info_from_filename(filename: str) -> Dict[str, Any]:

Extract information from a ebook filename.

The input patterns of the settings are tried first (sok.core.name_patterns); the name is otherwise read by the rules of _parse_filename. "pattern" is the pattern that matched, if any.

Parameters

NameTypeDescription
filenamestrFile name to parse.

Returns

  • Dict[str, Any]Dictionary with extracted information.
Source

find_book_files

def find_book_files(directory: str, recursive: bool = True) -> List[str]:

Find all ebook files in a directory.

Parameters

NameTypeDefaultDescription
directorystrDirectory to scan.
recursiveboolTrueEnable recursive search.

Returns

  • List[str]List of ebook file paths.
Source

find_files

def find_files(directory: str, recursive: bool = True) -> List[str]:

Unified alias for find_book_files.

Parameters

NameTypeDefaultDescription
directorystr
recursiveboolTrue
Source

generate_new_filename

def generate_new_filename(
media_item: Optional[MediaItem],
original_filename: str,
) -> str:

Generate a new filename for a book.

With a book found online, the book format of the settings: 'Author - Title (Year).epub' by default. Otherwise the file name is tidied: 'Author - Title.epub' or 'Author - [Series 01] - Title.epub'.

Parameters

NameTypeDescription
media_itemOptional[MediaItem]The media item (Book), or None.
original_filenamestrOriginal filename.

Returns

  • strNew filename.
Source

organize_by_author

def organize_by_author(
source_path: str,
dest_path: str,
use_metadata: bool = True,
group_series: bool = True,
dry_run: bool = False,
) -> Dict[str, Any]:

Organize ebook files by Author (and optionally by series).

Created structure:

  • Author/Book.epub (if no series)
  • Author/Series/Book.epub (if series)

Parameters

NameTypeDefaultDescription
source_pathstrSource folder.
dest_pathstrDestination folder.
use_metadataboolTrueUse file metadata.
group_seriesboolTrueGroup books from the same series.
dry_runboolFalseSimulation mode.

Returns

  • Dict[str, Any]Organization report.
Source

read_metadata

def read_metadata(file_path: str) -> Dict[str, Any]:

Read metadata from an ebook file.

Parameters

NameTypeDescription
file_pathstrEbook file path.

Returns

  • Dict[str, Any]Dictionary with read metadata.
Source

Attributes

NameValue
loggerlogging.getLogger(__name__)
Built with Kiln