Skip to content

[MNT]: Clarify the difference between Artist.set and Artist.update #30957

Closed

Description

@timhoffm

Summary

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.

Activity

  1. sanrishi commented on Jan 13, 2026

    @sanrishi
    Contributor

    @timhoffm Is anyone working on it,
    May I go for it ?

  2. timhoffm commented on Jan 13, 2026

    @timhoffm
    MemberAuthor

    You are welcome to investigate.

  3. anntzer commented on Jan 15, 2026

    @anntzer
    Contributor

    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.

  4. rcomer commented on Jan 17, 2026

    @rcomer
    Member

    I guess update can save the user some nanoseconds if they're really worried about speed (with Python 3.13.11)

    In [1]: def foo(**kwargs):
       ...:     pass
       ...: 
    
    In [2]: def bar(my_dict):
       ...:     pass
       ...: 
    
    In [3]: d = {'x': 4, 'y':7}
    
    In [4]: %timeit foo(**d)
    149 ns ± 0.823 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)
    
    In [5]: %timeit bar(d)
    26.5 ns ± 0.382 ns per loop (mean ± std. dev. of 7 runs, 10,000,000 loops each)
  5. timhoffm commented on Jan 17, 2026

    @timhoffm
    MemberAuthor

    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()

    In [10]: %timeit line.set(linewidth=5)
    
    17.8 μs ± 267 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
    
    In [11]: %timeit line.update({'linewidth': 1})
    12.1 μs ± 133 ns per loop (mean ± std. dev. of 7 runs, 100,000 loops each)
    
    In [12]: %timeit line.set_linewidth(5)
    1.35 μs ± 10.6 ns per loop (mean ± std. dev. of 7 runs, 1,000,000 loops each)

    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.

  6. sanrishi commented on Jan 17, 2026

    @sanrishi
    Contributor

    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.

  7. timhoffm commented on Jan 17, 2026

    @timhoffm
    MemberAuthor

    even though fig.set(lw=1) works fine because of the normalization.

    That is not true. Figure currently has no lw alias. Neither fig.set(lw=1) nor fig.set_lw(1) work.

  8. timhoffm commented on Jan 18, 2026

    @timhoffm
    MemberAuthor

    We first have to become clear what we want: #30979 (comment)

  9. sanrishi commented on Jan 18, 2026

    @sanrishi
    Contributor

    @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.

  10. timhoffm commented on Jan 18, 2026

    @timhoffm
    MemberAuthor

    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.

  11. sanrishi commented on Jan 19, 2026

    @sanrishi
    Contributor

    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

  12. timhoffm commented on Jan 19, 2026

    @timhoffm
    MemberAuthor

    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.

  13. timhoffm commented on Feb 2, 2026

    @timhoffm
    MemberAuthor

    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).

  14. added this to the v3.11.0 milestone on Feb 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions