[FEATURE]: autorangePadding

[ranjeet7980]

[FEATURE]: autorangePadding — Explicit Control and Introspection of Autorange Padding

Summary

When autorange: true is set on an axis, Plotly silently adds a padding fraction
around the data range. This padding is internally computed, never documented as a
configurable value, and impossible to query without using full_figure_for_development().
This issue proposes:

1. A new per-axis layout attribute autorangePadding to give users explicit control
   over the padding fraction
2. Exposure of the computed padding via get_computed_values() for introspection

---

Problem Statement

Autorange padding causes subtle but persistent issues in several common workflows:

Problem 1 — Multi-figure axis alignment:
Two figures sharing a conceptual x-axis (e.g. a price chart above a volume chart)
will not align perfectly even when their data ranges are identical, because autorange
applies padding independently on each figure. There is no way to force consistent
padding without disabling autorange entirely.

Problem 2 — Controlled range extension:
A user wants autorange but needs extra space on one side for an annotation or legend.
Currently this is impossible without computing the full data range manually and setting
a fixed range — defeating the purpose of autorange.

Problem 3 — Range introspection in production:
Users who need the exact rendered axis range must use full_figure_for_development(),
which is explicitly documented as not for production use. There is no lightweight
alternative.

---

Proposed Solution

1. New Layout Attribute: autorangePadding

Set per axis as a fraction of the total data range:

fig.update_layout(
    xaxis=dict(
        autorange=True,
        autorangePadding=0.05   # 5% padding each side — matches current default behavior
    ),
    yaxis=dict(
        autorange=True,
        autorangePadding=0.0    # no padding — data fills axis edge to edge
    )
)

Default value matches the current implicit behavior so all existing figures are
unaffected.

Asymmetric Padding

For cases where padding is only needed on one side:

fig.update_layout(
    yaxis=dict(
        autorange=True,
        autorangePadding=dict(before=0.0, after=0.15)  # extra headroom at top only
    )
)

before = lower end of the axis, after = upper end, regardless of axis direction.

---

2. Introspection via get_computed_values()

computed = fig.get_computed_values(include=["axis_ranges", "autorange_padding"])

Returns:

{
    "axis_ranges": {
        "xaxis": [-0.5, 10.5],
        "yaxis": [-4.35, 102.1]
    },
    "autorange_padding": {
        "xaxis": {
            "before": 0.05,
            "after": 0.05,
            "pixels": {"before": 18.4, "after": 18.4}
        },
        "yaxis": {
            "before": 0.05,
            "after": 0.05,
            "pixels": {"before": 14.2, "after": 14.2}
        }
    }
}

Both fractional and pixel values are returned, making the result useful for
data-space alignment and pixel-space layout work respectively.

---

3. Companion Utility: match_axis_ranges() (Optional)

A natural extension that syncs axis ranges across multiple figures:

import plotly.utils as pu

pu.match_axis_ranges([fig1, fig2], axis="x")

Computes the union of both figures' data ranges and applies a consistent range to both
so they align exactly — the most common use case motivating this feature.

---

Relationship to get_computed_values()

This feature is a direct extension of the get_computed_values() proposal:

• axis_ranges already proposes returning the final rendered range
• autorange_padding extends that with a breakdown of how much of the range is
  padding vs. actual data span
• autorangePadding is the write-side complement to the read-side introspection

Together they give full round-trip control: set the padding you want, then verify
exactly what was applied.

---

Prior Art

Tool	Equivalent
matplotlib	ax.margins(x=0.05) sets padding; ax.get_xlim() returns final range
Vega-Lite	Explicit "padding" property on scale definitions
D3.js	scale.nice() and direct scale.domain() control

---

Backward Compatibility

• autorangePadding is a new optional attribute. Omitting it preserves current behavior exactly.
• No existing figures, layouts, or workflows are affected unless users explicitly opt in.

---

Acceptance Criteria

• autorangePadding accepted as a per-axis layout attribute (scalar or asymmetric dict)
• Default value matches current implicit padding so existing figures are unchanged
• Computed padding values returned via get_computed_values(include=["autorange_padding"])
• Both fractional and pixel padding values included in the return
• Documented in the axis layout attribute reference
• match_axis_ranges() utility considered as a follow-up or included in scope

---

Related Issues

• Companion to: [FEATURE]: get_computed_values() ([FEATURE]: Access values calculated / derived by plotly.js as part of plotting #5552)
• Companion to: [FEATURE]: get_subplot_geometry() ([FEATURE]: get_subplot_geometry() #5554)
• Related to any issue requesting consistent axis ranges across multiple figures

---

I am happy to discuss the naming convention for autorangePadding vs autorange_padding
to match the existing attribute style guide, and whether the match_axis_ranges()
utility belongs in this issue or a separate one.

[camdecoster]

Thanks for the idea! At this time, we're not planning on implementing a autorangePadding attribute, but exposing more information is something we're open to. That work would be covered in #5552. Let's keep the discussion about accessing additional information in that issue.

[ranjeet7980]

Thanks for the clarification — that makes sense, and I appreciate the transparency about
the current roadmap.

I understand the preference to keep autorangePadding as a separate concern, and I am fully
on board with focusing the "expose more computed information" discussion in #5552.

To make sure my thoughts are useful there, I'll summarize what I'd want to contribute to
that issue specifically around autorange:

What I'd add to #5552 regarding autorange introspection:

1. The core ask — computed axis ranges — being able to retrieve the final rendered
   [min, max] for each axis in a production-safe, lightweight way. I know this is already
   part of the discussion there, but I wanted to flag it as the highest-priority item from
   my side.

2. The padding breakdown — even without a settable autorangePadding attribute, it
   would still be very useful to know how much of the rendered range is data vs. padding.
   For example:

   computed = fig.get_computed_values(include=["axis_ranges", "autorange_padding"])
   # "autorange_padding": {
   #     "xaxis": {"before": 0.05, "after": 0.05}
   # }

This is read-only introspection only — no new attribute, no write-side change — which
hopefully fits within the scope of what #5552 is trying to do.

3. Multi-figure alignment use case — the most common reason users need this information
   is to align axis ranges across two figures that share a conceptual axis (e.g. a price
   chart above a volume chart). If [FEATURE]: Access values calculated / derived by plotly.js as part of plotting #5552 exposes the final rendered range, that use case is
   already largely solved. I'll note this explicitly in that issue so the motivation is clear.

I will go ahead and add a focused comment in #5552 with these points. Thanks again for
redirecting rather than just closing — it's clear there's genuine interest in making
computed values accessible and I'm glad to contribute to that discussion.