python:main← JulienPalard:mdk-stick-to-python-syntax
opened 01:37PM - 05 Sep 22 UTC
I tried my idea at documenting Python functions using only Python syntax (avoidi…ng manpages-like brackets to denote optional arguments), please tell me what you think.
It sometimes went "badly", like:
```diff
-.. class:: set([iterable])
+.. class:: set(iterable=())
```
where I "had" to use an empty tuple because it would have looked very recursive to use a set here, like `set(iterable=set())`. It's also a lie: it's not an empty tuple by default (it's a C `NULL`), but there's no practical difference for the reader.
Sometimes the change is more neutral, like in:
```diff
-.. awaitablefunction:: anext(async_iterator[, default])
+.. awaitablefunction:: anext(async_iterator)
+ anext(async_iterator, default)
```
or:
```diff
-.. function:: max(iterable, *[, key, default])
- max(arg1, arg2, *args[, key])
+.. function:: max(iterable, /, *, key=None)
+ max(iterable, /, *, default, key=None)
+ max(arg1, arg2, *args, key=None)
```
(where I'm happy to remove `, *[,` because it hurt my eyes.)
Sometimes it's good as it add information:
```diff
-.. class:: complex([real[, imag]])
+.. class:: complex(real=0, imag=0)
```
Or make more explicit where it's OK to pass `None` and where it's not, like in:
```diff
-.. class:: super([type[, object-or-type]])
+.. class:: super()
+ super(type, object_or_type=None)
```
I bet you think « People should know this syntax, or learn it anyway », but I don't think so, I mean yes they will learn it anyway, but why forcing them to learn it at the same time as they learn basic Python functions? Learning one thing at a time is complicated enough.
Many are alone facing those pages and showing them:
complex(real=0, imag=0)
teach them how to implement default arguments in their own functions, and explicitly show them what happen when they don't give the values, while:
complex([real[, imag]])
don't.
* Issue: gh-91485
