0
# IMGKit
1

2
A Python wrapper around the wkhtmltoimage utility for converting HTML content to image files using the WebKit rendering engine. IMGKit supports converting from URLs, files, and HTML strings to various image formats with extensive configuration options.
3

4
## Package Information
5

6
- **Package Name**: imgkit
7
- **Language**: Python
8
- **Installation**: `pip install imgkit`
9
- **Dependencies**: `six`, `wkhtmltoimage` system binary
10

11
## Core Imports
12

13
```python
14
import imgkit
15
```
16

17
For individual functions:
18

19
```python
20
from imgkit import from_url, from_file, from_string, config, IMGKit
21
```
22

23
## Basic Usage
24

25
```python
26
import imgkit
27

28
# Convert from URL
29
imgkit.from_url('http://google.com', 'out.jpg')
30

31
# Convert from HTML file
32
imgkit.from_file('test.html', 'out.jpg')
33

34
# Convert from HTML string
35
imgkit.from_string('<h1>Hello World!</h1>', 'out.jpg')
36

37
# Convert to binary data instead of file
38
img_data = imgkit.from_url('http://google.com', False)
39
```
40

41
## Architecture
42

43
IMGKit acts as a Python wrapper around the wkhtmltoimage system binary, providing a high-level interface for HTML-to-image conversion:
44

45
- **API Layer** (`api.py`): Convenience functions (from_url, from_file, from_string, config) that create IMGKit instances
46
- **Core Engine** (`imgkit.py`): IMGKit class handles command generation, subprocess execution, and error handling
47
- **Configuration** (`config.py`): Config class manages binary paths and meta tag processing
48
- **Source Handling** (`source.py`): Source class validates and normalizes different input types (URL, file, string)
49
- **System Integration**: Executes wkhtmltoimage binary via subprocess, with optional xvfb for headless environments
50

51
This architecture allows flexible input handling while maintaining consistent conversion behavior across different source types.
52

53
## Capabilities
54

55
### URL to Image Conversion
56

57
Convert web pages from URLs to image files with full browser rendering support including JavaScript, CSS, and external resources.
58

59
```python { .api }
60
def from_url(
61
    url,  # str or list of str - URL(s) to be saved
62
    output_path,  # str or False - path to output file, False returns bytes
63
    options=None,  # dict - wkhtmltoimage options
64
    toc=None,  # dict - table of contents options
65
    cover=None,  # str - cover page URL/filename
66
    config=None,  # Config - imgkit.Config() instance
67
    cover_first=None  # bool - if True, cover precedes TOC
68
):  # Returns: bool (True on success) or bytes (when output_path=False)
69
    """
70
    Convert URL/URLs to IMG file/files.
71

72
    Parameters:
73
    - url: URL or list of URLs to be saved
74
    - output_path: path to output image file/files. False means file will be returned as bytes
75
    - options: dict with wkhtmltoimage global and page options, with or w/o '--'
76
    - toc: dict with toc-specific wkhtmltoimage options, with or w/o '--'
77
    - cover: string with url/filename with a cover html page
78
    - config: instance of imgkit.Config()
79
    - cover_first: if True, cover always precedes TOC
80

81
    Returns:
82
    - True when successful and output_path provided
83
    - bytes when output_path is False
84
    """
85
```
86

87
### File to Image Conversion
88

89
Convert HTML files to image files with support for CSS stylesheets, file-like objects, and batch processing of multiple files.
90

91
```python { .api }
92
def from_file(
93
    filename,  # str, list of str, or file-like object - HTML file(s)
94
    output_path,  # str or False - path to output file, False returns bytes
95
    options=None,  # dict - wkhtmltoimage options
96
    toc=None,  # dict - table of contents options
97
    cover=None,  # str - cover page URL/filename
98
    css=None,  # str or list of str - CSS file(s) to include
99
    config=None,  # Config - imgkit.Config() instance
100
    cover_first=None  # bool - if True, cover precedes TOC
101
):  # Returns: bool (True on success) or bytes (when output_path=False)
102
    """
103
    Convert HTML file/files to IMG file/files.
104

105
    Parameters:
106
    - filename: path of HTML file or list with paths or file-like object
107
    - output_path: path to output image file/files. False means file will be returned as bytes
108
    - options: dict with wkhtmltoimage global and page options, with or w/o '--'
109
    - toc: dict with toc-specific wkhtmltoimage options, with or w/o '--'
110
    - cover: string with url/filename with a cover html page
111
    - css: path to CSS file or list of CSS files to include
112
    - config: instance of imgkit.Config()
113
    - cover_first: if True, cover always precedes TOC
114

115
    Returns:
116
    - True when successful and output_path provided
117
    - bytes when output_path is False
118
    """
119
```
120

