Skip to content

sok.core.interfaces

Core interfaces and abstract base classes.

Defines the abstract interfaces for media APIs, media types, content types, and media items that all implementations must follow.

ContentType

class ContentType

Bases: Enum

Specific content types within media categories.

Used to specify the exact type of content when searching or retrieving details from media APIs.

Source

Attributes

Name
ALBUM
ARTIST
AUDIOBOOK
BOOK
COMIC
DLC
DOCUMENTARY
EBOOK
EPISODE
GAME
MOVIE
PLAYLIST
TRACK
TV_SERIES

FileOperations

class FileOperations

Bases: ABC

Interface for file operations specific to each media type.

Implementations handle media-type-specific file operations like parsing filenames, generating new names, and validating extensions.

Source

supported_extensionsproperty

List[str]

Supported file extensions for this media type.

extract_info_from_filenameabstractmethod

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

Extract information from a filename.

Parameters

NameTypeDescription
filenamestrThe filename to parse.

Returns

  • Dict[str, Any]Dict containing extracted information (title, year, etc.).
Source

generate_new_filenameabstractmethod

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

Generate a new filename based on media item metadata.

Parameters

NameTypeDescription
media_itemMediaItemThe media item with metadata.
original_filenamestrThe original filename.

Returns

  • strNew formatted filename.
Source

MediaAPI

class MediaAPI

Bases: ABC

Abstract interface for all media APIs.

Defines the contract that all API implementations must follow. Implementations should handle authentication, rate limiting, and response normalization internally.

Source

supported_content_typesproperty

List[ContentType]

Content types supported by this API.

supported_media_typesproperty

List[MediaType]

Media types supported by this API.

get_detailsabstractmethodasync

async def get_details(
item_id: str,
content_type: ContentType,
**kwargs,
) -> Dict[str, Any]:

Retrieve detailed information about an item.

Parameters

NameTypeDescription
item_idstrUnique identifier of the item.
content_typeContentTypeType of content.
**kwargsAdditional API-specific parameters.

Returns

  • Dict[str, Any]Dict containing detailed item information.
Source
async def get_related_items(
item_id: str,
content_type: ContentType,
**kwargs,
) -> List[Dict[str, Any]]:

Retrieve related items (episodes, tracks, chapters, etc.).

Parameters

NameTypeDescription
item_idstrUnique identifier of the parent item.
content_typeContentTypeType of content.
**kwargsAdditional API-specific parameters.

Returns

  • List[Dict[str, Any]]List of related item dictionaries.
Source
async def search(
query: str,
content_type: ContentType,
**kwargs,
) -> Dict[str, Any]:

Search for media items.

Parameters

NameTypeDescription
querystrSearch query string.
content_typeContentTypeType of content to search for.
**kwargsAdditional API-specific parameters.

Returns

  • Dict[str, Any]Dict with 'results' key containing list of matching items.
Source

MediaItem

class MediaItem(title: str, media_type: MediaType, content_type: ContentType)

Bases: ABC

Abstract interface for all media items.

Base class for all media domain objects (Movie, Series, Album, etc.). Provides common functionality for formatting names and generating folder structures.

Initialize a media item.

Parameters

NameTypeDescription
titlestrThe item's display title.
media_typeMediaTypeThe media category.
content_typeContentTypeThe specific content type.
Source

Attributes

NameTypeDescription
content_type

Specific type (MOVIE, ALBUM, etc.).

idOptional[str]

Unique identifier from the source API.

media_type

Category (VIDEO, MUSIC, etc.).

metadataDict[str, Any]

Additional metadata dictionary.

poster_urlOptional[str]

Poster or cover of the item, as the service gives it (a URL, or a TMDB path), or None.

title

The item's title/name.

get_folder_structureabstractmethod

def get_folder_structure() -> List[str]:

Return the recommended folder structure.

Returns

  • List[str]List of folder names from root to item location.
Source

get_formatted_nameabstractmethod

def get_formatted_name() -> str:

Return the formatted name for the file.

Returns

  • strFormatted string suitable for use as a filename.
Source

to_dict

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

Convert the item to a dictionary.

Returns

  • Dict[str, Any]Dict representation of the media item.
Source

MediaType

class MediaType

Bases: Enum

Supported media type categories.

Source

Attributes

NameDescription
BOOK

Books, ebooks, audiobooks, comics.

GAME

Video games, DLCs.

MUSIC

Albums, tracks, artists, playlists.

VIDEO

Movies, TV series, documentaries.

Built with Kiln