Как читать документацию python

Русскоязычная документация по Python¶

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

Что такое Python¶

Язык программирования Python 3 — это мощный инструмент для создания программ самого разнообразного назначения, доступный даже для новичков. С его помощью можно решать задачи различных типов.

Этот сайт призван помочь начинающим научиться программировать на python 3. Также здесь можно подробнее узнать об особенностях функционирования этого языка.

Язык Python обладает некоторыми примечательными особенностями, которые обуславливают его широкое распространение. Поэтому прежде чем изучать python, следует рассказать о его достоинствах и недостатках.

Python 3: преимущества и недостатки языка¶

Python — интерпретируемый язык программирования. С одной стороны, это позволяет значительно упростить отладку программ, с другой — обуславливает сравнительно низкую скорость выполнения.

• Динамическая типизация. В python не надо заранее объявлять тип переменной, что очень удобно при разработке.
• Хорошая поддержка модульности. Вы можете легко написать свой модуль и использовать его в других программах.
• Встроенная поддержка Unicode в строках. В Python необязательно писать всё на английском языке, в программах вполне может использоваться ваш родной язык.
• Поддержка объектно-ориентированного программирования. При этом его реализация в python является одной из самых понятных.
• Автоматическая сборка мусора, отсутствие утечек памяти.
• Интеграция с C/C++, если возможностей python недостаточно.
• Понятный и лаконичный синтаксис, способствующий ясному отображению кода. Удобная система функций позволяет при грамотном подходе создавать код, в котором будет легко разобраться другому человеку в случае необходимости. Также вы сможете научиться читать программы и модули, написанные другими людьми.
• Огромное количество модулей, как входящих в стандартную поставку Python 3, так и сторонних. В некоторых случаях для написания программы достаточно лишь найти подходящие модули и правильно их скомбинировать. Таким образом, вы можете думать о составлении программы на более высоком уровне, работая с уже готовыми элементами, выполняющими различные действия.
• Кроссплатформенность. Программа, написанная на Python, будет функционировать совершенно одинаково вне зависимости от того, в какой операционной системе она запущена. Отличия возникают лишь в редких случаях, и их легко заранее предусмотреть благодаря наличию подробной документации.

