6 ms·

The features of Python's help() function

155 points by danso 2y ago

ape4 2y ago
Cool idea. Do any other languages have this?
- jhbadger 2y ago
  R has probably the best help feature for any language -- not only can you ask it about help on individual functions with "?", the tradition (and this continues with most add in packages as well as builtins) is not only does it give you info on the function, it gives you example code using it so you can understand what it does in practice.
- emmelaich 2y ago
  utop for ocaml is cool, gives type signatures for functions. no explicit help, but does offer completions with tab. Similarly, rtop for reason. https://opam.ocaml.org/blog/about-utop/ https://opam.ocaml.org/blog/about-utop/ and https://opam.ocaml.org/packages/rtop/ https://opam.ocaml.org/packages/rtop/
  - reycharles 2y ago
    I wrote a small thing for adding a `#doc List.find` directive. However, I don't maintain it anymore since I think it doesn't see much use and it's work to keep up on OCaml compiler internals changes (and it's my impression it never picked up much adoption). https://github.com/reynir/ocp-index-top https://github.com/reynir/ocp-index-top dbuenzli's down also has a similar feature.
- stevekemp 2y ago
  Like many others here I once wrote a toy lisp in golang, and I added a help function. It would give usage-information for all the built-in functions. > (help +) Arguments N arg1..argN Adds all arguments present to the first number. > (help map) Arguments lst:list fun:function Return a list with the contents of evaluating the given function on every item of the supplied list. See-also: map-pairs
- freedomben 2y ago
  Ruby has a similar help() function you can invoke from the REPL (irb), or from the CLI with the standalone tool `ri`[1]. Pretty nifty feature! [1]: https://stackoverflow.com/a/25671404 https://stackoverflow.com/a/25671404
- chillpenguin 2y ago
  Smalltalk, by far, is the best in this category.
- mechanicum 2y ago
  Clojure has doc and source functions. For example: user=> (doc clojure.core) ------------------------- clojure.core Fundamental library of the Clojure language user=> (doc +) ------------------------- clojure.core/+ ([] [x] [x y] [x y & more]) Returns the sum of nums. (+) returns 0. Does not auto-promote longs, will throw on overflow. See also: +' user=> (source +) (defn + "Returns the sum of nums. (+) returns 0. Does not auto-promote longs, will throw on overflow. See also: +'" {:inline (nary-inline 'add 'unchecked_add) :inline-arities >1? :added "1.2"} ([] 0) ([x] (cast Number x)) ([x y] (. clojure.lang.Numbers (add x y))) ([x y & more] (reduce1 + (+ x y) more)))
- JadeNB 2y ago
  Although it's probably not at the top of many people's minds (includind mine) as a favorite programming language, Mathematica does have fantastic help, accessible with `?` and expandable from there as needed.
viccis 2y ago
help() is great, but my favorite tool for getting quick info about an object from the Python REPL is still wat. Just `pip install wat` and then if you need info about some object o, do `wat / o`. If you want full docstrings, do `wat.long / o` It's a lifesaver when you're using a poorly documented package.
- kstrauser 2y ago
  Dear god: https://github.com/igrek51/wat?tab=readme-ov-file#load-from-unicode-glyph https://github.com/igrek51/wat?tab=readme-ov-file#load-from-...
  - extraduder_ire 2y ago
    I always think of python as a more readable version of perl. I first got that impression from the "import this" statement. That load from glyph snippet aligns with my understanding.
    - kstrauser 2y ago
      For the record, this is not what I would consider idiomatic Python.
