Где я могу найти «точно» описанную документацию Python?

Question

[Phys_Math_Man]

Я давно заметил, что документация, как правило, написана как-то "по-гуманитарному" - много текста и мало "формул". Я бы хотел найти такое описание, чтобы для любого выражения питоновского кода можно было найти точную семантику в виде псевдокода или кода python. У меня два вопроса. 1) Почему документация написана таким неточным языком? 2) Можно ли где-то найти точное описание?

Answer 1

[Everything_is_bad]

https://docs.python.org/3/

Почему документация написана таким неточным языком?

это твое субъективное мнение, не понятно где ты там увидел "неточным языком". Ну возьми тогда учебники по языку и выбери более тебе понятно написанный.

Можно ли где-то найти точное описание?

"более точное" это уже исходники https://github.com/python/cpython

Comments

[Phys_Math_Man]

Я привык, чтобы все было написано с математической строгостью. Документация Python, очевидно, не удовлетворяет этому требованию. Хотя расписать формальную семантику вполне возможно и даже, я считаю, нужно. И это совсем не то же самое, что изучить полностью все исходники.

[Everything_is_bad]

Phys_Math_Man, покажи пример "математически строгой" документации

[Phys_Math_Man]

https://peps.python.org/pep-0380/
Здесь, например, почти строго (но некоторых мелочей не хватает) описана семантика оператора 'yield from' посредством python-кода

[Everything_is_bad]

Phys_Math_Man, ты кажется путаешь описание, что именно и делают доки, с разжевыванием материала, этим как раз занимаются учебники.

[Сергей Горностаев]

Phys_Math_Man, документацию для языков, применяемых в отрасли для реальных задач, так не пишут. Дрочат математематику только в научной области. Вам вместо Python какой-нибудь там OCaml нужен.

[Phys_Math_Man]

Everything_is_bad, возможно. Посоветуй тогда, пожалуйста, учебник с подробным изложением, если знаешь такие.

[Everything_is_bad]

Phys_Math_Man, без понятия какой устроит, мне хватает оф доков и кучи статей, которые ищу гуглом, где уже есть более подробная информация, хотя они больше про решение проблем, чем про доки.

[Phys_Math_Man]

Сергей Горностаев, Сергей Горностаев, я с Вами не соглашусь. Семантика должна быть точно описана. Иначе какие-то части кода могут работать неожиданно для разработчика (из-за того, что он, например, не знает всех деталей вызова данной функции). Информатика - это ведь точная наука.

[Сергей Горностаев]

Phys_Math_Man, не важно, что должно, а что нет, факт в том, что никто не описывает. Даже у Scala документация предельно прикладная, ориентированная на человека с восемью классами образования, хотя Одерский и позиционирует язык, как исследовательский.

Answer 2

[Руслан .]

Что-то типа такого?
https://docs.python.org/3/library/functions.html
Или это не достаточно локонично.

Comments

[Phys_Math_Man]

Нет, там тоже неполное описание.

[Руслан .]

А что есть полное описание? У вас есть пример?

[Phys_Math_Man]

Например, в описании встроенной функции __import__ должна быть полная семантика ее вызова (проверка наличия ключа в sys.modules, обход sys.meta_path и т. д.), а иначе смысла в такой документации мало

[Руслан .]

Phys_Math_Man, любая документация почти всегда отстает от кода и не содержит всех нюансов.
То что вам нужно, можно взять только из исходников.

[Phys_Math_Man]

Руслан ., я понял Вашу мысль. В этом и проблема. Потому что написать документацию так, чтобы она точно описывала семантику оператора, вполне возможно. Если бы я был разработчиком языка, я бы принципиально писал документацию именно так.

[Руслан .]

Phys_Math_Man, такое к сожалению возможно, если ты пилишь пет-проект. В проме у тебя, как разработчика столько работы, что доку ты физически не осилишь. Кроме того, все осложняется тем, что одну фичу пилит команда разработчиков и всех мотивировать на поддержание актуальности доки очень сложно. Также часто случается испраление ошибок и рефактортнг. И после каждого изменения в коде нужно чекать доку. А еще и ПМ со сроками напирает. Поэтому актуальная дока это очень сложно и дорого, а потому ее редко где есть.