FAQ
I've been looking at the docstrings of the built-in types, and I found
the docstring for dict.update() really hard to understand.
update(...)
D.update(E, **F) -> None. Update D from E and F: for k in E: D[k] = E[k]
(if E has keys else: for (k, v) in E: D[k] = v) then: for k in F: D[k] = F[k]
The parenthetical 'if E has keys' is the most unreadable part; it's
actually referring to the keys() method.

My proposed rewrite (as formatted by pydoc):
update(...)
D.update(E, **F) -> None. Update D from dict/iterable E and F.
If E has a .keys() method, does: for k in E: D[k] = E[k]
If E lacks .keys() method, does: for (k, v) in E: D[k] = v
In either case, this is followed by: for k in F: D[k] = F[k]
Does this seem clear, or should it be expanded more? dict.update is
pretty complicated!

--amk

Search Discussions

  • Aahz at Oct 4, 2008 at 3:23 am

    On Fri, Oct 03, 2008, A.M. Kuchling wrote:
    I've been looking at the docstrings of the built-in types, and I found
    the docstring for dict.update() really hard to understand.
    update(...)
    D.update(E, **F) -> None. Update D from E and F: for k in E: D[k] = E[k]
    (if E has keys else: for (k, v) in E: D[k] = v) then: for k in F: D[k] = F[k]
    The parenthetical 'if E has keys' is the most unreadable part; it's
    actually referring to the keys() method.

    My proposed rewrite (as formatted by pydoc):
    update(...)
    D.update(E, **F) -> None. Update D from dict/iterable E and F.
    If E has a .keys() method, does: for k in E: D[k] = E[k]
    If E lacks .keys() method, does: for (k, v) in E: D[k] = v
    In either case, this is followed by: for k in F: D[k] = F[k]
    Does this seem clear, or should it be expanded more? dict.update is
    pretty complicated!
    The docstring should only be a reminder, not a complete set of docs;
    given a person who once understood what d.update() does and how it
    works, your proposed rewrite seems to me more than sufficient.
    --
    Aahz (aahz at pythoncraft.com) <*> http://www.pythoncraft.com/

    "...if I were on life-support, I'd rather have it run by a Gameboy than a
    Windows box." --Cliff Wells, comp.lang.python, 3/13/2002
  • Georg Brandl at Oct 4, 2008 at 8:18 am

    Aahz schrieb:
    On Fri, Oct 03, 2008, A.M. Kuchling wrote:

    I've been looking at the docstrings of the built-in types, and I found
    the docstring for dict.update() really hard to understand.
    update(...)
    D.update(E, **F) -> None. Update D from E and F: for k in E: D[k] = E[k]
    (if E has keys else: for (k, v) in E: D[k] = v) then: for k in F: D[k] = F[k]
    The parenthetical 'if E has keys' is the most unreadable part; it's
    actually referring to the keys() method.

    My proposed rewrite (as formatted by pydoc):
    update(...)
    D.update(E, **F) -> None. Update D from dict/iterable E and F.
    If E has a .keys() method, does: for k in E: D[k] = E[k]
    If E lacks .keys() method, does: for (k, v) in E: D[k] = v
    In either case, this is followed by: for k in F: D[k] = F[k]
    Does this seem clear, or should it be expanded more? dict.update is
    pretty complicated!
    The docstring should only be a reminder, not a complete set of docs;
    given a person who once understood what d.update() does and how it
    works, your proposed rewrite seems to me more than sufficient.
    I agree.

    Georg

    --
    Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
    Four shall be the number of spaces thou shalt indent, and the number of thy
    indenting shall be four. Eight shalt thou not indent, nor either indent thou
    two, excepting that thou then proceed to four. Tabs are right out.

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupdoc-sig @
categoriespython
postedOct 4, '08 at 1:16a
activeOct 4, '08 at 8:18a
posts3
users3
websitepython.org

People

Translate

site design / logo © 2018 Grokbase