0
# Content Entities
1

2
Data models representing albums, photos, images, and search results with rich metadata and download capabilities. These entities provide structured access to content information and support various operations like indexing, iteration, and file I/O.
3

4
## Types
5

6
```python { .api }
7
from typing import List, Dict, Any, Optional, Iterator, Union
8
```
9

10
## Capabilities
11

12
### Base Entity Classes
13

14
Foundation classes that provide common functionality for all content entities.
15

16
```python { .api }
17
class JmBaseEntity:
18
    """
19
    Base class for all entities with file I/O support and common properties.
20
    
21
    Attributes:
22
    - Various properties for metadata and file operations
23
    
24
    Methods:
25
    - to_file(filepath): Save entity to file
26
    - from_file(filepath): Load entity from file
27
    """
28

29
class DetailEntity(JmBaseEntity):
30
    """
31
    Base class for detailed entities with ID, title, and author properties.
32
    
33
    Attributes:
34
    - id: str - Entity identifier
35
    - title: str - Entity title/name  
36
    - author: List[str] - List of authors
37
    """
38

39
class IndexedEntity:
40
    """
41
    Provides indexing and iteration support for collections.
42
    
43
    Methods:
44
    - __getitem__(index): Access items by index
45
    - __iter__(): Iterate over items
46
    - __len__(): Get collection length
47
    """
48

49
class Downloadable:
50
    """
51
    Mixin class for entities that can be downloaded.
52
    
53
    Methods:
54
    - download(): Initiate download process
55
    """
56
```
57

58
### Album Entity
59

60
Represents a manga album/book with complete metadata including episodes, tags, and author information.
61

62
```python { .api }
63
class JmAlbumDetail(DetailEntity, IndexedEntity, Downloadable):
64
    """
65
    Represents a manga album with metadata and episodes.
66
    
67
    Attributes:
68
    - id: str - Album ID
69
    - title: str - Album title
70
    - author: List[str] - List of authors
71
    - name: str - Album name (alias for title)
72
    - description: str - Album description
73
    - tags: List[str] - List of tags/categories
74
    - episodes: List[JmPhotoDetail] - List of chapters/photos
75
    - episode_list: List[JmPhotoDetail] - Alias for episodes
76
    - page_count: int - Total number of pages across all episodes
77
    - pub_date: str - Publication date
78
    - update_date: str - Last update date
79
    - series_id: str - Series identifier if part of series
80
    - related_list: List[JmAlbumDetail] - Related albums
81
    - scramble_id: int - Image scrambling identifier
82
    
83
    Methods:
84
    - __getitem__(index): Access episodes by index
85
    - __iter__(): Iterate over episodes
86
    - __len__(): Get number of episodes
87
    - download(): Download entire album
88
    """
89
```
90

91
Usage examples:
92

93
```python
94
# Access album information
95
album, _ = download_album("123456")
96
print(f"Title: {album.title}")
97
print(f"Authors: {', '.join(album.author)}")
98
print(f"Episodes: {len(album)}")
99
print(f"Tags: {', '.join(album.tags)}")
100

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

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

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

112
# Load album data from file
113
loaded_album = JmAlbumDetail.from_file("album_123456.json")
114
```
115

116
### Photo Entity
117

118
Represents a chapter/photo within an album, containing images and metadata.
119

120
```python { .api }
121
class JmPhotoDetail(DetailEntity, IndexedEntity, Downloadable):
122
    """
123
    Represents a chapter/photo with images and metadata.
124
    
125
    Attributes:
126
    - id: str - Photo ID
127
    - title: str - Photo title
128
    - author: List[str] - List of authors
129
    - name: str - Photo name (alias for title)
130
    - index: int - Photo index within album
131
    - page_count: int - Number of images in this photo
132
    - images: List[JmImageDetail] - List of images
133
    - image_list: List[JmImageDetail] - Alias for images
134
    - album_id: str - Parent album ID
135
    - pub_date: str - Publication date
136
    - scramble_id: int - Image scrambling identifier
137
    - data_original: Dict[str, Any] - Original API response data
138
    
139
    Methods:
140
    - __getitem__(index): Access images by index
141
    - __iter__(): Iterate over images
142
    - __len__(): Get number of images
143
    - download(): Download all images in this photo
144
    """
145
```
146

147
Usage examples:
148

