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
[MNT]: Clarify the difference between Artist.set and Artist.update #30957
Those functions are quite similar. In #30956, I tried to relate them via
a.update(props) is equivalent to a.set(**props)
And got the the question, why we have them both.
From a quick look at the code, it seems set is doing name normalization, so I wrote
This is a slightly more efficient variant of `.Artist.set`. It's
primarily intended to be used internally and by third party
plotting libraries. End users are recommended to use the more
readable and flexible `.Artist.set`.
``a.update(props)`` is equivalent to ``a.set(**props)``, but does
not support aliases / shortcuts; e.g. you can do ``set(lw=1)`` as
a shortcut for ``set_linewidth(1)``, but you cannot do
``update({"lw": 1})``.
But turns out that is not true either. While update does not normalize, it likely will just call set_lw().
This needs more investigation.
Proposed fix
Identify whether there are any behavior differences or whether it's just the API (props vs. **props).
This possibly involves digging into the history.
Document the findings and define the scope when/whether update should still be used.
Looking at git blame both functions were introduced independently and I'm not sure there was much intended design initially, but for a while update() was important because you could pass an OrderedDict() to guarantee property order, whereas the ordering of kwargs passed to set() was getting scrambled. However this is no longer the case and I suspect update() is just an old relic that isn't really needed anymore.
That's negligiable. If time is critical, you should not use bulk update at all. set() and update() are both wrappers and iterate through their parameters to call the individual setters. Calling them individually will always be faster than set() or update()
I didn't look into the difference between set() and update() but it could be the normalization. Anyway set_linewidth() is an order of magnitude faster.
Thanks for the benchmarks! That actually makes sense and lines up with what I was seeing.
It looks like set() does property name normalization (mapping lw -> linewidth automatically), while update() seems to skip that step for speed.
That explains why line.update({'lw': 1}) worked—Line2D happens to have a real set_lw method. But fig.update({'lw': 1}) failed because Figure doesn't have that exact method, even though fig.set(lw=1) works fine because of the normalization.
I just updated the docstring to be specific about this: update skips normalization and only works if the setter method explicitly exists.
@timhoffm Reading the latest comment of yours on #30979 ('signature rewriting', 'import-time costs'), it's clear that a unified fix is a longer-term project.
That confirms the current behavioral difference between set and update isn't going away soon.
I'm marking this as Ready for Review so we can at least have the documentation match the current reality while the architecture is being debated.
Oh sorry @tim#30978 I want to say ready for review for my PR #30978
Should we wait for PR #30979 to be merged or at least have the documentation match the current reality
Let's not invest time in documentation right now since chances are high, we're revising it as part of #30979 or related follow-up actions discussed therein.
My understanding now and per #30957 (comment) is that update and set behave almost the same even though they have somewhat different code paths. The only noticable behavioral difference I'm aware of is that update will accept a property and its alias (e.g. update(linewidh=2, lw=3)) and will excute both set_s, where es set will raise.
Since set is much more useful, I propose to discourage update and recommend set as the public API. - I suspect there's enough historic code out there that uses Artist.update so that it's not worth a deprecation (e.g. in a quick check Cartopy has two usages).
Activity
sanrishi commentedon Jan 13, 2026
@timhoffm Is anyone working on it,
May I go for it ?
timhoffm commentedon Jan 13, 2026
You are welcome to investigate.
anntzer commentedon Jan 15, 2026
Looking at git blame both functions were introduced independently and I'm not sure there was much intended design initially, but for a while update() was important because you could pass an OrderedDict() to guarantee property order, whereas the ordering of kwargs passed to set() was getting scrambled. However this is no longer the case and I suspect update() is just an old relic that isn't really needed anymore.
rcomer commentedon Jan 17, 2026
I guess
updatecan save the user some nanoseconds if they're really worried about speed (with Python 3.13.11)timhoffm commentedon Jan 17, 2026
That's negligiable. If time is critical, you should not use bulk update at all.
set()andupdate()are both wrappers and iterate through their parameters to call the individual setters. Calling them individually will always be faster thanset()orupdate()I didn't look into the difference between
set()andupdate()but it could be the normalization. Anywayset_linewidth()is an order of magnitude faster.sanrishi commentedon Jan 17, 2026
Thanks for the benchmarks! That actually makes sense and lines up with what I was seeing.
It looks like set() does property name normalization (mapping lw -> linewidth automatically), while update() seems to skip that step for speed.
That explains why line.update({'lw': 1}) worked—Line2D happens to have a real set_lw method. But fig.update({'lw': 1}) failed because Figure doesn't have that exact method, even though fig.set(lw=1) works fine because of the normalization.
I just updated the docstring to be specific about this: update skips normalization and only works if the setter method explicitly exists.
timhoffm commentedon Jan 17, 2026
That is not true. Figure currently has no lw alias. Neither
fig.set(lw=1)norfig.set_lw(1)work.timhoffm commentedon Jan 18, 2026
We first have to become clear what we want: #30979 (comment)
sanrishi commentedon Jan 18, 2026
@timhoffm Reading the latest comment of yours on #30979 ('signature rewriting', 'import-time costs'), it's clear that a unified fix is a longer-term project.
That confirms the current behavioral difference between set and update isn't going away soon.
I'm marking this as Ready for Review so we can at least have the documentation match the current reality while the architecture is being debated.
timhoffm commentedon Jan 18, 2026
I'm sorry, I don't understand what you are saying. This is an issue, which cannot be marked as Ready for Review.
Also, as far as I've understood so far, three no notable behavioral difference for the user.
I don't see that we can make any reasonable improvements on the current state right now.
sanrishi commentedon Jan 19, 2026
Oh sorry @tim#30978 I want to say ready for review for my PR #30978
Should we wait for PR #30979 to be merged or at least have the documentation match the current reality
timhoffm commentedon Jan 19, 2026
Let's not invest time in documentation right now since chances are high, we're revising it as part of #30979 or related follow-up actions discussed therein.
timhoffm commentedon Feb 2, 2026
My understanding now and per #30957 (comment) is that
updateandsetbehave almost the same even though they have somewhat different code paths. The only noticable behavioral difference I'm aware of is thatupdatewill accept a property and its alias (e.g.update(linewidh=2, lw=3)) and will excute bothset_s, where essetwill raise.Since
setis much more useful, I propose to discourageupdateand recommendsetas the public API. - I suspect there's enough historic code out there that usesArtist.updateso that it's not worth a deprecation (e.g. in a quick check Cartopy has two usages).