121
Usage example with CSS:
122

123
```python
124
# Single CSS file
125
imgkit.from_file('file.html', 'out.jpg', css='styles.css')
126

127
# Multiple CSS files
128
imgkit.from_file('file.html', 'out.jpg', css=['styles.css', 'theme.css'])
129

130
# With file-like object
131
with open('file.html') as f:
132
    imgkit.from_file(f, 'out.jpg')
133
```
134

135
### String to Image Conversion
136

137
Convert HTML strings directly to image files with support for meta tag options and CSS injection.
138

139
```python { .api }
140
def from_string(
141
    string,  # str - HTML string content to convert
142
    output_path,  # str or False - path to output file, False returns bytes
143
    options=None,  # dict - wkhtmltoimage options
144
    toc=None,  # dict - table of contents options
145
    cover=None,  # str - cover page URL/filename
146
    css=None,  # str or list of str - CSS file(s) to include
147
    config=None,  # Config - imgkit.Config() instance
148
    cover_first=None  # bool - if True, cover precedes TOC
149
):  # Returns: bool (True on success) or bytes (when output_path=False)
150
    """
151
    Convert given string/strings to IMG file.
152

153
    Parameters:
154
    - string: HTML string content to convert
155
    - output_path: path to output image file/files. False means file will be returned as bytes
156
    - options: dict with wkhtmltoimage global and page options, with or w/o '--'
157
    - toc: dict with toc-specific wkhtmltoimage options, with or w/o '--'
158
    - cover: string with url/filename with a cover html page
159
    - css: path to CSS file or list of CSS files to include
160
    - config: instance of imgkit.Config()
161
    - cover_first: if True, cover always precedes TOC
162

163
    Returns:
164
    - True when successful and output_path provided
165
    - bytes when output_path is False
166
    """
167
```
168

169
Usage example with meta tags:
170

171
```python
172
html_content = """
173
<html>
174
  <head>
175
    <meta name="imgkit-format" content="png"/>
176
    <meta name="imgkit-orientation" content="Landscape"/>
177
  </head>
178
  <body>Hello World!</body>
179
</html>
180
"""
181

182
imgkit.from_string(html_content, 'out.png')
183
```
184

185
### Configuration Management
186

187
Create and manage configuration for wkhtmltoimage binary paths and meta tag prefixes.
188

189
```python { .api }
190
def config(**kwargs):  # Returns: Config instance
191
    """
192
    Constructs and returns a Config instance with given options.
193

194
    Parameters:
195
    - wkhtmltoimage: path to wkhtmltoimage binary
196
    - xvfb: path to xvfb-run binary
197
    - meta_tag_prefix: prefix for imgkit specific meta tags (default: "imgkit-")
198

199
    Returns:
200
    Config instance
201
    """
202
```
203

204
Usage example:
205

206
```python
207
# Custom binary paths
208
config = imgkit.config(
209
    wkhtmltoimage='/opt/bin/wkhtmltoimage',
210
    xvfb='/opt/bin/xvfb-run'
211
)
212

213
# Use custom config
214
imgkit.from_string('<h1>Hello</h1>', 'out.jpg', config=config)
215
```
216

217
### Advanced Image Generation
218

219
Direct access to the IMGKit class for advanced usage scenarios, custom command generation, and fine-grained control over the conversion process.
220

