latex-process 0.1.2

Ultimate LaTeX Processing Tool

Ultimate LaTeX Processing Tool

Welcome to the Ultimate LaTeX Processing Tool (powered by the LatexProcess class). This Python package provides a streamlined way to compile, render, and manage LaTeX documents, featuring advanced functionalities such as:

• Multiple LaTeX engines (pdflatex, xelatex, lualatex, latexmk)
• Automatic bibliography handling (bibtex or biber)
• Plugin architecture for extending capabilities
• Support for exporting to various formats (PDF, DVI, HTML, EPUB, DOCX) via Pandoc
• Jinja2 template rendering
• Watchdog-based file watching and automatic recompilation
• Logging with Rich integration
• Basic security scanning (placeholder functionality)
• Async compilation

---

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
  • Command-Line Usage
  • API Usage
• Plugins
• Advanced Features
  • Template Rendering
  • Watching a File for Changes
  • Async Compilation
  • Exporting to Different Formats
  • Security Scan
• Logging
• Contributing
• License

---

Features

1. Multiple LaTeX Engines
   Compile your .tex file using pdflatex, xelatex, lualatex, or latexmk.

2. Bibliography Handling
   Automatically processes bibliographies via either bibtex or biber.

3. Export to Various Formats
   Convert LaTeX documents to PDF, DVI, HTML, EPUB, or DOCX using Pandoc.

4. File Watching
   Recompile automatically on file changes with the help of watchdog.

5. Plugin Architecture
   Extend core functionality with plugin modules or custom plugin functions.

6. Logging and Debugging
   Rich-integrated logging, with colorized and nicely formatted logs.

7. Security Scan (Basic)
   Detect certain LaTeX commands that may be unsafe (placeholder functionality).

8. Async Support
   Asynchronous LaTeX compilation using Python's asyncio.

---

Requirements

• Python 3.7+
• LaTeX Distribution (e.g., TeX Live, MiKTeX) that provides:
  • pdflatex, xelatex, lualatex, or latexmk
• Bibliography Tools (if needed):
  • bibtex or biber
• Pandoc (if you want to export to HTML, EPUB, DOCX, etc.)
• Jinja2 (if you want to render LaTeX templates)
• watchdog (if you want to watch .tex files for changes)

---

Installation

You can install this package from source or add it to your pyproject.toml / requirements.txt after creating a new Python project.

Installing from Source (Local):

git clone https://github.com/yourusername/latex-process-tool.git
cd latex-process-tool
pip install .

(If you plan to develop or modify the code, you can install in editable mode with pip install -e ..)

---

Quick Start

Below are two ways to use the Ultimate LaTeX Processing Tool: via the command line and via the Python API.

Command-Line Usage

After installation, you can run the tool via:

python -m latex-process --help

or if you’ve set up a console script, something like:

ultlatex --help

Basic usage:

python -m latex-process \
  <input.tex> \
  -o output/document.pdf \
  --engine pdflatex \
  --bibtool bibtex \
  --format pdf \
  --log-level INFO

Parameters:

• input: Path to a .tex file. Use - to read from stdin.
• -o, --output: Output file path (e.g., output/document.pdf).
• -e, --engine: Choose LaTeX engine (pdflatex, xelatex, lualatex, latexmk).
• -b, --bibtool: Select bibliography tool (bibtex or biber).
• -f, --format: Output format (pdf, dvi, html, epub, or docx).
• -t, --template: Path to a Jinja2 LaTeX template.
• --log-level: Logging verbosity (DEBUG, INFO, WARNING, ERROR, CRITICAL).

Example:

python -m latex-process \
  main.tex \
  -o my_paper.pdf \
  -e pdflatex \
  -b bibtex \
  -f pdf \
  --log-level DEBUG

API Usage

In your Python scripts or notebooks, you can use the LatexProcess class directly:

from latex-process.latex_process import LatexProcess

processor = LatexProcess(
    engine='pdflatex',
    bib_tool='bibtex',
    output_format='pdf',
    output_dir='output',
    output_filename='document.pdf'
)

# Load from file
processor.load_from_file("main.tex")

# Compile
try:
    output_path = processor.compile()
    print(f"Compilation successful! Output at: {output_path}")
except Exception as e:
    print(f"Compilation failed: {e}")

Or load LaTeX content from a string:

latex_code = r"""
\documentclass{article}
\begin{document}
Hello from LaTeX string!
\end{document}
"""

processor.load_from_string(latex_code)
output_path = processor.compile()
print(f"Output generated at: {output_path}")

---

Plugins

You can extend the tool’s functionality by adding plugins. A plugin is any callable that accepts a LatexProcess instance as its only argument. For instance:

def my_custom_plugin(processor: LatexProcess):
    # Do something with processor
    processor.logger.info("My Custom Plugin is running...")

my_custom_plugin.is_plugin = True  # Mark it as a plugin

processor.add_plugin(my_custom_plugin)

The tool also looks for plugins in a plugins directory (if load_plugins() is called). Any .py file in that directory with callables marked with is_plugin = True will be automatically loaded.

---

Advanced Features

Template Rendering

If you have a LaTeX template that uses Jinja2, set the template parameter and call render_template() with a context dictionary:

processor = LatexProcess(template="path/to/template.tex")
context = {"title": "My Document", "author": "Jane Doe"}
processor.render_template(context)
output_path = processor.compile()

Watching a File for Changes

Automatically recompile when a .tex file changes using the watch method. This requires watchdog to be installed.

processor.watch("main.tex", interval=5)

This will watch main.tex and recompile every time it detects a file modification, polling every 5 seconds.

Async Compilation

Run LaTeX compilation in an asynchronous context:

import asyncio
from latex-process.latex_process import LatexProcess

async def main():
    processor = LatexProcess()
    processor.load_from_file("main.tex")
    output_path = await processor.compile_async()
    print(f"Compiled asynchronously, output at: {output_path}")

asyncio.run(main())

Exporting to Different Formats

In addition to PDF, you can export to DVI, HTML, EPUB, or DOCX by specifying the output_format. For convenience, you may use helper methods:

# Export to HTML
processor.export_html("output.html")

# Export to EPUB
processor.export_epub("output.epub")

# Export to DOCX
processor.export_docx("output.docx")

These methods internally call Pandoc, so ensure Pandoc is installed.

Security Scan

A basic security scan checks for certain LaTeX commands that might be unsafe, such as \write18. This functionality is a placeholder and not comprehensive.

issues = processor.security_scan()
if issues:
    print("Security issues found:", issues)
else:
    print("No security issues detected.")

---

Logging

By default, the logging level is INFO and outputs to the console with Rich styling. You can adjust this level:

import logging
processor.set_logging_level(logging.DEBUG)

You can also add a logging plugin to log to a file:

processor.add_logging_plugin()  # By default logs to `latex_process.log` in the output directory

---

Contributing

Contributions are welcome! Please:

1. Fork the repository.
2. Create a new feature branch.
3. Make your changes or additions.
4. Write tests if appropriate.
5. Submit a Pull Request.

We appreciate your help in making this tool better.

---

License

This project is licensed under the MIT License. You’re free to use, modify, and distribute this software with attribution.