Metadata-Version: 2.4
Name: SQL2Excel
Version: 0.1.0
Summary: Exporting SQL queries and/or Pandas DataFrames to Excel, with support for chart generation and data visualization.
Author-email: Ahmed Hassan <ahmedhassan@aims.ac.za>
Maintainer-email: Ahmed Hassan <ahmedhassan@aims.ac.za>
License: MIT License
        
        Copyright (c) 2025 Ahmed Hassan
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/Al-Madina/SQL2Excel
Project-URL: Repository, https://github.com/Al-Madina/SQL2Excel
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.21
Requires-Dist: pandas<3.0,>=1.3
Requires-Dist: matplotlib<4.0,>=3.4
Requires-Dist: seaborn<1.0,>=0.11
Requires-Dist: openpyxl==3.1.2
Requires-Dist: SQLAlchemy<3.0,>=1.4
Provides-Extra: test
Requires-Dist: coverage<8.0,>=7.0; extra == "test"
Requires-Dist: pytest<9.0,>=7.0; extra == "test"
Requires-Dist: pytest-cov<6.0,>=4.0; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Provides-Extra: ssh
Requires-Dist: paramiko<4.0,>=2.8; extra == "ssh"
Requires-Dist: sshtunnel<1.0,>=0.4; extra == "ssh"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary<3.0,>=2.9; extra == "postgres"
Provides-Extra: postgres-psycopg
Requires-Dist: psycopg<3.4,>=3.1; extra == "postgres-psycopg"
Provides-Extra: mysql
Requires-Dist: pymysql; extra == "mysql"
Provides-Extra: mssql
Requires-Dist: pyodbc; extra == "mssql"
Provides-Extra: oracle
Requires-Dist: oracledb; extra == "oracle"
Provides-Extra: snowflake
Requires-Dist: snowflake-sqlalchemy; extra == "snowflake"
Provides-Extra: databricks
Requires-Dist: databricks-sqlalchemy; extra == "databricks"
Provides-Extra: bigquery
Requires-Dist: sqlalchemy-bigquery; extra == "bigquery"
Dynamic: license-file

<div>
<p align="center">
  <img
    src="https://raw.githubusercontent.com/Al-Madina/SQL2Excel/main/data/SQL2Excel_logo.png"
    width="250"
    height="250"
    alt="SQL2Excel logo">
</p>
<p align="center">A Python library for exporting SQL queries and/or Pandas DataFrames to Excel, with support for chart generation and data visualization.</p>


<p align="center">
  <!-- PyPI Version -->
  <a href="https://pypi.org/project/SQL2Excel/">
    <img src="https://img.shields.io/pypi/v/SQL2Excel?color=blue&logo=pypi&logoColor=white" alt="PyPI Version">
  </a>

  <!-- Python Supported Versions -->
  <a href="https://pypi.org/project/SQL2Excel/">
    <img src="https://img.shields.io/pypi/pyversions/SQL2Excel?color=red&logo=python&logoColor=white" alt="Python Version">
  </a>

  <!-- CI Tests Workflow Status (Dynamic via ci.yml) -->
  <a href="https://github.com/Al-Madina/SQL2Excel/actions/workflows/ci.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/Al-Madina/SQL2Excel/ci.yml?branch=main&label=tests&color=blue&logo=github" alt="CI Build Status">
  </a>

  <!-- Code Coverage Badge (Dynamic via Codecov) -->
  <a href="https://codecov.io/gh/Al-Madina/SQL2Excel">
    <img src="https://codecov.io/gh/Al-Madina/SQL2Excel/branch/main/graph/badge.svg" alt="Code Coverage">
  </a>

  <!-- License -->
  <a href="https://github.com/Al-Madina/SQL2Excel/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/Al-Madina/SQL2Excel?color=green" alt="License">
  </a>

  <!-- PyPI Downloads -->
  <a href="https://pypistats.org/packages/sql2excel">
    <img src="https://img.shields.io/pypi/dm/SQL2Excel?color=orange" alt="PyPI Downloads">
  </a>

  <!-- Code style -->
  <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black">

  <!-- Documentation -->
  <img src="https://img.shields.io/badge/docs-online-blue?logo=readthedocs" alt="Documentation">

  <!-- Stars -->
  <img src="https://img.shields.io/github/stars/Al-Madina/SQL2Excel?style=social" alt="GitHub Stars">
</p>
</div>


# SQL2Excel

