0
# Core Download API
1
2
High-level download functions that provide the main interface for downloading albums and photos from JMComic. These functions handle automatic retry, error checking, and batch processing with multi-threading support.
3
4
## Capabilities
5
6
### Album Download
7
8
Downloads a complete manga album including all chapters/photos with metadata. Supports both single album downloads and batch processing.
9
10
```python { .api }
11
def download_album(jm_album_id, option=None, downloader=None, callback=None, check_exception=True):
12
"""
13
Download a complete album (manga) including all chapters.
14
15
Parameters:
16
- jm_album_id: str or int or iterable - Album ID(s) to download
17
- option: JmOption, optional - Download configuration options
18
- downloader: JmDownloader class, optional - Custom downloader class
19
- callback: callable, optional - Callback function for completion events
20
- check_exception: bool - Whether to check and raise download exceptions
21
22
Returns:
23
Union[Tuple[JmAlbumDetail, JmDownloader], Set[Tuple[JmAlbumDetail, JmDownloader]]]
24
- Single album: (JmAlbumDetail, JmDownloader) tuple
25
- Multiple albums: Set of (JmAlbumDetail, JmDownloader) tuples
26
"""
27
```
28
29
Usage examples:
30
31
```python
32
# Download single album
33
album, downloader = download_album("123456")
34
35
# Download with custom options
36
option = create_option_by_file("config.yml")
37
album, downloader = download_album("123456", option=option)
38
39
# Download multiple albums (batch mode)
40
album_ids = ["123456", "789012", "345678"]
41
results = download_album(album_ids, option=option)
42
43
# Download with callback
44
def on_complete(album, downloader):
45
print(f"Completed: {album.title}")
46
47
album, downloader = download_album("123456", callback=on_complete)
48
```
49
50
### Photo Download
51
52
Downloads a single chapter/photo with all its images. Supports both individual photo downloads and batch processing.
53
54
```python { .api }
55
def download_photo(jm_photo_id, option=None, downloader=None, callback=None, check_exception=True):
56
"""
57
Download a single chapter/photo with all images.
58
59
Parameters:
60
- jm_photo_id: str or int or iterable - Photo ID(s) to download
61
- option: JmOption, optional - Download configuration options
62
- downloader: JmDownloader class, optional - Custom downloader class
63
- callback: callable, optional - Callback function for completion events
64
- check_exception: bool - Whether to check and raise download exceptions
65
66
Returns:
67
Union[Tuple[JmPhotoDetail, JmDownloader], Set[Tuple[JmPhotoDetail, JmDownloader]]]
68
- Single photo: (JmPhotoDetail, JmDownloader) tuple
69
- Multiple photos: Set of (JmPhotoDetail, JmDownloader) tuples
70
"""
71
```
72
73
Usage examples:
74
75
```python
76
# Download single photo
77
photo, downloader = download_photo("456789")
78
79
# Download multiple photos (batch mode)
80
photo_ids = ["456789", "012345", "678901"]
81
results = download_photo(photo_ids)
82
```
83
84
### Batch Download
85
86
Processes multiple downloads concurrently using multi-threading. Each item gets its own thread and uses the same configuration options.
87
88
```python { .api }
89
def download_batch(download_api, jm_id_iter, option=None, downloader=None):
90
"""
91
Download multiple albums or photos concurrently.
92
93
Parameters:
94
- download_api: callable - Download function (download_album or download_photo)
95
- jm_id_iter: iterable - Iterator of JM IDs to download
96
- option: JmOption, optional - Shared download configuration
97
- downloader: JmDownloader class, optional - Downloader class for all downloads
98
99
Returns:
100
Set[Tuple[Union[JmAlbumDetail, JmPhotoDetail], JmDownloader]]
101
Set of (entity, downloader) tuples for each completed download
102
"""
103
```
104
105
Usage examples:
106
107
```python
108
# Download multiple albums concurrently
109
album_ids = ["123456", "789012", "345678"]
110
results = download_batch(download_album, album_ids)
111
112
# Download multiple photos concurrently
113
photo_ids = ["456789", "012345", "678901"]
114
results = download_batch(download_photo, photo_ids)
115
116
# Process results
117
for entity, downloader in results:
118
print(f"Downloaded: {entity.title}")
119
if downloader.has_exception():
120
print(f" Errors: {len(downloader.exception_list)}")
121
```
122
123
### Downloader Creation
124
125
Creates new downloader instances with specified configuration options.
126
127
```python { .api }
128
def new_downloader(option=None, downloader=None):
129
"""
130
Create a new downloader instance.
131
132
Parameters:
133
- option: JmOption, optional - Configuration options (uses default if None)
134
- downloader: JmDownloader class, optional - Downloader class (uses default if None)
135
136
Returns:
137
JmDownloader - Configured downloader instance
138
"""
139
```
140
141
Usage examples:
142
143
```python
144
# Create downloader with default settings
145
downloader = new_downloader()
146
147
# Create downloader with custom options
148
option = create_option_by_file("config.yml")
149
downloader = new_downloader(option=option)
150
151
# Use custom downloader class
152
from jmcomic import DoNotDownloadImage
153
test_downloader = new_downloader(downloader=DoNotDownloadImage)
154
```
155
156
## Error Handling
157
158
All download functions support the `check_exception` parameter (default: True) to control exception handling:
159
160
- **True**: Raises `PartialDownloadFailedException` if any downloads fail
161
- **False**: Returns results without raising exceptions; check `downloader.has_exception()`
162
163
```python
164
# Strict error checking (default)
165
try:
166
album, downloader = download_album("123456")
167
except PartialDownloadFailedException as e:
168
print(f"Download failed: {e}")
169
170
# Lenient error checking
171
album, downloader = download_album("123456", check_exception=False)
172
if downloader.has_exception():
173
print(f"Errors occurred: {len(downloader.exception_list)}")
174
```