ks2048 2y ago
Some room for improvement on getting help for symbols: help("**") explains the power operator, but could also mention dict unpacking. help("<<") doesn't mention bit shifting (shows a page for "operator precedence"). I was going to say languages should emphasize help for symbols because they're hard to Google for - but I guess in the LLM age, that's no longer true.
- emmelaich 2y ago
  Also uses / in the method signatures with no indication of what it means. This article doesn't either. Apparently "It signifies the end of the positional only parameters, parameters you cannot use as keyword parameters." Which is redundant for most functions as they only have positional parameters.
  - hermitdev 2y ago
    > Which is redundant for most functions as they only have positional parameters. Huh? This is not true. def foo(a, b, c): ... This can be invoked as either `foo(1, 2, 3)` or `foo(c=3, b=2, a=1)`: >>> def foo(a, b, c): ... print(f"{a=}") ... print(f"{b=}") ... print(f"{c=}") ... >>> foo(1, 2, 3) a=1 b=2 c=3 >>> foo(c=3, b=2, a=1) a=1 b=2 c=3 >>>
    - emmelaich 2y ago
      Help on built-in function sin in module math: sin(x, /) Return the sine of x (measured in radians). >>> math.sin(x=2) ~~~~~~~~^^^^^ TypeError: math.sin() takes no keyword arguments / is used everwhere and it's usually just noise. Unexplained noise.
      - mananaysiempre 2y ago
        It is often used for builtins, because emulating the default Python behaviour of accepting arguments both by position and by name is a pain with the Python/C API. (There are other use cases for positional-only arguments, such as accepting an arbitrary function and an arbitrary set of arguments to call it with at the same time—for example, to invoke it in a new coroutine—but they are pretty rare.) This pecularity of most builtin functions has been there since before Python 3 was a thing, it’s just been undocumented and difficult to emulate in Python before this syntax was introduced. As for unexplained noise—well, all other parts of the function declaration syntax aren’t explained either. You’re expected to know the function declaration syntax in order to read help on individual function declarations; that’s what the syntax reference is for.
tclancy 2y ago
Nice. I usually fall back to dir() as my first inspection tool at the command line.
- mdaniel 2y ago
  or its awesome two friends: locals() and globals() to see their names and values simultaneously; I've gotten a lot of mileage out of that as a pseudo-debugger when the only insight you have is a logger in production
  - kstrauser 2y ago
    Don't forget `vars()`.
- analog31 2y ago
  I bounce back and forth. First dir() then help()...
- bayesianbot 2y ago
  I used to, but wat offers a better printout of the methods: https://github.com/igrek51/wat https://github.com/igrek51/wat
- infamia 2y ago
  vars() is another good one if you're looking for something with a particular value.
shawnz 2y ago
> There are other ways to use the help function, but before we dive into those I'd like to address the *, and / symbols shown in the output above. Where is this addressed? Is there a section missing here?
- mdaniel 2y ago
  I am posting this because I always forget which one it is and searching for it is damn near impossible https://peps.python.org/pep-0457/#syntax-and-semantics https://peps.python.org/pep-0457/#syntax-and-semantics "/" marks the boundary between "positional only" and "mixed" and then "*" does the same for "mixed" and "kwargs only"
nayuki 2y ago
The web page's stylesheet is broken (returns HTTP 404) but the text is still quite readable. Good job!
btdmaster 2y ago
An interesting side effect is that it runs the code inside the module you import, so that code can act based on whether it gets imported by help or not: https://tio.run/##VY6/DoIwEMb3PsUXl6ODLK7ETVcfwBhylBqIpW1KB3n6eqDRuF1@37/reB5KMZzRNDhdzjjiHkIdFzVOMaSMnNjYjs1DxTT6XNFgXSSMHtc5C26ts1PtebISTPix1fIN1/a53rnd9ErfwL7H1lXJnoZh52xPkAoSgPe6EK3kK6XikofgD9gb0OczsdG/sNXthO80lfIC https://tio.run/##VY6/DoIwEMb3PsUXl6ODLK7ETVcfwBhylBqIpW1KB3...
rzzzt 2y ago
Before 3.13: https://thejenkinscomic.net/?id=52 https://thejenkinscomic.net/?id=52
PyWoody 2y ago
If you use Vim, SHIFT+K will bring up the help docstring for the object under your cursor. If you want `method`'s help from `object.method`, all you have to do is highlight `object.method` then do SHIFT+K. The navigation is a little awkward but it's super handy for quick one-offs right in the buffer.
- otherayden 2y ago
  Thank you for this, super handy
chthonicdaemon 2y ago
For quick lookups, I usually use pydoc[1], which displays roughly the same help string but without having to go into the repl. I think there are several *doc functions like this. Off the top of my head I can think of texdoc (which usually just opens the pdf of the package documentation) and perldoc. pydoc -b is also very useful as a standard lib reference when you're not connected to the internet and you can live with the quite interesting default color scheme. [1] https://docs.python.org/3/library/pydoc.html https://docs.python.org/3/library/pydoc.html
curtisszmania 2y ago
[dead]

