MatplotLibAPI 3.2.13__tar.gz → 3.2.15__tar.gz

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

@@ -0,0 +1,43 @@
+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@v3
+
+    - 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 style checks
+      run: |
+        pydocstyle MatplotLibAPI
+        black --check .
+
+    - name: Run static type analysis
+      run: |
+        pyright MatplotLibAPI
+
+    - name: Run tests with coverage
+      run: |
+        pytest -q --cov=MatplotLibAPI --cov-report=term-missing --cov-fail-under=70

matplotlibapi-3.2.15/.github/workflows/python-publish.yml

@@ -0,0 +1,39 @@
+# This workflow will upload a Python Package using Twine when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+    - name: Build package
+      run: python -m build
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

matplotlibapi-3.2.15/.gitignore

@@ -0,0 +1,19 @@
+.DS_Store
+.vscode
+.env
+.pytest_cache
+.benchmarks
+scratch*
+data/
+# Python build artifacts
+*.egg-info/
+dist/
+build/
+
+# Python cache files
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+.coverage

matplotlibapi-3.2.15/AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md
+
+These instructions apply to any automated agent contributing to this repository.
+
+## 1. Code Style
+
+- Use standard PEP 8 formatting for all Python code.
+- Write commit messages in the imperative mood (e.g., "Add feature" not "Added feature").
+- Keep the implementation Pythonic and maintainable.
+
+## 2. Docstring Style
+
+- Document all public classes, parameters, methods, and functions.
+- Use **NumPy-style** docstrings following [PEP 257](httpshttps://peps.python.org/pep-0257/) conventions.
+- **Do not** use `:param` / `:type` syntax (reST/Sphinx style) or Google-style `Args`.
+- Always include type hints in function signatures.
+- Begin docstrings with a **short, one-line summary**, followed by a blank line and an optional extended description.
+- Use the following NumPy-style sections when applicable:
+  - `Parameters`
+  - `Returns`
+  - `Raises`
+  - `Examples`
+- **For classes, the main docstring should include a `Methods` section summarizing each public method and its one-line description.**
+- For optional parameters, note the default value in the description.
+- Use present tense and active voice (“Return…”, “Fetch…”).
+
+## 3. Code Quality and Testing
+
+Before running tests, install the development dependencies declared in `pyproject.toml`:
+
+```bash
+pip install -e .[dev]
+```
+
+To ensure your changes will pass the automated checks in our Continuous Integration (CI) pipeline, run the following commands locally before committing. All checks must pass.
+
+**Style Checks:**
+```bash
+pydocstyle MatplotLibAPI
+black --check .
+```
+
+**Static Type Analysis:**
+```bash
+pyright MatplotLibAPI
+```
+
+**Unit Tests and Coverage:**
+```bash
+pytest -q --cov=MatplotLibAPI --cov-report=term-missing --cov-fail-under=70
+```
+
+## 4. Directory Layout
+
+- Production code lives in `MatplotLibAPI/`.
+- Tests live in `tests/`.
+- Keep imports relative within the package (e.g., `from MatplotLibAPI...`).
+
+## 5. Pull Request Messages
+
+Each pull request should include:
+
+1. **Summary** – brief description of the change.
+2. **Testing** – commands run and confirmation that the tests passed.
+
+Example PR body:
+
+```
+### Summary
+- add new helper to utils.list
+- expand tests for list chunking
+
+### Testing
+- `pytest` (all tests passed)
+```
+
+## 6. General Guidelines
+
+- Avoid pushing large data files to the repository.
+- Prefer small, focused commits over sweeping changes.
+- Update or add tests whenever you modify functionality.

matplotlibapi-3.2.15/MatplotLibAPI/Area.py

@@ -0,0 +1,76 @@
+"""Area chart helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    AREA_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_area(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    label: Optional[str] = None,
+    stacked: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = AREA_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot area charts, optionally stacked for part-to-whole trends."""
+    cols = [x, y]
+    if label:
+        cols.append(label)
+    validate_dataframe(pd_df, cols=cols)
+    plot_ax = _get_axis(ax)
+
+    if label:
+        pivot_df = pd_df.pivot_table(
+            index=x, columns=label, values=y, aggfunc="sum"
+        ).sort_index()
+        pivot_df.plot(kind="area", stacked=stacked, alpha=0.7, ax=plot_ax)
+    else:
+        sorted_df = pd_df.sort_values(by=x)
+        plot_ax.fill_between(
+            sorted_df[x], sorted_df[y], color=style.font_color, alpha=0.4
+        )
+        plot_ax.plot(sorted_df[x], sorted_df[y], color=style.font_color)
+
+    plot_ax.set_xlabel(string_formatter(x))
+    plot_ax.set_ylabel(string_formatter(y))
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_area(
+    pd_df: pd.DataFrame,
+    x: str,
+    y: str,
+    label: Optional[str] = None,
+    stacked: bool = True,
+    title: Optional[str] = None,
+    style: StyleTemplate = AREA_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot area charts on a new figure."""
+    return _wrap_aplot(
+        aplot_area,
+        pd_df=pd_df,
+        figsize=figsize,
+        x=x,
+        y=y,
+        label=label,
+        stacked=stacked,
+        title=title,
+        style=style,
+    )

matplotlibapi-3.2.15/MatplotLibAPI/Bar.py

@@ -0,0 +1,79 @@
+"""Bar and stacked bar chart helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_bar(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    group: Optional[str] = None,
+    stacked: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot bar or stacked bar charts for categorical comparisons."""
+    cols = [category, value]
+    if group:
+        cols.append(group)
+    validate_dataframe(pd_df, cols=cols)
+
+    plot_ax = _get_axis(ax)
+    plot_df = pd_df.copy()
+
+    if group:
+        pivot_df = plot_df.pivot_table(
+            index=category, columns=group, values=value, aggfunc="sum"
+        )
+        pivot_df.plot(kind="bar", stacked=stacked, ax=plot_ax, alpha=0.85)
+    else:
+        sns.barplot(
+            data=plot_df, x=category, y=value, palette=style.palette, ax=plot_ax
+        )
+
+    plot_ax.set_facecolor(style.background_color)
+    plot_ax.set_xlabel(string_formatter(category))
+    plot_ax.set_ylabel(string_formatter(value))
+    if title:
+        plot_ax.set_title(title)
+    plot_ax.tick_params(axis="x", labelrotation=45)
+    return plot_ax
+
+
+def fplot_bar(
+    pd_df: pd.DataFrame,
+    category: str,
+    value: str,
+    group: Optional[str] = None,
+    stacked: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot bar or stacked bar charts on a new figure."""
+    return _wrap_aplot(
+        aplot_bar,
+        pd_df=pd_df,
+        figsize=figsize,
+        category=category,
+        value=value,
+        group=group,
+        stacked=stacked,
+        title=title,
+        style=style,
+    )

matplotlibapi-3.2.15/MatplotLibAPI/BoxViolin.py

@@ -0,0 +1,69 @@
+"""Box and violin plot helpers."""
+
+from typing import Any, Optional, Tuple
+
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+from .StyleTemplate import (
+    DISTRIBUTION_STYLE_TEMPLATE,
+    StyleTemplate,
+    string_formatter,
+    validate_dataframe,
+)
+from ._visualization_utils import _get_axis, _wrap_aplot
+
+
+def aplot_box_violin(
+    pd_df: pd.DataFrame,
+    column: str,
+    by: Optional[str] = None,
+    violin: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    ax: Optional[Axes] = None,
+    **kwargs: Any,
+) -> Axes:
+    """Plot box or violin charts to summarize distributions."""
+    cols = [column]
+    if by:
+        cols.append(by)
+    validate_dataframe(pd_df, cols=cols)
+    plot_ax = _get_axis(ax)
+
+    if violin:
+        sns.violinplot(data=pd_df, x=by, y=column, palette=style.palette, ax=plot_ax)
+    else:
+        sns.boxplot(data=pd_df, x=by, y=column, palette=style.palette, ax=plot_ax)
+
+    plot_ax.set_facecolor(style.background_color)
+    plot_ax.set_ylabel(string_formatter(column))
+    if by:
+        plot_ax.set_xlabel(string_formatter(by))
+    if title:
+        plot_ax.set_title(title)
+    return plot_ax
+
+
+def fplot_box_violin(
+    pd_df: pd.DataFrame,
+    column: str,
+    by: Optional[str] = None,
+    violin: bool = False,
+    title: Optional[str] = None,
+    style: StyleTemplate = DISTRIBUTION_STYLE_TEMPLATE,
+    figsize: Tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot box or violin charts on a new figure."""
+    return _wrap_aplot(
+        aplot_box_violin,
+        pd_df=pd_df,
+        figsize=figsize,
+        column=column,
+        by=by,
+        violin=violin,
+        title=title,
+        style=style,
+    )