221
```python { .api }
222
class IMGKit:
223
    """Main class for imgkit HTML to image conversion."""
224
    
225
    def __init__(
226
        self,
227
        url_or_file,  # str, list of str, or file-like object - source content
228
        source_type,  # str - "url", "file", or "string"
229
        options=None,  # dict - wkhtmltoimage options
230
        config=None,  # Config - imgkit.Config() instance
231
        **kwargs  # Additional parameters: toc, cover, cover_first, css
232
    ):
233
        """
234
        Initialize IMGKit instance.
235

236
        Parameters:
237
        - url_or_file: Source content (URL, file path, or HTML string)
238
        - source_type: Type of source ("url", "file", or "string")
239
        - options: Optional dict with wkhtmltoimage options
240
        - config: Optional Config instance
241
        - **kwargs: Additional parameters (toc, cover, cover_first, css)
242
        """
243

244
    def to_img(self, path=None):  # Returns: bool (True on success) or bytes (when path=None/False)
245
        """
246
        Generate image to path.
247

248
        Parameters:
249
        - path: Output file path. If None or False, returns binary data
250

251
        Returns:
252
        - True when successful and path provided
253
        - bytes when path is None or False
254
        
255
        Raises:
256
        - OSError: For missing binaries, command failures, X server issues
257
        - SourceError: For invalid source types with CSS operations
258
        """
259

260
    def command(self, path=None):  # Returns: list of str - command arguments
261
        """
262
        Generate command array for wkhtmltoimage execution.
263

264
        Parameters:
265
        - path: Output file path
266

267
        Returns:
268
        List of command arguments
269
        """
270
```
271

272
Usage example:
273

274
```python
275
# Advanced usage with direct class access
276
kit = imgkit.IMGKit('<h1>Hello</h1>', 'string', options={'format': 'png'})
277
result = kit.to_img('output.png')
278

279
# Get command without executing
280
command_args = kit.command('output.png')
281
print(' '.join(command_args))
282
```
283

284
## Configuration Options
285

286
### Common Options
287

288
These are the most frequently used wkhtmltoimage options supported by imgkit:
289

290
```python
291
options = {
292
    'format': 'png',           # Output format: jpg, png, bmp, svg, pdf
293
    'width': 1024,             # Screenshot width
294
    'height': 768,             # Screenshot height
295
    'quality': 94,             # JPEG quality (0-100)
296
    'crop-h': 200,             # Crop height
297
    'crop-w': 200,             # Crop width
298
    'crop-x': 0,               # Crop x offset
299
    'crop-y': 0,               # Crop y offset
300
    'encoding': 'UTF-8',       # Character encoding
301
    'no-outline': None,        # Disable outline (no value needed)
302
    'outline-depth': 4,        # Outline depth
303
    'quiet': '',               # Suppress wkhtmltoimage output
304
    'xvfb': '',                # Use virtual display (headless)
305
}
306

307
imgkit.from_url('http://google.com', 'out.png', options=options)
308
```
309

310
### Headers and Cookies
311

312
```python
313
options = {
314
    'custom-header': [
315
        ('Accept-Encoding', 'gzip'),
316
        ('Authorization', 'Bearer token123')
317
    ],
318
    'cookie': [
319
        ('session_id', 'abc123'),
320
        ('user_pref', 'dark_mode')
321
    ]
322
}
323
```
324

325
### TOC and Cover Pages
326

327
```python
328
# Table of contents options
329
toc = {
330
    'xsl-style-sheet': 'toc.xsl'
331
}
332

333
# Cover page
334
cover = 'cover.html'
335

336
imgkit.from_file(
337
    'content.html',
338
    'output.jpg',
339
    toc=toc,
340
    cover=cover,
341
    cover_first=True  # Cover before TOC
342
)
343
```
344

345
## Types
346

