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.
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.
It would not need to exist if that were the case.
The “default” in Python is that a parameter can be passed both positionally and by keyword. Until Python 3.8, the only way to have positional only parameters in pure Python was to use *args and unpack them yourself.
What's the advantage of stopping someone from naming the parameter when they pass it in?
https://peps.python.org/pep-0570/#rationale
That being said, you can find quite a lot of uses in the modules written in Python - though I'm not going to pretend I can tell you the reasoning for all them.
grep "/\s*[,)]" /usr/lib/python3.13/ --recursive --include "*.py" --exclude-dir site-packages
def func(x, /, **kwargs):
print(x, kwargs)
func(1, x=2)
There are cases where a parameter name is worthless on the calling side, this is especially common for unary or binary functions.
In that case, the ability to name the parameter on the call site just constrains the implementation, and the overrides (in the case of methods).
def abs_days_difference(date1, date2, /):
# note that swapping passed params will yield the same result
delta = abs((date2 - date1).days)
return delta
d1 = date(2023, 1, 1)
d2 = date(2024, 1, 15)
abs_days_difference(d1,d2)==abs_days_difference(d2,d1)
Compare with
def day_difference(earlier_date, later_date):
delta = (later_date - earlier_date).days
return delta
d1 = date(2023, 1, 1)
d2 = date(2024, 1, 15)
day_difference(d1,d2)!=day_difference(d2,d1)
d1 = date(2023, 1, 1)
d2 = date(2024, 1, 15)
#this now doesn't work
day_difference(d1,d2)
# this works and is much clearer for caller
day_difference(earlier_date=d1,later_date=d2)-- original below --
> What's the advantage of stopping someone from naming the parameter when they pass it in?
From what I have seen, this feature is mostly used for the opposite direction, to force the caller to use keyword arguments past a certain number of (or zero) positional arguments.
1. It's useless noise for something like help(math.sin).
2. It's everywhere and not well documented. Ironical for a help system!
Damn it's been hard to improve Python's help system. Python2 didn't have an entry for re.MatchObject. When I mentioned this on irc #python the response was to just google it. Talk about not getting the point. help() should help.
Huh? This is not true.
def foo(a, b, c): ...
>>> 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
>>> 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
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.
The navigation is a little awkward but it's super handy for quick one-offs right in the buffer.
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.
That load from glyph snippet aligns with my understanding.
https://tio.run/##VY6/DoIwEMb3PsUXl6ODLK7ETVcfwBhylBqIpW1KB3...
Where is this addressed? Is there a section missing here?
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"
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.
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))) > (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-pairsSimilarly, rtop for reason.
https://opam.ocaml.org/blog/about-utop/ and https://opam.ocaml.org/packages/rtop/
dbuenzli's down also has a similar feature.