155 points by danso 2y ago

ape4 2y ago

Cool idea. Do any other languages have this?

jhbadger 2y ago
R has probably the best help feature for any language -- not only can you ask it about help on individual functions with "?", the tradition (and this continues with most add in packages as well as builtins) is not only does it give you info on the function, it gives you example code using it so you can understand what it does in practice.
emmelaich 2y ago
utop for ocaml is cool, gives type signatures for functions. no explicit help, but does offer completions with tab. Similarly, rtop for reason. https://opam.ocaml.org/blog/about-utop/ https://opam.ocaml.org/blog/about-utop/ and https://opam.ocaml.org/packages/rtop/ https://opam.ocaml.org/packages/rtop/
- reycharles 2y ago
  I wrote a small thing for adding a `#doc List.find` directive. However, I don't maintain it anymore since I think it doesn't see much use and it's work to keep up on OCaml compiler internals changes (and it's my impression it never picked up much adoption). https://github.com/reynir/ocp-index-top https://github.com/reynir/ocp-index-top dbuenzli's down also has a similar feature.
stevekemp 2y ago
Like many others here I once wrote a toy lisp in golang, and I added a help function. It would give usage-information for all the built-in functions. > (help +) Arguments N arg1..argN Adds all arguments present to the first number. > (help map) Arguments lst:list fun:function Return a list with the contents of evaluating the given function on every item of the supplied list. See-also: map-pairs
freedomben 2y ago
Ruby has a similar help() function you can invoke from the REPL (irb), or from the CLI with the standalone tool `ri`[1]. Pretty nifty feature! [1]: https://stackoverflow.com/a/25671404 https://stackoverflow.com/a/25671404
chillpenguin 2y ago
Smalltalk, by far, is the best in this category.
mechanicum 2y ago
Clojure has doc and source functions. For example: user=> (doc clojure.core) ------------------------- clojure.core Fundamental library of the Clojure language user=> (doc +) ------------------------- clojure.core/+ ([] [x] [x y] [x y & more]) Returns the sum of nums. (+) returns 0. Does not auto-promote longs, will throw on overflow. See also: +' user=> (source +) (defn + "Returns the sum of nums. (+) returns 0. Does not auto-promote longs, will throw on overflow. See also: +'" {:inline (nary-inline 'add 'unchecked_add) :inline-arities >1? :added "1.2"} ([] 0) ([x] (cast Number x)) ([x y] (. clojure.lang.Numbers (add x y))) ([x y & more] (reduce1 + (+ x y) more)))
JadeNB 2y ago
Although it's probably not at the top of many people's minds (includind mine) as a favorite programming language, Mathematica does have fantastic help, accessible with `?` and expandable from there as needed.

viccis 2y ago

help() is great, but my favorite tool for getting quick info about an object from the Python REPL is still wat. Just `pip install wat` and then if you need info about some object o, do `wat / o`. If you want full docstrings, do `wat.long / o` It's a lifesaver when you're using a poorly documented package.

kstrauser 2y ago
Dear god: https://github.com/igrek51/wat?tab=readme-ov-file#load-from-unicode-glyph https://github.com/igrek51/wat?tab=readme-ov-file#load-from-...
- extraduder_ire 2y ago
  I always think of python as a more readable version of perl. I first got that impression from the "import this" statement. That load from glyph snippet aligns with my understanding.
  - kstrauser 2y ago
    For the record, this is not what I would consider idiomatic Python.

ks2048 2y ago

Some room for improvement on getting help for symbols: help("**") explains the power operator, but could also mention dict unpacking. help("<<") doesn't mention bit shifting (shows a page for "operator precedence"). I was going to say languages should emphasize help for symbols because they're hard to Google for - but I guess in the LLM age, that's no longer true.

