MatplotLibAPI 3.3.0__tar.gz → 4.0.0__tar.gz

matplotlibapi-4.0.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

matplotlibapi-4.0.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: Python CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Run docstring style checks
+        run: pydocstyle src
+
+
+      - name: Set Black target version
+        id: black_version
+        run: echo "BLACK_TARGET_VERSION=py${PYTHON_VERSION//./}" >> $GITHUB_ENV
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+
+      - name: Format check with black
+        run: black --check . --target-version=$BLACK_TARGET_VERSION
+
+      - name: Type check with pyright
+        run: pyright src

{matplotlibapi-3.3.0 → matplotlibapi-4.0.0}/.github/workflows/python-publish.yml

@@ -21,9 +21,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v4
       with:
         python-version: '3.x'
     - name: Install dependencies
@@ -33,7 +33,6 @@ jobs:
     - name: Build package
       run: python -m build
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}

matplotlibapi-4.0.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.3.0
+    hooks:
+      - id: black
+        language_version: python3
+
+  - repo: https://github.com/PyCQA/pydocstyle
+    rev: 6.3.0
+    hooks:
+      - id: pydocstyle
+        name: pydocstyle
+        entry: pydocstyle
+        language: system
+        types: [python]
+
+  - repo: https://github.com/pre-commit/mirrors-pyright
+    rev: v1.1.350
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: pyright
+        language: node
+        types: [python]
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest -q --cov=MatplotLibAPI --cov-report=term-missing --cov-fail-under=70
+        language: system
+        types: [python]
+        pass_filenames: false