`SQL2Excel` exports result sets from SQL queries and/or Pandas DataFrames into Excel including chart generation and data visualization with a strong focus on __automating__  and __simplifying__ the process of exporting data from SQL/Python to Excel. It supports various chart types and allows for basic chart customization.

## Installation

- Create a virtual environment (`.env`)

```bash
python -m venv .env
```

- Activate the environment

```bash
source .env/bin/activate
```


- Install `SQL2Excel` and its dependencies

```bash
pip install SQL2Excel
```

- Verify the Installation

```bash
python -c "import sql2excel; print(f'version: {sql2excel.__version__}')";
```

!!! tip
    To install `SQL2Excel` dependencies for a specific database (e.g. Postgres), see [Database Support](#database-support).

## Getting Started

`SQL2Excel` requires you to add special comments (called _directives_) to your SQL script to instruct it how to export the query result.

```sql
-- my_script.sql

-- chart
SELECT year, revenue FROM annual_sales;

-- chart=bar
SELECT region, SUM(revenue) AS total_revenue
FROM regional_sales
GROUP BY region
ORDER BY total_revenue DESC;

-- exec
CREATE TEMPORARY TABLE tmp_table AS ...

-- This query will be SKIPPED
SELECT * from foo.bar
```

- `-- chart` directive will export the query result to Excel without generating any chart because the chart type is not provided.

- `-- char=bar` directive will export the query result to Excel and generate a bar chart from the result.

- `-- exec` executes the third query without exporting any result. This is useful for DDL, DML, and temporary tables that might be used in subsequent query.

- The fourth query will be ignored because it does not contain any directives.

Then, run the command `sql2excel` in your terminal:

```bash
sql2excel my_script.sql \
    --dialect postgresql \
    --host localhost \
    --port 5432 \
    --user username \
    --password secret \
    --dbname my_db \
    --output report.xlsx
```

That's it!



## Story of `SQL2Excel`

`SQL2Excel` stems from a project at [CREST](https://www0.sun.ac.za/crest/) to profile the scientific performance of the African countries across 52 scientific disciplines using the [Web of Science](https://clarivate.com/products/scientific-and-academic-research/research-discovery-and-workflow-solutions/webofscience-platform/) database. This resulted in generating 1560 reports, each with several performance indicators and different visualizations. `SQL2Excel` made such job possible!


## Why Use SQL2Excel

The main reasons why you should consider using `SQL2Excel` despite the existence of `Openpyxl` are:

- Integration with SQL
    - `SQL2Excel` executes your SQL script and exports all results to Excel including chart generation.
    - `SQL2Excel` offers support for exporting data from parameterized queries. This improves the efficiency of repetitive tasks.
  
- Support for Pandas DataFrames

    - `SQL2Excel` exports DataFrames to Excel. While `Pandas` supports exporting dataframe to Excel, `SQL2Excel` offers more than just writing the dataframe to Excel. SQL2Excel can generate a full report from different dataframes including different visualizations.

- `Matplotlib` and externally generated images
    - Inserting `Matplotlib` figures and externally generated images is straightforward in `SQL2Excel`. This is useful if you require advanced charts that cannot be generated in Excel.
- Simple API
    - `SQL2Excel` offers simple API for data export and chart generation.

`SQL2Excel` is not meant as a library for reading/writing into Excel and it is not suitable for fine customizations of Excel. _Its purpose is to improve productivity, automate repetitive tasks, and simplify data export and chart creation._
If you want more control over excel from within Python, use `Openpyxl` instead.

## Database Support

`SQL2Excel` works with any database supported by [SQLAlchemy](https://www.sqlalchemy.org/). This includes PostgreSQL, MySQL, Oracle, and SQL Server. It is currently tested against PostgreSQL and MySQL. 


### PostgreSQL

To install `SQL2Excel`for postgres you have two options:

- Using `pyscopg2-binary`

```bash
pip install SQL2Excel[postgres]
```

- Using pycopg3 

```bash
pip install SQL2Excel[postgres-psycopg]
```


### MySQL

```bash
pip install SQL2Excel[mysql]
```

### Oracle

```bash
pip install SQL2Excel[oracle]
```

### SQL Server

```bash
pip install SQL2Excel[mssql]
```

### Snowflake

```bash
pip install SQL2Excel[snowflake]
```

### Databricks 

```bash
pip install SQL2Excel[databricks]
```

### BigQuery

```bash
pip install SQL2Excel[bigquery]
```


## Official Documentation
The official documentation is available [here](https://Al-Madina.github.io/SQL2Excel/).
