diff --git a/docs/ru/docs/async.md b/docs/ru/docs/async.md index c667629ef..15d4e108a 100644 --- a/docs/ru/docs/async.md +++ b/docs/ru/docs/async.md @@ -1,18 +1,18 @@ -# Конкурентность и async / await +# Конкурентность и async / await { #concurrency-and-async-await } -Здесь приведена подробная информация об использовании синтаксиса `async def` при написании *функций обработки пути*, а также рассмотрены основы асинхронного программирования, конкурентности и параллелизма. +Подробности о синтаксисе `async def` для *функций-обработчиков пути* и немного фона об асинхронном коде, конкурентности и параллелизме. -## Нет времени? +## Нет времени? { #in-a-hurry } -TL;DR: +TL;DR: -Допустим, вы используете сторонюю библиотеку, которая требует вызова с ключевым словом `await`: +Если вы используете сторонние библиотеки, которые нужно вызывать с `await`, например: ```Python results = await some_library() ``` -В этом случае *функции обработки пути* необходимо объявлять с использованием синтаксиса `async def`: +Тогда объявляйте *функции-обработчики пути* с `async def`, например: ```Python hl_lines="2" @app.get('/') @@ -21,18 +21,15 @@ async def read_results(): return results ``` -/// note +/// note | Примечание -`await` можно использовать только внутри функций, объявленных с использованием `async def`. +`await` можно использовать только внутри функций, объявленных с `async def`. /// --- -Если вы обращаетесь к сторонней библиотеке, которая с чем-то взаимодействует -(с базой данных, API, файловой системой и т. д.), и не имеет поддержки синтаксиса `await` -(что относится сейчас к большинству библиотек для работы с базами данных), то -объявляйте *функции обработки пути* обычным образом с помощью `def`, например: +Если вы используете стороннюю библиотеку, которая взаимодействует с чем-то (база данных, API, файловая система и т.д.) и не поддерживает использование `await` (сейчас это относится к большинству библиотек для БД), тогда объявляйте *функции-обработчики пути* как обычно, просто с `def`, например: ```Python hl_lines="2" @app.get('/') @@ -43,310 +40,283 @@ def results(): --- -Если вашему приложению (странным образом) не нужно ни с чем взаимодействовать и, соответственно, -ожидать ответа, используйте `async def`. +Если вашему приложению (по какой-то причине) не нужно ни с чем взаимодействовать и ждать ответа, используйте `async def`, даже если внутри не нужен `await`. --- -Если вы не уверены, используйте обычный синтаксис `def`. +Если вы просто не уверены, используйте обычный `def`. --- -**Примечание**: при необходимости можно смешивать `def` и `async def` в *функциях обработки пути* -и использовать в каждом случае наиболее подходящий синтаксис. А FastAPI сделает с этим всё, что нужно. +**Примечание**: вы можете смешивать `def` и `async def` в *функциях-обработчиках пути* столько, сколько нужно, и объявлять каждую так, как лучше для вашего случая. FastAPI сделает с ними всё как надо. -В любом из описанных случаев FastAPI работает асинхронно и очень быстро. +В любом из случаев выше FastAPI всё равно работает асинхронно и очень быстро. -Однако придерживаясь указанных советов, можно получить дополнительную оптимизацию производительности. +Но следуя этим шагам, он сможет выполнить некоторые оптимизации производительности. -## Технические подробности +## Технические подробности { #technical-details } -Современные версии Python поддерживают разработку так называемого **"асинхронного кода"** посредством написания **"сопрограмм"** с использованием синтаксиса **`async` и `await`**. +Современные версии Python поддерживают **«асинхронный код»** с помощью **«сопрограмм»** (coroutines) и синтаксиса **`async` и `await`**. -Ниже разберём эту фразу по частям: +Разберём эту фразу по частям в разделах ниже: * **Асинхронный код** * **`async` и `await`** * **Сопрограммы** -## Асинхронный код +## Асинхронный код { #asynchronous-code } -Асинхронный код означает, что в языке 💬 есть возможность сообщить машине / программе 🤖, -что в определённой точке кода ей 🤖 нужно будет ожидать завершения выполнения *чего-то ещё* в другом месте. Допустим это *что-то ещё* называется "медленный файл" 📝. +Асинхронный код значит, что в языке 💬 есть способ сказать компьютеру/программе 🤖, что в некоторый момент кода ему 🤖 придётся подождать, пока *что-то ещё* где-то в другом месте завершится. Назовём это *что-то ещё* «медленный файл» 📝. -И пока мы ждём завершения работы с "медленным файлом" 📝, компьютер может переключиться для выполнения других задач. +И пока мы ждём завершения работы с «медленныи файлом» 📝, компьютер может заняться другой работой. -Но при каждой возможности компьютер / программа 🤖 будет возвращаться обратно. Например, если он 🤖 опять окажется в режиме ожидания, или когда закончит всю работу. В этом случае компьютер 🤖 проверяет, не завершена ли какая-нибудь из текущих задач. +Затем компьютер/программа 🤖 будет возвращаться каждый раз, когда появится возможность (пока снова где-то идёт ожидание), или когда 🤖 завершит всю текущую работу. И он 🤖 проверит, не завершилась ли какая-либо из задач, которых он ждал, и сделает то, что нужно. -Потом он 🤖 берёт первую выполненную задачу (допустим, наш "медленный файл" 📝) и продолжает работу, производя с ней необходимые действия. +Далее он 🤖 возьмёт первую завершившуюся задачу (скажем, наш «медленный файл» 📝) и продолжит делать с ней то, что требуется. -Вышеупомянутое "что-то ещё", завершения которого приходится ожидать, обычно относится к достаточно "медленным" операциям I/O (по сравнению со скоростью работы процессора и оперативной памяти), например: +Это «ожидание чего-то ещё» обычно относится к операциям I/O, которые относительно «медленные» (по сравнению со скоростью процессора и оперативной памяти), например ожидание: -* отправка данных от клиента по сети -* получение клиентом данных, отправленных вашей программой по сети -* чтение системой содержимого файла с диска и передача этих данных программе -* запись на диск данных, которые программа передала системе -* обращение к удалённому API -* ожидание завершения операции с базой данных -* получение результатов запроса к базе данных -* и т. д. +* отправки данных клиентом по сети +* получения клиентом данных, отправленных вашей программой по сети +* чтения системой содержимого файла на диске и передачи этих данных вашей программе +* записи на диск содержимого, которое ваша программа передала системе +* операции удалённого API +* завершения операции базы данных +* возврата результатов запроса к базе данных +* и т.д. -Поскольку в основном время тратится на ожидание выполнения операций I/O, -их обычно называют операциями, ограниченными скоростью ввода-вывода. +Поскольку основное время выполнения уходит на ожидание операций I/O, их называют операциями, «ограниченными вводом-выводом» (I/O bound). -Код называют "асинхронным", потому что компьютеру / программе не требуется "синхронизироваться" с медленной задачей и, -будучи в простое, ожидать момента её завершения, с тем чтобы забрать результат и продолжить работу. +Это называется «асинхронным», потому что компьютеру/программе не нужно «синхронизироваться» с медленной задачей, простаивая и выжидая точный момент её завершения, чтобы забрать результат и продолжить работу. -Вместо этого в "асинхронной" системе завершённая задача может немного подождать (буквально несколько микросекунд), -пока компьютер / программа занимается другими важными вещами, с тем чтобы потом вернуться, -забрать результаты выполнения и начать их обрабатывать. +Вместо этого, в «асинхронной» системе, уже завершившаяся задача может немного подождать (несколько микросекунд) в очереди, пока компьютер/программа завершит то, чем занимался, и затем вернётся, чтобы забрать результаты и продолжить работу с ними. -"Синхронное" исполнение (в противовес "асинхронному") также называют "последовательным", -потому что компьютер / программа последовательно выполняет все требуемые шаги перед тем, как перейти к следующей задаче, -даже если в процессе приходится ждать. +Для «синхронного» (в противоположность «асинхронному») исполнения часто используют термин «последовательный», потому что компьютер/программа выполняет все шаги по порядку, прежде чем переключиться на другую задачу, даже если эти шаги включают ожидание. -### Конкурентность и бургеры +### Конкурентность и бургеры { #concurrency-and-burgers } -Тот **асинхронный** код, о котором идёт речь выше, иногда называют **"конкурентностью"**. Она отличается от **"параллелизма"**. +Та идея **асинхронного** кода, описанная выше, иногда также называется **«конкурентностью»**. Она отличается от **«параллелизма»**. -Да, **конкурентность** и **параллелизм** подразумевают, что разные вещи происходят примерно в одно время. +И **конкурентность**, и **параллелизм** относятся к «разным вещам, происходящим примерно одновременно». -Но внутреннее устройство **конкурентности** и **параллелизма** довольно разное. +Но различия между *конкурентностью* и *параллелизмом* довольно существенные. -Чтобы это понять, представьте такую картину: +Чтобы их увидеть, представьте следующую историю про бургеры: -### Конкурентные бургеры +### Конкурентные бургеры { #concurrent-burgers } - +Вы идёте со своей возлюбленной за фастфудом, вы стоите в очереди, пока кассир принимает заказы у людей перед вами. 😍 -Вы идёте со своей возлюбленной 😍 в фастфуд 🍔 и становитесь в очередь, в это время кассир 💁 принимает заказы у посетителей перед вами. + -Когда наконец подходит очередь, вы заказываете парочку самых вкусных и навороченных бургеров 🍔, один для своей возлюбленной 😍, а другой себе. +Наконец ваша очередь: вы заказываете 2 очень «навороченных» бургера — для вашей возлюбленной и для себя. 🍔🍔 -Отдаёте деньги 💸. + -Кассир 💁 что-то говорит поварам на кухне 👨‍🍳, теперь они знают, какие бургеры нужно будет приготовить 🍔 -(но пока они заняты бургерами предыдущих клиентов). +Кассир говорит что-то повару на кухне, чтобы они знали, что нужно приготовить ваши бургеры (хотя сейчас они готовят бургеры для предыдущих клиентов). -Кассир 💁 отдаёт вам чек с номером заказа. + -В ожидании еды вы идёте со своей возлюбленной 😍 выбрать столик, садитесь и довольно продолжительное время общаетесь 😍 -(поскольку ваши бургеры самые навороченные, готовятся они не так быстро ✨🍔✨). +Вы платите. 💸 -Сидя за столиком с возлюбленной 😍 в ожидании бургеров 🍔, вы отлично проводите время, -восхищаясь её великолепием, красотой и умом ✨😍✨. +Кассир выдаёт вам номер вашей очереди. -Всё ещё ожидая заказ и болтая со своей возлюбленной 😍, время от времени вы проверяете, -какой номер горит над прилавком, и не подошла ли уже ваша очередь. + -И вот наконец настаёт этот момент, и вы идёте к стойке, чтобы забрать бургеры 🍔 и вернуться за столик. +Пока вы ждёте, вы вместе со своей возлюбленной идёте и выбираете столик, садитесь и долго болтаете (ваши бургеры очень «навороченные», поэтому им нужно время на приготовление). -Вы со своей возлюбленной 😍 едите бургеры 🍔 и отлично проводите время ✨. +Сидя за столиком со своей возлюбленной в ожидании бургеров, вы можете провести это время, восхищаясь тем, какая она классная, милая и умная ✨😍✨. + + + +Пока вы ждёте и разговариваете, время от времени вы поглядываете на номер на табло, чтобы понять, не подошла ли уже ваша очередь. + +И вот в какой-то момент ваша очередь наступает. Вы подходите к стойке, забираете свои бургеры и возвращаетесь к столику. + + + +Вы со своей возлюбленной едите бургеры и отлично проводите время. ✨ + + + +/// info | Информация + +Прекрасные иллюстрации от Ketrina Thompson. 🎨 + +/// --- -А теперь представьте, что в этой небольшой истории вы компьютер / программа 🤖. +Представьте, что в этой истории вы — компьютер/программа 🤖. -В очереди вы просто глазеете по сторонам 😴, ждёте и ничего особо "продуктивного" не делаете. -Но очередь движется довольно быстро, поскольку кассир 💁 только принимает заказы (а не занимается приготовлением еды), так что ничего страшного. +Пока вы стоите в очереди, вы просто бездействуете 😴, ждёте своей очереди и не делаете ничего особо «продуктивного». Но очередь движется быстро, потому что кассир только принимает заказы (а не готовит их), так что это нормально. -Когда подходит очередь вы наконец предпринимаете "продуктивные" действия 🤓: просматриваете меню, выбираете в нём что-то, узнаёте, что хочет ваша возлюбленная 😍, собираетесь оплатить 💸, смотрите, какую достали карту, проверяете, чтобы с вас списали верную сумму, и что в заказе всё верно и т. д. +Когда приходит ваша очередь, вы выполняете действительно «продуктивную» работу: просматриваете меню, решаете, чего хотите, учитываете выбор своей возлюбленной, платите, проверяете, что дали правильную купюру/карту, что сумма списана корректно, что в заказе верные позиции и т.д. -И хотя вы всё ещё не получили бургеры 🍔, ваша работа с кассиром 💁 ставится "на паузу" ⏸, -поскольку теперь нужно ждать 🕙, когда заказ приготовят. +Но затем, хотя у вас ещё нет бургеров, ваша «работа» с кассиром поставлена «на паузу» ⏸, потому что нужно подождать 🕙, пока бургеры будут готовы. -Но отойдя с номерком от прилавка, вы садитесь за столик и можете переключить 🔀 внимание -на свою возлюбленную 😍 и "работать" ⏯ 🤓 уже над этим. И вот вы снова очень -"продуктивны" 🤓, мило болтаете вдвоём и всё такое 😍. +Но, отойдя от стойки и сев за столик с номерком, вы можете переключить 🔀 внимание на свою возлюбленную и «поработать» ⏯ 🤓 над этим. Снова очень «продуктивно» — флирт с вашей возлюбленной 😍. -В какой-то момент кассир 💁 поместит на табло ваш номер, подразумевая, что бургеры готовы 🍔, но вы не станете подскакивать как умалишённый, лишь только увидев на экране свою очередь. Вы уверены, что ваши бургеры 🍔 никто не утащит, ведь у вас свой номерок, а у других свой. +Потом кассир 💁 «говорит»: «Я закончил делать бургеры», — выводя ваш номер на табло, но вы не подпрыгиваете как сумасшедший в ту же секунду, как только номер сменился на ваш. Вы знаете, что ваши бургеры никто не украдёт, потому что у вас есть номер вашей очереди, а у других — их. -Поэтому вы подождёте, пока возлюбленная 😍 закончит рассказывать историю (закончите текущую работу ⏯ / задачу в обработке 🤓), -и мило улыбнувшись, скажете, что идёте забирать заказ ⏸. +Поэтому вы дожидаетесь, пока ваша возлюбленная закончит историю (завершится текущая работа ⏯ / выполняемая задача 🤓), мягко улыбаетесь и говорите, что идёте за бургерами ⏸. -И вот вы подходите к стойке 🔀, к первоначальной задаче, которая уже завершена ⏯, берёте бургеры 🍔, говорите спасибо и относите заказ за столик. На этом заканчивается этап / задача взаимодействия с кассой ⏹. -В свою очередь порождается задача "поедание бургеров" 🔀 ⏯, но предыдущая ("получение бургеров") завершена ⏹. +Затем вы идёте к стойке 🔀, к исходной задаче, которая теперь завершена ⏯, забираете бургеры, благодарите и несёте их к столику. На этом шаг/задача взаимодействия со стойкой завершён ⏹. Это, в свою очередь, создаёт новую задачу — «есть бургеры» 🔀 ⏯, но предыдущая «получить бургеры» — завершена ⏹. -### Параллельные бургеры +### Параллельные бургеры { #parallel-burgers } -Теперь представим, что вместо бургерной "Конкурентные бургеры" вы решили сходить в "Параллельные бургеры". +Теперь представим, что это не «Конкурентные бургеры», а «Параллельные бургеры». -И вот вы идёте со своей возлюбленной 😍 отведать параллельного фастфуда 🍔. +Вы идёте со своей возлюбленной за параллельным фастфудом. -Вы становитесь в очередь пока несколько (пусть будет 8) кассиров, которые по совместительству ещё и повары 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, принимают заказы у посетителей перед вами. +Вы стоите в очереди, пока несколько (скажем, 8) кассиров, которые одновременно являются поварами, принимают заказы у людей перед вами. -При этом клиенты не отходят от стойки и ждут 🕙 получения еды, поскольку каждый -из 8 кассиров идёт на кухню готовить бургеры 🍔, а только потом принимает следующий заказ. +Все перед вами ждут, пока их бургеры будут готовы, не отходя от стойки, потому что каждый из 8 кассиров сразу идёт готовить бургер перед тем, как принять следующий заказ. -Наконец настаёт ваша очередь, и вы просите два самых навороченных бургера 🍔, один для дамы сердца 😍, а другой себе. + -Ни о чём не жалея, расплачиваетесь 💸. +Наконец ваша очередь: вы заказываете 2 очень «навороченных» бургера — для вашей возлюбленной и для себя. -И кассир уходит на кухню 👨‍🍳. +Вы платите 💸. -Вам приходится ждать перед стойкой 🕙, чтобы никто по случайности не забрал ваши бургеры 🍔, ведь никаких номерков у вас нет. + -Поскольку вы с возлюбленной 😍 хотите получить заказ вовремя 🕙, и следите за тем, чтобы никто не вклинился в очередь, -у вас не получается уделять должного внимание своей даме сердца 😞. +Кассир уходит на кухню. -Это "синхронная" работа, вы "синхронизированы" с кассиром/поваром 👨‍🍳. Приходится ждать 🕙 у стойки, -когда кассир/повар 👨‍🍳 закончит делать бургеры 🍔 и вручит вам заказ, иначе его случайно может забрать кто-то другой. +Вы ждёте, стоя у стойки 🕙, чтобы никто не забрал ваши бургеры раньше вас, так как никаких номерков нет. -Наконец кассир/повар 👨‍🍳 возвращается с бургерами 🍔 после невыносимо долгого ожидания 🕙 за стойкой. + -Вы скорее забираете заказ 🍔 и идёте с возлюбленной 😍 за столик. +Так как вы со своей возлюбленной заняты тем, чтобы никто не встал перед вами и не забрал ваши бургеры, как только они появятся, вы не можете уделить внимание своей возлюбленной. 😞 -Там вы просто едите эти бургеры, и на этом всё 🍔 ⏹. +Это «синхронная» работа, вы «синхронизированы» с кассиром/поваром 👨‍🍳. Вам нужно ждать 🕙 и находиться там в точный момент, когда кассир/повар 👨‍🍳 закончит бургеры и вручит их вам, иначе их может забрать кто-то другой. -Вам не особо удалось пообщаться, потому что большую часть времени 🕙 пришлось провести у кассы 😞. + ---- +Затем ваш кассир/повар 👨‍🍳 наконец возвращается с вашими бургерами, после долгого ожидания 🕙 у стойки. -В описанном сценарии вы компьютер / программа 🤖 с двумя исполнителями (вы и ваша возлюбленная 😍), -на протяжении долгого времени 🕙 вы оба уделяете всё внимание ⏯ задаче "ждать на кассе". + -В этом ресторане быстрого питания 8 исполнителей (кассиров/поваров) 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳. -Хотя в бургерной конкурентного типа было всего два (один кассир и один повар) 💁 👨‍🍳. +Вы берёте бургеры и идёте со своей возлюбленной к столику. -Несмотря на обилие работников, опыт в итоге получился не из лучших 😞. +Вы просто их съедаете — и всё. ⏹ + + + +Разговоров и флирта было немного, потому что большую часть времени вы ждали 🕙 у стойки. 😞 + +/// info | Информация + +Прекрасные иллюстрации от Ketrina Thompson. 🎨 + +/// --- -Так бы выглядел аналог истории про бургерную 🍔 в "параллельном" мире. +В этом сценарии «параллельных бургеров» вы — компьютер/программа 🤖 с двумя процессорами (вы и ваша возлюбленная), оба ждут 🕙 и уделяют внимание ⏯ тому, чтобы «ждать у стойки» 🕙 долгое время. + +В ресторане 8 процессоров (кассиров/поваров). Тогда как в «конкурентных бургерах» могло быть только 2 (один кассир и один повар). -Вот более реалистичный пример. Представьте себе банк. +И всё же финальный опыт — не самый лучший. 😞 -До недавних пор в большинстве банков было несколько кассиров 👨‍💼👨‍💼👨‍💼👨‍💼 и длинные очереди 🕙🕙🕙🕙🕙🕙🕙🕙. +--- -Каждый кассир обслуживал одного клиента, потом следующего 👨‍💼⏯. +Это была параллельная версия истории про бургеры. 🍔 -Нужно было долгое время 🕙 стоять перед окошком вместе со всеми, иначе пропустишь свою очередь. +Для более «жизненного» примера представьте банк. -Сомневаюсь, что у вас бы возникло желание прийти с возлюбленной 😍 в банк 🏦 оплачивать налоги. +До недавнего времени в большинстве банков было несколько кассиров 👨‍💼👨‍💼👨‍💼👨‍💼 и длинная очередь 🕙🕙🕙🕙🕙🕙🕙🕙. -### Выводы о бургерах +Все кассиры делают всю работу с одним клиентом за другим 👨‍💼⏯. -В нашей истории про поход в фастфуд за бургерами приходится много ждать 🕙, -поэтому имеет смысл организовать конкурентную систему ⏸🔀⏯. +И вам приходится долго 🕙 стоять в очереди, иначе вы потеряете свою очередь. -И то же самое с большинством веб-приложений. +Вы вряд ли захотите взять свою возлюбленную 😍 с собой, чтобы заняться делами в банке 🏦. -Пользователей очень много, но ваш сервер всё равно вынужден ждать 🕙 запросы по их слабому интернет-соединению. +### Вывод про бургеры { #burger-conclusion } -Потом снова ждать 🕙, пока вернётся ответ. +В этом сценарии «фастфуда с вашей возлюбленной», так как много ожидания 🕙, гораздо логичнее иметь конкурентную систему ⏸🔀⏯. - -Это ожидание 🕙 измеряется микросекундами, но если всё сложить, то набегает довольно много времени. +Так обстоит дело и с большинством веб-приложений. -Вот почему есть смысл использовать асинхронное ⏸🔀⏯ программирование при построении веб-API. +Очень много пользователей, но ваш сервер ждёт 🕙, пока их не самое хорошее соединение отправит их запросы. -Большинство популярных фреймворков (включая Flask и Django) создавались -до появления в Python новых возможностей асинхронного программирования. Поэтому -их можно разворачивать с поддержкой параллельного исполнения или асинхронного -программирования старого типа, которое не настолько эффективно. +А затем снова ждёт 🕙, пока отправятся ответы. -При том, что основная спецификация асинхронного взаимодействия Python с веб-сервером -(ASGI) -была разработана командой Django для внедрения поддержки веб-сокетов. +Это «ожидание» 🕙 измеряется микросекундами, но если всё сложить, то в сумме получается много ожидания. -Именно асинхронность сделала NodeJS таким популярным (несмотря на то, что он не параллельный), -и в этом преимущество Go как языка программирования. +Вот почему асинхронный ⏸🔀⏯ код очень уместен для веб-API. -И тот же уровень производительности даёт **FastAPI**. +Именно такая асинхронность сделала NodeJS популярным (хотя NodeJS — не параллельный), и это сильная сторона Go как языка программирования. -Поскольку можно использовать преимущества параллелизма и асинхронности вместе, -вы получаете производительность лучше, чем у большинства протестированных NodeJS фреймворков -и на уровне с Go, который является компилируемым языком близким к C (всё благодаря Starlette). +Того же уровня производительности вы получаете с **FastAPI**. -### Получается, конкурентность лучше параллелизма? +А так как можно одновременно использовать параллелизм и асинхронность, вы получаете производительность выше, чем у большинства протестированных фреймворков на NodeJS и на уровне Go, который — компилируемый язык, ближе к C (всё благодаря Starlette). -Нет! Мораль истории совсем не в этом. +### Конкурентность лучше параллелизма? { #is-concurrency-better-than-parallelism } -Конкурентность отличается от параллелизма. Она лучше в **конкретных** случаях, где много времени приходится на ожидание. -Вот почему она зачастую лучше параллелизма при разработке веб-приложений. Но это не значит, что конкурентность лучше в любых сценариях. +Нет! Мораль истории не в этом. -Давайте посмотрим с другой стороны, представьте такую картину: +Конкурентность отличается от параллелизма. И она лучше в **конкретных** сценариях, где много ожидания. Поэтому при разработке веб-приложений она обычно намного лучше параллелизма. Но не во всём. -> Вам нужно убраться в большом грязном доме. +Чтобы уравновесить это, представьте такую короткую историю: + +> Вам нужно убрать большой грязный дом. *Да, это вся история*. --- -Тут не нужно нигде ждать 🕙, просто есть куча работы в разных частях дома. +Здесь нигде нет ожидания 🕙, просто очень много работы в разных местах дома. -Можно организовать очередь как в примере с бургерами, сначала гостиная, потом кухня, -но это ни на что не повлияет, поскольку вы нигде не ждёте 🕙, а просто трёте да моете. +Можно организовать «очереди» как в примере с бургерами — сначала гостиная, потом кухня, — но так как вы ничего не ждёте 🕙, а просто убираете и убираете, очереди ни на что не повлияют. -И понадобится одинаковое количество времени с очередью (конкурентностью) и без неё, -и работы будет сделано тоже одинаковое количество. +На завершение уйдёт одинаковое время — с очередями (конкурентностью) и без них — и объём выполненной работы будет одинаковым. -Однако в случае, если бы вы могли привести 8 бывших кассиров/поваров, а ныне уборщиков 👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳👩‍🍳👨‍🍳, -и каждый из них (вместе с вами) взялся бы за свой участок дома, -с такой помощью вы бы закончили намного быстрее, делая всю работу **параллельно**. +Но в этом случае, если бы вы могли привести 8 бывших кассиров/поваров, а теперь — уборщиков, и каждый из них (плюс вы) взял бы свою зону дома для уборки, вы могли бы сделать всю работу **параллельно**, с дополнительной помощью, и завершить гораздо быстрее. -В описанном сценарии каждый уборщик (включая вас) был бы исполнителем, занятым на своём участке работы. +В этом сценарии каждый уборщик (включая вас) был бы процессором, выполняющим свою часть работы. -И поскольку большую часть времени выполнения занимает реальная работа (а не ожидание), -а работу в компьютере делает ЦП, -такие задачи называют ограниченными производительностью процессора. +И так как основное время выполнения уходит на реальную работу (а не ожидание), а работу в компьютере выполняет CPU, такие задачи называют «ограниченными процессором» (CPU bound). --- -Ограничение по процессору проявляется в операциях, где требуется выполнять сложные математические вычисления. +Типичные примеры CPU-bound операций — те, которые требуют сложной математической обработки. Например: -* Обработка **звука** или **изображений**. -* **Компьютерное зрение**: изображение состоит из миллионов пикселей, в каждом пикселе 3 составляющих цвета, -обработка обычно требует проведения расчётов по всем пикселям сразу. -* **Машинное обучение**: здесь обычно требуется умножение "матриц" и "векторов". -Представьте гигантскую таблицу с числами в Экселе, и все их надо одновременно перемножить. -* **Глубокое обучение**: это область *машинного обучения*, поэтому сюда подходит то же описание. -Просто у вас будет не одна таблица в Экселе, а множество. В ряде случаев используется -специальный процессор для создания и / или использования построенных таким образом моделей. +* Обработка **аудио** или **изображений**. +* **Компьютерное зрение**: изображение состоит из миллионов пикселей, каждый пиксель имеет 3 значения/цвета; обычно требуется вычислить что-то для всех этих пикселей одновременно. +* **Машинное обучение**: обычно требует множества умножений «матриц» и «векторов». Представьте огромную таблицу с числами и умножение всех этих чисел «одновременно». +* **Глубокое обучение**: это подполе Машинного обучения, так что всё вышесказанное применимо. Просто это не одна таблица чисел, а их огромный набор, и во многих случаях вы используете специальный процессор, чтобы строить и/или использовать такие модели. -### Конкурентность + параллелизм: Веб + машинное обучение +### Конкурентность + параллелизм: Веб + Машинное обучение { #concurrency-parallelism-web-machine-learning } -**FastAPI** предоставляет возможности конкуретного программирования, -которое очень распространено в веб-разработке (именно этим славится NodeJS). +С **FastAPI** вы можете использовать преимущества конкурентности, что очень распространено в веб-разработке (это та же основная «фишка» NodeJS). -Кроме того вы сможете использовать все преимущества параллелизма и -многопроцессности (когда несколько процессов работают параллельно), -если рабочая нагрузка предполагает **ограничение по процессору**, -как, например, в системах машинного обучения. +Но вы также можете использовать выгоды параллелизма и многопроцессности (когда несколько процессов работают параллельно) для рабочих нагрузок, **ограниченных процессором** (CPU bound), как в системах Машинного обучения. -Необходимо также отметить, что Python является главным языком в области -**дата-сайенс**, -машинного обучения и, особенно, глубокого обучения. Всё это делает FastAPI -отличным вариантом (среди многих других) для разработки веб-API и приложений -в области дата-сайенс / машинного обучения. +Плюс к этому простой факт, что Python — основной язык для **Data Science**, Машинного обучения и особенно Глубокого обучения, делает FastAPI очень хорошим выбором для веб-API и приложений в области Data Science / Машинного обучения (среди многих других). -Как добиться такого параллелизма в эксплуатации описано в разделе [Развёртывание](deployment/index.md){.internal-link target=_blank}. +Как добиться такого параллелизма в продакшн, см. раздел [Развёртывание](deployment/index.md){.internal-link target=_blank}. -## `async` и `await` +## `async` и `await` { #async-and-await } -В современных версиях Python разработка асинхронного кода реализована очень интуитивно. -Он выглядит как обычный "последовательный" код и самостоятельно выполняет "ожидание", когда это необходимо. +В современных версиях Python есть очень интуитивный способ определять асинхронный код. Это делает его похожим на обычный «последовательный» код, а «ожидание» выполняется за вас в нужные моменты. -Если некая операция требует ожидания перед тем, как вернуть результат, и -поддерживает современные возможности Python, код можно написать следующим образом: +Когда есть операция, которой нужно подождать перед тем, как вернуть результат, и она поддерживает эти новые возможности Python, вы можете написать так: ```Python burgers = await get_burgers(2) ``` -Главное здесь слово `await`. Оно сообщает интерпретатору, что необходимо дождаться ⏸ -пока `get_burgers(2)` закончит свои дела 🕙, и только после этого сохранить результат в `burgers`. -Зная это, Python может пока переключиться на выполнение других задач 🔀 ⏯ -(например получение следующего запроса). +Ключ здесь — `await`. Он говорит Python, что нужно подождать ⏸, пока `get_burgers(2)` закончит своё дело 🕙, прежде чем сохранять результат в `burgers`. Благодаря этому Python будет знать, что за это время можно заняться чем-то ещё 🔀 ⏯ (например, принять другой запрос). -Чтобы ключевое слово `await` сработало, оно должно находиться внутри функции, -которая поддерживает асинхронность. Для этого вам просто нужно объявить её как `async def`: +Чтобы `await` работал, он должен находиться внутри функции, которая поддерживает такую асинхронность. Для этого просто объявите её с `async def`: ```Python hl_lines="1" async def get_burgers(number: int): - # Готовим бургеры по специальному асинхронному рецепту + # Сделать что-то асинхронное, чтобы приготовить бургеры return burgers ``` @@ -355,26 +325,22 @@ async def get_burgers(number: int): ```Python hl_lines="2" # Это не асинхронный код def get_sequential_burgers(number: int): - # Готовим бургеры последовательно по шагам + # Сделать что-то последовательное, чтобы приготовить бургеры return burgers ``` -Объявление `async def` указывает интерпретатору, что внутри этой функции -следует ожидать выражений `await`, и что можно поставить выполнение такой функции на "паузу" ⏸ и -переключиться на другие задачи 🔀, с тем чтобы вернуться сюда позже. +С `async def` Python знает, что внутри этой функции нужно учитывать выражения `await` и что выполнение такой функции можно «приостанавливать» ⏸ и идти делать что-то ещё 🔀, чтобы потом вернуться. -Если вы хотите вызвать функцию с `async def`, вам нужно "ожидать" её. -Поэтому такое не сработает: +Когда вы хотите вызвать функцию, объявленную с `async def`, нужно её «ожидать». Поэтому вот так не сработает: ```Python -# Это не заработает, поскольку get_burgers объявлена с использованием async def +# Это не сработает, потому что get_burgers определена с: async def burgers = get_burgers(2) ``` --- -Если сторонняя библиотека требует вызывать её с ключевым словом `await`, -необходимо писать *функции обработки пути* с использованием `async def`, например: +Итак, если вы используете библиотеку, которую можно вызывать с `await`, вам нужно создать *функцию-обработчик пути*, которая её использует, с `async def`, например: ```Python hl_lines="2-3" @app.get('/burgers') @@ -383,129 +349,96 @@ async def read_burgers(): return burgers ``` -### Технические подробности +### Более технические подробности { #more-technical-details } + +Вы могли заметить, что `await` можно использовать только внутри функций, определённых с `async def`. -Как вы могли заметить, `await` может применяться только в функциях, объявленных с использованием `async def`. +Но при этом функции, определённые с `async def`, нужно «ожидать». Значит, функции с `async def` тоже можно вызывать только из функций, определённых с `async def`. - -Но выполнение такой функции необходимо "ожидать" с помощью `await`. -Это означает, что её можно вызвать только из другой функции, которая тоже объявлена с `async def`. +Так что же с «яйцом и курицей» — как вызвать первую `async` функцию? -Но как же тогда появилась первая курица? В смысле... как нам вызвать первую асинхронную функцию? +Если вы работаете с **FastAPI**, вам не о чем беспокоиться, потому что этой «первой» функцией будет ваша *функция-обработчик пути*, а FastAPI знает, как сделать всё правильно. -При работе с **FastAPI** просто не думайте об этом, потому что "первой" функцией является ваша *функция обработки пути*, -и дальше с этим разберётся FastAPI. +Но если вы хотите использовать `async` / `await` без FastAPI, вы тоже можете это сделать. -Кроме того, если хотите, вы можете использовать синтаксис `async` / `await` и без FastAPI. +### Пишите свой асинхронный код { #write-your-own-async-code } -### Пишите свой асинхронный код +Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми и со стандартной библиотекой Python asyncio, и с Trio. -Starlette (и **FastAPI**) основаны на AnyIO, что делает их совместимыми как со стандартной библиотекой asyncio в Python, так и с Trio. +В частности, вы можете напрямую использовать AnyIO для продвинутых сценариев конкурентности, где в вашем коде нужны более сложные паттерны. -В частности, вы можете напрямую использовать AnyIO в тех проектах, где требуется более сложная логика работы с конкурентностью. +И даже если вы не используете FastAPI, вы можете писать свои асинхронные приложения с AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например, *структурную конкурентность*). -Даже если вы не используете FastAPI, вы можете писать асинхронные приложения с помощью AnyIO, чтобы они были максимально совместимыми и получали его преимущества (например *структурную конкурентность*). +Я создал ещё одну библиотеку поверх AnyIO, тонкий слой, чтобы немного улучшить аннотации типов и получить более качественное **автозавершение**, **ошибки прямо в редакторе** и т.д. Там также есть дружелюбное введение и руководство, чтобы помочь вам **понять** и писать **свой собственный асинхронный код**: Asyncer. Она особенно полезна, если вам нужно **комбинировать асинхронный код с обычным** (блокирующим/синхронным) кодом. -### Другие виды асинхронного программирования +### Другие формы асинхронного кода { #other-forms-of-asynchronous-code } -Стиль написания кода с `async` и `await` появился в языке Python относительно недавно. +Такой стиль использования `async` и `await` относительно новый в языке. -Но он сильно облегчает работу с асинхронным кодом. +Но он сильно упрощает работу с асинхронным кодом. -Ровно такой же синтаксис (ну или почти такой же) недавно был включён в современные версии JavaScript (в браузере и NodeJS). +Такой же (или почти такой же) синтаксис недавно появился в современных версиях JavaScript (в браузере и NodeJS). -До этого поддержка асинхронного кода была реализована намного сложнее, и его было труднее воспринимать. +До этого работа с асинхронным кодом была заметно сложнее и труднее для понимания. -В предыдущих версиях Python для этого использовались потоки или Gevent. Но такой код намного сложнее понимать, отлаживать и мысленно представлять. +В предыдущих версиях Python можно было использовать потоки или Gevent. Но такой код гораздо сложнее понимать, отлаживать и держать в голове. -Что касается JavaScript (в браузере и NodeJS), раньше там использовали для этой цели -"обратные вызовы". Что выливалось в -"ад обратных вызовов". +В прежних версиях NodeJS/браузерного JavaScript вы бы использовали «callbacks» (обратные вызовы), что приводит к «callback hell» (ад обратных вызовов). -## Сопрограммы +## Сопрограммы { #coroutines } -**Корути́на** (или же сопрограмма) — это крутое словечко для именования той сущности, -которую возвращает функция `async def`. Python знает, что её можно запустить, как и обычную функцию, -но кроме того сопрограмму можно поставить на паузу ⏸ в том месте, где встретится слово `await`. +**Сопрограмма** (coroutine) — это просто «навороченное» слово для того, что возвращает функция `async def`. Python знает, что это похоже на функцию: её можно запустить, она когда-нибудь завершится, но её выполнение может приостанавливаться ⏸ внутри, когда встречается `await`. -Всю функциональность асинхронного программирования с использованием `async` и `await` -часто обобщают словом "корутины". Они аналогичны "горутинам", ключевой особенности -языка Go. +Часто всю функциональность использования асинхронного кода с `async` и `await` кратко называют «сопрограммами». Это сопоставимо с ключевой особенностью Go — «goroutines». -## Заключение +## Заключение { #conclusion } -В самом начале была такая фраза: +Вернёмся к той же фразе: -> Современные версии Python поддерживают разработку так называемого -**"асинхронного кода"** посредством написания **"сопрограмм"** с использованием -синтаксиса **`async` и `await`**. +> Современные версии Python поддерживают **«асинхронный код»** с помощью **«сопрограмм»** (coroutines) и синтаксиса **`async` и `await`**. -Теперь всё должно звучать понятнее. ✨ +Теперь это должно звучать понятнее. ✨ -На этом основана работа FastAPI (посредством Starlette), и именно это -обеспечивает его высокую производительность. +Именно это «движет» FastAPI (через Starlette) и обеспечивает столь впечатляющую производительность. -## Очень технические подробности +## Очень технические подробности { #very-technical-details } -/// warning +/// warning | Предупреждение -Этот раздел читать не обязательно. +Скорее всего, этот раздел можно пропустить. -Здесь приводятся подробности внутреннего устройства **FastAPI**. +Здесь — очень технические подробности о том, как **FastAPI** работает «под капотом». -Но если вы обладаете техническими знаниями (корутины, потоки, блокировка и т. д.) -и вам интересно, как FastAPI обрабатывает `async def` в отличие от обычных `def`, -читайте дальше. +Если у вас есть достаточно технических знаний (сопрограммы, потоки, блокировки и т.д.) и вам интересно, как FastAPI обрабатывает `async def` по сравнению с обычным `def`, — вперёд. /// -### Функции обработки пути +### Функции-обработчики пути { #path-operation-functions } -Когда вы объявляете *функцию обработки пути* обычным образом с ключевым словом `def` -вместо `async def`, FastAPI ожидает её выполнения, запустив функцию во внешнем -пуле потоков, а не напрямую (это бы заблокировало сервер). +Когда вы объявляете *функцию-обработчик пути* обычным `def` вместо `async def`, она запускается во внешнем пуле потоков, который затем «ожидается», вместо прямого вызова (прямой вызов заблокировал бы сервер). -Если ранее вы использовали другой асинхронный фреймворк, который работает иначе, -и привыкли объявлять простые вычислительные *функции* через `def` ради -незначительного прироста скорости (порядка 100 наносекунд), обратите внимание, -что с **FastAPI** вы получите противоположный эффект. В таком случае больше подходит -`async def`, если только *функция обработки пути* не использует код, приводящий -к блокировке I/O. - +Если вы пришли из другого async-фреймворка, который работает иначе, и привыкли объявлять тривиальные *функции-обработчики пути*, выполняющие только вычисления, через простой `def` ради крошечной выгоды в производительности (около 100 наносекунд), обратите внимание: в **FastAPI** эффект будет противоположным. В таких случаях лучше использовать `async def`, если только ваши *функции-обработчики пути* не используют код, выполняющий блокирующий I/O. - -Но в любом случае велика вероятность, что **FastAPI** [окажется быстрее](index.md#_11){.internal-link target=_blank} -другого фреймворка (или хотя бы на уровне с ним). +Тем не менее, в обоих случаях велика вероятность, что **FastAPI** [всё равно будет быстрее](index.md#performance){.internal-link target=_blank} (или как минимум сопоставим) с вашим предыдущим фреймворком. -### Зависимости +### Зависимости { #dependencies } -То же относится к зависимостям. Если это обычная функция `def`, а не `async def`, -она запускается во внешнем пуле потоков. +То же относится к [зависимостям](tutorial/dependencies/index.md){.internal-link target=_blank}. Если зависимость — это обычная функция `def`, а не `async def`, она запускается во внешнем пуле потоков. -### Подзависимости +### Подзависимости { #sub-dependencies } -Вы можете объявить множество ссылающихся друг на друга зависимостей и подзависимостей -(в виде параметров при определении функции). Какие-то будут созданы с помощью `async def`, -другие обычным образом через `def`, и такая схема вполне работоспособна. Функции, -объявленные с помощью `def` будут запускаться на внешнем потоке (из пула), -а не с помощью `await`. +У вас может быть несколько зависимостей и [подзависимостей](tutorial/dependencies/sub-dependencies.md){.internal-link target=_blank}, которые требуют друг друга (в виде параметров определений функций): часть из них может быть объявлена с `async def`, а часть — обычным `def`. Всё будет работать, а те, что объявлены обычным `def`, будут вызываться во внешнем потоке (из пула), а не «ожидаться». -### Другие служебные функции +### Другие служебные функции { #other-utility-functions } -Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять -с использованием `def` или `async def`. FastAPI не будет влиять на то, как вы -их запускаете. +Любые другие служебные функции, которые вы вызываете напрямую, можно объявлять обычным `def` или `async def`, и FastAPI не будет влиять на то, как вы их вызываете. -Этим они отличаются от функций, которые FastAPI вызывает самостоятельно: -*функции обработки пути* и зависимости. +В отличие от функций, которые FastAPI вызывает за вас: *функции-обработчики пути* и зависимости. -Если служебная функция объявлена с помощью `def`, она будет вызвана напрямую -(как вы и написали в коде), а не в отдельном потоке. Если же она объявлена с -помощью `async def`, её вызов должен осуществляться с ожиданием через `await`. +Если служебная функция — обычная функция с `def`, она будет вызвана напрямую (как вы и пишете в коде), не в пуле потоков; если функция объявлена с `async def`, тогда при её вызове в вашем коде вы должны использовать `await`. --- - -Ещё раз повторим, что все эти технические подробности полезны, только если вы специально их искали. +Снова: это очень технические подробности, полезные, вероятно, только если вы целенаправленно их ищете. -В противном случае просто ознакомьтесь с основными принципами в разделе выше: Нет времени?. +Иначе вам достаточно руководствоваться рекомендациями из раздела выше: Нет времени?. diff --git a/docs/ru/docs/help-fastapi.md b/docs/ru/docs/help-fastapi.md index 2f73c3c10..6bfabb96c 100644 --- a/docs/ru/docs/help-fastapi.md +++ b/docs/ru/docs/help-fastapi.md @@ -1,261 +1,255 @@ -# Помочь FastAPI - Получить помощь +# Помочь FastAPI - Получить помощь { #help-fastapi-get-help } Нравится ли Вам **FastAPI**? -Хотели бы Вы помочь FastAPI, его пользователям и автору? +Хотели бы Вы помочь FastAPI, другим пользователям и автору? -Может быть у Вас возникли трудности с **FastAPI** и Вам нужна помощь? +Или Вы хотите получить помощь по **FastAPI**? -Есть несколько очень простых способов оказания помощи (иногда достаточно всего лишь одного или двух кликов). +Есть несколько очень простых способов помочь (иногда достаточно всего лишь одного-двух кликов). И также есть несколько способов получить помощь. -## Подписаться на новостную рассылку +## Подписаться на новостную рассылку { #subscribe-to-the-newsletter } Вы можете подписаться на редкую [новостную рассылку **FastAPI и его друзья**](newsletter.md){.internal-link target=_blank} и быть в курсе о: * Новостях о FastAPI и его друзьях 🚀 * Руководствах 📝 * Возможностях ✨ -* Исправлениях 🚨 +* Ломающих изменениях 🚨 * Подсказках и хитростях ✅ -## Подписаться на FastAPI в X (Twitter) +## Подписаться на FastAPI в X (Twitter) { #follow-fastapi-on-x-twitter } Подписаться на @fastapi в **X (Twitter)** для получения наисвежайших новостей о **FastAPI**. 🐦 -## Добавить **FastAPI** звезду на GitHub +## Добавить **FastAPI** звезду на GitHub { #star-fastapi-in-github } -Вы можете добавить FastAPI "звезду" на GitHub (кликнуть на кнопку звезды в верхнем правом углу экрана): https://github.com/fastapi/fastapi. ⭐️ +Вы можете добавить FastAPI "звезду" на GitHub (кликнув на кнопку звезды в правом верхнем углу): https://github.com/fastapi/fastapi. ⭐️ -Чем больше звёзд, тем легче другим пользователям найти нас и увидеть, что проект уже стал полезным для многих. +Чем больше звёзд, тем легче другим пользователям найти проект и увидеть, что он уже оказался полезным для многих. -## Отслеживать свежие выпуски в репозитории на GitHub +## Отслеживать свежие выпуски в репозитории на GitHub { #watch-the-github-repository-for-releases } -Вы можете "отслеживать" FastAPI на GitHub (кликните по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 +Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 -Там же Вы можете указать в настройках - "Releases only". +Там же Вы можете выбрать "Releases only". С такой настройкой Вы будете получать уведомления на вашу электронную почту каждый раз, когда появится новый релиз (новая версия) **FastAPI** с исправлениями ошибок и новыми возможностями. -## Связаться с автором +## Связаться с автором { #connect-with-the-author } -Можно связаться со мной (Себястьян Рамирез / `tiangolo`), автором FastAPI. +Можно связаться со мной (Sebastián Ramírez / `tiangolo`), автором. Вы можете: * Подписаться на меня на **GitHub**. * Посмотреть другие мои проекты с открытым кодом, которые могут быть полезны Вам. - * Подписавшись на меня Вы сможете получать уведомления, что я создал новый проект с открытым кодом,. + * Подписаться, чтобы видеть, когда я создаю новый проект с открытым кодом. * Подписаться на меня в **X (Twitter)** или в Mastodon. - * Поделиться со мной, как Вы используете FastAPI (я обожаю читать про это). - * Получать уведомления, когда я делаю объявления и представляю новые инструменты. + * Поделиться со мной, как Вы используете FastAPI (я обожаю это читать). + * Узнавать, когда я делаю объявления или выпускаю новые инструменты. * Вы также можете подписаться на @fastapi в X (Twitter) (это отдельный аккаунт). -* Подписаться на меня в **Linkedin**. - * Получать уведомления, когда я делаю объявления и представляю новые инструменты (правда чаще всего я использую X (Twitter) 🤷‍♂). -* Читать, что я пишу (или подписаться на меня) в **Dev.to** или в **Medium**. - * Читать другие идеи, статьи и читать об инструментах созданных мной. - * Подпишитесь на меня, чтобы прочитать, когда я опубликую что-нибудь новое. +* Подписаться на меня в **LinkedIn**. + * Узнавать, когда я делаю объявления или выпускаю новые инструменты (хотя чаще я использую X (Twitter) 🤷‍♂). +* Читать, что я пишу (или подписаться на меня) на **Dev.to** или **Medium**. + * Читать другие идеи, статьи и о созданных мной инструментах. + * Подписаться, чтобы читать, когда я публикую что-то новое. -## Оставить сообщение в X (Twitter) о **FastAPI** +## Оставить сообщение в X (Twitter) о **FastAPI** { #tweet-about-fastapi } -Оставьте сообщение в X (Twitter) о **FastAPI** и позвольте мне и другим узнать - почему он Вам нравится. 🎉 +Оставьте сообщение в X (Twitter) о **FastAPI** и позвольте мне и другим узнать, почему он Вам нравится. 🎉 -Я люблю узнавать о том, как **FastAPI** используется, что Вам понравилось в нём, в каких проектах/компаниях Вы используете его и т.п. +Я люблю узнавать о том, как **FastAPI** используется, что Вам понравилось в нём, в каких проектах/компаниях Вы его используете и т.д. -## Оставить голос за FastAPI +## Оставить голос за FastAPI { #vote-for-fastapi } * Голосуйте за **FastAPI** в Slant. -* Голосуйте за **FastAPI** в AlternativeTo. -* Расскажите, как Вы используете **FastAPI** на StackShare. +* Голосуйте за **FastAPI** в AlternativeTo. +* Расскажите, что Вы используете **FastAPI** на StackShare. -## Помочь другим с их проблемами на GitHub +## Помочь другим с вопросами на GitHub { #help-others-with-questions-in-github } -Вы можете посмотреть, какие проблемы испытывают другие люди и попытаться помочь им. Чаще всего это вопросы, на которые, весьма вероятно, Вы уже знаете ответ. 🤓 +Вы можете попробовать помочь другим с их вопросами в: -Если Вы будете много помогать людям с решением их проблем, Вы можете стать официальным [Экспертом FastAPI](fastapi-people.md#_3){.internal-link target=_blank}. 🎉 +* GitHub Discussions +* GitHub Issues -Только помните, самое важное при этом - доброта. Столкнувшись с проблемой, люди расстраиваются и часто задают вопросы не лучшим образом, но постарайтесь быть максимально доброжелательным. 🤗 +Во многих случаях Вы уже можете знать ответы на эти вопросы. 🤓 -Идея сообщества **FastAPI** в том, чтобы быть добродушным и гостеприимными. Не допускайте издевательств или неуважительного поведения по отношению к другим. Мы должны заботиться друг о друге. +Если Вы много помогаете людям с их вопросами, Вы станете официальным [Экспертом FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. 🎉 + +Только помните, самое важное — постарайтесь быть добрыми. Люди приходят со своими разочарованиями и часто задают вопросы не лучшим образом, но постарайтесь, насколько можете, быть доброжелательными. 🤗 + +Идея сообщества **FastAPI** — быть доброжелательным и гостеприимным. В то же время не допускайте травлю или неуважительное поведение по отношению к другим. Мы должны заботиться друг о друге. --- -Как помочь другим с их проблемами: +Как помочь другим с вопросами (в обсуждениях или Issues): -### Понять вопрос +### Понять вопрос { #understand-the-question } -* Удостоверьтесь, что поняли **цель** и обстоятельства случая вопрошающего. +* Убедитесь, что поняли **цель** и кейс использования задающего вопрос. -* Затем проверьте, что вопрос (в подавляющем большинстве - это вопросы) Вам **ясен**. +* Затем проверьте, что вопрос (в подавляющем большинстве это вопросы) сформулирован **ясно**. -* Во многих случаях вопрос касается решения, которое пользователь придумал сам, но может быть и решение **получше**. Если Вы поймёте проблему и обстоятельства случая, то сможете предложить **альтернативное решение**. +* Во многих случаях спрашивают о воображаемом решении пользователя, но может быть решение **получше**. Если Вы лучше поймёте проблему и кейс, сможете предложить **альтернативное решение**. -* Ежели вопрос Вам непонятен, запросите больше **деталей**. +* Если вопрос непонятен, запросите больше **деталей**. -### Воспроизвести проблему +### Воспроизвести проблему { #reproduce-the-problem } -В большинстве случаев есть что-то связанное с **исходным кодом** вопрошающего. +В большинстве случаев и вопросов есть что-то связанное с **исходным кодом** автора. -И во многих случаях будет предоставлен только фрагмент этого кода, которого недостаточно для **воспроизведения проблемы**. +Во многих случаях предоставляют только фрагмент кода, но этого недостаточно, чтобы **воспроизвести проблему**. -* Попросите предоставить минимальный воспроизводимый пример, который можно **скопировать** и запустить локально дабы увидеть такую же ошибку, или поведение, или лучше понять обстоятельства случая. +* Попросите предоставить минимальный воспроизводимый пример, который Вы сможете **скопировать-вставить** и запустить локально, чтобы увидеть ту же ошибку или поведение, или лучше понять их кейс. -* Если на Вас нахлынуло великодушие, то можете попытаться **создать похожий пример** самостоятельно, основываясь только на описании проблемы. Но имейте в виду, что это может занять много времени и, возможно, стоит сначала позадавать вопросы для прояснения проблемы. +* Если чувствуете себя особенно великодушными, можете попытаться **создать такой пример** сами, основываясь только на описании проблемы. Просто помните, что это может занять много времени, и, возможно, сначала лучше попросить уточнить проблему. -### Предложить решение +### Предложить решение { #suggest-solutions } -* После того как Вы поняли вопрос, Вы можете дать **ответ**. +* После того как Вы поняли вопрос, Вы можете дать возможный **ответ**. -* Следует понять **основную проблему и обстоятельства случая**, потому что может быть решение лучше, чем то, которое пытались реализовать. +* Во многих случаях лучше понять **исходную проблему или кейс**, потому что может существовать способ решить её лучше, чем то, что пытаются сделать. -### Попросить закрыть проблему +### Попросить закрыть { #ask-to-close } -Если Вам ответили, высоки шансы, что Вам удалось решить проблему, поздравляю, **Вы - герой**! 🦸 +Если Вам ответили, велика вероятность, что Вы решили их проблему, поздравляю, **Вы — герой**! 🦸 -* В таком случае, если вопрос решён, попросите **закрыть проблему**. +* Теперь, если проблема решена, можно попросить их: + * В GitHub Discussions: пометить комментарий как **answer** (ответ). + * В GitHub Issues: **закрыть** Issue. -## Отслеживать репозиторий на GitHub +## Отслеживать репозиторий на GitHub { #watch-the-github-repository } -Вы можете "отслеживать" FastAPI на GitHub (кликните по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 +Вы можете "отслеживать" FastAPI на GitHub (кликнув по кнопке "watch" наверху справа): https://github.com/fastapi/fastapi. 👀 -Если Вы выберете "Watching" вместо "Releases only", то будете получать уведомления когда кто-либо попросит о помощи с решением его проблемы. +Если Вы выберете "Watching" вместо "Releases only", то будете получать уведомления, когда кто-либо создаёт новый вопрос или Issue. Вы также можете указать, что хотите получать уведомления только о новых Issues, или обсуждениях, или пулл-реквестах и т.д. -Тогда Вы можете попробовать решить эту проблему. +Тогда Вы можете попробовать помочь им с решением этих вопросов. -## Запросить помощь с решением проблемы +## Задать вопросы { #ask-questions } -Вы можете создать новый запрос с просьбой о помощи в репозитории на GitHub, например: +Вы можете создать новый вопрос в репозитории GitHub, например: -* Задать **вопрос** или попросить помощи в решении **проблемы**. -* Предложить новое **улучшение**. +* Задать **вопрос** или спросить о **проблеме**. +* Предложить новую **возможность**. -**Заметка**: Если Вы создаёте подобные запросы, то я попрошу Вас также оказывать аналогичную помощь другим. 😉 +**Заметка**: если Вы это сделаете, то я попрошу Вас также помогать другим. 😉 -## Проверять пул-реквесты +## Проверять пулл-реквесты { #review-pull-requests } -Вы можете помочь мне проверять пул-реквесты других участников. +Вы можете помочь мне проверять пулл-реквесты других участников. -И повторюсь, постарайтесь быть доброжелательным. 🤗 +И, снова, постарайтесь быть доброжелательными. 🤗 --- -О том, что нужно иметь в виду при проверке пул-реквестов: +О том, что нужно иметь в виду и как проверять пулл-реквест: -### Понять проблему +### Понять проблему { #understand-the-problem } -* Во-первых, убедитесь, что **поняли проблему**, которую пул-реквест пытается решить. Для этого может потребоваться продолжительное обсуждение. +* Во-первых, убедитесь, что **поняли проблему**, которую пулл-реквест пытается решить. Возможно, это обсуждалось более подробно в GitHub Discussion или Issue. -* Также есть вероятность, что пул-реквест не актуален, так как проблему можно решить **другим путём**. В таком случае Вы можете указать на этот факт. +* Также есть вероятность, что пулл-реквест не нужен, так как проблему можно решить **другим путём**. Тогда Вы можете предложить или спросить об этом. -### Не переживайте о стиле +### Не переживайте о стиле { #dont-worry-about-style } -* Не стоит слишком беспокоиться о таких вещах, как стиль сообщений в коммитах или количество коммитов. При слиянии пул-реквеста с основной веткой, я буду сжимать и настраивать всё вручную. +* Не стоит слишком беспокоиться о таких вещах, как стиль сообщений в коммитах — при слиянии я выполню squash и настрою коммит вручную. -* Также не беспокойтесь о правилах стиля, для проверки сего есть автоматизированные инструменты. +* Также не беспокойтесь о правилах стиля, это уже проверяют автоматизированные инструменты. -И если всё же потребуется какой-то другой стиль, я попрошу Вас об этом напрямую или добавлю сам коммиты с необходимыми изменениями. +Если будет нужна какая-то другая стилистика или единообразие, я попрошу об этом напрямую или добавлю поверх свои коммиты с нужными изменениями. -### Проверить код +### Проверить код { #check-the-code } -* Проверьте и прочитайте код, посмотрите, какой он имеет смысл, **запустите его локально** и посмотрите, действительно ли он решает поставленную задачу. +* Проверьте и прочитайте код, посмотрите, логичен ли он, **запустите его локально** и проверьте, действительно ли он решает проблему. -* Затем, используя **комментарий**, сообщите, что Вы сделали проверку, тогда я буду знать, что Вы действительно проверили код. +* Затем оставьте **комментарий**, что Вы это сделали, так я пойму, что Вы действительно проверили код. /// info | Информация -К сожалению, я не могу так просто доверять пул-реквестам, у которых уже есть несколько одобрений. +К сожалению, я не могу просто доверять PR-ам только потому, что у них есть несколько одобрений. -Бывали случаи, что пул-реквесты имели 3, 5 или больше одобрений, вероятно из-за привлекательного описания, но когда я проверял эти пул-реквесты, они оказывались сломаны, содержали ошибки или вовсе не решали проблему, которую, как они утверждали, должны были решить. 😅 +Несколько раз было так, что у PR-ов было 3, 5 или больше одобрений, вероятно из-за привлекательного описания, но когда я их проверял, они оказывались сломанными, содержали баги или вовсе не решали заявленную проблему. 😅 -Потому это действительно важно - проверять и запускать код, и комментарием уведомлять меня, что Вы проделали эти действия. 🤓 +Поэтому очень важно действительно прочитать и запустить код и сообщить мне об этом в комментарии. 🤓 /// -* Если Вы считаете, что пул-реквест можно упростить, то можете попросить об этом, но не нужно быть слишком придирчивым, может быть много субъективных точек зрения (и у меня тоже будет своя 🙈), поэтому будет лучше, если Вы сосредоточитесь на фундаментальных вещах. +* Если PR можно упростить, Вы можете попросить об этом, но не нужно быть слишком придирчивым — может быть много субъективных мнений (и у меня тоже 🙈), поэтому лучше сосредоточиться на фундаментальных вещах. -### Тестировать +### Тестировать { #tests } -* Помогите мне проверить, что у пул-реквеста есть **тесты**. +* Помогите мне проверить, что у PR есть **тесты**. -* Проверьте, что тесты **падали** до пул-реквеста. 🚨 +* Проверьте, что тесты **падают** до PR. 🚨 -* Затем проверьте, что тесты **не валятся** после пул-реквеста. ✅ +* Затем проверьте, что тесты **проходят** после PR. ✅ -* Многие пул-реквесты не имеют тестов, Вы можете **напомнить** о необходимости добавления тестов или даже **предложить** какие-либо свои тесты. Это одна из тех вещей, которые отнимают много времени и Вы можете помочь с этим. +* Многие PR не имеют тестов — Вы можете **напомнить** добавить тесты или даже **предложить** некоторые тесты сами. Это одна из самых трудозатратных частей, и здесь Вы можете очень помочь. -* Затем добавьте комментарий, что Вы испробовали в ходе проверки. Таким образом я буду знать, как Вы произвели проверку. 🤓 +* Затем добавьте комментарий, что Вы попробовали, чтобы я знал, что Вы это проверили. 🤓 -## Создать пул-реквест +## Создать пулл-реквест { #create-a-pull-request } -Вы можете [сделать вклад](contributing.md){.internal-link target=_blank} в код фреймворка используя пул-реквесты, например: +Вы можете [сделать вклад](contributing.md){.internal-link target=_blank} в исходный код пулл-реквестами, например: -* Исправить опечатку, которую Вы нашли в документации. -* Поделиться статьёй, видео или подкастом о FastAPI, которые Вы создали или нашли изменив этот файл. - * Убедитесь, что Вы добавили свою ссылку в начало соответствующего раздела. -* Помочь с [переводом документации](contributing.md#_8){.internal-link target=_blank} на Ваш язык. - * Вы также можете проверять переводы сделанные другими. +* Исправить опечатку, найденную в документации. +* Поделиться статьёй, видео или подкастом о FastAPI, которые Вы создали или нашли, изменив этот файл. + * Убедитесь, что добавили свою ссылку в начало соответствующего раздела. +* Помочь с [переводом документации](contributing.md#translations){.internal-link target=_blank} на Ваш язык. + * Вы также можете проверять переводы, сделанные другими. * Предложить новые разделы документации. -* Исправить существующуе проблемы/баги. +* Исправить существующую проблему/баг. * Убедитесь, что добавили тесты. * Добавить новую возможность. * Убедитесь, что добавили тесты. - * Убедитесь, что добавили документацию, если она необходима. + * Убедитесь, что добавили документацию, если это уместно. -## Помочь поддерживать FastAPI +## Помочь поддерживать FastAPI { #help-maintain-fastapi } Помогите мне поддерживать **FastAPI**! 🤓 -Предстоит ещё много работы и, по большей части, **ВЫ** можете её сделать. +Предстоит ещё много работы, и, по большей части, **ВЫ** можете её сделать. Основные задачи, которые Вы можете выполнить прямо сейчас: -* [Помочь другим с их проблемами на GitHub](#github_1){.internal-link target=_blank} (смотрите вышестоящую секцию). -* [Проверить пул-реквесты](#-){.internal-link target=_blank} (смотрите вышестоящую секцию). +* [Помочь другим с вопросами на GitHub](#help-others-with-questions-in-github){.internal-link target=_blank} (смотрите секцию выше). +* [Проверять пулл-реквесты](#review-pull-requests){.internal-link target=_blank} (смотрите секцию выше). -Эти две задачи **отнимают больше всего времени**. Это основная работа по поддержке FastAPI. +Именно эти две задачи **забирают больше всего времени**. Это основная работа по поддержке FastAPI. -Если Вы можете помочь мне с этим, **Вы помогаете поддерживать FastAPI** и следить за тем, чтобы он продолжал **развиваться быстрее и лучше**. 🚀 +Если Вы можете помочь мне с этим, **Вы помогаете поддерживать FastAPI** и делаете так, чтобы он продолжал **развиваться быстрее и лучше**. 🚀 -## Подключиться к чату +## Подключиться к чату { #join-the-chat } -Подключайтесь к 👥 чату в Discord 👥 и общайтесь с другими участниками сообщества FastAPI. +Подключайтесь к 👥 серверу чата в Discord 👥 и общайтесь с другими участниками сообщества FastAPI. /// tip | Подсказка -Вопросы по проблемам с фреймворком лучше задавать в GitHub issues, так больше шансов, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#_3){.internal-link target=_blank}. +По вопросам — задавайте их в GitHub Discussions, так гораздо выше шанс, что Вы получите помощь от [Экспертов FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}. -Используйте этот чат только для бесед на отвлечённые темы. +Используйте чат только для прочих общих бесед. /// -### Не использовать чаты для вопросов - -Имейте в виду, что чаты позволяют больше "свободного общения", потому там легко задавать вопросы, которые слишком общие и на которые труднее ответить, так что Вы можете не получить нужные Вам ответы. - -В разделе "проблемы" на GitHub, есть шаблон, который поможет Вам написать вопрос правильно, чтобы Вам было легче получить хороший ответ или даже решить проблему самостоятельно, прежде чем Вы зададите вопрос. В GitHub я могу быть уверен, что всегда отвечаю на всё, даже если это займет какое-то время. И я не могу сделать то же самое в чатах. 😅 - -Кроме того, общение в чатах не так легкодоступно для поиска, как в GitHub, потому вопросы и ответы могут потеряться среди другого общения. И только проблемы решаемые на GitHub учитываются в получении лычки [Эксперт FastAPI](fastapi-people.md#_3){.internal-link target=_blank}, так что весьма вероятно, что Вы получите больше внимания на GitHub. - -С другой стороны, в чатах тысячи пользователей, а значит есть большие шансы в любое время найти там кого-то, с кем можно поговорить. 😄 - -## Спонсировать автора - -Вы также можете оказать мне финансовую поддержку посредством спонсорства через GitHub. +### Не используйте чат для вопросов { #dont-use-the-chat-for-questions } -Там можно просто купить мне кофе ☕️ в знак благодарности. 😄 +Имейте в виду, что в чатах, благодаря "свободному общению", легко задать вопросы, которые слишком общие и на которые сложнее ответить, поэтому Вы можете не получить ответы. -А ещё Вы можете стать Серебряным или Золотым спонсором для FastAPI. 🏅🎉 +На GitHub шаблон поможет Вам правильно сформулировать вопрос, чтобы Вам было легче получить хороший ответ или даже решить проблему самостоятельно ещё до того, как спросите. И на GitHub я могу следить за тем, чтобы всегда отвечать на всё, даже если это занимает время. А с чатами я не могу сделать этого лично. 😅 -## Спонсировать инструменты, на которых зиждется мощь FastAPI +Кроме того, переписка в чатах хуже ищется, чем на GitHub, поэтому вопросы и ответы могут теряться среди остальных сообщений. И только те, что на GitHub, учитываются для получения лычки [Эксперт FastAPI](fastapi-people.md#fastapi-experts){.internal-link target=_blank}, так что вероятнее всего Вы получите больше внимания именно на GitHub. -Как Вы могли заметить в документации, FastAPI опирается на плечи титанов: Starlette и Pydantic. +С другой стороны, в чатах тысячи пользователей, так что почти всегда есть шанс найти там кого-то для разговора. 😄 -Им тоже можно оказать спонсорскую поддержку: +## Спонсировать автора { #sponsor-the-author } -* Samuel Colvin (Pydantic) -* Encode (Starlette, Uvicorn) +Если Ваш **продукт/компания** зависят от **FastAPI** или связаны с ним и Вы хотите донести до пользователей информацию о себе, Вы можете спонсировать автора (меня) через GitHub Sponsors. В зависимости от уровня поддержки Вы можете получить дополнительные бонусы, например, бейдж в документации. 🎁 --- -Благодарствую! 🚀 +Спасибо! 🚀 diff --git a/docs/ru/docs/index.md b/docs/ru/docs/index.md index 692c03ecb..1fcc9ea9d 100644 --- a/docs/ru/docs/index.md +++ b/docs/ru/docs/index.md @@ -1,4 +1,4 @@ -# FastAPI +# FastAPI { #fastapi }