Metadata-Version: 2.2
Name: thefreeconverter
Version: 1.0.0
Summary: Official Python SDK & CLI for The Free Converter - Fast, secure, and privacy-focused conversion, calculation, and text utilities.
Author-email: The Free Converter Team <support@thefreeconverter.com>
Project-URL: Homepage, https://thefreeconverter.com
Project-URL: Documentation, https://thefreeconverter.com/about
Project-URL: Bug Tracker, https://thefreeconverter.com/contact
Project-URL: PDF Converters, https://thefreeconverter.com/pdf
Project-URL: Audio Converters, https://thefreeconverter.com/audio-converters
Project-URL: Image Converters, https://thefreeconverter.com/image-converters
Project-URL: SEO Tools, https://thefreeconverter.com/seo
Project-URL: Finance Calculators, https://thefreeconverter.com/finance-calculators
Project-URL: Text Tools, https://thefreeconverter.com/text-tools
Keywords: converter,file-converter,pdf-converter,mortgage-calculator,compound-interest,vat-calculator,gst-calculator,json-formatter,seo-tools,thefreeconverter
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Topic :: Text Processing
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# The Free Converter (Python SDK & CLI)

[![PyPI version](https://img.shields.io/pypi/v/thefreeconverter.svg)](https://pypi.org/project/thefreeconverter/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Website](https://img.shields.io/badge/Website-thefreeconverter.com-success.svg)](https://thefreeconverter.com)

The official Python client and CLI toolkit for [The Free Converter](https://thefreeconverter.com) — a comprehensive suite of 160+ privacy-focused file conversion tools, financial calculators, SEO analyzers, and text utilities.

---

## Online Web Platform & Tool Hubs

Access full-featured, browser-based online tools with zero software installation required:

* 📄 **[PDF & Document Converters](https://thefreeconverter.com/pdf)** — Convert PDF to Word, Excel, JPG, PNG, EPUB, CSV, RTF, TXT, and manage PDF security, merging, splitting, compression, and watermarking.
* 🎵 **[Audio & Video Converters](https://thefreeconverter.com/audio-converters)** — Transcode MP3, WAV, AAC, FLAC, OGG, M4A, OPUS, MP4, and WEBM with high-fidelity acoustic preservation.
* 🖼️ **[Image & Next-Gen Graphic Converters](https://thefreeconverter.com/image-converters)** — Convert WEBP, AVIF, HEIC, PNG, JPG, SVG, and RAW camera DNG formats with optimized lossless and lossy compression.
* 🔍 **[SEO & Webmaster Tools](https://thefreeconverter.com/seo)** — Audit broken links, verify dofollow/nofollow link equity, validate XML sitemaps, extract sitemap URLs, and monitor domain age.
* 💰 **[Financial & Tax Calculators](https://thefreeconverter.com/finance-calculators)** — Calculate mortgage amortization, mortgage overpayment interest savings, crypto capital gains (FIFO/LIFO/HIFO), compound interest, VAT addition/extraction, and GST breakdowns.
* ✍️ **[Text & Markup Utilities](https://thefreeconverter.com/text-tools)** — Format & validate JSON, convert text to JSON arrays, deduplicate large email/URL lists, count words/reading times, and convert Markdown to clean HTML.

---

## Installation

Install the package directly from PyPI via pip:

```bash
pip install thefreeconverter
```

---

## Python SDK Quickstart

### 1. Financial & Tax Calculations

```python
from thefreeconverter.calculators import (
    calculate_percentage_change,
    calculate_compound_interest,
    calculate_mortgage_payment,
    calculate_vat,
    calculate_gst,
    calculate_effective_interest_rate
)

# Calculate percentage increase
change = calculate_percentage_change(initial=50, final=65)
print(f"Percentage Change: {change}%") # +30.0%

# Calculate compound interest growth with monthly contributions
ci = calculate_compound_interest(
    principal=10000,
    annual_rate_percent=7.5,
    years=10,
    compounding_frequency=12,
    monthly_contribution=500
)
print(f"Future Balance: ${ci['future_value']:,.2f}")
print(f"Total Interest Earned: ${ci['total_interest']:,.2f}")

# Calculate monthly mortgage amortization (P&I)
mortgage = calculate_mortgage_payment(
    principal=350000,
    annual_rate_percent=6.5,
    term_years=30
)
print(f"Monthly Payment: ${mortgage['monthly_payment']:,.2f}")
print(f"Total Lifetime Interest: ${mortgage['total_interest']:,.2f}")

# Add or extract VAT / GST
vat = calculate_vat(amount=120.0, rate_percent=20.0, mode="extract")
print(f"Net Price: ${vat['net_amount']:.2f}, VAT Extracted: ${vat['vat_amount']:.2f}")
```

### 2. Text & Data Formatting

```python
from thefreeconverter.formatters import (
    format_json_string,
    deduplicate_lines,
    text_to_json_list,
    count_text_metrics
)

# Clean, validate, and prettify raw JSON
raw_json = '{"name":"TheFreeConverter","tools":166,"features":["pdf","audio","finance"]}'
pretty_json = format_json_string(raw_json, indent=2)
print(pretty_json)

# Fast line deduplication
raw_list = ["apple@test.com", "banana@test.com", "apple@test.com", "cherry@test.com"]
unique_lines = deduplicate_lines(raw_list, case_sensitive=False)
print("Unique entries:", unique_lines)

# Real-time text & readability analysis
metrics = count_text_metrics("The quick brown fox jumps over the lazy dog.")
print(f"Words: {metrics['word_count']}, Characters: {metrics['char_count']}, Reading Time: {metrics['reading_time_seconds']}s")
```

---

## Command Line Interface (CLI)

The package installs the `thefreeconverter` (or alias `tfc`) command line utility:

```bash
# Calculate percentage difference
tfc percentage --initial 50 --final 75

# Calculate monthly mortgage payments
tfc mortgage --principal 400000 --rate 6.5 --years 30

# Calculate compound interest
tfc compound --principal 5000 --rate 8 --years 20 --monthly 250

# Deduplicate lines from a text file
tfc dedup --input contacts.txt --output clean_contacts.txt

# Prettify a JSON file
tfc format-json --input config.min.json --output config.json --indent 2
```

---

## Security & Privacy Commitment

At [The Free Converter](https://thefreeconverter.com), we believe your data should remain yours:
* Client calculations run locally in memory.
* Web conversions execute in isolated, secure sandboxes with automatic purging.
* We never store, catalog, or inspect your uploaded files.

---

## License

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