IMGKit

import imgkit

from imgkit import from_url, from_file, from_string, config, IMGKit

import imgkit

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

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

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

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

def from_url(
    url,  # str or list of str - URL(s) to be saved
    output_path,  # str or False - path to output file, False returns bytes
    options=None,  # dict - wkhtmltoimage options
    toc=None,  # dict - table of contents options
    cover=None,  # str - cover page URL/filename
    config=None,  # Config - imgkit.Config() instance
    cover_first=None  # bool - if True, cover precedes TOC
):  # Returns: bool (True on success) or bytes (when output_path=False)
    """
    Convert URL/URLs to IMG file/files.

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

    Returns:
    - True when successful and output_path provided
    - bytes when output_path is False
    """

def from_file(
    filename,  # str, list of str, or file-like object - HTML file(s)
    output_path,  # str or False - path to output file, False returns bytes
    options=None,  # dict - wkhtmltoimage options
    toc=None,  # dict - table of contents options
    cover=None,  # str - cover page URL/filename
    css=None,  # str or list of str - CSS file(s) to include
    config=None,  # Config - imgkit.Config() instance
    cover_first=None  # bool - if True, cover precedes TOC
):  # Returns: bool (True on success) or bytes (when output_path=False)
    """
    Convert HTML file/files to IMG file/files.

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

    Returns:
    - True when successful and output_path provided
    - bytes when output_path is False
    """

# Single CSS file
imgkit.from_file('file.html', 'out.jpg', css='styles.css')

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

# With file-like object
with open('file.html') as f:
    imgkit.from_file(f, 'out.jpg')

def from_string(
    string,  # str - HTML string content to convert
    output_path,  # str or False - path to output file, False returns bytes
    options=None,  # dict - wkhtmltoimage options
    toc=None,  # dict - table of contents options
    cover=None,  # str - cover page URL/filename
    css=None,  # str or list of str - CSS file(s) to include
    config=None,  # Config - imgkit.Config() instance
    cover_first=None  # bool - if True, cover precedes TOC
):  # Returns: bool (True on success) or bytes (when output_path=False)
    """
    Convert given string/strings to IMG file.

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

    Returns:
    - True when successful and output_path provided
    - bytes when output_path is False
    """

html_content = """
<html>
  <head>
    <meta name="imgkit-format" content="png"/>
    <meta name="imgkit-orientation" content="Landscape"/>
  </head>
  <body>Hello World!</body>
</html>
"""

imgkit.from_string(html_content, 'out.png')

def config(**kwargs):  # Returns: Config instance
    """
    Constructs and returns a Config instance with given options.

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

    Returns:
    Config instance
    """

# Custom binary paths
config = imgkit.config(
    wkhtmltoimage='/opt/bin/wkhtmltoimage',
    xvfb='/opt/bin/xvfb-run'
)

# Use custom config
imgkit.from_string('<h1>Hello</h1>', 'out.jpg', config=config)

class IMGKit:
    """Main class for imgkit HTML to image conversion."""
    
    def __init__(
        self,
        url_or_file,  # str, list of str, or file-like object - source content
        source_type,  # str - "url", "file", or "string"
        options=None,  # dict - wkhtmltoimage options
        config=None,  # Config - imgkit.Config() instance
        **kwargs  # Additional parameters: toc, cover, cover_first, css
    ):
        """
        Initialize IMGKit instance.

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

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

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

        Returns:
        - True when successful and path provided
        - bytes when path is None or False
        
        Raises:
        - OSError: For missing binaries, command failures, X server issues
        - SourceError: For invalid source types with CSS operations
        """

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

        Parameters:
        - path: Output file path

        Returns:
        List of command arguments
        """

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

# Get command without executing
command_args = kit.command('output.png')
print(' '.join(command_args))

options = {
    'format': 'png',           # Output format: jpg, png, bmp, svg, pdf
    'width': 1024,             # Screenshot width
    'height': 768,             # Screenshot height
    'quality': 94,             # JPEG quality (0-100)
    'crop-h': 200,             # Crop height
    'crop-w': 200,             # Crop width
    'crop-x': 0,               # Crop x offset
    'crop-y': 0,               # Crop y offset
    'encoding': 'UTF-8',       # Character encoding
    'no-outline': None,        # Disable outline (no value needed)
    'outline-depth': 4,        # Outline depth
    'quiet': '',               # Suppress wkhtmltoimage output
    'xvfb': '',                # Use virtual display (headless)
}

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

options = {
    'custom-header': [
        ('Accept-Encoding', 'gzip'),
        ('Authorization', 'Bearer token123')
    ],
    'cookie': [
        ('session_id', 'abc123'),
        ('user_pref', 'dark_mode')
    ]
}

# Table of contents options
toc = {
    'xsl-style-sheet': 'toc.xsl'
}

# Cover page
cover = 'cover.html'

imgkit.from_file(
    'content.html',
    'output.jpg',
    toc=toc,
    cover=cover,
    cover_first=True  # Cover before TOC
)

class Config:
    """Config class to configure wkhtmltoimage, xvfb-run and meta tag prefix."""
    
    def __init__(
        self,
        wkhtmltoimage="",  # str - wkhtmltoimage binary path
        xvfb="",  # str - xvfb-run binary path
        meta_tag_prefix="imgkit-"  # str - prefix for imgkit meta tags
    ):
        """
        Configure wkhtmltoimage, xvfb, meta_tag_prefix.

        Parameters:
        - wkhtmltoimage: wkhtmltoimage binary path
        - xvfb: xvfb-run binary path
        - meta_tag_prefix: prefix for imgkit specific meta tags
        """

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

        Returns:
        String path to wkhtmltoimage binary

        Raises:
        OSError: if wkhtmltoimage not found
        """

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

        Returns:
        String path to xvfb-run binary

        Raises:
        OSError: if xvfb not found
        """

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

        Parameters:
        - url_or_file: Source content
        - type_: Source type ("url", "file", or "string")
        
        Raises:
        OSError: if type_ is "file" and file paths don't exist
        """

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

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

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

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

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

    def checkFiles(self):  # Returns: None, raises OSError if files don't exist
        """
        Validate file paths exist.
        
        Raises:
        OSError: if files don't exist
        """

class SourceError(Exception):
    """Wrong source type for stylesheets."""
    
    def __init__(self, message):  # message: str
        """SourceError with message."""

try:
    imgkit.from_url('http://invalid-url', 'out.jpg')
except OSError as e:
    if "No wkhtmltoimage executable found" in str(e):
        print("Install wkhtmltoimage binary")
    elif "cannot connect to X server" in str(e):
        print("Use xvfb option for headless servers")
        # Retry with xvfb
        imgkit.from_url('http://google.com', 'out.jpg', options={'xvfb': ''})
    elif "Command failed" in str(e):
        print("wkhtmltoimage execution failed")
    else:
        print(f"Other error: {e}")

# Import SourceError from IMGKit class
from imgkit import IMGKit

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

# Debian/Ubuntu
sudo apt-get install wkhtmltopdf xvfb

# macOS
brew install --cask wkhtmltopdf

# CentOS/RHEL
yum install wkhtmltopdf xorg-x11-server-Xvfb