kleinpanic/convertions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
convertions/README.md

6.2 KiB
Raw Permalink Blame History

Convertions

The convertions project is a comprehensive suite of Python scripts designed to handle various file format conversions and content extractions. It supports operations on CSV, JSON, Excel, HTML, Markdown, YAML, PNG, JPG, PDF, audio, video, and more.

This tool is modular, highly extensible, and packaged for ease of use. You can run it as a Python script or compile it into a standalone binary for seamless deployment.

Table of Contents

Installation

1. Clone the Repository

git clone https://github.com/yourusername/convertions.git
cd convertions

2. Set Up the Virtual Environment

Create and activate a Python virtual environment to isolate dependencies:

python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

Install the required Python packages using the virtual environment's pip:

./venv/bin/pip install -r requirements.txt

4. Optional: Add Convertions to Your PATH

To make the convertions command globally accessible:

  • For Bash: 
    echo 'export PATH="$HOME/convertions:$PATH"' >> ~/.bashrc
source ~/.bashrc
  • For Zsh: 
    echo 'export PATH="$HOME/convertions:$PATH"' >> ~/.zshrc
source ~/.zshrc

Usage

The convertions tool accepts various commands corresponding to supported operations. Each command is mapped to a specific utility script.

Global Options

  • --help or -h: Display help and a list of available commands.
  • --version or -v: Print the version of the convertions tool.
convertions --help
convertions --version

Available Commands

Each command has its usage syntax. Below is the full list:

General Format

convertions <command> <input_path> <output_path>

File Operations

  • CSV to Excel: csvtoexcel <input_csv_path> <output_excel_path>
  • CSV to JSON: csvtojson <input_csv_path> <output_json_path>
  • CSV to YAML: csvtoyaml <input_csv_path> <output_yaml_path>
  • Excel to CSV: exceltocsv <input_excel_path> <output_csv_path>
  • Excel to JSON: exceltojson <input_excel_path> <output_json_path>
  • HTML to Markdown: htmltomd <input_html_path> <output_md_path>
  • HTML to PDF: htmltopdf <input_html_path> <output_pdf_path>
  • Image to Markdown (OCR): imagetomd <input_image_path> <output_md_path>
  • JPG to PNG: jpgtopng <input_jpg_path> <output_png_path>
  • JSON to CSV: jsontocsv <input_json_path> <output_csv_path>
  • JSON to Excel: jsontoexcel <input_json_path> <output_excel_path>
  • JSON to YAML: jsontoyaml <input_json_path> <output_yaml_path>
  • Markdown Table to CSV: mdtabletocsv <input_md_path> <output_csv_path>
  • Markdown to DOCX: mdtodocx <input_md_path> <output_docx_path>
  • Markdown to HTML: mdtohtml <input_md_path> <output_html_path>
  • Markdown to PDF: mdtopdf <input_md_path> <output_pdf_path>
  • Markdown to YAML: mdtoyaml <input_md_path> <output_yaml_path>
  • Merge PDFs: mergepdfs <output_pdf_path> <input_pdf1> <input_pdf2> ...
  • PDF to JPG: pdftojpg <input_pdf_path> <output_jpg_base_path>
  • PDF to Markdown: pdftomd <input_pdf_path> <output_md_path>
  • PDF to Text: pdftotext <input_pdf_path> <output_txt_path>
  • PNG to JPG: pngtojpg <input_png_path> <output_jpg_path>
  • Text to Speech: texttospeech <input_text_path> <output_audio_path>
  • Video to Audio: videotoaudio <input_video_path> <output_audio_path>
  • YAML to JSON: yamltojson <input_yaml_path> <output_json_path>
  • YAML to Markdown: yamltomd <input_yaml_path> <output_md_path>

Adding New Scripts

To extend convertions with additional commands:

  1. Add the Script: Place the script in the utils directory.
  2. Make It Executable: Ensure the script has execute permissions: 
    chmod +x <script_name>.py
  3. Update the Mapping: Edit convertions.py and add a new entry to the SCRIPT_MAP dictionary: 
    "newcommand": "new_script.py"

Virtual Environment

To ensure proper dependency management, activate the virtual environment before running or modifying the convertions tool:

source venv/bin/activate

To deactivate the virtual environment:

deactivate

Compilation into a Binary

The install.sh script simplifies the process of creating a standalone binary using PyInstaller. It also allows for optional installation to /usr/local/bin for system-wide usage.

Steps:

  1. Run the install.sh script: 
    ./install.sh
  2. Follow the prompts to decide whether to move the compiled binary to /usr/local/bin. If skipped, the binary will remain in the ./dist directory.

Key Features of install.sh:

  • Checks and installs dependencies in the virtual environment.
  • Compiles all scripts and utilities into a single binary.
  • Optionally installs the binary globally for ease of use.

Dependencies

This project relies on several Python libraries and external tools. Ensure the following are installed:

  • Python 3.11+
  • wkhtmltopdf (for HTML to PDF conversion)
  • External dependencies in requirements.txt, managed by the virtual environment:
    • pandas
    • PyMuPDF
    • pytesseract
    • markdown
    • pdfkit
    • gTTS
    • pillow
    • moviepy
    • PyYAML

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

The following libraries and tools power convertions: