Suggestion

This would subsume#10976: see#10961#10960 for secondary axes requests.

See#8952 for the poor state of documentation and confusing behaviour ofaxes_grid1.inset_axes.#10986,#10756

There are a few instances where it would make sense for an axes to have an axes as a child artist:

1. an inset_axes with a subsection of the data, or some other information (ala

   matplotlib/lib/mpl_toolkits/axes_grid1/inset_locator.py

   Lines 389 to 390 inadaa8e5

   	definset_axes(parent_axes,width,height,loc=1,
   	bbox_to_anchor=None,bbox_transform=None,

   )
2. a secondary scale (i.e a second x-scale at the top of the axes in a different unit).

I'd propose we create an API for these. I would expect the legend API would be fine for inset axes, and would closely follow the one already in axes_grid1. An example would be:

# inset from x=0.65 to 0.95, y=0.75 to 0.95inax=ax.inset_axes(location='upper_right',width=0.3,height=0.2,padding=0.05)# inset from x=0 to 0.25, y=0.3 to 0.7inax=ax.inset_axes(bbox_to_anchor=(0,0.3,0.25,0.4))

Secondary axes would be basically aninset_axes, except with the appropriate spines turned off:

secx=ax.extra_spine_x(location='top',convert=(lambdax:1/x))thirdx=ax.extra_spine_x(location=0.5,convert=(lambdax:1/x))secy=ax.extra_spine_y(location='right',convert=(lambday:y**2))

Implementation

I would like to have these be children of the parent axes simply for the reason that they are decorators, and should be included in the list of artists a) at draw time, and b) when the bbox for the parent axes is calculated for tools like constrained_layout and tight_layout. Also having them as children makes it possible to change the limits if the parent limits change, and avoids the messiness of twin axes, which have a peer-to-peer relationship.