Added Python Library support

Author: datsom1

README.md

@@ -21,6 +21,7 @@ A powerful CLI and GUI tool to export Salesforce SOQL query results to local CSV
 - [Usage](#usage)
   - [CLI Usage](#cli-usage)
   - [GUI Usage](#gui-usage) 
+- [Library Usage](#library-usage)
 - [Post-processing](#post-processing)
 - [Examples](#examples)
 - [Troubleshooting](#troubleshooting)
@@ -52,7 +53,8 @@ pip install -e "git+https://github.com/datsom1/soql2csv.git#egg=soql2csv[dev]"
 soql2csv requires Salesforce authentication credentials in a `.env` file.
 
 Example `.env` file:
-```
+
+```env
 SF_USERNAME=your_salesforce_username
 SF_PASSWORD=your_salesforce_password
 SF_SECURITY_TOKEN=your_salesforce_security_token
@@ -72,6 +74,7 @@ soql2csv [OPTIONS] SOQLFILE
 ```
 
 Get help:
+
 ```bash
 soql2csv --help
 ```
@@ -99,7 +102,7 @@ soql2csv --help
 soql2csv path/to/query.soql --outfilename=Extract_Table__c.csv --outfilepath=./output
 ```
 
-**CLI Preview**
+### CLI Preview
 
 ![soql2csv v2 2 CLI helptext](https://github.com/user-attachments/assets/a630de3d-d0d3-4c12-a2f2-80129d39f157)
 
@@ -113,6 +116,7 @@ soql2csv --gui
 ```
 
 The GUI provides fields for:
+
 - SOQL File: Select your query file
 - Output Folder: Where exported CSVs will be saved
 - Env File: Path to your .env file with Salesforce credentials
@@ -121,13 +125,82 @@ The GUI provides fields for:
 
 A console output area displays progress and results.
 
-**Gui Preview**
+### GUI Preview
 
 ![soql2csv v2 2 GUI](https://github.com/user-attachments/assets/a0a18088-65ff-4f06-b0a7-cc5fc3a52d4e)
 
+## Library Usage
+
+You can also call `soql2csv` directly from Python code without invoking the CLI.
+
+Primary helper:
+
+```text
+export_soql_to_csv(soql_path, output_base_name, output_dir='.', env_path='.env', postprocess_path=None, timestamp=True) -> str
+```
+
+Parameters:
+
+| Parameter | Description |
+|-----------|-------------|
+| `soql_path` | Path to the `.soql` file containing your query. |
+| `output_base_name` | Base name for the exported CSV (with or without `.csv`). |
+| `output_dir` | Destination directory (created if it does not exist). Default: current directory. |
+| `env_path` | Path to the `.env` file containing Salesforce credentials. Default: `.env`. |
+| `postprocess_path` | Optional path to a Python script for post-processing. Receives temp_input and final_output CSV paths as argv[1], argv[2]. |
+| `timestamp` | If True (default) prefixes filename like the CLI with a timestamp. Set to False to suppress. |
+
+Returns: Absolute path to the final CSV file.
+
+Example:
+
+```python
+from soql2csv import export_soql_to_csv
+
+csv_path = export_soql_to_csv(
+    soql_path="queries/Accounts.soql",
+    output_base_name="Accounts.csv",
+    output_dir="./exports",
+    env_path="./salesforce.env",  # or leave as default '.env'
+    postprocess_path=None,         # or a script like 'scripts/clean_accounts.py'
+    timestamp=True                 # set False to disable timestamp prefix
+)
+
+print("CSV exported to", csv_path)
+```
+
+Minimal example (defaults to `.env` in cwd, current directory output, adds timestamp):
+
+```python
+from soql2csv import export_soql_to_csv
+export_soql_to_csv("query.soql", "MyData")
+```
+
+With post-processing (script signature identical to CLI expectations):
+
+```python
+from soql2csv import export_soql_to_csv
+export_soql_to_csv(
+    soql_path="query.soql",
+    output_base_name="FilteredData",
+    postprocess_path="scripts/filter_script.py"
+)
+```
+
+Errors you might encounter:
+
+| Exception | Cause |
+|-----------|-------|
+| `FileNotFoundError` | The `.soql`, `.env`, or postprocess script path does not exist. |
+| `EnvironmentError` | Missing required Salesforce environment variables. |
+| `SalesforceAPIError` | Any Salesforce API interaction failed. |
+
+The function internally mirrors CLI logic: loads env vars, executes Bulk API v2 query, waits for completion, downloads paginated results, optionally runs a postprocess script (on a temporary copy), and returns the final CSV path.
+
 ## Post-processing
 
 Post-processing scripts allow you to transform the exported data. The script automatically receives two arguments:
+
 1. `sys.argv[1]`: Path to the input CSV file (exported from Salesforce)
 2. `sys.argv[2]`: Path to the output CSV file (to write processed data)
 
@@ -185,23 +258,27 @@ with open(output_csv, 'w', newline='', encoding='utf-8') as outfile:
 ```
 
 Run with:
+ 
 ```bash
 soql2csv query.soql --outfilename=Extract.csv --outfilepath=./output --postprocess=process_script.py
 ```
 
 ## Examples
 
 Basic extraction:
+
 ```bash
 soql2csv queries/Accounts.soql --outfilename=Accounts.csv --outfilepath=./exports
 ```
 
 Using a custom environment file:
+
 ```bash
 soql2csv queries/Contacts.soql --outfilename=Contacts.csv --outfilepath=./exports --envpath=./salesforce.env
 ```
 
 With post-processing:
+
 ```bash
 soql2csv queries/Opportunities.soql --outfilename=Opportunities.csv --outfilepath=./exports --postprocess=scripts/clean_opps.py
 ```

setup.py

@@ -7,7 +7,7 @@ def readme():
 
 setup(
     name="soql2csv",
-    version="2.2",
+    version="2.3",
     description="A powerful CLI and GUI tool to export Salesforce SOQL query results to CSV using Bulk API v2.",
     long_description=readme(),
     long_description_content_type="text/markdown",

soql2csv/__init__.py

@@ -6,7 +6,8 @@
 import requests
 import sys
 import logging
-from typing import Tuple
+from pathlib import Path
+from typing import Tuple, Optional
 
 logger = logging.getLogger("soql2csv")
 logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s")
@@ -190,4 +191,110 @@ def generate_csv_from_soql(soql_file_location: str, output_csv_location: str) ->
         raise SalesforceAPIError(f"Job did not complete successfully. Status: {status}")
     logger.info("Downloading results...")
     download_bulk_v2_results(instance_url, access_token, job_id, output_csv_location)
-    logger.info(f"Results written to {output_csv_location}")
+    logger.info(f"Results written to {output_csv_location}")
+
+# ------------------------------ Public Library API ------------------------------
+def export_soql_to_csv(
+    soql_path: str,
+    output_base_name: str,
+    output_dir: str = ".",
+    env_path: str = ".env",
+    postprocess_path: Optional[str] = None,
+    timestamp: bool = True,
+) -> str:
+    """Programmatic helper to export a SOQL query to CSV (with optional post-processing).
+
+    This mirrors the CLI / GUI behavior in a single simple call.
+
+    Parameters
+    ----------
+    soql_path : str
+        Path to the .soql file containing the query.
+    output_base_name : str
+        Base name for the output CSV (with or without .csv extension).
+    output_dir : str, default "."
+        Directory where the CSV should be written (created if missing).
+    env_path : str, default ".env"
+        Path to a .env file containing Salesforce credentials.
+    postprocess_path : str | None, default None
+        Optional path to a Python script to postprocess the CSV. The script
+        will be invoked as: python postprocess_path temp_input_csv final_output_csv
+    timestamp : bool, default True
+        Whether to prefix the file with a timestamp like the CLI (YYYY-MM-DD_HH-MM-SS_Export_...).
+
+    Returns
+    -------
+    str
+        Absolute path to the final (possibly post-processed) CSV file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the provided soql_path (or postprocess script path) does not exist.
+    EnvironmentError
+        If required Salesforce environment variables are missing.
+    SalesforceAPIError
+        If any Salesforce interaction fails.
+    """
+    from dotenv import load_dotenv  # Local import so library users without dotenv still get a clear error earlier
+    import subprocess
+    import shutil
+
+    soql_file = Path(soql_path)
+    if not soql_file.is_file():
+        raise FileNotFoundError(f"SOQL file not found: {soql_path}")
+
+    output_dir_path = Path(output_dir)
+    output_dir_path.mkdir(parents=True, exist_ok=True)
+
+    base_name = output_base_name
+    if not base_name.lower().endswith(".csv"):
+        base_name += ".csv"
+
+    if timestamp:
+        ts = time.strftime("%Y-%m-%d_%H-%M-%S")
+        filename = f"{ts}_Export_{base_name}"
+    else:
+        filename = base_name
+
+    final_csv_path = output_dir_path / filename
+
+    # Load environment variables
+    if env_path:
+        env_file = Path(env_path)
+        if not env_file.is_file():
+            raise FileNotFoundError(f".env file not found: {env_path}")
+        load_dotenv(str(env_file), override=True)
+
+    start = time.time()
+    generate_csv_from_soql(str(soql_file), str(final_csv_path))
+
+    if postprocess_path:
+        post_script = Path(postprocess_path)
+        if not post_script.is_file():
+            raise FileNotFoundError(f"Postprocess script not found: {postprocess_path}")
+        temp_csv = final_csv_path.with_name(final_csv_path.stem + "_temp.csv")
+        shutil.copy2(final_csv_path, temp_csv)
+        try:
+            subprocess.run([sys.executable, str(post_script), str(temp_csv), str(final_csv_path)], check=True)
+        finally:
+            if temp_csv.exists():
+                try:
+                    temp_csv.unlink()
+                except OSError:
+                    pass
+
+    elapsed = time.time() - start
+    logger.info(f"Completed export in {elapsed:.2f}s -> {final_csv_path}")
+    return str(final_csv_path.absolute())
+
+__all__ = [
+    "SalesforceAPIError",
+    "salesforce_login",
+    "create_bulk_v2_query_job",
+    "poll_bulk_v2_job",
+    "download_bulk_v2_results",
+    "strip_soql_comments",
+    "generate_csv_from_soql",
+    "export_soql_to_csv",
+]