Content Entities

from typing import List, Dict, Any, Optional, Iterator, Union

class JmBaseEntity:
    """
    Base class for all entities with file I/O support and common properties.
    
    Attributes:
    - Various properties for metadata and file operations
    
    Methods:
    - to_file(filepath): Save entity to file
    - from_file(filepath): Load entity from file
    """

class DetailEntity(JmBaseEntity):
    """
    Base class for detailed entities with ID, title, and author properties.
    
    Attributes:
    - id: str - Entity identifier
    - title: str - Entity title/name  
    - author: List[str] - List of authors
    """

class IndexedEntity:
    """
    Provides indexing and iteration support for collections.
    
    Methods:
    - __getitem__(index): Access items by index
    - __iter__(): Iterate over items
    - __len__(): Get collection length
    """

class Downloadable:
    """
    Mixin class for entities that can be downloaded.
    
    Methods:
    - download(): Initiate download process
    """

class JmAlbumDetail(DetailEntity, IndexedEntity, Downloadable):
    """
    Represents a manga album with metadata and episodes.
    
    Attributes:
    - id: str - Album ID
    - title: str - Album title
    - author: List[str] - List of authors
    - name: str - Album name (alias for title)
    - description: str - Album description
    - tags: List[str] - List of tags/categories
    - episodes: List[JmPhotoDetail] - List of chapters/photos
    - episode_list: List[JmPhotoDetail] - Alias for episodes
    - page_count: int - Total number of pages across all episodes
    - pub_date: str - Publication date
    - update_date: str - Last update date
    - series_id: str - Series identifier if part of series
    - related_list: List[JmAlbumDetail] - Related albums
    - scramble_id: int - Image scrambling identifier
    
    Methods:
    - __getitem__(index): Access episodes by index
    - __iter__(): Iterate over episodes
    - __len__(): Get number of episodes
    - download(): Download entire album
    """

# Access album information
album, _ = download_album("123456")
print(f"Title: {album.title}")
print(f"Authors: {', '.join(album.author)}")
print(f"Episodes: {len(album)}")
print(f"Tags: {', '.join(album.tags)}")

# Iterate through episodes
for i, episode in enumerate(album):
    print(f"Episode {i+1}: {episode.title}")

# Access specific episode
first_episode = album[0]
print(f"First episode: {first_episode.title}")

# Save album data to file
album.to_file("album_123456.json")

# Load album data from file
loaded_album = JmAlbumDetail.from_file("album_123456.json")

class JmPhotoDetail(DetailEntity, IndexedEntity, Downloadable):
    """
    Represents a chapter/photo with images and metadata.
    
    Attributes:
    - id: str - Photo ID
    - title: str - Photo title
    - author: List[str] - List of authors
    - name: str - Photo name (alias for title)
    - index: int - Photo index within album
    - page_count: int - Number of images in this photo
    - images: List[JmImageDetail] - List of images
    - image_list: List[JmImageDetail] - Alias for images
    - album_id: str - Parent album ID
    - pub_date: str - Publication date
    - scramble_id: int - Image scrambling identifier
    - data_original: Dict[str, Any] - Original API response data
    
    Methods:
    - __getitem__(index): Access images by index
    - __iter__(): Iterate over images
    - __len__(): Get number of images
    - download(): Download all images in this photo
    """

# Access photo information
photo, _ = download_photo("456789")
print(f"Title: {photo.title}")
print(f"Images: {len(photo)}")
print(f"Album ID: {photo.album_id}")

# Iterate through images
for i, image in enumerate(photo):
    print(f"Image {i+1}: {image.filename}")

# Access specific image
first_image = photo[0]
print(f"First image URL: {first_image.download_url}")

class JmImageDetail(JmBaseEntity, Downloadable):
    """
    Represents an individual image with download URL and properties.
    
    Attributes:
    - id: str - Image ID
    - filename: str - Image filename
    - download_url: str - Image download URL
    - img_url: str - Alias for download_url
    - width: int - Image width in pixels
    - height: int - Image height in pixels
    - size: int - File size in bytes
    - index: int - Image index within photo
    - photo_id: str - Parent photo ID
    - album_id: str - Parent album ID
    - scramble_id: int - Image scrambling identifier
    - is_scrambled: bool - Whether image is scrambled
    
    Methods:
    - download(): Download this specific image
    """

# Access image information
album, _ = download_album("123456")
first_photo = album[0]
first_image = first_photo[0]

print(f"Filename: {first_image.filename}")
print(f"Size: {first_image.width}x{first_image.height}")
print(f"Download URL: {first_image.download_url}")
print(f"File size: {first_image.size} bytes")

class JmPageContent:
    """
    Base class for paginated content with navigation support.
    
    Attributes:
    - page_num: int - Current page number
    - total_pages: int - Total number of pages
    - has_next: bool - Whether next page exists
    - has_prev: bool - Whether previous page exists
    
    Methods:
    - next_page(): Get next page content
    - prev_page(): Get previous page content
    """

class JmSearchPage(JmPageContent, IndexedEntity):
    """
    Search results page with albums and pagination.
    
    Attributes:
    - albums: List[JmAlbumDetail] - List of albums in search results
    - content: List[JmAlbumDetail] - Alias for albums
    - search_query: str - Original search query
    - total_results: int - Total number of results
    
    Methods:
    - __getitem__(index): Access albums by index
    - __iter__(): Iterate over albums
    - __len__(): Get number of albums on this page
    """

class JmFavoritePage(JmPageContent, IndexedEntity):
    """
    User favorites page content.
    
    Attributes:
    - albums: List[JmAlbumDetail] - List of favorite albums
    - content: List[JmAlbumDetail] - Alias for albums
    - folder_name: str - Favorites folder name
    
    Methods:
    - __getitem__(index): Access albums by index
    - __iter__(): Iterate over albums
    - __len__(): Get number of albums on this page
    """

class JmCategoryPage(JmSearchPage):
    """
    Category listing page (alias for JmSearchPage).
    
    Attributes:
    - category_name: str - Category name
    - category_id: str - Category identifier
    """

# Search for albums
from jmcomic import JmHtmlClient
client = JmHtmlClient()
search_page = client.search_album("search_term")

print(f"Found {search_page.total_results} results")
print(f"Page {search_page.page_num} of {search_page.total_pages}")

# Iterate through search results
for album in search_page:
    print(f"Album: {album.title}")

# Navigate pages
if search_page.has_next:
    next_page = search_page.next_page()
    print(f"Next page has {len(next_page)} albums")