149
```python
150
# Access photo information
151
photo, _ = download_photo("456789")
152
print(f"Title: {photo.title}")
153
print(f"Images: {len(photo)}")
154
print(f"Album ID: {photo.album_id}")
155

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

160
# Access specific image
161
first_image = photo[0]
162
print(f"First image URL: {first_image.download_url}")
163
```
164

165
### Image Entity
166

167
Represents an individual image with download URL and metadata.
168

169
```python { .api }
170
class JmImageDetail(JmBaseEntity, Downloadable):
171
    """
172
    Represents an individual image with download URL and properties.
173
    
174
    Attributes:
175
    - id: str - Image ID
176
    - filename: str - Image filename
177
    - download_url: str - Image download URL
178
    - img_url: str - Alias for download_url
179
    - width: int - Image width in pixels
180
    - height: int - Image height in pixels
181
    - size: int - File size in bytes
182
    - index: int - Image index within photo
183
    - photo_id: str - Parent photo ID
184
    - album_id: str - Parent album ID
185
    - scramble_id: int - Image scrambling identifier
186
    - is_scrambled: bool - Whether image is scrambled
187
    
188
    Methods:
189
    - download(): Download this specific image
190
    """
191
```
192

193
Usage examples:
194

195
```python
196
# Access image information
197
album, _ = download_album("123456")
198
first_photo = album[0]
199
first_image = first_photo[0]
200

201
print(f"Filename: {first_image.filename}")
202
print(f"Size: {first_image.width}x{first_image.height}")
203
print(f"Download URL: {first_image.download_url}")
204
print(f"File size: {first_image.size} bytes")
205
```
206

207
### Search and Page Entities
208

209
Entities representing search results and paginated content.
210

211
```python { .api }
212
class JmPageContent:
213
    """
214
    Base class for paginated content with navigation support.
215
    
216
    Attributes:
217
    - page_num: int - Current page number
218
    - total_pages: int - Total number of pages
219
    - has_next: bool - Whether next page exists
220
    - has_prev: bool - Whether previous page exists
221
    
222
    Methods:
223
    - next_page(): Get next page content
224
    - prev_page(): Get previous page content
225
    """
226

227
class JmSearchPage(JmPageContent, IndexedEntity):
228
    """
229
    Search results page with albums and pagination.
230
    
231
    Attributes:
232
    - albums: List[JmAlbumDetail] - List of albums in search results
233
    - content: List[JmAlbumDetail] - Alias for albums
234
    - search_query: str - Original search query
235
    - total_results: int - Total number of results
236
    
237
    Methods:
238
    - __getitem__(index): Access albums by index
239
    - __iter__(): Iterate over albums
240
    - __len__(): Get number of albums on this page
241
    """
242

243
class JmFavoritePage(JmPageContent, IndexedEntity):
244
    """
245
    User favorites page content.
246
    
247
    Attributes:
248
    - albums: List[JmAlbumDetail] - List of favorite albums
249
    - content: List[JmAlbumDetail] - Alias for albums
250
    - folder_name: str - Favorites folder name
251
    
252
    Methods:
253
    - __getitem__(index): Access albums by index
254
    - __iter__(): Iterate over albums
255
    - __len__(): Get number of albums on this page
256
    """
257

258
class JmCategoryPage(JmSearchPage):
259
    """
260
    Category listing page (alias for JmSearchPage).
261
    
262
    Attributes:
263
    - category_name: str - Category name
264
    - category_id: str - Category identifier
265
    """
266
```
267

268
Usage examples:
269

270
```python
271
# Search for albums
272
from jmcomic import JmHtmlClient
273
client = JmHtmlClient()
274
search_page = client.search_album("search_term")
275

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

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

283
# Navigate pages
284
if search_page.has_next:
285
    next_page = search_page.next_page()
286
    print(f"Next page has {len(next_page)} albums")
287
```
288

289
## Entity Relationships
290

291
The entities form a hierarchical structure:
292

293
- **JmAlbumDetail** contains multiple **JmPhotoDetail** objects (episodes)
294
- **JmPhotoDetail** contains multiple **JmImageDetail** objects (images)
295
- **JmSearchPage** and **JmFavoritePage** contain multiple **JmAlbumDetail** objects
296
- All entities support file I/O operations for persistence
297
- Downloadable entities can initiate their own download processes