### Automated Development Setup Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Run the automated development setup script provided by Poe the Poet. ```bash poe dev-setup ``` -------------------------------- ### Install Dependencies Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/README.md Use pip to install project dependencies, including development and documentation-specific packages. ```bash pip install -e ".[dev]" ``` ```bash pip install -e ".[docs]" ``` -------------------------------- ### Install Dependencies for eml2pdf Documentation Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/documentation.md Use this command to install all development dependencies, including those for documentation. Alternatively, install only documentation dependencies. ```bash pip install -e ".[dev]" ``` ```bash # or just docs dependencies: pip install -e ".[docs]" ``` -------------------------------- ### Install from local source Source: https://github.com/plenaerts/eml2pdf/blob/main/INSTALL.md Install eml2pdf from a local source directory (e.g., a downloaded git repository). Replace `` with the actual path. ```bash pip install ``` -------------------------------- ### Install Development Dependencies Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Install the package in editable mode with all development dependencies, including testing and documentation tools. ```bash pip install -e ".[dev]" ``` -------------------------------- ### Install Specific Dependency Groups Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Install the package with specific dependency groups like 'test' or 'docs' in editable mode. ```bash pip install -e ".[test]" ``` ```bash pip install -e ".[docs]" ``` ```bash pip install -e ".[dev]" ``` -------------------------------- ### Install latest release from PyPI Source: https://github.com/plenaerts/eml2pdf/blob/main/INSTALL.md Install the latest stable version of eml2pdf from the Python Package Index using pip. ```bash pip install eml2pdf ``` -------------------------------- ### Header Decoding Strategy Example Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Illustrates the decoding strategy for email headers, handling encoded parts and potential errors. ```python # Uses email.header.decode_header() to parse encoded headers # Handles multi-part headers by concatenating them # For string parts, uses them directly # For byte parts, decodes with specified encoding (defaults to 'ascii' if None) # HTML-escapes the result to prevent XSS # UnicodeError during header decoding is caught and logged # Failed headers retain default value: "Not decoded." ``` -------------------------------- ### Serve Documentation Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/README.md Run the 'docs-serve' task with Poe to build and serve the documentation locally, accessible at http://localhost:8000. ```bash poe docs-serve ``` -------------------------------- ### Build Documentation with Poe Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/development.md Builds the project's HTML documentation using the 'docs' Poe task. Use 'docs-serve' to build and serve it locally. ```bash poe docs ``` ```bash poe docs-serve ``` -------------------------------- ### Build Documentation Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/README.md Execute the 'docs' task using Poe to build the Sphinx documentation. ```bash poe docs ``` -------------------------------- ### Clean and Rebuild Documentation Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/README.md To perform a clean build of the documentation, first run the 'docs-clean' task with Poe, followed by the 'docs' task. ```bash poe docs-clean poe docs ``` -------------------------------- ### eml2pdf Command-Line Usage Source: https://github.com/plenaerts/eml2pdf/blob/main/README.md The main entry point for eml2pdf is via the command line. Use subcommands like `convert_dir` or `convert_file` for specific operations. Use `--help` for detailed options. ```text usage: eml2pdf [-h] {convert_dir,convert_file} ... Convert EML files to PDF options: -h, --help show this help message and exit supported subcommands:: {convert_dir,convert_file} Use {subcommand} --help for options. convert_dir Convert all EML files in an input dir to PDF files in an output dir. convert_file Convert a single EML file to a single PDF ``` -------------------------------- ### Activate virtual environment on Linux Source: https://github.com/plenaerts/eml2pdf/blob/main/INSTALL.md Activate the created virtual environment in your Linux shell. Replace `` with the path to your virtual environment. ```bash source /bin/activate ``` -------------------------------- ### Build Distribution Packages Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Create source distribution and wheel packages for the project using the 'build' Poe task. ```bash poe build ``` -------------------------------- ### Create a New Git Tag for Versioning Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Create an annotated git tag for a new release version and push it to the remote repository. ```bash git tag -a v1.0.0 -m "Release 1.0.0" git push origin v1.0.0 ``` -------------------------------- ### eml2pdf convert_dir Help Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/readme.md Displays the help message for the `convert_dir` command, outlining its usage, positional arguments, and available options. ```text $ eml2pdf convert_dir -h usage: eml2pdf convert_dir [-h] [-p size] [--unsafe] [-d] [-v] [-q] [-n number] input_dir output_dir positional arguments: input_dir Directory containing EML files output_dir Directory for PDF output options: -h, --help show this help message and exit -p, --page size One of a3, a4, a5, b4, b5, letter, legal, or ledger, with or without "landscape", for example: "a4 landscape" or a3. Surround with quotes if there is a space in the argument value. Defaults to "a4", implying portrait. --unsafe Don't sanitize HTML from potentially unsafe elements such as remote images, scripts, etc. This may expose sensitive user information. -d, --debug_html Write intermediate html file next to PDF's -v, --verbose Show a lot of verbose debugging info. Forces number of procs to 1. -q, --quiet Show only errors. -n, --number-of-procs number Number of parallel processes. Defaults to the number of available logical CPU's to eml_to_pdf. ``` -------------------------------- ### Navigate to Project Directory Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Change the current directory to the root of the eml2pdf project. ```bash cd /path/to/eml2pdf ``` -------------------------------- ### Publish to PyPI with Poe Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/development.md Uploads distribution packages to PyPI. Use 'upload-test' for TestPyPI and 'upload' for the real PyPI. ```bash poe upload-test ``` ```bash poe upload ``` -------------------------------- ### Create a virtual environment Source: https://github.com/plenaerts/eml2pdf/blob/main/INSTALL.md Use this command to create an isolated Python environment. Replace `` with your desired path. ```bash python3 -m venv ``` -------------------------------- ### Upload to PyPI Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Upload distribution packages to the real PyPI repository using the 'upload' Poe task. Requires PyPI credentials. ```bash poe upload ``` -------------------------------- ### Run All Tests Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Execute all project tests using the 'test' Poe task. ```bash poe test ``` -------------------------------- ### Run Tests with Coverage Report Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Execute project tests and generate a coverage report using the 'coverage' Poe task. ```bash poe coverage ``` -------------------------------- ### List Available Poe Tasks Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Display all available tasks defined in pyproject.toml using Poe the Poet. ```bash poe ``` -------------------------------- ### Run Tests with Poe Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/development.md Executes all project tests using the 'test' Poe task. Use 'test-verbose' for detailed output. ```bash poe test ``` ```bash poe test-verbose ``` -------------------------------- ### Process EML directory via API (default secure) Source: https://github.com/plenaerts/eml2pdf/blob/main/SECURITY.md Use the `process_all_emls_in_dir` function to convert all EML files in a directory. Sanitization is enabled by default. ```python # Or for a whole dir libeml2pdf.process_all_emls_in_dir(input_dir, output_dir) ``` -------------------------------- ### Clean All Artifacts Including Docs Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Remove all build artifacts, cache, and documentation directories using the 'clean-all' Poe task. ```bash poe clean-all ``` -------------------------------- ### Activate virtual environment on Windows PowerShell Source: https://github.com/plenaerts/eml2pdf/blob/main/INSTALL.md Activate the created virtual environment in Windows PowerShell. Replace `` with the path to your virtual environment. ```powershell \Scripts\Activate.ps1 ``` -------------------------------- ### Convert Directory of EML Files to PDF Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/readme.md Use this command to convert all .eml files in a specified input directory to PDF format, saving them in an output directory. Filenames are automatically generated based on email date and subject, with counters for duplicates. The `-n` option controls parallel processes. ```bash eml2pdf convert_dir -p "a4 landscape" ./emails ./pdfs ``` -------------------------------- ### EML Parsing: Handle No Content Found Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Logs a warning and skips PDF generation if no HTML or plain text content is found within the EML file. ```python else: logger.warning("No plain text or HTML content found in {eml_path}. Skipping...") ``` -------------------------------- ### Clean Build Artifacts Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/development.md Removes build artifacts and cache directories using Poe tasks. 'clean-all' removes everything including documentation. ```bash poe clean ``` ```bash poe clean-all ``` -------------------------------- ### Process EML file via API (default secure) Source: https://github.com/plenaerts/eml2pdf/blob/main/SECURITY.md Use the `process_eml` function to convert a single EML file. Sanitization is enabled by default (`unsafe=False`). ```python from eml2pdf import libeml2pdf # Sanitization is enabled by default (unsafe=False) libeml2pdf.process_eml(eml_path, output_path) ``` -------------------------------- ### Convert EML Directory to PDF Source: https://github.com/plenaerts/eml2pdf/blob/main/README.md Converts all .eml files in an input directory to PDF, saving them in an output directory with a specific filename format. Supports parallel processing. ```text $ eml2pdf convert_dir -h usage: eml2pdf convert_dir [-h] [-p size] [--unsafe] [-d] [-v] [-q] [-n number] input_dir output_dir positional arguments: input_dir Directory containing EML files output_dir Directory for PDF output options: -h, --help show this help message and exit -p, --page size One of a3, a4, a5, b4, b5, letter, legal, or ledger, with or without "landscape", for example: "a4 landscape" or a3. Surround with quotes if there is a space in the argument value. Defaults to "a4", implying portrait. --unsafe Don't sanitize HTML from potentially unsafe elements such as remote images, scripts, etc. This may expose sensitive user information. -d, --debug_html Write intermediate html file next to PDF's -v, --verbose Show a lot of verbose debugging info. Forces number of procs to 1. -q, --quiet Show only errors. -n, --number-of-procs number Number of parallel processes. Defaults to the number of available logical CPU's to eml_to_pdf. ``` ```bash eml2pdf -p "a4 landscape" ./emails ./pdfs ``` -------------------------------- ### Clean Build Artifacts and Cache Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Remove build artifacts and cache directories using the 'clean' Poe task. ```bash poe clean ``` -------------------------------- ### Convert EML file via CLI (unsafe mode) Source: https://github.com/plenaerts/eml2pdf/blob/main/SECURITY.md Use the `--unsafe` flag to disable HTML sanitization. Only use if you completely trust the EML source and understand the risks. ```bash eml2pdf convert_file input_file output_file --unsafe ``` -------------------------------- ### Convert Single EML File to PDF Source: https://github.com/plenaerts/eml2pdf/blob/main/README.md Converts a single EML file to a PDF file. Allows specifying input and output filenames. ```text $ eml2pdf convert_file -h usage: eml2pdf convert_file [-h] [-p size] [--unsafe] [-d] [-v] [-q] input_file output_file positional arguments: input_file Input EML file to convert output_file Output PDF file to convert to options: -h, --help show this help message and exit -p, --page size One of a3, a4, a5, b4, b5, letter, legal, or ledger, with or without "landscape", for example: "a4 landscape" or a3. Surround with quotes if there is a space in the argument value. Defaults to "a4", implying portrait. --unsafe Don't sanitize HTML from potentially unsafe elements such as remote images, scripts, etc. This may expose sensitive user information. -d, --debug_html Write intermediate html file next to PDF's -v, --verbose Show a lot of verbose debugging info. Forces number of procs to 1. -q, --quiet Show only errors. ``` -------------------------------- ### Convert Directory Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/readme.md Converts all .eml files in an input directory to PDF files, saving them in a specified output directory. Output filenames are generated based on the email's sent date and subject, with a counter for duplicates. ```APIDOC ## convert_dir ### Description Converts all .eml files in an input directory to PDF files, saving them in a specified output directory. Output filenames are generated based on the email's sent date and subject, with a counter for duplicates. ### Usage `eml2pdf convert_dir [-h] [-p size] [--unsafe] [-d] [-v] [-q] [-n number] input_dir output_dir ### Arguments * `input_dir`: Directory containing EML files. * `output_dir`: Directory for PDF output. ### Options * `-h`, `--help`: Show this help message and exit. * `-p`, `--page size`: Specifies page size and orientation (e.g., "a4 landscape", "a3"). Defaults to "a4" portrait. * `--unsafe`: Disables HTML sanitization, potentially exposing sensitive information. * `-d`, `--debug_html`: Writes intermediate HTML file next to PDF's. * `-v`, `--verbose`: Enables verbose debugging output. Forces number of processes to 1. * `-q`, `--quiet`: Shows only errors. * `-n`, `--number-of-procs number`: Sets the number of parallel processes. Defaults to the number of available logical CPUs. ``` -------------------------------- ### EML Parsing: Generate Attachment List Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Creates an HTML table that summarizes all attachments, including their name, size (human-readable), and MD5 checksum. ```python attachment_list = generate_attachment_list(attachments) ``` -------------------------------- ### Convert EML directory via CLI Source: https://github.com/plenaerts/eml2pdf/blob/main/SECURITY.md Use this command to process all EML files in a directory, applying default security sanitization. ```bash eml2pdf convert_dir input_dir output_dir ``` -------------------------------- ### Shared Options Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/readme.md Details on options common to both `convert_dir` and `convert_file` operations, including page size, security considerations for HTML sanitization, and debugging. ```APIDOC ## Shared options between convert_dir and convert_file ### Debug HTML (`--debug_html`) Saves the intermediate HTML file generated during the conversion process, which can be useful for diagnosing parsing or PDF conversion issues. ### Page Size (`-p`/`--page`) Allows adjustment of the PDF page size and orientation (e.g., "a3", "a4 landscape") to accommodate different email content widths and ensure all parts of the email are visible. ### Security (`--unsafe`) * **HTML Sanitization**: By default, `eml2pdf` cleans HTML content to remove potentially malicious elements and tracking mechanisms. The `--unsafe` flag disables this sanitization. Use with caution and only if you trust the source of the EML files. ``` -------------------------------- ### Run Tests with Verbose Output Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Execute all project tests with verbose output using the 'test-verbose' Poe task. ```bash poe test-verbose ``` -------------------------------- ### Convert single EML file via CLI Source: https://github.com/plenaerts/eml2pdf/blob/main/SECURITY.md Use this command to process a single EML file, applying default security sanitization. ```bash eml2pdf convert_file input_file output_file ``` -------------------------------- ### Email Class Initialization Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md The Email class encapsulates a parsed email message and its associated file path, initializing with header and walked message parts. ```python class Email: def __init__(self, msg: email.message.Message, eml_path: Path): self.header = Header(msg, eml_path) self.html, self.attachments = walk_eml(msg, eml_path) ``` -------------------------------- ### HTML Sanitization Integration in PDF Generation Source: https://github.com/plenaerts/eml2pdf/blob/main/SECURITY.md Illustrates how HTML content is sanitized before PDF generation within the `generate_pdf` function when `unsafe` is False. ```python def generate_pdf(html_content: str, outfile_path: Path, infile: Path, debug_html: bool = False, page: str = 'a4', unsafe: bool = False): """Convert HTML to PDF.""" # ... Some logging config first ... if not unsafe: html_content = security.sanitize_html(html_content) # ... PDF generation continues ... ``` -------------------------------- ### Upload to TestPyPI Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Upload distribution packages to the TestPyPI repository using the 'upload-test' Poe task. ```bash poe upload-test ``` -------------------------------- ### Final HTML Content Assembly Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Combines HTML content with embedded images or converts plain text to HTML if no HTML content is present. ```python html_content = embed_imgs(html_content, cid_attachments) \ if html_content else markdown(plain_text_content) ``` -------------------------------- ### EML Parsing: Assemble Complete HTML Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Constructs the final HTML content for the PDF by combining UTF-8 meta tags, the email header table, the attachment list table, a separator, and the main email body content. ```python if html_content: html_content = f" {email_header.html} {attachment_list}
{html_content} " ``` -------------------------------- ### Decode to String Function Logic Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Details the logic within the decode_to_str() function for robust byte-to-string conversion. ```python # This function implements a robust decoding strategy for converting bytes to strings. ``` -------------------------------- ### EML Parsing: Generate Output Path Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Determines the output PDF file path based on the email's date and subject, formatted as '{date}-{subject}.pdf'. ```python output_path = get_output_base_path(email_header.date, email_header.subject, output_dir) ``` -------------------------------- ### Convert File Source: https://github.com/plenaerts/eml2pdf/blob/main/docs/readme.md Converts a single EML file to a PDF file, specifying both the input EML file and the output PDF filename. ```APIDOC ## convert_file ### Description Converts a single EML file to a PDF file, specifying both the input EML file and the output PDF filename. ### Usage `eml2pdf convert_file [-h] [-p size] [--unsafe] [-d] [-v] [-q] input_file output_file ### Arguments * `input_file`: Input EML file to convert. * `output_file`: Output PDF file to convert to. ### Options * `-h`, `--help`: Show this help message and exit. * `-p`, `--page size`: Specifies page size and orientation (e.g., "a4 landscape", "a3"). Defaults to "a4" portrait. * `--unsafe`: Disables HTML sanitization, potentially exposing sensitive information. * `-d`, `--debug_html`: Writes intermediate HTML file next to PDF's. * `-v`, `--verbose`: Enables verbose debugging output. Forces number of processes to 1. * `-q`, `--quiet`: Shows only errors. ``` -------------------------------- ### Attachment and Inline File Processing Conditions Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Conditions for processing parts marked as attachments or inline content. ```python elif (content_disposition == 'attachment' or content_disposition == 'inline'): ``` -------------------------------- ### EML Parsing: Generate PDF Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Invokes the PDF generation function using the assembled HTML content and the determined output path. Includes options for HTML sanitization (`unsafe` flag). ```python generate_pdf(html_content, output_path, eml_path, debug_html=debug_html, page=page, unsafe=unsafe) ``` -------------------------------- ### EML Charset Detection with Default Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Retrieves the character set from the MIME part's Content-Type header. If no charset is specified, it defaults to 'utf-8'. ```python content_charset = part.get_content_charset() or 'utf-8' ``` -------------------------------- ### Include Markdown File in RST Documentation Source: https://github.com/plenaerts/eml2pdf/blob/main/DEVELOPMENT.md Use the 'include' directive with the 'myst_parser' to embed Markdown content within RST files. ```rst .. include:: ../README.md :parser: myst_parser.sphinx_ ``` -------------------------------- ### EML Parsing: Open and Parse EML File Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Opens an EML file for reading and parses its content into an email message object using Python's built-in `email` library. ```python with open(eml_path, "r") as f: msg = email.message_from_file(f) ``` -------------------------------- ### Parallel Processing with Multiprocessing Pool Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Uses Python's multiprocessing.Pool for parallel processing of multiple EML files. Conditions for multiprocessing include number_of_procs > 1, verbose is False, and logger level is not DEBUG. ```python with Pool(number_of_procs) as p: p.starmap(process_eml, p_args) ``` -------------------------------- ### EML Parsing: Walk Message Parts Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Recursively traverses the MIME structure of the email message to extract text content, attachment metadata, and identify inline images. ```python html_content, attachments = walk_eml(msg, eml_path) ``` -------------------------------- ### Image Embedding Data URI Generation Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Generates data URIs for inline images by Base64-encoding image bytes. These URIs replace 'cid:' references in HTML, allowing images to be embedded directly in the PDF. ```text Before: After: ``` -------------------------------- ### EML Unicode Escape Sequence Handling Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Processes email content to decode Unicode escape sequences (e.g., \uXXXX) that might be present due to certain email clients. It attempts to re-encode as UTF-8 and decode using 'unicode-escape'. If this fails, the 'replace' version is retained. ```python unicode_escape_pattern = r'\\u[0-9a-fA-F]{4}|\\U[0-9a-fA-F]{8}' try: if re.search(unicode_escape_pattern, decoded): decoded = decoded.encode('utf-8').decode('unicode-escape') except Exception as e: logger.debug(f"Unicode escape decoding skipped: {e}") ``` -------------------------------- ### Text Content Processing Conditions Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Conditions for processing text parts (plain and HTML) that are not explicitly marked as attachments. ```python if (content_type == 'text/plain' or content_type == 'text/html') and \ (content_disposition is None or content_disposition == 'inline'): ``` -------------------------------- ### Part Skipping Conditions Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Conditions under which message parts are skipped during the EML parsing process. ```python # Parts are skipped if: # - No payload exists # - Payload is not bytes # - Does not match any classification above ``` -------------------------------- ### EML Parsing: Extract Email Header Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Extracts and decodes key header fields (From, To, Subject, Date) from the parsed email message and prepares an HTML table representation. ```python email_header = Header(msg, eml_path) ``` -------------------------------- ### Strict EML Decoding Attempt Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md Attempts to decode email content using the charset specified in the Content-Type header. This is the primary decoding method. ```python try: decoded = bytes_content.decode(content_charset) ``` -------------------------------- ### EML Decoding Fallback with Error Replacement Source: https://github.com/plenaerts/eml2pdf/blob/main/doc/eml_parsing.md If strict decoding fails due to invalid byte sequences or an unknown charset, this fallback attempts decoding with error replacement. Invalid bytes are replaced with the Unicode replacement character (U+FFFD). ```python except (UnicodeDecodeError, LookupError): logger.warning(f"Strict decode failed for {content_charset}. Using 'replace' mode.") decoded = bytes_content.decode(content_charset, errors='replace') ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.