• Установка
  • Windows
  • Linux: Ubuntu
  • Linux: Fedora
  • Интерактивная среда IDLE
  • Редакторы кода и серда разработки IDE
  • Виртуальное окружение (venv)
  • Первая программа
  • 1. Типы данных
    • 1.1. Переменные в Python:
    • 1.2. Числа
    • 1.3. Строки
    • 1.4. Списки
    • 1.5. Словари
    • 1.6. Методы для работы со словарями
    • 1.7. Кортежи
    • 1.8. Множество
    • 1.9. Методы для работы с множествами
    • 1.10. Булевы значения
    • 1.11. Преобразование типов
    • 1.12. Проверка типов
    • 1.13. Файлы
    • 2.1. Базовые операторы
    • 2.2. Управляющие операторы
    • 3.1. Параметры функций
    • 3.2. Локальные переменные
    • 3.3. Зарезервированное слово “global”
    • 3.4. Зарезервированное слово “nonlocal”
    • 3.5. Значения аргументов по умолчанию
    • 3.6. Ключевые аргументы
    • 3.7. Переменное число параметров
    • 3.8. Только ключевые параметры
    • 3.9. Оператор “return”
    • 3.10. Строки документации
    • 1. Модули
      • 1.1. Файлы байткода .pyc
      • 1.2. Оператор from … import …
      • 1.3. Имя модуля – __name__
      • 1.4. Создание собственных модулей

      Просьба наглядно объяснить как читать документацию к библиотеке discord на Python [закрыт]

      Закрыт. На этот вопрос невозможно дать объективный ответ. Ответы на него в данный момент не принимаются.

      Хотите улучшить этот вопрос? Переформулируйте вопрос так, чтобы на него можно было дать ответ, основанный на фактах и цитатах.

      Закрыт 3 года назад .

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

      Отслеживать
      задан 12 ноя 2020 в 20:35
      Vakhalay Mahalay Vakhalay Mahalay
      11 4 4 бронзовых знака
      примите ответ, если он вам помог — галочка слева от ответа 😉
      12 ноя 2020 в 20:54

      1 ответ 1

      Сортировка: Сброс на вариант по умолчанию

      я не понимаю как читать эту документацию

      Самые азы можно и даже лучше учить не из доков, а из чего-нибудь более «наглядного».

      Иногда начинать сразу с документации — не очень удобно и понятно. Начать можно с тьюториала нарпимер. Вот отличный по-русски. Ну а дальше — гугл. 😉 Ну а если доки — то начинать с Quick Start наверно.

      А вот минимальный код:

      import discord client = discord.Client() @client.event async def on_ready(): print('We have logged in as '.format(client)) @client.event async def on_message(message): if message.author == client.user: return if message.content.startswith('$hello'): await message.channel.send('Hello!') client.run('your token here') 

      • Импортируем библиотеку. import discord
      • Создаем главный объект — client = discord.Client()
      • Когда все запустилось:

      @client.event async def on_ready(): print('We have logged in as '.format(client)) 

      • И дальше читаем каждое сообщение, и если оно — «$hello» , то:

      await message.channel.send('Hello!') 

      Что еще?

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

      Учимся читать код, изучая стандартную библиотеку Python

      Итак, вы уже продвинутый новичок — вы изучили основы Python и способны решать реальные задачи.

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

      Наверно, вы слышали, что нужно нарабатывать понимание чтением и написанием больших объёмов кода. Это правда.

      Но какой же код нужно читать?

      «Просто читай то, что нравится». А если вы не знаете, что вам нравится? А если вам не нравится что-то правильное?

      Или хуже того — если вам нравится что-то неправильное и из-за этого у вас выработаются вредные привычки?

      В конечном итоге, для этого ведь необходимо понимание… Но именно его мы и стремимся обрести.

      «На GitHub куча проектов — выберите понравившийся и изучайте, как его реализовали разработчики». Однако самые успешные проекты довольно объёмны — с чего начинать?

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

      Да, вы видите код своими глазами, но он не говорит вам о том, почему разработчики написали его так, чего они не делали и как они рассуждали о проекте в целом.

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

      В этой статье мы рассмотрим некоторые модули стандартной библиотеки Python.

      Примечание о стандартной библиотеке

      В целом, стандартная библиотека Python неидеальна для изучения «хорошего» стиля.

      Хотя все её модули полезны, они не особо однородны:

      • их писали разные авторы;
      • некоторые из них старые (стиль Python 10-20 лет назад был другим);
      • им нужно было сохранять обратную совместимость (то есть невозможно провести рефакторинг багов и вносить крупные изменения в API).

      Мы рассмотрим как раз некоторые из них.

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

      Любопытно изучить различия в возможностях stdlib и её новых внешних альтернатив — разница между ними демонстрирует дефицит, который испытывают разработчики (ведь в противном случае они бы не заморачивались созданием альтернативы). Хорошим примером этого является разница между urllib и requests .

      Как читать модули

      Приблизительно в таком порядке:

      • Познакомьтесь с библиотекой как пользователь: прочитайте документацию, поэкспериментируйте с примерами.
      • Прочитайте соответствующее Python Enhancement Proposal (PEP). Интересное обычно содержится в разделах Abstract, Rationale, Design Decisions, Discussion и Rejected Ideas.
      • Прочитайте код; ссылка на него приведена в начале каждой страницы документации.

      statistics

      Модуль statistics добавляет в стандартную библиотеку статистические функции; он не создавался в качестве конкурента таких библиотек, как NumPy , а «находится на уровне построителя графиков и научного калькулятора».

      Он был внедрён в PEP 450. Если вы незнакомы с этим предложением, то это очень любопытное чтиво:

      • В разделе Rationale предложение сравнивается с NumPy и самодельными решениями; он особенно хорошо демонстрирует, что и почему было добавлено в стандартную библиотеку.
      • Также там есть раздел Design Decisions, в котором объясняется, какой была общая философия проектирования; в разделах Discussion и FAQ тоже есть интересные подробности.

      «Большая часть документации предназначена для читателей, понимающих базовые концепции, но которые могут не знать (например), какую дисперсию им стоит использовать [. ] Однако документация избегает скучных математических подробностей».

      Код относительно прост, а когда это не так, то в нём есть комментарии и ссылки на подробные объяснения или статьи. Это может быть полезным, если вы изучаете все эти концепции и вам проще читать код, чем математическиe условные обозначения.

      pathlib

      Модуль pathlib обеспечивает простую иерархию классов для работы с путями файловой системы; он является высокоуровневой альтернативой os.path .

      Модуль был внедрён в PEP 428. Большинство примеров используется для иллюстрации лежащей в основе модуля философии, а код оставлен в качестве спецификации.

      Код хорошо читается по следующим причинам:

      • Вероятно, вы уже знакомы с этой тематикой; даже если вы не пользовались раньше pathlib , то могли работать с os.path , или с похожей библиотекой в каком-то другом языке.
      • Это хорошее объектно-ориентированное решение. Оно использует объектно-ориентированное программирование с абстрактными (читай: изобретёнными) концепциями, чтобы улучшить структуру кода и его многократное использование. Наверно, это гораздо лучший пример, чем старый Animal​–​Dog​–​Cat​–​Duck​–​speak().
      • Это хорошая тема для сравнительного изучения: pathlib и os.path решают одну задачу, однако в совершенно разных стилях программирования. Кроме того, существовало ещё одно предложение, которое было отклонено, а ещё есть не меньше пяти похожих библиотек; pathlib позаимствовал что-то от каждой из них.

      dataclasses

      Модуль dataclasses снижает объём бойлерплейта при написании классов, генерируя специальные методы наподобие __init__ и __repr__ . (См. в качестве введения этот туториал, потому что в нём используются гораздо более конкретные примеры, чем в официальной документации.)

      Он был внедрён в PEP 557 в качестве упрощённой версии attrs . Раздел Specification схож с документацией; интересные вещи встречаются в Rationale, Discussion и Rejected Ideas.

      Кроме того, это отличный пример метапрограммирования; этот аспект подробно рассматривается в докладке Реймонда Хеттингера Dataclasses: The code generator to end all code generators. [Слайды с доклада в HTML и PDF.] Если у вас возникли проблемы с пониманием кода, то сначала посмотрите доклад; для меня оказалось довольно полезным объяснение генерируемого кода.

      Бонус: graphlib

      Модуль graphlib был добавлен в Python 3.9, и на данный момент содержит только одну вещь: реализацию алгоритма топологической сортировки (вот описание того, что это такое, и почему он полезен).

      Он появился не через PEP; однако у него есть issue со множеством комментариев от разных разработчиков ядра, в том числе Реймонда Хеттингера и Тима Питерса (известного своим «Дзен языка Python»).

      Так как это, по сути, решённая задача, в обсуждениях рассматривается API: куда его вставлять, кто должен его вызывать, как представлять входные и выходные данные, как одновременно обеспечить простоту использования и гибкость.

      В обсуждении пытаются примирить два различных способа использования модуля:

      • Вот граф, верни мне все узлы в топологическом порядке.
      • Вот граф, верни мне все узлы, которые можно обработать прямо сейчас (или потому, что у них нет зависимостей, или потому, что их зависимости уже обработаны). Это полезно для распараллеливания работы, например, для скачивания и установки пакетов, зависимых от других пакетов.

      По сравнению с обсуждением issue, сам код очень мал — меньше 250 строк, и в основном состоит из комментариев и документации.

      На правах рекламы

      Серверы для разработчиков и не только! Дешёвые VDS на базе новейшего «железа» для размещения проектов любой сложности, от корпоративных сетей и игровых проектов до лендингов и VPN.

      правильно читать документацию по Python | Ти Кент | апрель 2023 г.

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

      Типы документации Python

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

      Python поставляется со встроенной документацией, доступ к которой можно получить с помощью функции help(). Эта документация охватывает сам язык Python, включая ключевые слова, встроенные функции и исключения.

      Документация стандартной библиотеки

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

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

      Чтение документации Python

      Теперь, когда мы рассмотрели различные типы документации Python, давайте рассмотрим несколько советов по ее эффективному чтению.

      Начните с обзора

      Когда вы впервые открываете документацию по модулю или библиотеке, начните с чтения обзора. Это даст вам общее представление о том, что делает модуль или библиотека и для чего они используются.

      Прочитайте сигнатуру функции/класса/метода

      Следующим шагом является просмотр сигнатуры функции, класса или метода. Это даст вам представление об аргументах, которые принимает функция, о возвращаемом значении (если есть) и любых необязательных аргументах. Эта информация необходима для понимания того, как правильно использовать функцию.

      Read more: Преимущества роскошного дизайна Oppo Reno 8T 5G, использование новейшего чипсета Snapdragon и 108-мегапиксельной камеры

      После того, как вы просмотрели сигнатуру функции, прочтите описание. Это даст вам более подробную информацию о том, что делает функция, как она работает, а также о любых особенностях, о которых вам следует знать. Эта информация поможет вам понять, как эффективно использовать эту функцию.

      Посмотрите на примеры

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

      Проверьте связанные функции/классы/методы

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

      Используйте функцию поиска

      Если вы ищете конкретную информацию, не бойтесь использовать функцию поиска. На веб-сайте документации Python есть мощная функция поиска, которая поможет вам быстро найти то, что вы ищете.

      Используйте внешние ресурсы

      Наконец, не забывайте, что для разработчиков Python доступно множество внешних ресурсов. Это могут быть блоги, онлайн-учебники и дискуссионные форумы. Если у вас возникли проблемы с пониманием определенной концепции или функции, попробуйте найти ее в Интернете, чтобы узнать, есть ли какие-либо полезные ресурсы.

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

      Читать:

      Вольво как поменять батарейку в ключе хс90