347
```python { .api }
348
class Config:
349
    """Config class to configure wkhtmltoimage, xvfb-run and meta tag prefix."""
350
    
351
    def __init__(
352
        self,
353
        wkhtmltoimage="",  # str - wkhtmltoimage binary path
354
        xvfb="",  # str - xvfb-run binary path
355
        meta_tag_prefix="imgkit-"  # str - prefix for imgkit meta tags
356
    ):
357
        """
358
        Configure wkhtmltoimage, xvfb, meta_tag_prefix.
359

360
        Parameters:
361
        - wkhtmltoimage: wkhtmltoimage binary path
362
        - xvfb: xvfb-run binary path
363
        - meta_tag_prefix: prefix for imgkit specific meta tags
364
        """
365

366
    def get_wkhtmltoimage(self):  # Returns: str - path to wkhtmltoimage binary
367
        """
368
        Get wkhtmltoimage binary path, auto-detecting if not set.
369

370
        Returns:
371
        String path to wkhtmltoimage binary
372

373
        Raises:
374
        OSError: if wkhtmltoimage not found
375
        """
376

377
    def get_xvfb(self):  # Returns: str - path to xvfb-run binary
378
        """
379
        Get xvfb-run binary path, auto-detecting if not set.
380

381
        Returns:
382
        String path to xvfb-run binary
383

384
        Raises:
385
        OSError: if xvfb not found
386
        """
387

388
class Source:
389
    """Handle source object for different input types."""
390
    
391
    def __init__(self, url_or_file, type_):  # url_or_file: str/list/file, type_: str
392
        """
393
        Initialize source handler. Automatically validates file paths for file types.
394

395
        Parameters:
396
        - url_or_file: Source content
397
        - type_: Source type ("url", "file", or "string")
398
        
399
        Raises:
400
        OSError: if type_ is "file" and file paths don't exist
401
        """
402

403
    def isUrl(self):  # Returns: bool
404
        """Check if source is URL type."""
405

406
    def isString(self):  # Returns: bool
407
        """Check if source is string type."""
408

409
    def isFile(self, path=None):  # Returns: bool, path: str (optional)
410
        """Check if source is file type."""
411

412
    def isFileObj(self):  # Returns: bool
413
        """Check if source is a file-like object."""
414

415
    def to_s(self):  # Returns: str
416
        """Convert source to string representation."""
417

418
    def checkFiles(self):  # Returns: None, raises OSError if files don't exist
419
        """
420
        Validate file paths exist.
421
        
422
        Raises:
423
        OSError: if files don't exist
424
        """
425

426
class SourceError(Exception):
427
    """Wrong source type for stylesheets."""
428
    
429
    def __init__(self, message):  # message: str
430
        """SourceError with message."""
431
```
432

433
## Error Handling
434

435
IMGKit raises several types of exceptions that should be handled appropriately:
436

437
### OSError Scenarios
438

439
```python
440
try:
441
    imgkit.from_url('http://invalid-url', 'out.jpg')
442
except OSError as e:
443
    if "No wkhtmltoimage executable found" in str(e):
444
        print("Install wkhtmltoimage binary")
445
    elif "cannot connect to X server" in str(e):
446
        print("Use xvfb option for headless servers")
447
        # Retry with xvfb
448
        imgkit.from_url('http://google.com', 'out.jpg', options={'xvfb': ''})
449
    elif "Command failed" in str(e):
450
        print("wkhtmltoimage execution failed")
451
    else:
452
        print(f"Other error: {e}")
453
```
454

455
### SourceError Scenarios
456

457
```python
458
# Import SourceError from IMGKit class
459
from imgkit import IMGKit
460

461
try:
462
    # This will fail - can't add CSS to URL sources
463
    imgkit.from_url('http://google.com', 'out.jpg', css='styles.css')
464
except IMGKit.SourceError as e:
465
    print("CSS can only be added to file or string sources")
466
    print(f"Error message: {e.message}")
467
```
468

469
## System Requirements
470

471
### Required System Binaries
472

473
- **wkhtmltoimage**: Core binary for HTML to image conversion
474
- **xvfb-run** (optional): Virtual display for headless servers
475

476
### Installation Commands
477

478
```bash
479
# Debian/Ubuntu
480
sudo apt-get install wkhtmltopdf xvfb
481

482
# macOS
483
brew install --cask wkhtmltopdf
484

485
# CentOS/RHEL
486
yum install wkhtmltopdf xorg-x11-server-Xvfb
487
```
488

489
Note: Some Linux distributions include reduced-functionality versions of wkhtmltoimage. For full feature support, install the static binary from the official wkhtmltopdf website.