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 ContentTypeBases: Enum
Specific content types within media categories.
Used to specify the exact type of content when searching or retrieving details from media APIs.
SourceAttributes
| Name |
|---|
ALBUM |
ARTIST |
AUDIOBOOK |
BOOK |
COMIC |
DLC |
DOCUMENTARY |
EBOOK |
EPISODE |
GAME |
MOVIE |
PLAYLIST |
TRACK |
TV_SERIES |
FileOperations
class FileOperationsBases: 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.
Sourcesupported_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
| Name | Type | Description |
|---|---|---|
filename | str | The filename to parse. |
Returns
Dict[str, Any]Dict containing extracted information (title, year, etc.).
generate_new_filenameabstractmethod
def generate_new_filename(media_item: MediaItem, original_filename: str) -> str:Generate a new filename based on media item metadata.
Parameters
| Name | Type | Description |
|---|---|---|
media_item | MediaItem | The media item with metadata. |
original_filename | str | The original filename. |
Returns
strNew formatted filename.
MediaAPI
class MediaAPIBases: 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.
Sourcesupported_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
| Name | Type | Description |
|---|---|---|
item_id | str | Unique identifier of the item. |
content_type | ContentType | Type of content. |
**kwargs | Additional API-specific parameters. |
Returns
Dict[str, Any]Dict containing detailed item information.
get_related_itemsabstractmethodasync
async def get_related_items( item_id: str, content_type: ContentType, **kwargs,) -> List[Dict[str, Any]]:Retrieve related items (episodes, tracks, chapters, etc.).
Parameters
| Name | Type | Description |
|---|---|---|
item_id | str | Unique identifier of the parent item. |
content_type | ContentType | Type of content. |
**kwargs | Additional API-specific parameters. |
Returns
List[Dict[str, Any]]List of related item dictionaries.
searchabstractmethodasync
async def search( query: str, content_type: ContentType, **kwargs,) -> Dict[str, Any]:Search for media items.
Parameters
| Name | Type | Description |
|---|---|---|
query | str | Search query string. |
content_type | ContentType | Type of content to search for. |
**kwargs | Additional API-specific parameters. |
Returns
Dict[str, Any]Dict with 'results' key containing list of matching items.
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
| Name | Type | Description |
|---|---|---|
title | str | The item's display title. |
media_type | MediaType | The media category. |
content_type | ContentType | The specific content type. |
Attributes
| Name | Type | Description |
|---|---|---|
content_type | Specific type (MOVIE, ALBUM, etc.). | |
id | Optional[str] | Unique identifier from the source API. |
media_type | Category (VIDEO, MUSIC, etc.). | |
metadata | Dict[str, Any] | Additional metadata dictionary. |
poster_url | Optional[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.
get_formatted_nameabstractmethod
def get_formatted_name() -> str:Return the formatted name for the file.
Returns
strFormatted string suitable for use as a filename.
to_dict
def to_dict() -> Dict[str, Any]:Convert the item to a dictionary.
Returns
Dict[str, Any]Dict representation of the media item.
MediaType
class MediaTypeBases: Enum
Supported media type categories.
SourceAttributes
| Name | Description |
|---|---|
BOOK | Books, ebooks, audiobooks, comics. |
GAME | Video games, DLCs. |
MUSIC | Albums, tracks, artists, playlists. |
VIDEO | Movies, TV series, documentaries. |