0
# Configuration Management
1
2
Flexible configuration system supporting YAML/JSON files, environment variables, and programmatic configuration. Enables comprehensive customization of download behavior, client settings, plugin options, and file organization rules.
3
4
## Types
5
6
```python { .api }
7
from typing import Dict, Any, List, Optional, Union, Callable
8
```
9
10
## Capabilities
11
12
### Main Configuration Class
13
14
Central configuration class that manages all download options, client settings, and plugin configurations.
15
16
```python { .api }
17
class JmOption:
18
"""
19
Central configuration class for download options and client settings.
20
21
Attributes:
22
- download: Dict[str, Any] - Download-related settings
23
- client: Dict[str, Any] - Client configuration options
24
- plugins: Dict[str, Any] - Plugin configurations
25
- dir_rule: DirRule - Directory naming and organization rules
26
- cache: CacheRegistry - Client caching configuration
27
28
Class Methods:
29
- default(): Create default configuration
30
- from_file(filepath): Load configuration from YAML/JSON file
31
- construct(data): Create from dictionary data
32
- merge(other): Merge with another JmOption instance
33
34
Instance Methods:
35
- to_dict(): Convert to dictionary
36
- to_file(filepath): Save configuration to file
37
- validate(): Validate configuration settings
38
"""
39
40
@classmethod
41
def default(cls) -> 'JmOption':
42
"""
43
Create default configuration with standard settings.
44
45
Returns:
46
JmOption - Default configuration instance
47
"""
48
49
@classmethod
50
def from_file(cls, filepath: str) -> 'JmOption':
51
"""
52
Load configuration from YAML or JSON file.
53
54
Parameters:
55
- filepath: str - Path to configuration file
56
57
Returns:
58
JmOption - Configuration loaded from file
59
"""
60
61
@classmethod
62
def construct(cls, data: Dict[str, Any]) -> 'JmOption':
63
"""
64
Create configuration from dictionary data.
65
66
Parameters:
67
- data: dict - Configuration data
68
69
Returns:
70
JmOption - Configuration instance
71
"""
72
73
def merge(self, other: 'JmOption') -> 'JmOption':
74
"""
75
Merge with another configuration instance.
76
77
Parameters:
78
- other: JmOption - Configuration to merge
79
80
Returns:
81
JmOption - New merged configuration
82
"""
83
84
def to_dict(self) -> Dict[str, Any]:
85
"""
86
Convert configuration to dictionary.
87
88
Returns:
89
dict - Configuration as dictionary
90
"""
91
92
def to_file(self, filepath: str):
93
"""
94
Save configuration to YAML file.
95
96
Parameters:
97
- filepath: str - Target file path
98
"""
99
100
def validate(self) -> bool:
101
"""
102
Validate configuration settings.
103
104
Returns:
105
bool - True if configuration is valid
106
107
Raises:
108
ValueError - If configuration is invalid
109
"""
110
```
111
112
Usage examples:
113
114
```python
115
# Create default configuration
116
option = JmOption.default()
117
118
# Load from file
119
option = JmOption.from_file("config.yml")
120
121
# Create from dictionary
122
config_data = {
123
"download": {
124
"base_dir": "/downloads",
125
"max_threads": 4
126
},
127
"client": {
128
"retry_count": 3,
129
"timeout": 30
130
}
131
}
132
option = JmOption.construct(config_data)
133
134
# Merge configurations
135
default_option = JmOption.default()
136
custom_option = JmOption.from_file("custom.yml")
137
merged_option = default_option.merge(custom_option)
138
139
# Save configuration
140
option.to_file("saved_config.yml")
141
```
142
143
### Directory Rules
144
145
Configuration for file and directory naming and organization patterns.
146
147
```python { .api }
148
class DirRule:
149
"""
150
File and directory naming and organization rules.
151
152
Attributes:
153
- base_dir: str - Base download directory
154
- album_dir_rule: str - Album directory naming pattern
155
- photo_dir_rule: str - Photo directory naming pattern
156
- image_filename_rule: str - Image filename pattern
157
- create_album_dir: bool - Whether to create album directories
158
- create_photo_dir: bool - Whether to create photo directories
159
160
Methods:
161
- format_album_dir(album): Generate album directory name
162
- format_photo_dir(photo): Generate photo directory name
163
- format_image_filename(image): Generate image filename
164
- validate_rules(): Validate naming rules
165
"""
166
167
def __init__(self,
168
base_dir: str = "./downloads",
169
album_dir_rule: str = "{album_id} - {title}",
170
photo_dir_rule: str = "{photo_id} - {title}",
171
image_filename_rule: str = "{index:03d}.{ext}"):
172
"""
173
Initialize directory rules.
174
175
Parameters:
176
- base_dir: str - Base download directory
177
- album_dir_rule: str - Album directory naming pattern
178
- photo_dir_rule: str - Photo directory naming pattern
179
- image_filename_rule: str - Image filename pattern
180
"""
181
182
def format_album_dir(self, album: 'JmAlbumDetail') -> str:
183
"""
184
Generate album directory name using the configured rule.
185
186
Parameters:
187
- album: JmAlbumDetail - Album entity
188
189
Returns:
190
str - Formatted directory name
191
"""
192
193
def format_photo_dir(self, photo: 'JmPhotoDetail') -> str:
194
"""
195
Generate photo directory name using the configured rule.
196
197
Parameters:
198
- photo: JmPhotoDetail - Photo entity
199
200
Returns:
201
str - Formatted directory name
202
"""
203
204
def format_image_filename(self, image: 'JmImageDetail') -> str:
205
"""
206
Generate image filename using the configured rule.
207
208
Parameters:
209
- image: JmImageDetail - Image entity
210
211
Returns:
212
str - Formatted filename
213
"""
214
```
215
216
Usage examples:
217
218
```python
219
# Create custom directory rules
220
dir_rule = DirRule(
221
base_dir="/home/user/comics",
222
album_dir_rule="{title} [{album_id}]",
223
photo_dir_rule="Chapter {index:02d} - {title}",
224
image_filename_rule="page_{index:03d}.{ext}"
225
)
226
227
# Use in configuration
228
option = JmOption.default()
229
option.dir_rule = dir_rule
230
231
# Generate paths
232
album = JmAlbumDetail(id="123456", title="Sample Album")
233
album_dir = dir_rule.format_album_dir(album) # "Sample Album [123456]"
234
```
235
236
### Client Caching
237
238
Caching mechanism for client operations to improve performance and reduce redundant requests.
239
240
```python { .api }
241
class CacheRegistry:
242
"""
243
Client caching mechanism for improved performance.
244
245
Attributes:
246
- enabled: bool - Whether caching is enabled
247
- cache_dir: str - Directory for cache files
248
- max_cache_size: int - Maximum cache size in MB
249
- ttl: int - Cache time-to-live in seconds
250
251
Methods:
252
- get(key): Retrieve cached value
253
- set(key, value): Store value in cache
254
- clear(): Clear all cached data
255
- cleanup(): Remove expired cache entries
256
"""
257
258
def __init__(self,
259
enabled: bool = True,
260
cache_dir: str = "./cache",
261
max_cache_size: int = 100,
262
ttl: int = 3600):
263
"""
264
Initialize cache registry.
265
266
Parameters:
267
- enabled: bool - Enable/disable caching
268
- cache_dir: str - Cache directory path
269
- max_cache_size: int - Max cache size in MB
270
- ttl: int - Cache TTL in seconds
271
"""
272
273
def get(self, key: str) -> Optional[Any]:
274
"""
275
Retrieve cached value by key.
276
277
Parameters:
278
- key: str - Cache key
279
280
Returns:
281
Any or None - Cached value if exists and valid
282
"""
283
284
def set(self, key: str, value: Any):
285
"""
286
Store value in cache.
287
288
Parameters:
289
- key: str - Cache key
290
- value: Any - Value to cache
291
"""
292
293
def clear(self):
294
"""Clear all cached data."""
295
296
def cleanup(self):
297
"""Remove expired cache entries."""
298
```
299
300
### Configuration Creation Functions
301
302
Utility functions for creating configuration instances from various sources.
303
304
```python { .api }
305
def create_option_by_file(filepath: str) -> JmOption:
306
"""
307
Create configuration from YAML or JSON file.
308
309
Parameters:
310
- filepath: str - Path to configuration file
311
312
Returns:
313
JmOption - Configuration instance
314
"""
315
316
def create_option_by_env(env_name: str = 'JM_OPTION_PATH') -> JmOption:
317
"""
318
Create configuration from environment variable path.
319
320
Parameters:
321
- env_name: str - Environment variable name containing file path
322
323
Returns:
324
JmOption - Configuration instance
325
326
Raises:
327
ValueError - If environment variable is not set
328
"""
329
330
def create_option_by_str(text: str, mode: Optional[str] = None) -> JmOption:
331
"""
332
Create configuration from string content.
333
334
Parameters:
335
- text: str - YAML or JSON configuration text
336
- mode: str, optional - Parse mode ('yml' or 'json')
337
338
Returns:
339
JmOption - Configuration instance
340
"""
341
342
# Alias for convenience
343
create_option = create_option_by_file
344
```
345
346
Usage examples:
347
348
```python
349
# Load from file
350
option = create_option_by_file("config.yml")
351
352
# Load from environment variable
353
import os
354
os.environ['JM_OPTION_PATH'] = "/path/to/config.yml"
355
option = create_option_by_env()
356
357
# Load from string
358
yaml_config = """
359
download:
360
base_dir: /downloads
361
max_threads: 4
362
client:
363
retry_count: 3
364
"""
365
option = create_option_by_str(yaml_config)
366
367
# Using alias
368
option = create_option("config.yml")
369
```
370
371
## Configuration Structure
372
373
A typical configuration file structure:
374
375
```yaml
376
# Download settings
377
download:
378
base_dir: "/home/user/downloads"
379
max_threads: 4
380
create_album_dir: true
381
create_photo_dir: true
382
383
# Directory naming rules
384
dir_rule:
385
album_dir_rule: "{title} [{album_id}]"
386
photo_dir_rule: "Chapter {index:02d}"
387
image_filename_rule: "{index:03d}.{ext}"
388
389
# Client settings
390
client:
391
retry_count: 3
392
timeout: 30
393
user_agent: "Custom User Agent"
394
headers:
395
"Accept": "image/*"
396
397
# Caching
398
cache:
399
enabled: true
400
cache_dir: "./cache"
401
max_cache_size: 100
402
ttl: 3600
403
404
# Plugin configurations
405
plugins:
406
JmLoginPlugin:
407
username: "user@example.com"
408
password: "password"
409
ZipPlugin:
410
enabled: true
411
password: "archive_password"
412
```
413
414
## Advanced Configuration
415
416
For complex scenarios, configurations can be programmatically modified:
417
418
```python
419
# Start with default configuration
420
option = JmOption.default()
421
422
# Modify specific settings
423
option.download['max_threads'] = 8
424
option.dir_rule.base_dir = "/custom/path"
425
option.cache.enabled = False
426
427
# Add plugin configuration
428
option.plugins['ZipPlugin'] = {
429
'enabled': True,
430
'password': 'my_password'
431
}
432
433
# Validate and save
434
option.validate()
435
option.to_file("custom_config.yml")
436
```