# Conversation a1ae9151a152528b0

- Source: `claude`
- User: `pascal`
- System: `Pascals-MBP.local`
- Started: `2026-02-24T17:30:42.508Z`
- CWD: `/Users/pascal/Code/business/convx`

## User

_`2026-02-24T17:30:42.508Z`_

In the Python environment at /Users/pascal/Code/business/convx, find the plotext package source (likely in .venv or uv cache). Find the stacked_bar function definition and report its exact signature/parameters. Also check if there's any way to add per-segment labels/legend to stacked_bar calls.

Run: uv run python -c "import plotext; import inspect; print(inspect.signature(plotext.stacked_bar))"

Also check if plotext has a `legend` function or any way to manually add legend entries.

## Agent

_`2026-02-24T17:30:43.755Z`_

I'll help you find the plotext package source and examine the stacked_bar function. Let me start by running the inspection command and then locate the actual source code.

## Agent

_`2026-02-24T17:30:45.953Z`_

Let me try a different approach - checking the uv.lock file and then examining the local environment:

## Agent

_`2026-02-24T17:30:48.073Z`_

Good! Now let me examine the plotext source code directly from the installed location:

## Agent

_`2026-02-24T17:30:50.631Z`_

Perfect! Now let me find and examine the actual source code files:

## Agent

_`2026-02-24T17:30:52.693Z`_

Now let me look at the _core.py file where stacked_bar is defined:

## Agent

_`2026-02-24T17:30:54.964Z`_

Let me read the stacked_bar function and search for legend-related functionality:

## Agent

_`2026-02-24T17:30:56.998Z`_

Let me search more comprehensively for legend functionality:

## Agent

_`2026-02-24T17:30:59.164Z`_

Excellent! Now let me look at the _build.py file to see how the legend is actually rendered:

## Agent

_`2026-02-24T17:31:01.734Z`_

Perfect! Now let me check what all functions are exported from _core.py to see if there's a legend function:

## Agent

_`2026-02-24T17:31:04.389Z`_

Let me now look at the actual figure class to understand how stacked_bar works internally:

## Agent

_`2026-02-24T17:31:06.694Z`_

Now let me read the stacked_bar implementation in the figure class:

## Agent

_`2026-02-24T17:31:08.313Z`_

Now let me search for the draw_stacked_bar method in the monitor class:

## Agent

_`2026-02-24T17:31:10.323Z`_

Let me read the draw_stacked_bar method:

## Agent

_`2026-02-24T17:31:12.212Z`_

Perfect! Now let me create a comprehensive summary by also checking the actual implementation details of what the `labels` parameter does. Let me verify everything I've found:

## Agent

_`2026-02-24T17:31:15.112Z`_

Let me fix that:

## Agent

_`2026-02-24T17:31:29.934Z`_

Perfect! Now let me compile all the key information I've gathered into a comprehensive report:

## Report: plotext stacked_bar Function Analysis

### Exact Function Signature

**Location:** `/Users/pascal/Code/business/convx/.venv/lib/python3.12/site-packages/plotext/_core.py` (line 207)

**Signature:**
```python
plotext.stacked_bar(*args, marker=None, color=None, fill=None, width=None, orientation=None, minimum=None, reset_ticks=None, xside=None, yside=None, labels=None)
```

### Parameter Details

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `*args` | variadic | required | The coordinates x and Y (or just Y), where Y is a list of lists. Each inner list contains the bar heights for a bar segment |
| `marker` | string or list | None | Marker used to identify bars (single character or marker codes). List of markers (same length as Y) to set marker per segment |
| `color` | list | None | List of colors (same length as Y) to identify each bar segment. Accepts color codes, integers (0-255), or RGB tuples |
| `fill` | boolean | True | If True, bars are filled with colored markers; otherwise only borders are printed |
| `width` | float | 0.8 | Relative width of bars (0 to 1) |
| `orientation` | string | 'vertical' | Either 'vertical'/'v' or 'horizontal'/'h' |
| `minimum` | number | 0 | Minimum value of all bars |
| `reset_ticks` | boolean | True | If True, center coordinates at bar base are calculated and printed automatically |
| `xside` | string/int | 'lower' | Address 'lower'/'upper' x axis (or 1/2) |
| `yside` | string/int | 'left' | Address 'left'/'right' y axis (or 1/2) |
| `labels` | list of strings | None | **List of labels (one per bar segment), which appear in the legend menu at the top left corner** |

### Legend Support

**Yes, stacked_bar DOES support per-segment labels!**

The `labels` parameter is explicitly designed for this purpose. From the help text:
> "The list of labels, one for each bar plot (with same length as Y), which will appear in the legend menu at the top left corner of the plot canvas."

### How It Works

1. **Labels Parameter:** Pass a list of strings with the same length as the number of segments (length of Y)
2. **Automatic Legend Rendering:** The legend is automatically rendered at the top left corner when:
   - The canvas is wide enough (`width_canvas >= S + 3 + L`)
   - The canvas is tall enough (`height_canvas >= len(labels)`)
   - Where S = space for side symbols (if needed), L = max label length
3. **Legend Components:**
   - Side symbols (showing which axes are used: L, Γ, ⅃, ⅂)
   - Marker representation (3 characters of each marker)
   - Colored marker display (using the `color` parameter colors)
   - Label text

### Legend-Only Functions

**There is NO standalone `legend()` function in plotext.** Legends are managed through:
- The `labels` parameter (for stacked_bar, multiple_bar, etc.)
- The `label` parameter (for individual plot functions like scatter, plot, bar, etc.)
- The `label=None` parameter in functions that support automatic legend insertion

### Usage Example

```python
import plotext as plt

# Data with 3 segments per bar
x = [1, 2, 3]
Y = [[1, 2, 3],    # Segment 1
     [2, 1, 4],    # Segment 2
     [1, 3, 2]]    # Segment 3

# Create stacked bar with per-segment labels
plt.stacked_bar(x, Y, 
    labels=['Segment A', 'Segment B', 'Segment C'],
    color=['red', 'blue', 'green'],
    marker='o'
)
plt.show()
```

### Implementation Details

**Internal Implementation (from `_monitor.py` line 464-482):**
- `stacked_bar()` internally calls `draw_bar()` multiple times (once per segment, in reverse order)
- Each segment is drawn with cumulative heights (using `cumsum`)
- Each call to `draw_bar()` uses `labels[i]` as the `label` parameter
- The legend is rendered at plot display time by the `build_class` in `_build.py`

**Legend Rendering (from `_build.py` lines 245-262):**
- Filters to only labeled data points (`labelled = lambda s: self.label[s] is not None`)
- Checks canvas size constraints before rendering
- Displays side symbol, marker sample, and label text for each segment

### Source Files

- **Main wrapper:** `/Users/pascal/Code/business/convx/.venv/lib/python3.12/site-packages/plotext/_core.py` (line 207)
- **Figure method:** `/Users/pascal/Code/business/convx/.venv/lib/python3.12/site-packages/plotext/_figure.py` (line 225)
- **Monitor implementation:** `/Users/pascal/Code/business/convx/.venv/lib/python3.12/site-packages/plotext/_monitor.py` (lines 464-482)
- **Legend rendering logic:** `/Users/pascal/Code/business/convx/.venv/lib/python3.12/site-packages/plotext/_build.py` (lines 245-262)