{matplotlibapi-3.3.0 → matplotlibapi-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MatplotLibAPI
-Version: 3.3.0
+Version: 4.0.0
 License-File: LICENSE
 Requires-Python: >=3.8
 Requires-Dist: kaleido
@@ -21,6 +21,8 @@ Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest-pydocstyle; extra == 'dev'
 Requires-Dist: tomli; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # MatplotLibAPI
@@ -47,23 +49,98 @@ This will create a `data` directory with CSV files for each plot type.
 
 ## Usage
 
-Here's a simple example of how to create a bubble chart using MatplotLibAPI with a sample CSV file:
+Here's a simple example of how to create a bubble chart using the object-based API with a sample CSV file:
 
 ```python
 import pandas as pd
 import matplotlib.pyplot as plt
-from MatplotLibAPI import fplot_bubble
+from MatplotLibAPI.bubble import Bubble
 
 # Load the sample data
 df = pd.read_csv('data/bubble.csv')
 
-# Generate the bubble chart
-fig = fplot_bubble(df, label='country', x='gdp_per_capita', y='population', z='population', title='Country Statistics')
+# Build and render the bubble chart
+fig = Bubble(
+    pd_df=df,
+    label='country',
+    x='gdp_per_capita',
+    y='population',
+    z='population',
+).fplot(title='Country Statistics')
 
 # Display the plot
 plt.show()
 ```
 
+
+## MCP Integration
+
+You can run a dedicated MCP server that exposes MatplotLibAPI plotting tools for LLM agents.
+
+1. Install MCP dependencies:
+
+```bash
+pip install -e .[mcp]
+```
+
+2. Start the MCP server over stdio:
+
+```bash
+matplotlibapi-mcp
+```
+
+### Tool surface
+
+The MCP server provides these tools:
+
+- `plot_bubble`: dedicated bubble-chart rendering.
+- `plot_network`: dedicated network-chart rendering.
+- `plot_module`: generic module renderer for `bar`, `histogram`, `box_violin`, `heatmap`, `correlation_matrix`, `area`, `pie`, `waffle`, `sankey`, `table`, `timeserie`, `wordcloud`, `treemap`, and `sunburst`.
+- Explicit module endpoints such as `plot_bar`, `plot_heatmap`, `plot_sankey`, `plot_treemap`, and others for direct LLM tool selection with no module-dispatch step.
+- `describe_plot_modules`: discoverability endpoint that returns supported modules, shared input contract, parameter hints, and dedicated-tool mapping.
+
+All rendering tools accept either:
+
+- `csv_path`: filesystem path to a CSV file, or
+- `table`: in-memory records (`list[dict]`).
+
+All rendering tools return PNG bytes (octet payload) for downstream transport.
+
+For LLM orchestration, explicit endpoints are generally easier to select and ground (for example `plot_heatmap` rather than `plot_module` + `plot_module="heatmap"`). Keep `plot_module` for dynamic clients that need one generic surface.
+
+### Discoverability-first workflow
+
+For dynamic clients and agent exploration, use this sequence:
+
+1. Call `describe_plot_modules`.
+2. Select a module from `supported_plot_modules`.
+3. Read recommended keys from `parameter_hints[module_name]`.
+4. Call `plot_module` with `params` + `csv_path` or `table`.
+
+If a module key is invalid, `plot_module` returns a clear error with supported values.
+
+### Example generic call
+
+Example payload for `plot_module` with in-memory table records:
+
+```json
+{
+  "plot_module": "heatmap",
+  "table": [
+    {"month": "Jan", "channel": "Email", "engagements": 120},
+    {"month": "Jan", "channel": "Social", "engagements": 200}
+  ],
+  "params": {
+    "x": "month",
+    "y": "channel",
+    "value": "engagements",
+    "title": "Engagement Heatmap"
+  }
+}
+```
+
+The package exposes a single MCP entry point: `matplotlibapi-mcp`.
+
 ## Plot Types
 
 The library supports the following plot types:
@@ -92,10 +169,16 @@ This repository includes a `data` directory with sample CSV files for each plot
 
 ```python
 import pandas as pd
-from MatplotLibAPI import fplot_bubble
+from MatplotLibAPI.bubble import Bubble
 
 df = pd.read_csv('data/bubble.csv')
-fig = fplot_bubble(df, label='country', x='gdp_per_capita', y='life_expectancy', z='population')
+fig = Bubble(
+    pd_df=df,
+    label='country',
+    x='gdp_per_capita',
+    y='life_expectancy',
+    z='population',
+).fplot()
 fig.show()
 ```
 
@@ -103,10 +186,16 @@ fig.show()
 
 ```python
 import pandas as pd
-from MatplotLibAPI import fplot_network
+from MatplotLibAPI.network import NetworkGraph
 
 df = pd.read_csv('data/network.csv')
-fig = fplot_network(df)
+graph = NetworkGraph.from_pandas_edgelist(
+    df,
+    source='city_a',
+    target='city_b',
+    edge_weight_col='distance_km',
+)
+fig = graph.fplot(title='City Network', edge_weight_col='distance_km')
 fig.show()
 ```
 

{matplotlibapi-3.3.0 → matplotlibapi-4.0.0}/README.md

@@ -22,23 +22,98 @@ This will create a `data` directory with CSV files for each plot type.
 
 ## Usage
 
-Here's a simple example of how to create a bubble chart using MatplotLibAPI with a sample CSV file:
+Here's a simple example of how to create a bubble chart using the object-based API with a sample CSV file:
 
 ```python
 import pandas as pd
 import matplotlib.pyplot as plt
-from MatplotLibAPI import fplot_bubble
+from MatplotLibAPI.bubble import Bubble
 
 # Load the sample data
 df = pd.read_csv('data/bubble.csv')
 
-# Generate the bubble chart
-fig = fplot_bubble(df, label='country', x='gdp_per_capita', y='population', z='population', title='Country Statistics')
+# Build and render the bubble chart
+fig = Bubble(
+    pd_df=df,
+    label='country',
+    x='gdp_per_capita',
+    y='population',
+    z='population',
+).fplot(title='Country Statistics')
 
 # Display the plot
 plt.show()
 ```
 
+
+## MCP Integration
+
+You can run a dedicated MCP server that exposes MatplotLibAPI plotting tools for LLM agents.
+
+1. Install MCP dependencies:
+
+```bash
+pip install -e .[mcp]
+```
+
+2. Start the MCP server over stdio:
+
+```bash
+matplotlibapi-mcp
+```
+
+### Tool surface
+
+The MCP server provides these tools:
+
+- `plot_bubble`: dedicated bubble-chart rendering.
+- `plot_network`: dedicated network-chart rendering.
+- `plot_module`: generic module renderer for `bar`, `histogram`, `box_violin`, `heatmap`, `correlation_matrix`, `area`, `pie`, `waffle`, `sankey`, `table`, `timeserie`, `wordcloud`, `treemap`, and `sunburst`.
+- Explicit module endpoints such as `plot_bar`, `plot_heatmap`, `plot_sankey`, `plot_treemap`, and others for direct LLM tool selection with no module-dispatch step.
+- `describe_plot_modules`: discoverability endpoint that returns supported modules, shared input contract, parameter hints, and dedicated-tool mapping.
+
+All rendering tools accept either:
+
+- `csv_path`: filesystem path to a CSV file, or
+- `table`: in-memory records (`list[dict]`).
+
+All rendering tools return PNG bytes (octet payload) for downstream transport.
+
+For LLM orchestration, explicit endpoints are generally easier to select and ground (for example `plot_heatmap` rather than `plot_module` + `plot_module="heatmap"`). Keep `plot_module` for dynamic clients that need one generic surface.
+
+### Discoverability-first workflow
+
+For dynamic clients and agent exploration, use this sequence:
+
+1. Call `describe_plot_modules`.
+2. Select a module from `supported_plot_modules`.
+3. Read recommended keys from `parameter_hints[module_name]`.
+4. Call `plot_module` with `params` + `csv_path` or `table`.
+
+If a module key is invalid, `plot_module` returns a clear error with supported values.
+
+### Example generic call
+
+Example payload for `plot_module` with in-memory table records:
+
+```json
+{
+  "plot_module": "heatmap",
+  "table": [
+    {"month": "Jan", "channel": "Email", "engagements": 120},
+    {"month": "Jan", "channel": "Social", "engagements": 200}
+  ],
+  "params": {
+    "x": "month",
+    "y": "channel",
+    "value": "engagements",
+    "title": "Engagement Heatmap"
+  }
+}
+```
+
+The package exposes a single MCP entry point: `matplotlibapi-mcp`.
+
 ## Plot Types
 
 The library supports the following plot types:
@@ -67,10 +142,16 @@ This repository includes a `data` directory with sample CSV files for each plot
 
 ```python
 import pandas as pd
-from MatplotLibAPI import fplot_bubble
+from MatplotLibAPI.bubble import Bubble
 
 df = pd.read_csv('data/bubble.csv')
-fig = fplot_bubble(df, label='country', x='gdp_per_capita', y='life_expectancy', z='population')
+fig = Bubble(
+    pd_df=df,
+    label='country',
+    x='gdp_per_capita',
+    y='life_expectancy',
+    z='population',
+).fplot()
 fig.show()
 ```
 
@@ -78,10 +159,16 @@ fig.show()
 
 ```python
 import pandas as pd
-from MatplotLibAPI import fplot_network
+from MatplotLibAPI.network import NetworkGraph
 
 df = pd.read_csv('data/network.csv')
-fig = fplot_network(df)
+graph = NetworkGraph.from_pandas_edgelist(
+    df,
+    source='city_a',
+    target='city_b',
+    edge_weight_col='distance_km',
+)
+fig = graph.fplot(title='City Network', edge_weight_col='distance_km')
 fig.show()
 ```
 

matplotlibapi-4.0.0/examples/__init__.py

@@ -0,0 +1,9 @@
+"""Global example fixtures and configuration."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Ensure the src directory is on the Python path for src layout
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))

matplotlibapi-4.0.0/examples/network.py

@@ -0,0 +1,41 @@
+"""
+Example module for network graph sample data generation and plotting.
+
+This module provides functions to generate and plot sample network data for testing.
+"""
+
+import sys
+from pathlib import Path
+from matplotlib.figure import Figure
+import pandas as pd
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+
+def generate_sample_network_data() -> pd.DataFrame:
+    """Generate and save sample data for a network graph."""
+    data = {
+        "city_a": ["New York", "London", "Tokyo", "Sydney", "New York"],
+        "city_b": ["London", "Tokyo", "Sydney", "New York", "Tokyo"],
+        "distance_km": [5585, 9562, 7824, 16027, 10850],
+    }
+    df = pd.DataFrame(data)
+    return df
+
+
+def plot_sample_network_data() -> Figure:
+    """Load a sample DataFrame for testing."""
+    from MatplotLibAPI.network import NetworkGraph
+
+    pd_df = generate_sample_network_data()
+    graph = NetworkGraph.from_pandas_edgelist(
+        pd_df, source="city_a", target="city_b", edge_weight_col="distance_km"
+    )
+    plot_fig = graph.fplot(title="Network Graph")
+
+    return plot_fig
+
+
+if __name__ == "__main__":
+    plot_fig = plot_sample_network_data()
+    plot_fig.show()

{matplotlibapi-3.3.0 → matplotlibapi-4.0.0}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 [project]
 name = "MatplotLibAPI"
-version = "3.3.0"
+version = "4.0.0"
 readme = "README.md"
 requires-python = ">=3.8"
 dependencies = [
@@ -29,6 +29,21 @@ dev = [
     "pytest-cov",
     "tomli",
 ]
+mcp = [
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+matplotlibapi-mcp = "MatplotLibAPI.mcp_server:main"
+
 
 [tool.hatch.build.targets.wheel]
-packages = ["MatplotLibAPI"]
+packages = ["src/MatplotLibAPI"]
+
+[tool.pyright]
+extraPaths = ["src"]
+
+[tool.pydocstyle]
+convention = "numpy"
+
+[tool.pytest.ini_options]

matplotlibapi-4.0.0/scripts/pre_commit.sh

@@ -0,0 +1,71 @@
+#!/bin/bash
+
+# Script to run all CI checks locally before committing
+# This ensures your changes will pass the automated checks in the CI pipeline
+
+set -e  # Exit on first error
+
+echo "=========================================="
+echo "Running CI Checks"
+echo "=========================================="
+echo ""
+
+# Change to project root directory
+cd "$(git rev-parse --show-toplevel)"
+
+# Track overall status
+FAILED=0
+
+pip install --upgrade pip
+pip install --upgrade -e ".[dev]"
+
+# Style Checks
+echo "▶ Running pydocstyle..."
+if pydocstyle src; then
+    echo "✓ pydocstyle passed"
+else
+    echo "✗ pydocstyle failed"
+    FAILED=1
+fi
+echo ""
+
+echo "▶ Running black..."
+if black .; then
+    echo "✓ black passed"
+else
+    echo "✗ black failed"
+    FAILED=1
+fi
+echo ""
+
+# Static Type Analysis
+echo "▶ Running pyright..."
+if pyright src; then
+    echo "✓ pyright passed"
+else
+    echo "✗ pyright failed"
+    FAILED=1
+fi
+echo ""
+
+# Unit Tests and Coverage
+echo "▶ Running pytest with coverage..."
+if pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70; then
+    echo "✓ pytest passed"
+else
+    echo "✗ pytest failed"
+    FAILED=1
+fi
+echo ""
+
+# Summary
+echo "=========================================="
+if [ $FAILED -eq 0 ]; then
+    echo "✓ All CI checks passed!"
+    echo "=========================================="
+    exit 0
+else
+    echo "✗ Some CI checks failed"
+    echo "=========================================="
+    exit 1
+fi

matplotlibapi-4.0.0/src/MatplotLibAPI/__init__.py

@@ -0,0 +1,7 @@
+"""Public API and pandas accessor for MatplotLibAPI."""
+
+from . import accessor as _accessor  # noqa: F401
+from .base_plot import BasePlot
+from .bubble import Bubble
+
+__all__ = ["BasePlot", "Bubble"]