emmelaich 2y ago
Also uses / in the method signatures with no indication of what it means. This article doesn't either. Apparently "It signifies the end of the positional only parameters, parameters you cannot use as keyword parameters." Which is redundant for most functions as they only have positional parameters.
- hermitdev 2y ago
  > Which is redundant for most functions as they only have positional parameters. Huh? This is not true. def foo(a, b, c): ... This can be invoked as either `foo(1, 2, 3)` or `foo(c=3, b=2, a=1)`: >>> def foo(a, b, c): ... print(f"{a=}") ... print(f"{b=}") ... print(f"{c=}") ... >>> foo(1, 2, 3) a=1 b=2 c=3 >>> foo(c=3, b=2, a=1) a=1 b=2 c=3 >>>
  - emmelaich 2y ago
    Help on built-in function sin in module math: sin(x, /) Return the sine of x (measured in radians). >>> math.sin(x=2) ~~~~~~~~^^^^^ TypeError: math.sin() takes no keyword arguments / is used everwhere and it's usually just noise. Unexplained noise.
    - mananaysiempre 2y ago
      It is often used for builtins, because emulating the default Python behaviour of accepting arguments both by position and by name is a pain with the Python/C API. (There are other use cases for positional-only arguments, such as accepting an arbitrary function and an arbitrary set of arguments to call it with at the same time—for example, to invoke it in a new coroutine—but they are pretty rare.) This pecularity of most builtin functions has been there since before Python 3 was a thing, it’s just been undocumented and difficult to emulate in Python before this syntax was introduced. As for unexplained noise—well, all other parts of the function declaration syntax aren’t explained either. You’re expected to know the function declaration syntax in order to read help on individual function declarations; that’s what the syntax reference is for.

tclancy 2y ago

Nice. I usually fall back to dir() as my first inspection tool at the command line.

mdaniel 2y ago
or its awesome two friends: locals() and globals() to see their names and values simultaneously; I've gotten a lot of mileage out of that as a pseudo-debugger when the only insight you have is a logger in production
- kstrauser 2y ago
  Don't forget `vars()`.
analog31 2y ago
I bounce back and forth. First dir() then help()...
bayesianbot 2y ago
I used to, but wat offers a better printout of the methods: https://github.com/igrek51/wat https://github.com/igrek51/wat
infamia 2y ago
vars() is another good one if you're looking for something with a particular value.

shawnz 2y ago

> There are other ways to use the help function, but before we dive into those I'd like to address the *, and / symbols shown in the output above. Where is this addressed? Is there a section missing here?

mdaniel 2y ago
I am posting this because I always forget which one it is and searching for it is damn near impossible https://peps.python.org/pep-0457/#syntax-and-semantics https://peps.python.org/pep-0457/#syntax-and-semantics "/" marks the boundary between "positional only" and "mixed" and then "*" does the same for "mixed" and "kwargs only"

nayuki 2y ago

The web page's stylesheet is broken (returns HTTP 404) but the text is still quite readable. Good job!

btdmaster 2y ago

An interesting side effect is that it runs the code inside the module you import, so that code can act based on whether it gets imported by help or not: https://tio.run/##VY6/DoIwEMb3PsUXl6ODLK7ETVcfwBhylBqIpW1KB3n6eqDRuF1@37/reB5KMZzRNDhdzjjiHkIdFzVOMaSMnNjYjs1DxTT6XNFgXSSMHtc5C26ts1PtebISTPix1fIN1/a53rnd9ErfwL7H1lXJnoZh52xPkAoSgPe6EK3kK6XikofgD9gb0OczsdG/sNXthO80lfIC https://tio.run/##VY6/DoIwEMb3PsUXl6ODLK7ETVcfwBhylBqIpW1KB3...

rzzzt 2y ago

Before 3.13: https://thejenkinscomic.net/?id=52 https://thejenkinscomic.net/?id=52

PyWoody 2y ago

If you use Vim, SHIFT+K will bring up the help docstring for the object under your cursor. If you want `method`'s help from `object.method`, all you have to do is highlight `object.method` then do SHIFT+K. The navigation is a little awkward but it's super handy for quick one-offs right in the buffer.

otherayden 2y ago
Thank you for this, super handy

chthonicdaemon 2y ago

For quick lookups, I usually use pydoc[1], which displays roughly the same help string but without having to go into the repl. I think there are several *doc functions like this. Off the top of my head I can think of texdoc (which usually just opens the pdf of the package documentation) and perldoc. pydoc -b is also very useful as a standard lib reference when you're not connected to the internet and you can live with the quite interesting default color scheme. [1] https://docs.python.org/3/library/pydoc.html https://docs.python.org/3/library/pydoc.html

curtisszmania 2y ago

[dead]