You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Doc]: Better document Axes.transData and other transXYZ attributes #25220
Alternative: Turn the trans* attributes into properties. They can be documented properly and have the advantage of being read-only. This is a slight performance cost, but should be negligible compared to any action involving the transforms.
That pattern would work but feels a bit contrived. The class attributes are None and exist only for the purpose of documentation. Upon instance initialization they are immediately shadowed by instance attributes.
I'm leaning towards turning these into properties, because they are read-only.
Better docs for the transforms would be great but fwiw I’m fairly certain the insights page counts all searches and then labels them with the most recent search, rather than showing the count for a specific query.
Properties probably make sense, especially if we want setting to be private behavior...
In the alternative, I do think that if we want to go the "class attribute" route, I'm not super happy with = None, as that introduces a different type that is not actually valid for any instance. Pep 526 allows a pure declaration (without initialization, but you have to put the type hint in... This is slightly odd in a setting where the actual type hints are in a parallel file, but it should work:
This is a declaration that transData will exist and have type Transform, but I don't have an initial value yet (it will still actually give AttributeError if accessed before it is initialized)
I do think that all of the transXYZ transforms from that method should be documented, not onlytransData, as well.
changed the title [-][Doc]: Better document Axes.transData[/-][+][Doc]: Better document Axes.transData and other transXYZ attributes[/+]on May 19, 2023
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
Minimal documentation should be added docs to type annotations in AxesBase, like we do for dataLim and spines (note: viewLim is different as it's not an attribute but actually a lazily computed quantity via a property; but for simple attributes we don't want to property overhead just for docs purpose).
Activity
tacaswell commentedon Feb 15, 2023
I think using a pattern like in #25187 to document class attributes (defaulting to
None) might work as well?timhoffm commentedon Feb 15, 2023
That pattern would work but feels a bit contrived. The class attributes are None and exist only for the purpose of documentation. Upon instance initialization they are immediately shadowed by instance attributes.
I'm leaning towards turning these into properties, because they are read-only.
mwaskom commentedon Feb 17, 2023
Better docs for the transforms would be great but fwiw I’m fairly certain the insights page counts all searches and then labels them with the most recent search, rather than showing the count for a specific query.
AnanasClassic commentedon Mar 30, 2023
I would like to take up this issue
ksunden commentedon May 19, 2023
Properties probably make sense, especially if we want setting to be private behavior...
In the alternative, I do think that if we want to go the "class attribute" route, I'm not super happy with
= None, as that introduces a different type that is not actually valid for any instance. Pep 526 allows a pure declaration (without initialization, but you have to put the type hint in... This is slightly odd in a setting where the actual type hints are in a parallel file, but it should work:This is a declaration that
transDatawill exist and have typeTransform, but I don't have an initial value yet (it will still actually giveAttributeErrorif accessed before it is initialized)I do think that all of the
transXYZtransforms from that method should be documented, not onlytransData, as well.AnanasClassic commentedon May 19, 2023
maybe it is acceptable to initialize transData some default Transform-object ?
AnanasClassic commentedon May 19, 2023
I think in order to document all the attributes, we need to create a new issue
[-][Doc]: Better document Axes.transData[/-][+][Doc]: Better document Axes.transData and other transXYZ attributes[/+]tacaswell commentedon May 19, 2023
I have updated this issue to cover all the transfrom attributes.
AnanasClassic commentedon May 21, 2023
Do you have any ideas how to document this?
I think I can write something like
But I'm afraid that in this case the clarity of the documentation will suffer
Or I can initialize transXYZ with default values (I don't quite understand what values to initialize them with)
timhoffm commentedon May 21, 2023
You should make the current attribute private
self._transDataand use the original name as a read-only accessorMerge branch 'matplotlib:main' into matplotlib#25220
github-actions commentedon Jul 6, 2026
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
timhoffm commentedon Jul 6, 2026
Minimal documentation should be added docs to type annotations in
AxesBase, like we do fordataLimandspines(note:viewLimis different as it's not an attribute but actually a lazily computed quantity via a property; but for simple attributes we don't want to property overhead just for docs purpose).I will take care of this.
DOC: Document ax.transData and ax.transAxes (matplotlib#32013)