# Quadrant Generator
A Python library for creating quadrant charts with customizable labels and data points, optimized for web applications and API integrations.
## Features
- Create quadrant charts from CSV strings or data points
- Customizable axis labels and titles
- Automatic text positioning to prevent overlap
- Generate base64-encoded images for easy web integration
- Clean, minimalist design
## Installation
### From Source
```bash
# Clone the repository
git clone https://github.com/ceccode/quadrant-gen.git
cd quadrant-gen
# Install the package
pip install -e .
```
### Using pip
```bash
pip install quadrant-gen
```
## Usage
The library is designed to be used programmatically in your Python applications, particularly for web applications and APIs.
### CSV Format
Your CSV file should have the following columns:
- `name`: Name of the data point
- `description`: Description of the data point
- `x`: X-coordinate (0.0 to 1.0)
- `y`: Y-coordinate (0.0 to 1.0)
Example:
```csv
name,description,x,y
Product A,High quality,0.2,0.8
Product B,Low cost,0.7,0.3
```
### Python API
#### Using CSV String Input
```python
from quadrant_gen.chart import csv_to_quadrant_chart
# CSV string with your data
csv_string = """
name,description,x,y
Product A,High quality,0.2,0.8
Product B,Low cost,0.7,0.3
"""
# Generate chart directly to base64-encoded image
base64_image = csv_to_quadrant_chart(
csv_string=csv_string,
title="My Quadrant Chart",
x_left="Low X",
x_right="High X",
y_bottom="Low Y",
y_top="High Y",
format="png" # or "pdf"
)
# Use the base64 image in HTML
html = f'<img src="{base64_image}" alt="Quadrant Chart">'
```
#### Using Data Points
```python
from quadrant_gen.chart import generate_quadrant_chart, sample_points
# Use sample data
points = sample_points()
# Or create your own data
points = [
{"label": "Item 1\n(Description)", "x": 0.2, "y": 0.8},
{"label": "Item 2\n(Description)", "x": 0.7, "y": 0.3},
]
# Generate chart directly to base64-encoded image
base64_image = generate_quadrant_chart(
points=points,
title="My Quadrant Chart",
x_left="Low X",
x_right="High X",
y_bottom="Low Y",
y_top="High Y",
format="png" # or "pdf"
)
```
## Examples
The following examples are included in the repository:
- **Simple Integration Example**: `examples/integration_example.py` - Shows how to use the library in a Python script
- **Flask API Example**: `examples/flask_api_example.py` - RESTful API for generating charts
- **Flask CSV App**: `examples/flask_csv_app/` - Web application with CSV input form
## Integration with Web Applications
The Quadrant Generator is optimized for web applications and API integrations:
### Flask Integration Example
```python
# Important: Set matplotlib backend to 'Agg' before importing any matplotlib modules
# This is required for web applications to avoid GUI-related errors
import matplotlib
matplotlib.use('Agg')
from flask import Flask, render_template_string
from quadrant_gen.chart import csv_to_quadrant_chart
app = Flask(__name__)
@app.route('/')
def index():
# Sample CSV data
csv_data = """
name,description,x,y
Product A,High quality,0.2,0.8
Product B,Low cost,0.7,0.3
""".strip()
# Generate chart as base64 image
base64_image = csv_to_quadrant_chart(
csv_string=csv_data,
title="Product Analysis",
x_left="Low Cost", x_right="High Cost",
y_bottom="Low Value", y_top="High Value"
)
# Return HTML with embedded image
return render_template_string("""
<!DOCTYPE html>
<html>
<head>
<title>Quadrant Chart Example</title>
</head>
<body>
<h1>Product Analysis</h1>
<img src="{{ chart }}" alt="Quadrant Chart">
</body>
</html>
""", chart=base64_image)
if __name__ == '__main__':
app.run(debug=True)
```
> **Note:** When using Matplotlib in web applications, you must set the backend to a non-interactive one like 'Agg' before importing any Matplotlib modules. This prevents GUI-related errors, especially on macOS where GUI operations must be on the main thread.
See the complete Flask integration example in `examples/flask_api_example.py`.
### Flask CSV Web Application
The repository includes a complete web application for generating quadrant charts from CSV data:
```bash
# Run the Flask CSV app
cd examples/flask_csv_app
python app.py
# Then open http://127.0.0.1:5001/ in your browser
```
This application provides:
- A form for entering CSV data
- Options to customize chart title and axis labels
- Preview of the generated chart
- Download options for PNG or PDF formats
See `examples/flask_csv_app/` for the complete application.
### API Integration
The library is perfect for API services that need to generate charts on-the-fly:
```python
# In a FastAPI application
from fastapi import FastAPI, Response
from pydantic import BaseModel
from quadrant_gen.chart import csv_to_quadrant_chart
app = FastAPI()
class ChartRequest(BaseModel):
csv_data: str
title: str = "Quadrant Chart"
x_left: str = "Low X"
x_right: str = "High X"
y_bottom: str = "Low Y"
y_top: str = "High Y"
@app.post("/generate-chart/")
async def generate_chart(request: ChartRequest):
# Generate base64 image
base64_image = csv_to_quadrant_chart(
csv_string=request.csv_data,
title=request.title,
x_left=request.x_left,
x_right=request.x_right,
y_bottom=request.y_bottom,
y_top=request.y_top
)
# Return JSON with the base64 image
return {"chart_data": base64_image}
```
### Output Formats
The library generates base64-encoded images in two formats:
- **PNG**: Web-friendly format for digital display
- **PDF**: Vector format for high-quality printing and scaling
## Contributing
### For Developers
If you're a developer looking to contribute or maintain this package:
- See [PUBLISHING.md](PUBLISHING.md) for instructions on how to build and publish new versions to PyPI
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/ceccode/quadrant-gen",
"name": "quadrant-gen",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "quadrant, chart, visualization, matplotlib, csv",
"author": "Francesco",
"author_email": "falanga.fra@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5c/cf/7fd84d55db1085b499a91526e849727ffaa0a64b5c2521c1d19370f1177d/quadrant_gen-0.2.0.tar.gz",
"platform": null,
"description": "# Quadrant Generator\n\nA Python library for creating quadrant charts with customizable labels and data points, optimized for web applications and API integrations.\n\n## Features\n\n- Create quadrant charts from CSV strings or data points\n- Customizable axis labels and titles\n- Automatic text positioning to prevent overlap\n- Generate base64-encoded images for easy web integration\n- Clean, minimalist design\n\n## Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/ceccode/quadrant-gen.git\ncd quadrant-gen\n\n# Install the package\npip install -e .\n```\n\n### Using pip\n\n```bash\npip install quadrant-gen\n```\n\n## Usage\n\nThe library is designed to be used programmatically in your Python applications, particularly for web applications and APIs.\n\n### CSV Format\n\nYour CSV file should have the following columns:\n- `name`: Name of the data point\n- `description`: Description of the data point\n- `x`: X-coordinate (0.0 to 1.0)\n- `y`: Y-coordinate (0.0 to 1.0)\n\nExample:\n```csv\nname,description,x,y\nProduct A,High quality,0.2,0.8\nProduct B,Low cost,0.7,0.3\n```\n\n### Python API\n\n#### Using CSV String Input\n\n```python\nfrom quadrant_gen.chart import csv_to_quadrant_chart\n\n# CSV string with your data\ncsv_string = \"\"\"\nname,description,x,y\nProduct A,High quality,0.2,0.8\nProduct B,Low cost,0.7,0.3\n\"\"\"\n\n# Generate chart directly to base64-encoded image\nbase64_image = csv_to_quadrant_chart(\n csv_string=csv_string,\n title=\"My Quadrant Chart\",\n x_left=\"Low X\",\n x_right=\"High X\",\n y_bottom=\"Low Y\",\n y_top=\"High Y\",\n format=\"png\" # or \"pdf\"\n)\n\n# Use the base64 image in HTML\nhtml = f'<img src=\"{base64_image}\" alt=\"Quadrant Chart\">' \n```\n\n#### Using Data Points\n\n```python\nfrom quadrant_gen.chart import generate_quadrant_chart, sample_points\n\n# Use sample data\npoints = sample_points()\n\n# Or create your own data\npoints = [\n {\"label\": \"Item 1\\n(Description)\", \"x\": 0.2, \"y\": 0.8},\n {\"label\": \"Item 2\\n(Description)\", \"x\": 0.7, \"y\": 0.3},\n]\n\n# Generate chart directly to base64-encoded image\nbase64_image = generate_quadrant_chart(\n points=points,\n title=\"My Quadrant Chart\",\n x_left=\"Low X\",\n x_right=\"High X\",\n y_bottom=\"Low Y\",\n y_top=\"High Y\",\n format=\"png\" # or \"pdf\"\n)\n```\n\n## Examples\n\nThe following examples are included in the repository:\n\n- **Simple Integration Example**: `examples/integration_example.py` - Shows how to use the library in a Python script\n- **Flask API Example**: `examples/flask_api_example.py` - RESTful API for generating charts\n- **Flask CSV App**: `examples/flask_csv_app/` - Web application with CSV input form\n\n## Integration with Web Applications\n\nThe Quadrant Generator is optimized for web applications and API integrations:\n\n### Flask Integration Example\n\n```python\n# Important: Set matplotlib backend to 'Agg' before importing any matplotlib modules\n# This is required for web applications to avoid GUI-related errors\nimport matplotlib\nmatplotlib.use('Agg')\n\nfrom flask import Flask, render_template_string\nfrom quadrant_gen.chart import csv_to_quadrant_chart\n\napp = Flask(__name__)\n\n@app.route('/')\ndef index():\n # Sample CSV data\n csv_data = \"\"\"\nname,description,x,y\nProduct A,High quality,0.2,0.8\nProduct B,Low cost,0.7,0.3\n \"\"\".strip()\n \n # Generate chart as base64 image\n base64_image = csv_to_quadrant_chart(\n csv_string=csv_data,\n title=\"Product Analysis\",\n x_left=\"Low Cost\", x_right=\"High Cost\",\n y_bottom=\"Low Value\", y_top=\"High Value\"\n )\n \n # Return HTML with embedded image\n return render_template_string(\"\"\"\n <!DOCTYPE html>\n <html>\n <head>\n <title>Quadrant Chart Example</title>\n </head>\n <body>\n <h1>Product Analysis</h1>\n <img src=\"{{ chart }}\" alt=\"Quadrant Chart\">\n </body>\n </html>\n \"\"\", chart=base64_image)\n\nif __name__ == '__main__':\n app.run(debug=True)\n```\n\n> **Note:** When using Matplotlib in web applications, you must set the backend to a non-interactive one like 'Agg' before importing any Matplotlib modules. This prevents GUI-related errors, especially on macOS where GUI operations must be on the main thread.\n\nSee the complete Flask integration example in `examples/flask_api_example.py`.\n\n### Flask CSV Web Application\n\nThe repository includes a complete web application for generating quadrant charts from CSV data:\n\n```bash\n# Run the Flask CSV app\ncd examples/flask_csv_app\npython app.py\n# Then open http://127.0.0.1:5001/ in your browser\n```\n\nThis application provides:\n- A form for entering CSV data\n- Options to customize chart title and axis labels\n- Preview of the generated chart\n- Download options for PNG or PDF formats\n\nSee `examples/flask_csv_app/` for the complete application.\n\n### API Integration\n\nThe library is perfect for API services that need to generate charts on-the-fly:\n\n```python\n# In a FastAPI application\nfrom fastapi import FastAPI, Response\nfrom pydantic import BaseModel\nfrom quadrant_gen.chart import csv_to_quadrant_chart\n\napp = FastAPI()\n\nclass ChartRequest(BaseModel):\n csv_data: str\n title: str = \"Quadrant Chart\"\n x_left: str = \"Low X\"\n x_right: str = \"High X\"\n y_bottom: str = \"Low Y\"\n y_top: str = \"High Y\"\n\n@app.post(\"/generate-chart/\")\nasync def generate_chart(request: ChartRequest):\n # Generate base64 image\n base64_image = csv_to_quadrant_chart(\n csv_string=request.csv_data,\n title=request.title,\n x_left=request.x_left,\n x_right=request.x_right,\n y_bottom=request.y_bottom,\n y_top=request.y_top\n )\n \n # Return JSON with the base64 image\n return {\"chart_data\": base64_image}\n```\n\n### Output Formats\n\nThe library generates base64-encoded images in two formats:\n\n- **PNG**: Web-friendly format for digital display\n- **PDF**: Vector format for high-quality printing and scaling\n\n## Contributing\n\n### For Developers\n\nIf you're a developer looking to contribute or maintain this package:\n\n- See [PUBLISHING.md](PUBLISHING.md) for instructions on how to build and publish new versions to PyPI\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "A library for creating quadrant charts with base64 output",
"version": "0.2.0",
"project_urls": {
"Bug Reports": "https://github.com/ceccode/quadrant-gen/issues",
"Homepage": "https://github.com/ceccode/quadrant-gen",
"Source": "https://github.com/ceccode/quadrant-gen"
},
"split_keywords": [
"quadrant",
" chart",
" visualization",
" matplotlib",
" csv"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "150838ede2369056ceb0ed1bb6a39df165221f07ffa0a5c0054be04eb8d8a512",
"md5": "2175c25390cc60bb5e638dfdba64471d",
"sha256": "9f00035acbe21addea62885afa983656b17951d0a06c085e32637960e2402243"
},
"downloads": -1,
"filename": "quadrant_gen-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2175c25390cc60bb5e638dfdba64471d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6310,
"upload_time": "2025-08-31T23:28:26",
"upload_time_iso_8601": "2025-08-31T23:28:26.779309Z",
"url": "https://files.pythonhosted.org/packages/15/08/38ede2369056ceb0ed1bb6a39df165221f07ffa0a5c0054be04eb8d8a512/quadrant_gen-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5ccf7fd84d55db1085b499a91526e849727ffaa0a64b5c2521c1d19370f1177d",
"md5": "6f14320c86f657c1c58336d38a33f1d9",
"sha256": "3af95ff3e400c26c07168ac9f4863b40305971a1ec3a2cc21cc5796448217e5e"
},
"downloads": -1,
"filename": "quadrant_gen-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "6f14320c86f657c1c58336d38a33f1d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6208,
"upload_time": "2025-08-31T23:28:27",
"upload_time_iso_8601": "2025-08-31T23:28:27.781425Z",
"url": "https://files.pythonhosted.org/packages/5c/cf/7fd84d55db1085b499a91526e849727ffaa0a64b5c2521c1d19370f1177d/quadrant_gen-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 23:28:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ceccode",
"github_project": "quadrant-gen",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.20.0"
]
]
}
],
"lcname": "quadrant-gen"
}
JSON
