Питонические атаки

Настройка точечного обхода блокировок на роутере с OpenWRT

2020-12-12T21:17:11+05:00

Думаю, не стоит объяснять, почему проблема блокировок в рунете стоит настолько остро. И дело даже не в пресловутых сериалах на торрентах. Если не обходить блокировки, то банально сложно работать: то bugs.python.org заблокирован, то документация по нужному тебе сервису недоступна, то какой-нибудь репозиторий с пакетами отвалился, из-за чего у тебя внезапно перестают собираться контейнеры, то LinkedIn пишет письма на почту, а зайти на него ты не можешь. Например, вот здесь можно найти список опенсорс-проектов, которые были заблокированы Роскомнадзором. Это всё тянется еще с тех времён в 2018 году, когда Роскомнадзор пытался накрыть Telegram ковровыми блокировками, блокируя без разбора всех направо и налево. Какое-то время я пытался с этим жить, игнорируя проблему, но однажды мое терпение лопнуло, во мне пробудился дух цифрового сопротивления, и я решил настроить себе VPN — да так, чтобы это работало на всех моих устройствах сразу.

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

Так как большая часть моего трафика всё-таки ходит к незаблокированной части интернета, то логично пускать через VPN лишь тот трафик, который в этом нуждается. Ну нет ведь смысла гонять через VPN просмотр видео на YouTube или какую-нибудь игру? В итоге получится просто более медленный доступ, а профита никакого.

Стоит отметить, что если вам нужен обход блокировок только на одном устройстве, там вам намного проще будет настроить VPN именно на нём. У многих провайдеров VPN есть программы-клиенты, которые в несколько кликов по красивым кнопкам настроят вам всё, что нужно — просто погуглите, сравните цены и условия. Ещё можете посмотреть в сторону таких бесплатных проектов, как АнтиЗапрет.

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

Роутер и прошивка

OpenWRT — это опенсорсный проект, который разрабатывает прошивки для роутеров на основе Linux. В той или иной мере, пожалуй, поддерживаются все существующие девайсы. Внутри есть даже свой собственный пакетный менеджер. Так как роутер с OpenWRT — это почти настоящая линукс-машина, то открывается огромное поле для различных извращений — файловые шары, торрент-клиенты, блокировка рекламы на уровне роутера, VPN — да что угодно.

Мой нынешний роутер — это Xiaomi Mi WiFi Router 3G. Выбрал его, потому что в нём достаточно мощи, чтобы на нём хорошо работала OpenWRT. Да и вообще, Mir3G — это, похоже, один из самых популярных девайсов в тусовке людей, которые занимаются дрессировкой роутеров, так что в сети по нему уже есть много мануалов и обсуждений на форумах. Если захотите купить такой же, то будьте аккуратны с конкретной моделью — их две под одним названием, а хорошая только та, у которой есть порт USB3. Такой роутер должно быть несложно купить на Авито или других досках объявлений.

У меня на данный момент установлена почти последняя версия прошивки:

OpenWrt 19.07.3, r11063-85e04e9f46

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

Блокировки

Грубо говоря, существует два типа блокировок:

по доменным именам;
по IP-адресам.

Нам нужно победить оба. Разберёмся с каждым из них по порядку.

Шаг 1. Шифрованный DNS

DNS (Domain Name System) — это распределенная система (нет, это не сеть магазинов), состоящая из множества серверов по всему миру, которая позволяет вашему компьютеру преобразовать человекочитаемое имя сайта в машиночитаемый IP-адрес, например, из github.com получить 140.82.121.3. Этот процесс называется "разрешением" или "резолвингом" доменного имени.

Блокировка по доменным именам зачастую реализуется провайдером следующим образом: ваш роутер по умолчанию использует DNS-сервер, который контролируется провайдером и для заблокированных доменных имён возвращает специальный адрес сайта-заглушки. Именно это происходит, когда вы видите в браузере "доступ к ресурсу ограничен в соответствии со 149-ФЗ".

Кажется, что решение очевидно — просто не пользоваться DNS-сервером провайдера, а использовать, например, Google DNS, IP-адреса которого уже стоит знать наизусть как считалку — 8.8.8.8, 8.8.4.4. Раньше это действительно работало, но сегодня провайдеры уже не дадут вам так просто себя обмануть.

Поскольку DNS — это очень старый протокол, в котором никак не было предусмотрено шифрование от слова "вообще", у провайдеров есть возможность перехватывать ваши запросы и подменять ответы, вставляя свой сайт-заглушку, даже если запрос шёл, например, к Google DNS. Именно этим они и занимаются. По сути, провайдер проводит против вас атаку DNS hijacking.

Вот как это работает, если всё хорошо. В таком сценарии можно даже не заметить этого "человека посередине" в лице вашего провайдера:

А вот так это работает, когда всё плохо. Провайдер наверняка даже не отправляет запрос к DNS-серверу, которому он предназначался, а просто сразу же возвращает ответ, подставляя адрес своей заглушки:

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

Совсем недавно стали появляться шифрованные версии протокола DNS — DNSCrypt, DoT (DNS-over-TLS) и DoH (DNS-over-HTTPS). Судя по всему, именно последний из них (DoH) получит наибольшую популярность. При использовании этого протокола DNS-запрос складывается внутрь HTTPS-запроса, который, само собой, зашифрован. Для человека посередине, который перехватит такой трафик, это будет выглядеть как просто один из миллиарда шифрованных HTTP-запросов к Google или Cloudflare.

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

Подключимся к роутеру по SSH:

~ $ ssh root@192.168.1.1
root@192.168.1.1's password:
BusyBox v1.30.1 () built-in shell (ash)
_______                     ________        __
|       |.-----.-----.-----.|  |  |  |.----.|  |_
|   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
|_______||   __|_____|__|__||________||__|  |____|
        |__| W I R E L E S S   F R E E D O M
-----------------------------------------------------
OpenWrt 19.07.3, r11063-85e04e9f46
-----------------------------------------------------
root@OpenWrt:~#

Обновим список пакетов. Эту команду нужно выполнять после каждой перезагрузки роутера перед установкой пакетов:
```
opkg update
```
Установим необходимые зависимости, которые в связке позволят принимать DNS-запросы от клиентов в локальной сети и отправлять их во внешний интернет, замаскированными под HTTPS-запросы. Третий пакет — это просто плагин для веб-интерфейса OpenWRT LuCI, чтобы можно было через GUI настраивать поведение DoH:
```
opkg install dnsmasq https-dns-proxy luci-app-https-dns-proxy
```
Чтобы плагин для LuCI заработал, нужно сделать выполнить вот такую команду:
```
/etc/init.d/rpcd restart
```

Готово! Теперь на компьютере, подключенном к роутеру, можно проверить как это работает:

# это было до настройки
$ nslookup linkedin.com
...
Name:   linkedin.com
Address: 95.213.158.61

# это после настройки
$ nslookup linkedin.com
...
Name:   linkedin.com
Address: 13.107.42.14
Name:   linkedin.com
Address: 2620:1ec:21::14

Обратите внимание, что адреса возвращаются разные: до настройки DoH — неправильный, это результат подмены адресов провайдером, а после — правильный. Можно считать это маленькой победой!

По умолчанию используются DNS-over-HTTPS сервера от Google и Cloudflare — очень разумный выбор, потому что на этих двух компаниях держится добрая половина глобального интернета, и их блокировка наверняка приведёт к катастрофическим последствиям, так что блокировать их, надеюсь, никто не будет. Если же хочется сменить используемые сервера, то сделать это теперь можно через веб-интерфейс: Services > DNS HTTPS Proxy.

Сам по себе обход блокировок по DNS вряд ли даст ожидаемый эффект, потому что, как правило, в довесок к доменному имени, ресурс блокируется еще и по IP-адресам — видимо, для надежности. Это следующий тип блокировок, которые нужно победить.

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

Если нравится статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить! А ещё читайте другие мои посты!

Шаг 2. Настройка VPN WireGuard

Для того, чтобы обходить блокировки по IP-адресам, придётся настроить VPN — другого способа нет. VPN "спрячёт" от провайдера ваши IP-пакеты так, что он не будет знать куда именно они направляются и что в себе содержат. В качестве протокола предлагаю использовать WireGuard — легковесный VPN-протокол, который к тому же довольно легко настраивать.

Всё описанное дальше вдохновлено и по сути является пересказом вот этой замечательной статьи на Хабре с некоторыми (минимальными) дополнениями от меня.

VPN — это клиент-серверный протокол. Наш роутер будет клиентом, но также нам обязательно нужен сервер. Можно либо поднять свой VPN-сервер самостоятельно (смотрите инструкцию в статье по ссылке выше, это не сложно), либо оформить подписку на какой-нибудь готовый VPN-сервис. Я пробовал оба варианта, но поддерживать свой VPN-сервер оказалось достаточно трудозатратно, и это тоже, как ни странно, стоит денег. Сложнее всего найти хостинг для своего VPN с незаруиненной репутацией. Проблема, с которой я столкнулся, заключалась в том, что все дешевые хостинги уже имеют плохую репутацию (спасибо вам, господа спамеры), и некоторые ресурсы, типа Пикабу (который тоже, как выяснилось, немножко заблокирован), сразу же заранее отвечают ошибкой 403. Намного проще купить готовый VPN, и пусть лучше кто-то другой за меня беспокоится о том, чтобы мне были доступны все нужные мне сайты.

В последнее время появляется очень много VPN-сервисов, которые работают по протоколу WireGuard — это нынче горячая тема. Недавно поддержка WireGuard была добавлена в основной состав ядра Linux. Погуглите, выбор сервисов действительно есть. Сейчас я пользуюсь RedShieldVPN, и меня пока что всё устраивает.

Бонус для читателей: при регистрации по этой ссылке вам подарят месяц бесплатного VPN.

Дальше буду описывать процесс для RedShieldVPN, но, думаю, для других подобных сервисов процесс должен быть похожим.

Переходим в раздел WireGuard, авторизуемся, выбираем страну и скачиваем конфиг. Я обычно выбираю какую-нибудь европейскую страну, чтобы пинг был приемлемым. В этот раз возьму Финляндию.

Вот примерно такой файл конфигурации скачался (ключи я заменил):
```
[Interface]
Address = 10.7.1.177/32, 6343:72e7:7ac3:e245:2675:1b79:4638:193a/128
PrivateKey = private_key_goes_here
DNS = 10.254.254.254
MTU = 1412

[Peer]
PublicKey = public_key_goes_here
AllowedIPs = 0.0.0.0/0, ::/0
Endpoint = fin.lopata.today:51820
PersistentKeepalive = 10
```
Переключимся на роутер и установим там нужную зависимость:
```
opkg install wireguard
```
Дальше нужно настроить сеть. Это происходит в файле /etc/config/network. Открываем его при помощи vi (если не умеете пользоваться этим редактором, то лучше предварительно почитайте что-нибудь для подготовки психики) и дописываем в конец две секции вот такого содержания:
```
config interface 'wg0'
    option private_key 'private_key_goes_here'
    list addresses '10.7.1.177/32'
    option listen_port '51820'
    option proto 'wireguard'

config wireguard_wg0
    option public_key 'public_key_goes_here'
    option allowed_ips '0.0.0.0/0'
    option route_allowed_ips '0'
    option persistent_keepalive '10'
    option endpoint_host 'fin.lopata.today'
    option endpoint_port '51820'
```
Приватный и публичный ключи замените соответствующими значениями из конфига. Поле list addresses заполняется IPv4-адресом из строчки Address в конфиге, а IPv6 адрес мы просто игнорируем — позже станет понятно почему. Поле Endpoint из конфига WireGuard распадается, соответственно, в поля endpoint_host и endpoint_port в конфиге OpenWRT. Остальные поля статичные.
Перезапустим сеть на роутере:
```
/etc/init.d/network restart
```

Проверим VPN:

# wg show
interface: wg0
public key: C4zR9CoziizrJcPFtcUg4yyyG1S6+a+/bAuGi2BpmlM=
private key: (hidden)
listening port: 51820

peer: public_key_goes_here
endpoint: 185.103.110.133:51820
allowed ips: 0.0.0.0/0
latest handshake: 33 seconds ago
transfer: 1012 B received, 3.53 KiB sent
persistent keepalive: every 10 seconds

Если команда wg show выводит что-то подобное, то всё идёт хорошо.

Шаг 3. Скрипт для сбора списков заблокированных адресов

Это возможно благодаря крутейшему сервису antifilter.download, который обрабатывает выгрузки Роскомнадзора и отдает их в виде списков IP-адресов в машиночитаемых форматах. Мы настроим периодическую выгрузку списков заблокированных адресов с antifilter.download, чтобы всегда иметь актуальную информацию о блокировках. По моему опыту обновлять этот список раз в сутки (например, ночью) вполне достаточно.

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

Начнём со скрипта, который реализует эту логику по обновлению списков заблокированных адресов.

Установим зависимости:
```
opkg install ipset curl
```
Создадим файл /etc/init.d/hirkn со скриптом следующего содержания:
```
#!/bin/sh
START=99
dir=/tmp/lst
mkdir -p $dir
echo "Downloading lists of blocked addresses..."
curl -z $dir/subnet.lst https://antifilter.download/list/subnet.lst --output $dir/subnet.lst
curl -z $dir/ipsum.lst https://antifilter.download/list/ipsum.lst --output $dir/ipsum.lst
echo "Restarting firewall..."
/etc/init.d/firewall restart
```
Этот скрипт скачивает два списка заблокированных адресов — один в виде сетей (иногда РКН блокирует адреса целыми подсетями), другой — обобщенный список отдельных заблокированных адресов. За счёт обобщения в небольшие подсети он содержит не миллионы строк, а всего лишь что-то около 15 тысяч. Нам нужны оба списка, они не пересекаются между собой. Файлы сохраняются в каталог /tmp, который в OpenWRT хранится в оперативной памяти — это должно работать быстро. В конце скрипт перезапускает файлволл. Настройка файлволла будет происходит позже.
Добавим этому скрипту права на выполнение:
```
chmod +x /etc/init.d/hirkn
```
Добавим скрипт в "автозапуск", чтобы он выполнялся при включении роутера после всех остальных скриптов:
```
ln -s /etc/init.d/hirkn /etc/rc.d/S99hirkn
```
Через cron запланируем выполнение этого скрипта раз в сутки:
```
crontab -e
```
В открывшемся редакторе нужно добавить на новой строке:
```
0 4 * * * /etc/init.d/hirkn
```
На crontab.guru можно посмотреть объяснение этой строчки.
Включим cron, потому что по умолчанию в OpenWRT он выключен:
```
/etc/init.d/cron enable
/etc/init.d/cron start
```
Убедимся, что скрипт работает.

Запустим его:
```
/etc/init.d/hirkn
```
Если файлы со списками заблокированных адресов появились, то всё ок:
```
# ls -lh /tmp/lst/
-rw-r--r--    1 root     root      270.4K Dec  7 07:18 ipsum.lst
-rw-r--r--    1 root     root         132 Dec  7 07:18 subnet.lst
```

Шаг 4. Дальнейшая настройка

Теперь осталось настроить роутер так, чтобы он правильно маршрутизировал пакеты через VPN-туннель.

Создадим таблицу маршрутизации для VPN, добавив в файл /etc/iproute2/rt_tables строчку следующего вида:
```
99      vpn
```
Добавим дефолтный маршрут для VPN через туннельный интерфейс:
```
ip route add table vpn default dev wg0
```
Чтобы сделать это изменение постоянным, чтобы оно переживало перезагрузки роутера, создадим файл /etc/hotplug.d/iface/30-rknroute с вот таким содержимым:
```
#!/bin/sh
ip route add table vpn default dev wg0
```
В файл /etc/config/network, который мы уже редактировали в процессе настройки WireGuard, добавим правило, которое будет перенаправлять маркированные пакеты в таблицу маршрутизации VPN:
```
config rule
    option priority '100'
    option lookup 'vpn'
    option mark '0x1'
```
Теперь приступим к настройке файрволла. Это самая важная часть логики, которая просматривает списки заблокированных адресов, и маркирует пакеты. В файл /etc/config/firewall допишем несколько абзацев:
```
config zone
    option name 'wg'
    option family 'ipv4'
    option masq '1'
    option output 'ACCEPT'
    option forward 'REJECT'
    option input 'REJECT'
    option mtu_fix '1'
    option network 'wg0'

config forwarding
    option src 'lan'
    option dest 'wg'

config ipset
    option name 'vpn_subnets'
    option storage 'hash'
    option loadfile '/tmp/lst/subnet.lst'
    option match 'dst_net'

config ipset
    option name 'vpn_ipsum'
    option storage 'hash'
    option loadfile '/tmp/lst/ipsum.lst'
    option match 'dst_net'

config rule
    option name 'mark_subnet'
    option src 'lan'
    option proto 'all'
    option ipset 'vpn_subnets'
    option set_mark '0x1'
    option target 'MARK'

config rule
    option name 'mark_ipsum'
    option src 'lan'
    option proto 'all'
    option ipset 'vpn_ipsum'
    option set_mark '0x1'
    option target 'MARK'
```
Первый из них настраивает зону для VPN — из неё разрешён лишь выход пакетов и включён маскарадинг.

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

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

Пятый и шестой абзацы отвечают за маркировку пакетов: "если пакет направляется на заблокированный адрес, то добавим ему пометку 0x1".
Перезапустим сеть:
```
/etc/init.d/network restart
```
И запустим наш скрипт:
```
/etc/init.d/hirkn
```
После этого трафик к заблокированным сайтам должен побежать через VPN. Если нет, то попробуйте перезагрузить роутер.

Шаг 5. Отключаем IPv6

Этот шаг мой самый нелюбимый, потому что я за всё новое и против всего старого. По моему глубокому убеждению IPv4 уже давно должен умереть и быть вытеснен шестой версией протокола. К сожалению, дела у IPv6 пока идут не так гладко, как хотелось бы (сейчас он занимает всего около 30% процентов трафика).

Проблема в том, что antifilter.download выдаёт только заблокированные IPv4 адреса. Это значит, что наш обход блокировок не будет работать по IPv6. Если разрешить вашему роутеру работать по IPv6, то многие ваши устройства предпочтут открывать сайты по IPv6 либо напарываясь на страницы с блокировками от провайдеров, либо просто получая ошибки подключения по таймауту.

Отключаем IPv6 (команды взяты отсюда):

uci set 'network.lan.ipv6=off'
uci set 'network.wan.ipv6=off'
uci set 'dhcp.lan.dhcpv6=disabled'
/etc/init.d/odhcpd disable
uci commit

После этого может потребоваться ещё одна перезагрузка роутера, чтобы он перестал раздавать вновь подключенным устройствам IPv6-адреса.

Заключение

Вот как-то так можно при помощи несложных (ладно, сложных) манипуляций настроить свой роутер на точечный обход блокировок. Все незаблокированные сайты работают как обычно, а заблокированные — через VPN. С такой конфигурацией можно полностью забыть про мелкие пакости от Роскомнадзора и начать, наконец, жить :)

Эффективный обход словарей в цикле в Python

2020-07-06T13:46:41+05:00

Эффективный обход словарей в цикле в Python

Словарь (dictionary, dict) — это ассоциативный массив, который позволяет сохранять значения по ключам.

Это очень важная, даже можно сказать основополагающая структура данных, которая используется в Python под капотом буквально повсюду: модули, классы, объекты, locals(), globals() — все это так или иначе работает лишь благодаря словарям.

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

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

Есть несколько способов обойти словарь в цикле. Очень важно научиться выбирать наиболее подходящий.

Что будет если просто попытаться обойти словарь в цикле?

Объявим словарь с отношением различных валют к российскому рублю, который нам по какой-то причине нужно обойти:

currencies = {"rub": 1, "usd": 69.78, "eur": 78.28}

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

for something in currencies:
    print(something)

Словарь и правда поддерживает протокол итераций, но словарь не так прост, как другие объекты, которые мы упомянули выше. Словарь состоит из нескольких частей, ведь словарь — это отношение между ключами и значениями. Получается, что теоретически цикл по словарю может получать либо ключи, либо значения, либо пары (ключ, значение). Попробуете угадать, что же именно выведет код выше?

А выведет он следующее:

rub
usd
eur

То есть обход словаря в цикле будет возвращать только ключи этого словаря.

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

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

Как обойти в цикле ключи словаря?

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

У словаря есть метод .keys(), который возвращает представление словаря (dict view), возвращающее ключи.

Что такое представление словаря? Это некий объект, который предоставляет доступ к данным в словаре, либо к части этих данных, и работает по следующим принципам:

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

Создадим такое представление словаря по ключам:

dict_keys = currencies.keys()

print(dict_keys)
# dict_keys(['rub', 'usd', 'eur'])

Давайте добавим новый ключ в словарь:

currencies["jpy"] = 0.65

print(dict_keys)
# dict_keys(['rub', 'usd', 'eur', 'jpy'])

Как видите, созданное ранее представление словаря обновилось автоматически, когда обновился его словарь.

Обратите внимание, что представление словаря — это не список, а совершенно другой объект. Представление словаря не поддерживает извлечение значений по индексам:

dict_keys[0]
# Traceback (most recent call last):
#   File "<stdin>", line 1, in <module>
# TypeError: 'dict_keys' object is not subscriptable

Зато представление словаря является итерируемым объектом и его без проблем можно обходить при помощи цикла:

for key in currencies.keys():
    print(key)
# rub
# usd
# eur
# jpy

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

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

Как обойти в цикле значения словаря?

По аналогии с ключами, из словаря можно извлечь только значения, без ключей. Это делается через метод словарей .values(), который возвращает представление словаря, содержащее только значения.

Это представление работает по тем же правилам, что и возвращаемое методом .keys().

Вот как можно обойти в цикле только значения словаря, без ключей:

for value in currencies.values():
    print(value)
# 1
# 69.78
# 78.28
# 0.65

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

Как обойти в цикле и ключи, и значения словаря?

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

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

Это представление работает по точно таким же правилам, как .keys() и .values(). Единственное отличие этого представления от предыдущих состоит в том, что оно возвращает не единичные значения, а кортежи из двух значений.

for item in currencies.items():
    # item — это кортеж (ключ, значение)
    print(item[0], item[1])
# rub 1
# usd 69.78
# eur 78.28
# jpy 0.65

В Python есть возможность распаковывать итерируемые объекты, такие как кортежи, в различные переменные. Давайте на примере посмотрим как это работает:

point = (1, 2, 3)
x, y, z = point

print(x)
# 1
print(y)
# 2
print(z)
# 3

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

Вот так можно обойти ключи и значения словаря, сохраняя ключ и значение в разные переменные прямо в заголовке цикла при помощи распаковки кортежа:

for key, value in currencies.items():
    print(key, value)
# rub 1
# usd 69.78
# eur 78.28
# jpy 0.65

Заключение

При обходе словаря стоит руководствоваться следующей логикой:

если в цикле используются и ключи, и значения словаря, то нужно использовать метод .items();
если в цикле используются только значения словаря, а ключи не важны, то нужно использовать метод .values();
если в цикле нужны ключи словаря и ничего больше, то нужно использовать метод .keys().

Идеоматичный код проще читается и, как правило, работает быстрее.

Посмотрите запись классического выступления Реймонда Хеттингера, где он рассказывает про написание идеоматичного код. Много внимания уделяется циклам и словарям.

Обратите внимание, что это запись выступления от 2013 года, когда ещё вовсю был в ходу Python 2. В выступлении часто сравнивается Python 2 и Python 3. Не запутайтесь.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Ссылки

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

Аннотации типов в Python

2020-06-22T23:35:05+05:00

Аннотации типов в Python

Python — это язык с сильной динамической типизацией.

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

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

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

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

По данным исследований StackOverflow за 2020, 2019, 2018, 2017, 2016, 2015 (там же можно посмотреть результаты за 2014 и 2013) годы, Python с каждым годом растёт в популярности.

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

Кроме того, даже если код без информации о типах может быть и вполне понятен человеку, например, благодаря удачно выбранным именам, то для автоматики — это в любом случае абсолютно непроницаемый ~~черный~~ непрозрачный ящик. В такой ситуации очень сложно, не выполняя код (мы же говорим про статический анализ), понять как он будет вести себя в ран-тайме. Аннотации типов позволяют IDE, линтерам и тайп-чекерам лучше понимать код программы, что дает возможность рано отлавливать достаточно хитрые ошибки. В конечном итоге это делает написанные программы надежнее.

По этим соображениям, в Python 3.5 появился специальный синтаксис для объявления типов параметров функций и их возвращаемых значений (PEP 484). В Python 3.6 эта возможность была расширена — стало можно объявлять типы переменных вообще в любом месте программы (PEP 526). С каждой новой версией языка эта функциональность улучшается, и писать аннотации типов становится всё проще, удобнее и естественнее, а экосистема вокруг типизированного Python развивается семимильными шагами.

Нужно отметить, что тайп-аннотации — это именно возможность, а не обязанность. У программиста есть выбор — добавлять информацию о типах или нет. Таким образом Python пытается усидеть на двух стульях — остаться языком с динамической типизацией и дать возможность для статического анализа написанных программ. Привнести в хаос немного порядка, так сказать. И, по-моему, у Python это неплохо получается.

Как это работает?

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

Зачем же тогда писать тайп-аннотации?

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

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

Простые типы

Вот так, например, можно тайп-аннотировать простую функцию:

def greeting(name: str = "world") -> str:
    return "Hello, " + name

Типы параметров, принимаемых функцией, записываются после имени параметра через знак двоеточия, но перед значением по умолчанию, если оно присутствует. Возвращаемое значение функции записывается после знака “стрелки”.

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

Точно так же можно использовать для тайп-аннотаций и любые другие базовые (примитивные, не-контейнерные) типы в Python: int, float, bool, str, bytes, None и вообще практически что угодно. Чуть позже посмотрим, как типизировать контейнерные типы данных, такие как списки, кортежи, словари и множества.

Вот так можно зааннотировать функцию, которая принимает два числа с плавающей точкой и возвращает число с плавающей точкой:

def body_mass_index(weight: float, height: float) -> float:
    return weight / height ** 2

А вот так функцию, которая принимает строку и булевый аргумент, но ничего не возвращает:

def print_hello(name: str, upper: bool = False) -> None:
    if upper:
        name = name.upper()
    print("Hello,", name)

Вот так можно аннотировать любые переменные в любом месте кода (Python 3.6+):

name: str = "Andrey"
age: int = 25
is_sick_with_covid19: bool = False  # надеюсь
pi: float = 3.1415

# можно даже аннотировать переменные, не назначая им значения
foo: str

Если мы создадим свой класс, то его тоже можно использовать для аннотаций:

class Example:
    pass

# довольно бессмысленно, но для примера пойдет
example_instance: Example = Example()

Контейнерные типы и дженерики

Перейдем к более сложным типам, таким как списки, кортежи, словари и множества. Можно аннотировать в лоб, используя сами имена классов:

primes: list
person_info: tuple
stock_prices: dict
valid_answers: set

Это не слишком информативно, потому что кроме самого типа контейнера было бы ещё полезно знать, какие данные он в себе содержит. Что такое person_info? Кортеж чего?

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

from typing import List, Tuple, Dict, Set

# тип всех элементов списка
primes: List[int]

# тип каждого элемента кортежа
person_info: Tuple[str, int, float, float]

# тип ключей, тип значений
stock_prices: Dict[str, float]

# тип всех элементов множества
valid_answers: Set[str]

Начиная с Python 3.9 можно использовать стандартные классы в точно таких же целях, ничего ниоткуда не импортируя:

# будет работать только начиная с Python 3.9!

# тип всех элементов списка
primes: list[int]

# тип каждого элемента кортежа
person_info: tuple[str, int, float, float]

# тип ключей, тип значений
stock_prices: dict[str, float]

# тип всех элементов множества
valid_answers: set[str]

Согласитесь, так намного понятнее. Сразу видно, какой тип данных лежит внутри контейнера. Такие типы называются обобщёнными (generic types).

Кстати, в типизации можно яснее увидеть разницу между тем как должны использоваться списки и кортежи (list vs. tuple).

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

Получается, кортеж — это не просто неизменяемый брат-близнец списка.

Если сильно хочется использовать кортеж как просто неизменяемую последовательность однородных данных, то можно зааннотировать его вот так, используя ... (это специальный объект Ellipsis, записывается как многоточие, при чтении исходников вслух в этом месте нужно делать драматическую паузу):

# кортеж из строк, длина неизвестна
months: Tuple[str, ...]

Составные типы

Часто случаются ситуации, когда нужно объединить несколько типов, например, для того, чтобы указать, что функция может принимать и строки, и числа. Этого можно достичь при помощи дженерик-типа Union из модуля typing:

from typing import Union

def add_or_concatenate(a: Union[str, int], b: Union[str, int]):
    return a + b

Также очень часто возникает ситуация, когда возможно либо значение определенного типа, либо None. Это настолько частая ситуация, что для этого даже сделали отдельный дженерик-тип Optional:

from typing import Optional, Union

# по сути это одно и то же, но первый вариант проще читается
phone: Optional[str]
phone: Union[str, None]

Также может возникнуть ситуация, когда не получается указать какой-либо конкретный тип, потому что, например, функция может принимать на вход абсолютно что угодно. Для этих случаев тоже есть специальный объект typing.Any:

from typing import Any

def func(arg: Any) -> Any:
    return arg

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

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

Проверка типов

Допустим, что тайп-аннотации написаны. Как начать получать от этого пользу?

В экосистеме Python есть несколько конкурирующих между собой тайп-чекеров, например, mypy, pyre, pytype, pyright. Самым популярным среди них является mypy, наверное, потому что одним из ключевых его разработчиков является сам Гвидо ван Россум. Давайте на mypy и остановимся.

Установим mypy в проект. Внутри виртуального окружения проекта нужно выполнить:

$ pip install mypy

Для pipenv и poetry соответственно вот так:

$ pipenv install --dev mypy
$ poetry add --dev mypy

Давайте напишем самый тривиальный пример программы с ошибкой:

print("qwerty" + 1)

При выполнении, очевидно, программа завершится ошибкой:

$ python example.py
Traceback (most recent call last):
  File "example.py", line 1, in <module>
    print("qwerty" + 1)
TypeError: can only concatenate str (not "int") to str

Давайте посмотрим, сможет ли тайп-чекер обнаружить эту проблему:

$ mypy example.py
example.py:1: error: Unsupported operand types for + ("str" and "int")
Found 1 error in 1 file (checked 1 source file)

Отлично! Не исполняя программу, mypy смог понять, что в ней присутствует ошибка. Давайте запрячем эту же самую ошибку чуть глубже, используя функцию:

def greet(name: str) -> None:
    print("Hello, " + name)

# правильный вызов
greet("world!")
# а вот тут будет ошибка
greet(5)

Проверим типы в этой программе:

$ mypy example2.py
example2.py:9: error: Argument 1 to "greet" has incompatible type "int"; expected "str"
Found 1 error in 1 file (checked 1 source file)

Тайп-чекер пропустил правильный вызов функции, но обнаружил вызов функции с ошибкой.

Заключение

Тайп-аннотации — это настолько круто и удобно, что, честно говоря, я уже плохо представляю, как раньше (до Python 3.5) без этого люди вообще программировали. Для меня это самый веский аргумент в пользу Python 3 и против Python 2. Это незаменимый инструмент при разработке насколько-нибудь крупной программы.

Обязательно нужно интегрировать тайп-чекинг в свой редактор/IDE, чтобы ошибки подсвечивались ещё на этапе написания кода. Можно интегрировать тайп-чекинг в Git-хуки и CI.

На странице "Awesome Python Typing" можно найти ещё много полезных инструментов, которые пользуются тайп-аннотациями.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение:

введение в аннотации типов часть 1 и часть 2 на Хабре;
документация к модулю typing;
документация mypy;
репозиторий mypy на GitHub;
сайт mypy;
сайт pyre;
репозиторий pytype на GitHub;
репозиторий pyright на GitHub;
Awesome Python Typing;
ликбез по типизации в языках программирования на Хабре.

Обложка: Windell Oskay, Technic Bits

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

2020-05-31T19:30:24+05:00

Иногда при просмотре диффов коммитов через git log или git diff можно заметить следующий вывод:

\ No newline at end of file

Или на GitHub в интерфейсе для просмотра диффов:

Почему это так важно, что Git и GitHub предупреждают нас об этом? Давайте разберемся.

Что такое символ переноса строки?

Что может быть проще, чем текстовый файл? Просто текстовые данные — как хранятся на диске, так и отображаются. На самом деле ~~правительство нам врёт~~ всё немного сложнее.

Оффтопик про управляющие символы ASCII

Не все символы, которые содержатся в текстовых файлах, имеют визуальное представление. Такие символы ещё называют "управляющими", и к ним относятся, например:

нулевой символ (x00, \0) — часто используется для кодирования конца строки в памяти; т.е. программа считывает символы из памяти по одному до тех пор, пока не встретит нулевой символ, и тогда строка считается завершённой;
табуляция (\x09, \t) — используется для выравнивания данных по границе столбца, так что это выглядит как таблица;
перевод строки (\x0a, \n) — используется для разделения текстовых данных на отдельные строки;
возврат каретки (\x0d, \r) — переместить курсор в начало строки;
возврат на один символ (\x08, \b) — переместить курсор на один символ назад;
звонок (\x07, \a) — если набрать этот символ в терминале, то будет бибикающий символ; именно так консольные программы, типа vim, бибикают на пользователей;
и другие.

Многие эти символы пришли к нам из эпохи печатных машинок, поэтому у них такие странные названия. И действительно, в контексте печатной машинки или принтера такие операции, как перевод строки (сместить лист бумаги вверх так, чтобы печатающая головка попала на следующую строку), возврат каретки (переместить печатающую головку в крайнее левое положение) и возврат на один символ назад, обретают смысл. При помощи возврата на один символ назад создавались жирные символы (печатаешь символ, возвращаешься назад и печатаешь его ещё раз) и буквы с диакритическими знаками, такие как à или ã (печатаешь символ, возвращаешься назад и печатаешь апостроф или тильду). Но зачем печатной машинке бибикалка?

Сегодня многие из этих символов потеряли смысл, но некоторые до сих пор выполняют функцию, схожую с исходной.

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

Для набора символа переноса строки достаточно нажать клавишу "Enter", но на разных платформах этот символ закодируется по-разному:

в Unix-совместимых системах (включая современные версии macOS) используется один символ перевода строки (LF);
в Windows используется сразу два символа — возврат каретки (CR) и перевод строки (LF);
в очень старых версиях Mac OS (до 2001 года) использовался один символ CR.

Как видите, Windows точнее всего эмулирует поведение печатной машинки.

В языках программирования символ новой строки часто кодируют при помощи бэкслэш-последовательностей, таких как \n или \r\n. Нужно понимать разницу между такой последовательностью и настоящим символом переноса строки. Если в редакторе в файле *.txt просто набрать \n и сохранить, то вы получите ровно то, что написали. Символом переноса строки оно не станет. Нужно что-то, что заменит эти бэкслэш-последовательности на настоящие символы переноса строки (например, компилятор или интерпретатор языка программирования).

Почему перенос строки в конце файла важен?

Согласно определению из стандарта POSIX, который тоже пришёл к нам из эпохи печатных машинок:

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

Почему важен этот стандарт? Возможен миллиард способов реализовать одно и то же, и только благодаря стандартам, таким как POSIX, мы имеем сейчас огромное количество качественного ПО, которое не конфликтует друг с другом.

Т.е. если вы не ставите символ переноса строки в конце строки, то формально по стандарту такая строка не является валидной. Множество утилит из Unix, которыми я пользуюсь каждый день, написано в согласии с этим стандартом, и они просто не могут правильно обрабатывать такие "сломанные" строки.

Давайте, например, через Python создадим такой файл со сломанными строками:

with open("broken.txt", "w") as f:
    f.write("qwe\n")
    f.write("asd\n")
    f.write("zxc")

Сколько по-вашему в этом файле строк? Три? Давайте посмотрим, что об этом файле думает утилита wc, которая с флагом -l умеет считать количество строк в файле:

$ wc -l broken.txt 
2 broken.txt

Упс! wc нашла только 2 строки!

Давайте создадим еще один файл:

with open("broken2.txt", "w") as f:
    f.write("rty\n")
    f.write("fgh\n")
    f.write("vbn")

И попробуем теперь склеить два созданных файла при помощи утилиты cat:

$ cat broken.txt broken2.txt 
qwe
asd
zxcrty
fgh
vbn

Название cat — это сокращение от "конкатенация", и никак не связано с котиками. А жаль.

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

Это только пара примеров, но многие другие утилиты, которые работают с текстом (например, diff, grep, sed), имеют такие же проблемы. Собственно говоря, это даже не проблемы, а их задокументированное поведение.

Ещё доводы:

при дозаписи содержимого в конец файла без переноса строки получится некрасивый дифф — будет изменена последняя строка (хотя на ней всего лишь добавился символ переноса);
файл с переносом строки и без переноса строки — это два разных файла; для diff и git diff единственный способ отобразить разницу между ними — это напечатать сообщение об отсутствии символа переноса строки;
согласно стандарту языка C (до 2014 года), непустые файлы с исходным кодом должны заканчиваться символом переноса строки.

Настраиваем редактор

Самый простой способ перестать думать о пустых строках ~~и начать жить~~ — это настроить свой текстовый редактор или IDE на автоматическое добавление символа переноса строки в конец файлов:

PyCharm и другие IDE JetBrains: Settings > Editor > General > Ensure an empty line at the end of a file on Save;
VS Code: "files.insertFinalNewline": true.

Для других редакторов смотрите настройку здесь.

Кстати, если вы пользуетесь форматтером black, то у меня хорошие новости — он всегда добавляет перенос строки в конец всех файлов *.py.

Заключение

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

В текстовом редакторе это выглядит как лишняя пустая строка в конце файла:

Дополнительное чтение

Запуск Git-хуков при помощи pre-commit

2020-05-31T15:54:18+05:00

Git-хуки

Умение работать с системой контроля версий Git — базовый навык для выживания разработчика (на любом языке программирования) в современных реалиях. Система контроля версий — это этакая машина времени для вашего проекта: всегда можно вернуться на любое прошлое состояние проекта, понять когда, как, что и кем менялось.

Интересный факт: согласно Google Trends, во всём мире Git фактически вытеснил другие системы контроля версий. Только в Китае почему-то до сих пор популярен Subversion (46% рынка). К чему бы это?

Git имеет крайне полезную фичу — возможность исполнять произвольный код на многих этапах работы через так называемые хуки. Вот примеры доступных хуков:

pre-commit — выполняется перед созданием коммита;
commit-msg — выполняется после добавления сообщения коммита;
post-checkout — выполняется после переключения ветки;
pre-push — выполняется перед загрузкой локальной истории на удалённый сервер.

Полный список хуков можно посмотреть в документации.

Как это работает? Рассмотрим, например, схему работы хука pre-commit:

пользователь пишет в терминале git commit -v;
git пытается выполнить хук pre-commit локально, на машине разработчика;
если хук завершается ошибкой, то операция коммита прерывается;
если хук выполнился без ошибок, то операция коммита продолжается, открывается текстовый редактор для ввода сообщения.

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

Пишем Git-хук на `bash`

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

В этом примере я использую Linux. Если вы пользуетесь Windows, то большинство описанный вещей будут работать без изменений через Git Bash, который устанавливается вместе с Git for Windows. Возможно, вам только придётся поменять путь до вашего bash в шебанге, как описано в конце этой статьи. Если же вы соберётесь писать в хуках что-то сложное и требующее интеграции с ОС, то, возможно, стоит вместо bash использовать PowerShell.

Создадим пустой репозиторий:

$ git init git_hooks_example
$ cd git_hooks_example/

Git уже заботливо создал для нас шаблоны для написания хуков, которые лежат в специальной служебной директории:

$ ls -l .git/hooks/
total 56
-rwxr-xr-x. 1 br0ke br0ke  482 May 30 21:36 applypatch-msg.sample*
-rwxr-xr-x. 1 br0ke br0ke  900 May 30 21:36 commit-msg.sample*
-rwxr-xr-x. 1 br0ke br0ke 4655 May 30 21:36 fsmonitor-watchman.sample*
-rwxr-xr-x. 1 br0ke br0ke  193 May 30 21:36 post-update.sample*
-rwxr-xr-x. 1 br0ke br0ke  428 May 30 21:36 pre-applypatch.sample*
-rwxr-xr-x. 1 br0ke br0ke 1647 May 30 21:36 pre-commit.sample*
-rwxr-xr-x. 1 br0ke br0ke  420 May 30 21:36 pre-merge-commit.sample*
-rwxr-xr-x. 1 br0ke br0ke 1496 May 30 21:36 prepare-commit-msg.sample*
-rwxr-xr-x. 1 br0ke br0ke 1352 May 30 21:36 pre-push.sample*
-rwxr-xr-x. 1 br0ke br0ke 4902 May 30 21:36 pre-rebase.sample*
-rwxr-xr-x. 1 br0ke br0ke  548 May 30 21:36 pre-receive.sample*
-rwxr-xr-x. 1 br0ke br0ke 3639 May 30 21:36 update.sample*

Можно, например, просто переименовать файл pre-commit.sample в pre-commit, и этот хук вступит в силу. В моём случае там на bash реализована проверка имён файлов, которая не допустит добавление файлов с именами, содержащими не-ASCII символы.

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

#!/usr/bin/env bash

# Получаем список файлов, которые пользователь пытается закоммитить,
# и выбираем из них те, которые заканчиваются на `.py`.
# Взято отсюда: https://stackoverflow.com/a/3068990/10650942.
CHANGED_PYTHON_FILES=$(git diff --cached --name-only --diff-filter=ACMR | grep ".py\$")

if [ -z "$CHANGED_PYTHON_FILES" ]
then
   echo "No Python files found. No reason to run checks."
   exit 0
fi

# Включаем режим, в котором любая ошибка сразу же завершит весь скрипт ошибкой.
set -e

# Запускаем проверки.
# Если хотя бы одна завершится ошибкой, то операция будет прервана.
flake8 $CHANGED_PYTHON_FILES
black --check $CHANGED_PYTHON_FILES

echo "All checks successfully passed."

Этот файл должен быть сохранён по пути .git/hooks/pre-commit. Файл нужно сделать исполняемым, иначе Git не сможет его запустить:

$ chmod a+x .git/hooks/pre-commit

Теперь давайте создадим какой-нибудь файл, который точно не пройдет этих проверок. Обратите внимание на лишние пробелы рядом со скобками, которые не понравятся flake8, и на одинарные кавычки, которые не понравятся black:

print( 'Hello world!' )

Попытаемся его закоммитить:

$ git add example.py
$ git commit -v
example.py:1:7: E201 whitespace after '('
example.py:1:22: E202 whitespace before ')'

Наш умный хук выполнился и запустил flake8, который нашел ошибки. Давайте удалим лишние пробелы и попытаемся закоммитить ещё раз:

$ git add example.py
$ git commit -v
would reformat example.py
Oh no! 💥 💔 💥
1 file would be reformatted.

В этот раз flake8 не нашёл ошибок, но операция всё равно завершилась ошибкой из-за black. Давайте отформатируем файл и наконец закоммитим его:

$ black .
$ git add example.py
$ git commit -v

На этот раз всё срабатывает успешно.

Чтобы закоммитить, игнорируя хуки, можно было передать в команду флаг --no-verify или -n:

git commit -v -n

Как видите, писать git-хуки самостоятельно не так уж и сложно. Не обязательно использовать bash, хуки можно писать на чём угодно — любой исполняемый файл подойдет, хоть на интерпретируемом языке, хоть на компилируемом. Если бы нужно было писать какую-то более сложную логику, то я бы, например, предпочёл написать хук на Python.

У такого ручного способа есть несколько недостатков:

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

Используем готовый инструмент — `pre-commit`

Как обычно, для всего уже есть решения. Представляю вашему вниманию pre-commit — умный инструмент для управления Git-хуками.

Установка

pre-commit написан на Python (ещё бы, иначе б я не был его фанатом 😁), поэтому установить его можно через pip. Он должен быть установлен глобально, а не в виртуальном окружении проекта, где вы собираетесь его использовать. Рекомендую использовать метод установки в домашнюю директорию пользователя (см. заметку про виртуальные окружения за подробностями):

$ pip install --user pre-commit

Проверим установку:

$ pre-commit --version
pre-commit 2.4.0

Настройка

pre-commit спроектирован с прицелом на удобное использование сторонних переиспользуемых хуков, но может исполнять и вообще любые команды. Уже написаны сотни полезных хуков для разных языков и задач, из которых, как из конструктора, можно собрать практически любой нужный вам вокрфлоу. Выбирайте те, которые вам понравятся. Для примера я возьму всё те же flake8 и black, и ещё несколько других хуков сверху (а что, бесплатно же).

pre-commit конфигурируется на уровне репозитория при помощи YAML-файла. Файл должен называться .pre-commit-config.yaml и находиться в корне репозитория. Давайте сгенерируем базовый конфиг:

$ pre-commit sample-config > .pre-commit-config.yaml

И допилим примерно до такого состояния:

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
  - repo: 'https://github.com/pre-commit/pre-commit-hooks'
    rev: v2.4.0
    hooks:
      # проверяет наличие переноса строки в конце всех текстовых файлов
      - id: end-of-file-fixer
      # предупреждает о добавлении больших файлов в Git
      - id: check-added-large-files
      # предупреждает о сохранении файлов с UTF-8 BOM
      - id: check-byte-order-marker
      # предотвращает сохранение приватных ключей
      - id: detect-private-key
      # проверяет, что файлы, которые мы собираемся сохранять, как минимум валидный Python
      - id: check-ast
  - repo: 'https://gitlab.com/pycqa/flake8'
    rev: 3.8.2
    hooks:
      - id: flake8
  - repo: 'https://github.com/psf/black'
    rev: 19.10b0
    hooks:
      - id: black

Теперь включим pre-commit в текущем репозитории.

$ pre-commit install

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

Можно убедиться, что pre-commit заменил наш старый хук на свой:

$ cat .git/hooks/pre-commit
#!/usr/bin/env python3.8
# File generated by pre-commit: https://pre-commit.com
...

При этом старый хук был переименован в pre-commit.legacy. Умный pre-commit будет запускать и его тоже, чтобы не сломать текущее поведение. Если это не желательно, то проще всего удалить этот старый файл:

$ rm .git/hooks/pre-commit.legacy

Проверим, что конфигурационный файл валиден, а заодно и что всё нынешнее содержимое репозитория удовлетворяет описанными правилам:

$ pre-commit run --all-files

При первом запуске pre-commit скачает и закэширует все файлы, необходимые для выполнения проверок. Для проверок, которые написаны на Python, будут созданы изолированные виртуальные окружения, так что они никак не будут зависеть от виртуального окружения проекта. Первый раз из-за скачивания зависимостей эта команда может выполняться секунд 30 (в зависимости от скорости интернета), но перезапустите её ещё раз и она завершится за секунду.

Возможно, pre-commit найдёт проблемы или даже исправит некоторые файлы.

Если проверка отработала без ошибок, то конфиг нужно добавить в Git:

$ git add .pre-commit-config.yaml
$ git commit -m “Add pre-commit configuration”

Плагины/зависимости для проверок

Из-за того, что для проверок, написанных на Python, создаются отдельные виртуальные окружения, может быть не совсем понятно, как устанавливать плагины для таких программ, как, например, flake8. Для flake8 важно, чтобы все его плагины были установлены с ним в одно виртуальное окружение, иначе он просто не сможет их найти. Специально для этого у pre-commit предусмотрена настройка additional_dependencies, которая используется вот таким образом:

  - repo: 'https://gitlab.com/pycqa/flake8'
    rev: 3.8.2
    hooks:
      - id: flake8
        additional_dependencies:
          - flake8-bugbear

При следующем запуске pre-commit обнаружит новую зависимость и установит её в то же виртуальное окружение, что и flake8. Теперь перед коммитом будет выполняться не просто голый flake8, но ещё и с дополнительным плагином. Таких зависимостей может быть сколько угодно.

Использование

Теперь можно вообще забыть про существование pre-commit и просто пользоваться Git как обычно, а pre-commit будет выполнять все описанные проверки, изредка беспокоя вас прерванными операциями, если будут найдены какие-нибудь проблемы. Давайте снова попробуем закоммитить тот сломанный файл с пробелами и кавычками:

$ git add example.py
$ git commit -v
Fix End of Files..................................Passed
Check for added large files.......................Passed
Check for byte-order marker.......................Passed
Detect Private Key................................Passed
Check python ast..................................Passed
flake8............................................Failed
- hook id: flake8
- exit code: 1
example.py:1:7: E201 whitespace after '('
example.py:1:22: E202 whitespace before ')'
black.............................................Failed
- hook id: black
- files were modified by this hook
reformatted example.py
All done! ✨ 🍰 ✨
1 file reformatted.

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

На YAML программировать намного приятнее, чем на bash! Да, честно говоря, практически на чём угодно писать приятнее, чем на bash.

Альтернативы `pre-commit`

Мне проще всего использовать инструменты, написанные на знакомом мне языке, но вообще pre-commit далеко не уникальный инструмент и имеет множество альтернатив. Если вы пишете не на Python, то может быть вам будут ближе другие инструменты, хотя все они имеют примерно схожий функционал:

Возможно, вы также найдете для себя что-то полезное на странице “Awesome Git hooks”.

Заключение

Я всегда стараюсь использовать Git-хуки для запуска всех быстрых проверок. Это не дает мне забывать о проверках, и позволяет быстрее получать обратную связь.

Представьте ситуацию, когда сидишь и ждёшь результатов проверок от CI, которые могут быть достаточно долгими (на проекте, где я сейчас работаю, тесты выполняются 8-10 минут), видишь красный крестик, идёшь посмотреть, что же там сломалось, а там всё почти отлично — тесты прошли, но только flake8 нашёл лишний пробел. Чинишь лишний пробел и снова ждёшь 10 минут, чтобы получить свою зелёную галочку. Дак вот хуки спасают от таких ситуаций, потому что все тривиальные проблемы обнаруживаются за несколько секунд локально на моей машине и никогда не попадают в историю Git.

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

Примеры из поста можно найти здесь.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Ссылки

Форматируем код при помощи black

2020-05-26T13:54:45+05:00

Почему полезно форматировать код

В сообществе Python ещё лет 20 назад осознали ценность форматирования кода, когда на свет появился PEP8 — документ, который призван сделать весь код, написанный на Python, оформленным одинаково и поставить точку в бесконечных спорах о стиле оформления кода. PEP8 и правда глубоко вошёл в идеологию Python. Писать код, который нарушает PEP8 — это считается очень плохой практикой. Это одна из первых заповедей, про которые говорят начинающим питонистам.

Почему же консистентный стиль оформления кода так важен, что этому посвящен целый PEP? Самая главная мысль — читаемость важна. Вот какие ещё мысли у меня возникают по поводу стиля оформления кода.

Код быстро меняется. Реалии разработки ПО сегодня очень отличаются от того, что было 50 или 30 лет назад. Тогда код мог быть написан единожды программистом-одиночкой, и работать десятилетиями без изменений. Сегодня код чаще разрабатывается командами программистов, и меняться он должен постоянно, реагируя на изменчивые обстоятельства внешней среды. К консистентно оформленному коду намного проще вернуться в будущем, понять его, найти ошибку и исправить, или допилить новую фичу.
Код пишется один раз, а читается множество раз. Сэкономленная сегодня минута на консистентном оформлении кода может вылиться в часы чтения и попыток понять этот же код завтра (или через полгода). Когда код оформлен одинаково, мозгу не нужно отвлекаться на незначащие детали оформления. Так намного проще вникнуть в суть написанного. В командной разработке просто необходим общий стиль, которого будут придерживаться все.
Код пишется для людей, а не для компьютеров. Машинам абсолютно индифферентно, сколько вы там ставите пробелов, пустых строк, какую длину строки используете или где вы ставите запятые. Если код синтаксически верен, то компьютер отлично вас поймёт. Языки высокого уровня (такие как Python) были специально разработаны для того, чтобы как можно дальше уйти от написания непонятного людям машинного кода. Мы пишем код для людей. Но людям очень важны такие незначащие детали, как отступы, запятые и скобки. С их помощью можно сделать код как понятным с первого взгляда, так и сложным и запутанным.
Время программиста стоит дорого. Писать хорошо оформленный код просто дешевле на долгих дистанциях. Допустим, что оформление кода поможет ускорить его понимание пусть даже всего на 1 минуту. Умножьте на количество человек, которые будут читать этот код, и на (потенциально бесконечное) количество раз, которое они будут к нему возвращаться, и на стоимость работы одного программиста за минуту — получаете кучу сэкономленных деняк.
Консистентный код сокращает количество дискуссий на ревью, потому что коллегам уже не приходится напоминать про скобки и запятые.
Консистентный код порождает меньшие диффы, так что его элементарно проще ревьювить.

Следование PEP8 можно автоматически контролировать при помощи таких инструментов, как flake8 или pylint, но тогда форматировать код придётся вручную. Как мы уже выяснили, время разработчика стоит дорого. Можно ли как-то автоматизировать этот процесс?

Кроме того, PEP8 описывает лишь основные правила оформления кода, но оставляет свободу интерпретации во множестве краевых случаев, из-за чего может появиться неконсистентность оформления. Есть ли какие-нибудь более строгие конвенции, чем PEP8?

`black` — бескомпромиссный форматтер кода

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

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

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

# так?
def func("arg1",
         "arg2",
         kwarg="value")

# или так?
def func(
    "arg1",
    "arg2",
    kwarg="value"
)

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

Да, иногда black выдаёт не самый красивый код, но, если подумать, красота кода не так важна, как консистентность, последовательность, одинаковость. black осознанно приносит красоту в жертву консистентности.

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

Установка

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

black устанавливается из PyPI. Давайте выясним, какая на данный момент последняя доступная версия при помощи следующего трюка (или можно просто её посмотреть на странице проекта на PyPI):

$ pip install black==
Collecting black==
  ERROR: Could not find a version that satisfies the requirement black== (from versions: 18.3a0, 18.3a1, 18.3a2, 18.3a3, 18.3a4, 18.4a0, 18.4a1, 18.4a2, 18.4a3, 18.4a4, 18.5b0, 18.5b1, 18.6b0, 18.6b1, 18.6b2, 18.6b3, 18.6b4, 18.9b0, 19.3b0, 19.10b0)
ERROR: No matching distribution found for black==

Команда завершится ошибкой, но выведет список доступных версий. Найдем последнюю доступную версию и запомним её.

Внутри виртуального окружения нужно выполнить, заменив версию на последнюю:

$ pip install black==19.10b0

А если вы используете pipenv или poetry, то вот так:

$ pipenv install --dev black==19.10b0
$ poetry add --dev black==19.10b0

Обратите внимание, что при установке black через pipenv обязательно нужно указывать конкретную версию. Я описал, что произойдёт, если этого не сделать, а взамен разрешить pipenv устанавливать пре-релизные версии в посте про pipenv.

Использование

black имеет очень интуитивный интерфейс командной строки.

Вот так можно отформатировать все файлы в текущей директории (и рекурсивно в поддиректориях):

$ black .
reformatted /home/br0ke/git/pipenv/pipenv/cli/__init__.py
reformatted /home/br0ke/git/pipenv/pipenv/__init__.py
...
All done! ✨ 🍰 ✨
50 files reformatted, 11 files left unchanged.

И это практически единственная команда, которую вам нужно запомнить.

А вот так можно отформатировать один конкретный файл:

$ black setup.py 
reformatted setup.py
All done! ✨ 🍰 ✨
1 file reformatted.

Интеграция с редактором/IDE

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

Использование в CI

А ещё нужно настроить запуск black в сервисе для непрерывной интеграции (CI), например, GitHub Actions, GitLab CI или Travis CI. Так black сможет блокировать пулл-реквесты (или мердж-реквесты), в которых содержится неотформатированный код.

$ black --check .

В режиме “проверки” black не будет форматировать файлы, а просто напечатает список неотформатированных файлов и завершится кодом ошибки, что должно “уронить” всю проверку целиком.

Конфигурация

Кое-какую минимальную возможность настройки black все-таки предоставляет. Стоит отметить, что в большинстве случаев этого делать не придётся, потому что у black достаточно разумные настройки по умолчанию.

Вот так можно настроить максимальную длину строки и файлы, которые форматировать не нужно. В pyproject.toml в корне проекта добавьте:

[tool.black]
line-length = 88
include = '\.pyi?$'
exclude = '''
(
  /(
      \.eggs         # exclude a few common directories in the
    | \.git          # root of the project
    | \.hg
    | \.mypy_cache
    | \.tox
    | \.venv
    | _build
    | buck-out
    | build
    | dist
  )/
  | foo.py           # also separately exclude a file named foo.py in
                     # the root of the project
)
'''

Настройка `flake8`, чтобы он не противоречил `black`

У flake8 своё мнение по поводу того, как должен быть отформатирован код, которое не всегда совпадает с мнением black. Чтобы не возникало конфликтов, рекомендуется выключить некоторые проверки flake8, по примеру того, как это сделано в репозитории black.

Что меня бесит в стиле `black`

Есть некоторые моменты, с которыми я категорически несогласен. Думаю, рассказать про них тоже нужно.

Рассмотрим пример исходного кода:

print(f"Hello, {user_name}!",
      "What a wonderful day!",
      "I don't know you. Are you new here?" if user_name != "Andrey" else "Nice to meet you again!",
      "Today is",
      datetime.datetime.now().isoformat())

Я специально сделал побольше аргументов в функцию print(), чтобы вызов функции стал достаточно длинным, чтобы black разнёс его на несколько строк. Обратите внимание на тернарный оператор. Теперь отформатируем и посмотрим на результат:

print(
    f"Hello, {user_name}!",
    "What a wonderful day!",
    "I don't know you. Are you new here?"
    if user_name != "Andrey"
    else "Nice to meet you again!",
    "Today is",
    datetime.datetime.now().isoformat(),
)

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

print(
    f"Hello, {user_name}!",
    "What a wonderful day!",
    (
        "I don't know you. Are you new here?"
        if user_name != "Andrey"
        else "Nice to meet you again!"
    ),
    "Today is",
    datetime.datetime.now().isoformat(),
)

Теперь намного понятнее, не правда ли? Такое может произойти не только с тернарными операторами, но и с длинными арифметическими выражениями, и с длинными строками, которые разбиты на несколько частей:

func(True,
     # Обратите внимание, что между следующими "строками" нет
     # запятой, так что фактически это один строковый литерал.
     # Хороший приём для объединения длинных строк внутри скобок.
     "Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
     "Sed dolor massa, mollis a commodo in, molestie in risus.")

Эта функция имеет два аргумента — булевый и строковый. Отформатируем:

func(
    True,
    "Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
    "Sed dolor massa, mollis a commodo in, molestie in risus.",
)

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

func(
    True,
    (
        "Lorem ipsum dolor sit amet, consectetur adipiscing elit. "
        "Sed dolor massa, mollis a commodo in, molestie in risus."
    ),
)

Стало в сто раз лучше. Теперь всё очевидно.

Надеюсь, что когда-нибудь эту шероховатость починят, а до тех пор я просто вручную ставлю скобки вокруг вот такого некрасивого кода. Такое случается не так уж часто. В целом, даже почти не больно.

Заключение

Консистентное форматирование кода — это невероятно важно, потому что упрощает восприятие кода другими людьми (или самим же автором кода, но через полгода). Автоматическое форматирование кода (почти) не требует вообще никаких усилий со стороны автора.

Хоть black и имеет свои недостатки, он всё равно явно окупает усилия, затраченные на ручную расстановку скобок, потому что случается это довольно редко. Как и любой инструмент, black дорабатывается, и будем верить, что все проблемы рано или поздно исправят.

black, наряду с flake8 и pytest, попал в мой набор незаменимых инструментов, которые я пытаюсь использовать во всех своих проектах. И вам рекомендую.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение

Почему print("Hello") работает в Python 2

2020-05-24T11:45:37+05:00

Почему print("Hello") работает в Python 2

Одним из самых заметных отличий Python 3 от Python 2 является разжалование print из инструкции языка (statement) до обычной функции.

Python 3:

# простое использование
print("Hello")
# выводит: Hello

# переданные аргументы по умолчанию объединяются через пробел
print("Hello", "world!")
# выводит: Hello world!

# объединяющий символ можно заменить на свой
print("Pythonic", "attacks!", sep="_")
# выводит: Pythonic_attacks!

# можно заменить символ конца строки на пустую строку,
# чтобы продолжить выводить что-нибудь в той же строке
print("Hello ", end="")
print("world!")
# выводит: Hello world!

Python 2:

# простое использование
print "Hello"
# выводит: Hello

# перечисленные аргументы объединяются через пробел
print "Hello", "world!"
# выводит: Hello world!

# если нужен не пробел, а другой символ для объединения,
# то остаётся делать только вот так:
print "_".join(["Hello", "world!"])
# выводит: Hello_world!

# можно при помощи запятой в конце избежать вывода \n (символа конца строки)
# и продолжить печатать что-нибудь на той же строке:
print "Hello",
print "world!"
# выводит: Hello world!

# если сделать специальный импорт из “будущего”, то
# в Python 2.6+ `print` начинает работать как функция:
from __future__ import print_function
print("Hello", "world!")
# выводит: Hello world!

Обычно инструкциями в Python являются только очень базовые вещи, такие как условия (if), циклы (for, while), возврат из функций (return) и т.д.

Преобразование print в функцию было сделано во имя упрощения синтаксиса языка. Инструкция print для работы требовала значительного количества синтаксических конструкций, например, для отсутствия символа переноса строки (,) или перенаправления вывода в файл (>>). Всё это можно было заставить играть по общим правилам (и даже значительно расширить функционал) через позиционные и именованные аргументы функций, вообще без какого-либо расширения синтаксиса языка. Кроме того, print как функцию можно использовать гораздо гибче — например, фиксируя часть аргументов (каррирование) через functools.partial или использовать её в других функциях (передавать саму функцию как аргумент), типа map() или filter().

Недавно в исходниках библиотеки logging_tree я увидел, что print используется как функция без каких-либо импортов из будущего, при этом у библиотеки заявлена поддержка версий Python, начиная аж с 2.3:

print(build_description(node)[:-1])

Меня это удивило. Я даже создал пулл-реквест, будучи уверен, что нашёл ошибку. После того, как автор возразил, что к нему не поступало никаких жалоб по поводу такого использования print, я решил всё-таки проверить, как это работает. И к ещё большему моему удивлению, это и правда работало на всех версиях Python 2, до которых я смог дотянуться, включая 2.7, 2.6, 2.5, 2.4 и даже 2.3:

# как??
print("Hello")
# выводит: Hello

Немного поразмыслив и почитав, я осознал, где тут собака зарыта. Хоть это и выглядит как вызов функции print(), на самом деле это всё та же старая добрая инструкция print. Давайте разложим всё по полочкам:

# сначала отодвинем скобки от print, чтобы было нагляднее, что это инструкция:
print ("Hello")
# выводит: Hello

# в Python можно засунуть в скобки любое выражение, но пока оно там одно,
# то скобки не оказывают никакого влияния:
("Hello")
# получается просто строка: 'Hello'

# а если выражений несколько, или там есть запятая, то тогда уже
# создаётся кортеж:
("Hello",)  # кортеж из одного элемента
("Hello", "world")  # кортеж из двух элементов

# в нашем случае выражение только одно, поэтому скобки можно отбросить:
print "Hello"
# выводит: Hello

Как выяснилось, в Python 2 print и правда можно так, что со стороны это будет выглядеть как вызов функции, но для очень ограниченного множества случаев, а именно — должен быть только один позиционный аргумент. Такой код будет успешно выполняться и на Python 2 (благодаря описанному трюку), и на Python 3 (по-настоящему).

Разница становится очевидной, если попытаться узнать тип:

# у инструкций нельзя запросить тип, это синтаксически невозможно
>>> type(print)
  File "<stdin>", line 1
    type(print)
             ^
SyntaxError: invalid syntax

# а у функций можно
>>> from __future__ import print_function
>>> type(print)
<type 'builtin_function_or_method'>

Трюки из той же серии:

# условие со скобками как в C:
>>> if(1 == 1):
...     print("Equal!")
...
Equal!

# return как функция:
>>> def func():
...     return(True)
...
>>> func()
True

Это код синтаксически верен, но просто обычно так не пишут. И правильно.

Заключение

Python 2.7 недавно получил свой последний релиз с исправлениями ошибок, и больше никогда не будет обновляться — даже новые найденные баги, связанные с безопасностью, не будут пофикшены. Хочется верить, что все заинтересованные уже обновились до Python 3, и никто больше активно не использует Python 2, в 2020-то году. К сожалению, вряд ли это так. Боюсь, что предсмертная агония Python 2 продлится ещё как минимум несколько лет. Поэтому знать про него хотя бы что-то всё равно полезно.

Благодаря этому случаю я узнал про странный трюк с print и извлёк урок, что нужно как минимум проверять свой фикс, прежде чем засылать куда-то пулл-реквест.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение

Обложка: Photo by mali maeder from Pexels

Chocolatey — пакетный менеджер для Windows

2020-05-18T13:22:50+05:00

Как сказал один мудрец (и по совместительству просто мой друг):

“нет плохих или хороших операционных систем, есть подходящие и не подходящие для решения конкретных пользовательских задач”.

Глубокая мысль, я с этим полностью согласен. Хотя для решения конкретно моих рабочих задач намного лучше подходят другие ОС, у Windows тоже есть своя ниша. Я уже давно привык пользоваться в повседневной деятельности Unix-подобными операционными системами, такими как Fedora Linux и macOS. Но недавно я решил совершить очередной набег в мир Windows — попробовать новые классные фичи WSL2 да в игры поиграть.

Только в этот раз я решил сразу сделать всё по-правильному, и устанавливать весь софт так, чтобы им потом было удобно управлять и обновлять. В поисках решения этой задачи я открыл для себя замечательный инструмент Chocolatey, который теперь считаю жизненно необходимым для комфортного пользования Windows.

Chocolatey — это пакетный менеджер для Windows, примерно как apt в мире Debian/Ubuntu или dnf в мире Fedora/CentOS. Пакетный менеджер занимается установкой, удалением и обновлением программ. Если вам, как и мне, надоело ставить галочки под текстом лицензии (хоть раз вообще читали?) и безразлично нажимать кнопку “далее”, то Chocolatey вам поможет. Он имеет интерфейс командной строки — то, что надо для такого гика, как я! У Chocolatey большая библиотека пакетов — больше 7500 штук, всё популярное там точно есть.

Хоть я привёл в пример apt и dnf, на самом деле, Chocolatey имеет намного больше общего с Homebrew — пакетным менеджером для macOS. В Linux пакетные менеджеры уже давно стали насущной необходимостью — там этим никого не удивить, а Chocolatey и Homebrew работают в окружениях, где изначально пакетные менеджеры не предусмотрены. При этом оба они отлично справляются со своими задачами.

Chocolatey написан на C# и PowerShell, имеет открытый исходный код. Для работы требует Windows 7 или новее.

Установка

Чтобы установить Chocolatey, нужно запустить командную строку с правами администратора. Сделать это в Windows 10 можно так:

Нажимаем на клавиатуре кнопку Win или просто открываем меню "Пуск";
Набираем cmd;
На найденной программе нажимаем правой кнопкой мыши и выбираем пункт “Run as administrator” или, в русской локализации, “Запуск от имени администратора”.

В открывшееся окно терминала нужно вставить следующую команду:

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command " [System.Net.ServicePointManager]::SecurityProtocol = 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"

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

После того, как команда отработает (у меня установка заняла примерно минуту), нужно перезапустить терминал. Вместо cmd можно запустить PowerShell (тоже от имени администратора) — он немного удобнее. Можно проверить установку:

choco -?

Если вы видите справку по команде, то установка прошла успешно.

Установка программ

Давайте установим через choco первые программы. Все эти программы найдены в реестре пакетов и проверены мной — работают. При установке вы можете заметить, что все программы скачиваются с официальных сайтов разработчиков. Если вы переживаете по поводу вирусов, то рекомендую почитать, какие меры предпринимают мейнтейнеры Chocolatey, чтобы обеспечить безопасность пакетов (там всё серьезно).

Во всех командах я добавил флаг -y, чтобы установщик не задавал вообще никаких вопросов. Эта команда автоматически соглашается с лицензиями и разрешает запуск скриптов установки. Ради интереса можете попробовать убрать этот флаг из команд, и посмотреть, что будет.

Допустим, что вам нужен браузер (удалите из команды ненужные названия):

choco install -y googlechrome firefox

Или текстовый редактор/IDE (удалите из команды ненужные названия):

choco install -y notepadplusplus.install vscode

Я являюсь заядлым пользователем PyCharm, который лучше всего устанавливать через JetBrains Toolbox (как и любые другие IDE от JetBrains):

choco install -y jetbrainstoolbox

Инструменты для разработки:

choco install -y git python3 microsoft-windows-terminal postman

Мессенджеры и видео-конференции:

choco install -y telegram.install slack zoom

Игры:

choco install -y steam epicgameslauncher

Всякое прочее-разное полезное:

choco install -y 7zip vlc paint.net teamviewer qbittorrent thunderbird putty.install

И для установки даже не пришлось кликать мышью по кнопкам!

Тут можете почитать про удаление программ при помощи choco.

Обновление

Вот так можно обновить все установленные через choco программы до актуальных версий:

choco upgrade all -y

По-моему, это очень круто и удобно!

Заключение

choco — теперь для меня это просто маст-хэв на Windows. Самая первая программа, которую я буду устанавливать. Благодаря Chocolatey, для меня Windows стала немного дружелюбнее. Всем рекомендую попробовать!

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение

Обложка: Jean Beaufort, Chocolate

Линтеры в Python

2020-05-17T22:38:56+05:00

Линтеры

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

К таким хорошим практикам можно отнести, например, следующие.

Форматировать код по PEP8 — если этого не делать, то другим людям будет намного сложнее понимать ваш код; в плохо оформленном коде сложнее увидеть суть, потому что мозг постоянно отвлекается на не несущие смысловой нагрузки особенности оформления.
Не допускать объявленных, но неиспользуемых переменных/функций/импортов — опять же, это усложняет восприятие кода; читателю потребуется потратить время на то, чтобы осознать, что вот на эту сущность обращать внимания не нужно.
Писать короткие функции — слишком сложные функции с большим количеством ветвлений и циклов тяжело понимать.
Не использовать изменяемый объект в качестве значения аргумента функции по умолчанию — иначе в результате можно получить очень неожиданные эффекты.

Соблюдать (и даже просто помнить) все хорошие практики — не самая простая задача. Зачастую люди плохо справляются с тем, чтобы отсчитывать пробелы и контролировать переменные, и вообще склонны допускать ошибки по невнимательности. Таковы люди, ничего не поделаешь. Машины, наоборот, прекрасно справляются с такими хорошо определёнными задачами, поэтому появились инструменты, которые контролируют следование хорошим практикам.

В компилируемых языках ещё на этапе компиляции программист может получить ~~по щщам~~ первый полезный фидбэк о написанном коде. Компилятор проверит, что код валиден и может быть скомпилирован, а также может выдать предупреждения и рекомендации, как сделать код лучше или читаемее. Т.к. Python является интерпретируемым языком, где этап компиляции как таковой отсутствует, линтеры особенно полезны. На самом деле, это очень важно и круто — узнать, что твой код как минимум является валидным Python-кодом, даже не запуская его.

В этом посте я рассмотрю два самых популярных линтера для Python:

flake8;
pylint.

Термин “lint” впервые начал использоваться в таком значении в 1979 году. Так называлась программа для статического анализа кода на C, которая предупреждала об использовании непортабельных на другие архитектуры языковых конструкций. С тех пор “линтерами” называют любые статические анализаторы кода, которые помогают находить распространённые ошибки, делать его однообразным и более читаемым. А названо оно "lint" в честь вот такой штуки:

flake8

flake8 — это утилита-комбайн, которая органично объединяет в себе несколько других анализаторов кода (pycodestyle, pyflakes и mccabe), а также имеет огромную экосистему плагинов, которые могут добавить к стандартной поставке ещё кучу различных проверок. На данный момент, это самый популярный линтер для Python-кода. Кроме того, он предельно прост в настройке и использовании.

Установка

flake8 устанавливается, как и любой другой Python-пакет, через pip. Внутри виртуального окружения проекта выполните:

$ pip install flake8

Если вы пользуетесь pipenv, то flake8 нужно устанавливать как dev-зависимость (ведь для работы программы линтер не нужен, он нужен только для разработчика):

$ pipenv install --dev flake8

Аналогично с poetry:

$ poetry add --dev flake8

Проверим установку:

$ flake8 --version
3.8.1 (mccabe: 0.6.1, pycodestyle: 2.6.0, pyflakes: 2.2.0) CPython 3.8.2 on Linux

Использование

Для работы flake8 нужно просто указать файл или директорию, которые нужно проверять, например:

# проверить один файл
$ flake8 file.py

# проверить директорию рекурсивно 
$ flake8 src/

# проверить текущую директорию рекурсивно
$ flake8 .

Давайте для демонстрации попытаемся написать программу с как можно большим количеством “плохих практик”:

Возможно, вам не видно всего, но в этом коде точно есть следующие "запахи кода":

import * — импортирование всех имен из модуля, хотя используется из них только одно;
import itertools — ненужный импорт;
во множестве мест стоят лишние или отсутствующие пробелы;
название функции написано в стиле PascalCase;
в некоторых местах используются табы для отступов;
используется список (изменяемый объект) в качестве значения аргумента функции по умолчанию;
используется слишком “широкое” выражение except: без указания конкретного исключения.

Давайте посмотрим, что flake8 скажет по поводу этого файла:

$ flake8 bad_code.py
bad_code.py:1:1: F403 'from math import *' used; unable to detect undefined names
bad_code.py:2:1: F401 'itertools' imported but unused
bad_code.py:4:1: E302 expected 2 blank lines, found 1
bad_code.py:4:4: E271 multiple spaces after keyword
bad_code.py:4:25: E211 whitespace before '('
bad_code.py:4:33: E202 whitespace before ')'
bad_code.py:5:1: W191 indentation contains tabs
bad_code.py:5:8: E271 multiple spaces after keyword
bad_code.py:5:10: F405 'sqrt' may be undefined, or defined from star imports: math
bad_code.py:5:21: E202 whitespace before ')'
bad_code.py:7:1: E302 expected 2 blank lines, found 1
bad_code.py:7:23: E741 ambiguous variable name 'l'
bad_code.py:8:1: E101 indentation contains mixed spaces and tabs
bad_code.py:9:1: E101 indentation contains mixed spaces and tabs
bad_code.py:11:1: E305 expected 2 blank lines after class or function definition, found 1
bad_code.py:12:1: E101 indentation contains mixed spaces and tabs
bad_code.py:13:1: E101 indentation contains mixed spaces and tabs
bad_code.py:13:20: E225 missing whitespace around operator
bad_code.py:14:1: E101 indentation contains mixed spaces and tabs
bad_code.py:14:67: W291 trailing whitespace
bad_code.py:15:1: E101 indentation contains mixed spaces and tabs
bad_code.py:15:14: W291 trailing whitespace
bad_code.py:16:1: E101 indentation contains mixed spaces and tabs
bad_code.py:16:5: E722 do not use bare 'except'
bad_code.py:17:1: E101 indentation contains mixed spaces and tabs

Как видите, flake8 нашёл кучу ошибок. Для каждой ошибки указана строка и номер символа в строке (не всегда точный), где произошла ошибка. Также у каждой категории ошибок есть свой код: E101, W291 и т.д. Эти коды ошибок могут использоваться для включения/отключения правил. Тем не менее, не все ошибки были найдены. Давайте установим пару плагинов, чтобы добавить ещё правил!

Плагины

Как я уже говорил, для flake8 написано множество плагинов. Обычно плагины легко гуглятся или находятся в списках плагинов. Есть плагины для всех популярных фреймворков и библиотек — пользуйтесь ими! Давайте для нашего простого примера установим flake8-bugbear (находит распространённые логические ошибки) и pep8-naming (проверяет имена на соответствие PEP8).

Плагины устанавливаются так же, как и сам flake8 (для краткости я не буду писать примеры для pipenv и poetry — сами сможете обобщить):

$ pip install flake8-bugbear pep8-naming

Давайте убедимся, что плагины действительно установились и flake8 может их найти:

$ flake8 --version
3.8.1 (flake8-bugbear: 20.1.4, mccabe: 0.6.1, naming: 0.10.0, pycodestyle: 2.6.0, pyflakes: 2.2.0) CPython 3.8.2 on Linux

Если вы видите в списке в скобках названия ваших плагинов, то всё хорошо.

Теперь снова проверим наш файл:

$ flake8 bad_code.py
bad_code.py:1:1: F403 'from math import *' used; unable to detect undefined names
bad_code.py:2:1: F401 'itertools' imported but unused
bad_code.py:4:1: E302 expected 2 blank lines, found 1
bad_code.py:4:4: E271 multiple spaces after keyword
bad_code.py:4:6: N802 function name 'CalculateSquareRoot' should be lowercase
bad_code.py:4:25: E211 whitespace before '('
bad_code.py:4:28: N803 argument name 'Number' should be lowercase
bad_code.py:4:33: E202 whitespace before ')'
bad_code.py:5:1: W191 indentation contains tabs
bad_code.py:5:8: E271 multiple spaces after keyword
bad_code.py:5:10: F405 'sqrt' may be undefined, or defined from star imports: math
bad_code.py:5:21: E202 whitespace before ')'
bad_code.py:7:1: E302 expected 2 blank lines, found 1
bad_code.py:7:23: E741 ambiguous variable name 'l'
bad_code.py:7:25: B006 Do not use mutable data structures for argument defaults.  They are created during function definition time. All calls to the function reuse this one instance of that data structure, persisting changes between them.
bad_code.py:8:1: E101 indentation contains mixed spaces and tabs
bad_code.py:9:1: E101 indentation contains mixed spaces and tabs
bad_code.py:11:1: E305 expected 2 blank lines after class or function definition, found 1
bad_code.py:12:1: E101 indentation contains mixed spaces and tabs
bad_code.py:13:1: E101 indentation contains mixed spaces and tabs
bad_code.py:13:20: E225 missing whitespace around operator
bad_code.py:14:1: E101 indentation contains mixed spaces and tabs
bad_code.py:14:67: W291 trailing whitespace
bad_code.py:15:1: E101 indentation contains mixed spaces and tabs
bad_code.py:15:14: W291 trailing whitespace
bad_code.py:16:1: E101 indentation contains mixed spaces and tabs
bad_code.py:16:5: E722 do not use bare 'except'
bad_code.py:16:5: B001 Do not use bare `except:`, it also catches unexpected events like memory errors, interrupts, system exit, and so on.  Prefer `except Exception:`.  If you're sure what you're doing, be explicit and write `except BaseException:`.
bad_code.py:17:1: E101 indentation contains mixed spaces and tabs

В выводе появились новые категории ошибок (N802, B006) — они как раз добавлены плагинами. На этот раз, как мне кажется, найдены все ошибки. К сожалению, flake8 не умеет сам чинить найденные ошибки, поэтому давайте сделаем это вручную:

Обратите внимание на строки 8 и 10, там содержится комментарии # noqa. При помощи этих комментариев можно заставить flake8 игнорировать ошибки. Это бывает полезно, когда по какой-то причине код должен остаться именно таким, например:

он автоматически сгенерирован и исправление в нём ошибок не имеет смысла;
исправление этой ошибки породит куда более уродливый код, чем комментарий # noqa;
у вас просто сейчас нет времени, чтобы исправлять эту ошибку (плохая отмазка, серьёзно).

Если не указать код ошибки, то будут проигнорированы все ошибки в строке — я не рекомендую так делать, потому что так можно пропустить и на самом деле плохие ошибки. Если указать номер правила, то flake8 будет игнорировать только указанную категорию, а о других ошибках в этой же строке доложит. Вообще, комментариями # noqa нужно пользоваться с большой осторожностью. Считайте, что каждый раз, когда вы это делаете, вы берёте на себя ответственность за эту строку кода. Если программа сломается в этом месте, то пеняйте на себя — ~~минздрав~~ линтер вас предупреждал.

Конфигурация

flake8 для работы не требует никакой конфигурации. Он имеет достаточно (но не слишком) строгие настройки по умолчанию, которые подойдут большинству пользователей, но иногда бывает нужно отключить (или наоборот включить) определённые правила на уровне всего проекта. Сделать это можно через файлы .flake8 или setup.cfg в корне проекта. Если у вас в проекте уже есть файл setup.cfg, то можно добавить конфигурацию flake8 в него. Если вы предпочитаете для каждой утилиты держать отдельный файл конфигурации, то используйте .flake8. В любом случае, формат для обоих этих файлов совпадает:

[flake8]
ignore = D203,E741
exclude =
    # No need to traverse our git directory
    .git,
    # There's no value in checking cache directories
    __pycache__,
    # The conf file is mostly autogenerated, ignore it
    docs/source/conf.py,
    # The old directory contains Flake8 2.0
    old,
    # This contains our built documentation
    build,
    # This contains builds of flake8 that we don't want to check
    dist
max-complexity = 10

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

Если же вам не хватает какого-нибудь правила, и его нет даже в уже готовых плагинах, то написание собственного плагина — не такая уж и сложная задача. Я попробовал, у меня на это ушло 2-3 часа.

pylint

pylint — это ещё один популярный линтер для Python. Этот линтер значительно умнее и продвинутее flake8. В pylint из коробки заложено очень много правил и рекомендаций, и по умолчанию они все включены, так что он достаточно строгий и придирчивый. Чтобы интегрировать его в существующий большой проект придётся потратить некоторое время, чтобы выбрать те правила, которые для вас важны. Так же как и flake8, pylint поддерживает плагины для расширения базовой функциональности, но насколько я вижу, экосистема плагинов у pylint значительно беднее.

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

Установка

Установка pylint принципиально ничем не отличается от установки flake8. Выполнить внутри виртуального окружения проекта:

$ pip install pylint

Для pipenv:

$ pipenv install --dev pylint

Для poetry:

$ poetry add --dev pylint

Использование

pylint можно натравить на определённый файл:

$ pylint file.py

С директориями у pylint дела обстоят чуть сложнее. Все директории он обрабатывает как питоновские модули, поэтому если в директории нет хотя бы пустого файла __init__.py, то работать с ней pylint не сможет. Имейте это ввиду.

Давайте попросим pylint прокомментировать файл с плохими практиками из предыдущего примера:

$ pylint bad_code.py
************* Module bad_code
bad_code.py:4:25: C0326: No space allowed before bracket
def  CalculateSquareRoot (Number ):
                         ^ (bad-whitespace)
bad_code.py:4:33: C0326: No space allowed before bracket
def  CalculateSquareRoot (Number ):
                                 ^ (bad-whitespace)
bad_code.py:5:0: W0312: Found indentation with tabs instead of spaces (mixed-indentation)
bad_code.py:5:21: C0326: No space allowed before bracket
    return  sqrt(Number )
                     ^ (bad-whitespace)
bad_code.py:13:19: C0326: Exactly one space required around assignment
        your_number=float(input('Enter your number: '))
                   ^ (bad-whitespace)
bad_code.py:14:66: C0303: Trailing whitespace (trailing-whitespace)
bad_code.py:15:13: C0303: Trailing whitespace (trailing-whitespace)
bad_code.py:1:0: W0622: Redefining built-in 'pow' (redefined-builtin)
bad_code.py:1:0: C0114: Missing module docstring (missing-module-docstring)
bad_code.py:1:0: W0401: Wildcard import math (wildcard-import)
bad_code.py:4:0: C0103: Function name "CalculateSquareRoot" doesn't conform to snake_case naming style (invalid-name)
bad_code.py:4:0: C0103: Argument name "Number" doesn't conform to snake_case naming style (invalid-name)
bad_code.py:4:0: C0116: Missing function or method docstring (missing-function-docstring)
bad_code.py:7:0: W0102: Dangerous default value [] as argument (dangerous-default-value)
bad_code.py:7:0: C0103: Argument name "l" doesn't conform to snake_case naming style (invalid-name)
bad_code.py:7:0: C0116: Missing function or method docstring (missing-function-docstring)
bad_code.py:16:4: W0702: No exception type(s) specified (bare-except)
bad_code.py:1:0: W0614: Unused import acos from wildcard import (unused-wildcard-import)
bad_code.py:1:0: W0614: Unused import acosh from wildcard import (unused-wildcard-import)
bad_code.py:1:0: W0614: Unused import asin from wildcard import (unused-wildcard-import)
bad_code.py:1:0: W0614: Unused import asinh from wildcard import (unused-wildcard-import)
...
bad_code.py:2:0: W0611: Unused import itertools (unused-import)
-------------------------------------
Your code has been rated at -41.43/10

Я немного сократил вывод. Как видите, даже без плагинов pylint нашёл все ожидаемые ошибки, и даже больше — например, он даже предлагает написать документацию.

По каждой ошибке можно запросить более подробную справку, используя название правила из конца строки с ошибкой или код:

$ pylint --help-msg=missing-docstring
$ pylint --help-msg=R0902

Вот какие ошибки pylint находит для файла, который с точки зрения flake8 не содержит никаких ошибок:

$ pylint not_so_bad_code.py 
************* Module not_so_bad_code
not_so_bad_code.py:1:0: C0114: Missing module docstring (missing-module-docstring)
not_so_bad_code.py:4:0: C0116: Missing function or method docstring (missing-function-docstring)
not_so_bad_code.py:8:0: C0103: Argument name "l" doesn't conform to snake_case naming style (invalid-name)
not_so_bad_code.py:8:0: C0116: Missing function or method docstring (missing-function-docstring)
not_so_bad_code.py:20:11: W0703: Catching too general exception Exception (broad-except)
-----------------------------------
Your code has been rated at 6.67/10

А вот так в pylint можно игнорировать отдельную ошибку на строке прямо в файлах с кодом:

def append_item(item, l=None):  # pylint: disable=C0103
   ...

Ещё pylint умеет игнорировать ошибки в блоках кода:

def test():
    # Disable all the no-member violations in this function
    # pylint: disable=no-member
    ...

И для файлов целиком. Вот так можно отключить все ошибки из категорий Warning, Convention и Refactor:

# pylint: disable=W,C,R

А можно не проверять файл вообще:

# pylint: skip-file

Подробнее о правилах управления сообщениями смотрите в документации. Для более сложной настройки правил, придётся по-настоящему сконфигурировать pylint.

Конфигурация

pylint настраивается через файл .pylintrc в корне проекта. Чтобы создать дефолтный файл конфигурации, нужно выполнить следующую команду:

$ pylint --generate-rcfile > .pylintrc

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

Плагины

Давайте установим какой-нибудь популярный плагин, например, pylint-django:

$ pip install pylint-django

Теперь запускать pylint нужно вот так:

$ pylint --load-plugins pylint_django [..other options..] <path_to_your_sources>

либо в .pylintrc нужно исправить директиву load-plugins:

load-plugins=pylint_django

Интеграция линтера в проект

Интегрировать линтер в проект можно на трёх уровнях. Я рекомендую по возможности использовать все три, но обязательным является как минимум один (лучше всего, чтобы это была CI система).

Редактор кода или IDE

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

PyCharm автоматически находить установленные flake8 и pylint внутри интерпретатора проекта и подключается к ним.

VS Code требует небольшой настройки, которая описана здесь.

Git-хуки

Также читайте пост про Git-хуки и pre-commit.

В git есть возможность запрограммировать определенные скрипты (хуки) в ответ на действия пользователя. Например, можно запускать какие-нибудь проверки перед коммитом, заново скачивать зависимости проекта при переключении веток, высылать сообщение в рабочий чат после пуша в удалённый репозиторий и вообще что угодно.

Нас интересует возможность запускать линтер перед коммитом так, чтобы если линтер найдёт какие-нибудь проблемы, операция коммита прерывалась. Git-хуки можно настроить, написав несложный shell-скрипт, но я рекомендую использовать для этого специальные утилиты, такие как pre-commit. Вот здесь можно найти описание процесса настройки запуска flake8 через pre-commit.

Обратите внимание, что Git-хуки нужно будет настроить на машине каждого разработчика в проекте.

Continuous Integration (CI)

Последний эшелоном защиты от попадания “сломанного” кода в основную ветку репозитория является система непрерывной интеграции (CI) — такая, как:

GitHub Actions;
GitLab CI (а ещё читайте пост в блоге моего хорошего товарища про основы GitLab CI);
Travis CI;
или другая.

На каждый пуш в репозиторий система непрерывной интеграции должна запускать проверки (включая все линтеры и тесты), и если что-то идёт не так, рядом с коммитом должен появиться красный крестик. Ветку с таким коммитом на конце нельзя будет слить с основной веткой проекта через пулл-реквест на GitHub (или мёрдж-реквест на GitLab). Пример того, как настроить GitHub Actions для запуска flake8 и других питоновских проверок.

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

Заключение

В подзаголовке этой статьи я написал фразу, что линтер способен сэкономить разработчику один день жизни в месяц. Фраза может показаться кликбейтной, но, поверьте мне, это так это и работает. Возможно, я даже преуменьшил. Чем раньше найдена ошибка, тем быстрее идёт разработка. Иногда линтер предотвращает баги, иногда спасает от мучительного траблшутинга. Линтеры абсолютно точно значительно сокращают время, потраченное коллегами на код-ревью, потому что все тривиальные ошибки будут отловлены автоматикой.

Не стоит недооценивать линтеры. Это те инструменты, которые делают из “кодера” настоящего “software engineer”, из мальчика — мужчину. Если вы до сих пор не пользуетесь каким-нибудь линтером, то рекомендую всерьез задуматься над внедрением!

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

У pylint тоже есть свои последователи. Его ценят за подробный вывод и большое количество правил в стандартной поставке. Мне же pylint всегда казался слишком сложным в эксплуатации.

А кто-то вообще рекомендует устанавливать flake8 и pylint параллельно.

Если понравилась статья, то подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение

Обложка: Sa Mu, Traffic Light

Управление версиями чего угодно при помощи asdf

2020-05-13T11:05:32+05:00

asdf

Нет, это не просто кто-то уронил четыре пальца на клавиатуру!

В предыдущей статье я писал про pyenv — отличный инструмент для установки различных версий интерпретатора. Для питонистов pyenv вполне достаточно, но люди, пишущие на нескольких языках, могут обнаружить себя в ситуации, когда им приходится держать установленными pyenv, rvm / rbenv, nvm, rustup, gvm или ещё какие-нибудь менеджеры версий для разных языков программирования. При этом, конечно же, у каждого инструмента свой синтаксис команд, свои тонкости по работе с ним, свои зависимости. Если установить это всё сразу в свой шелл, то боюсь представить, что будет с переменной $PATH (она будет очень толстой). Потенциально это может замедлить работу шелла вообще. Но все эти проблемы остались в прошлом — встречайте asdf, универсальный менеджер версий!

asdf, так же как и pyenv, написан на чистом bash. Это означает, что инструмент отлично работает под Linux и MacOS, но, к сожалению, никак не работает на Windows (ну, разве что в WSL). asdf сам по себе не требует никаких внешних зависимостей, кроме некоторых базовых утилит, типа git и curl, которые и так наверняка у вас есть. Эти утилиты нужны для установки плагинов.

Вокруг asdf выстроилась огромная экосистема плагинов. Именно благодаря плагинам asdf и именует себя универсальным менеджером версий.

Преимущества:

не нужно учить диалекты команд для каждой отдельной утилиты, чтобы делать типовые действия;
умеет управлять версиями всех мыслимых и немыслимых инструментов и языков программирования через плагины;
можно настроить версии локально для определённой директории и asdf автоматически переключит версии инструментов при входе в неё;
классное название — удобно печатать.

Недостатки:

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

Установка

Установка во всех подробностях описана на официальном сайте. Глупо было бы пытаться описать установку лучше, чем на оф.сайте — лучше и не напишешь. Документация у asdf просто бомбическая. Есть варианты установки на Linux или MacOS (через brew), описана настройка для всех популярных шеллов — bash, zsh и fish. Всё просто — выбираете вашу систему и шелл, и получаете команды по установке и настройке.

Обратите внимание, что для корректной работы asdf требует наличия git и curl. Если вдруг у вас в системе нет таких утилит, то инструкции по установке опять-таки можно найти на сайте asdf.

После установки перезапустите ваш шелл и проверьте установку:

$ asdf
...
"Late but latest"
-- Rajinikanth

Если вы видите этот девиз asdf после справки по командам, то установка удалась, можно продолжать. Девиз в моём вольном переводе означает что-то типа "да, поздновато, но после нас подобных утилит уже не будет". Амбициозно, но я думаю, что asdf и правда в силах вытеснить с рынка все другие подобные утилиты, которые специфичны для одного языка.

Плагины

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

$ asdf plugin list all

У меня вывелось аж 194 штуки. Список плагинов можно посмотреть и на сайте, вот здесь.

Есть плагины для всех популярных языков программирования:

python;
nodejs;
rust;
java;
kotlin;
golang;
php;
ruby;
и, конечно же, для вашего любимого языка плагин тоже наверняка есть.

Кроме того, через asdf можно управлять версиями различных утилит, например:

github-cli;
jq;
kubectl;
poetry.

И сервисов, например:

postgres;
mysql;
mongodb;
redis.

Установка интересующего плагина выполняется следующим образом:

$ asdf plugin add <имя плагина>

Рассмотрим работу с теми плагинами, с которыми мне доводилось работать.

Плагин для Python

Установим плагин для Python:

$ asdf plugin add python

asdf имеет очень логично организованный интерфейс командной строки. Запомните одно правило: если хотите просмотреть только установленные плагины или версии плагина, то делайте list, а если вообще все, то list all.

	плагин	версия
все	asdf plugin list all	asdf list all python
установленные	asdf plugin list	asdf list python

Выше мы уже смотрели список всех плагинов (через list all), а теперь давайте просмотрим список установленных плагинов. Там должен быть python, мы ведь его только что установили:

$ asdf plugin list
python

Отлично, плагин установлен! Давайте попросим asdf показать список доступных версий (хотим вообще все, поэтому list all) для плагина python:

$ asdf list all python
…
3.6-dev
3.6.1
3.6.2
3.6.3
3.6.4
3.6.5
3.6.6
3.6.7
3.6.8
3.6.9
3.6.10
3.7.0
3.7-dev
3.7.1
3.7.2
3.7.3
3.7.4
3.7.5
3.7.6
3.7.7
3.8.0
3.8-dev
3.8.1
3.8.2
3.9.0a6
3.9-dev
…

Список я подсократил, но поверьте — он длинный. Там есть как все версии эталонного интерпретатора CPython, начиная с 2.1.3, так и альтернативные реализации Python — PyPy, IronPython, Jython, MicroPython и другие. Этот список очень напоминает подобный список из pyenv, и это не просто совпадение. Плагин asdf-python действительно под капотом использует pyenv.

В процессе установки asdf скачивает исходники Python и собирает интерпретатор из них. Это значит, что на машине придётся иметь установленные инструменты для сборки кода на C/C++ и все нужные библиотеки-зависимости. Список зависимостей для всех ОС и дистрибутивов можно посмотреть здесь. Обязательно установите эти зависимости прежде чем пытаться устанавливать какой-либо интерпретатор.

Установка конкретной версии интерпретатора происходит вот так:

$ asdf install python 3.7.7
$ asdf install python 3.8.2

Давайте запросим список установленных версий (list):

$ asdf list python
  3.7.7
  3.8.2

Давайте назначим глобальной ту версию Python, которую собираемся использовать чаще всего. Она будет использоваться по умолчанию, когда не найдена никакая локальная версия. Здесь всё работает так же, как и в pyenv, но даже если вы никогда им не пользовались, то я надеюсь, что дальше по примеру станет понятно как работают глобальные и локальные версии:

$ asdf global python 3.8.2
$ python -V
Python 3.8.2

Если вам интересно, как работает asdf, то:

$ which python
/home/br0ke/.asdf/shims/python

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

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

$ mkdir my_project
$ cd my_project

Установим локальную версию:

$ asdf local python 3.7.7
$ python -V
Python 3.7.7

В этой директории asdf создал специальный файл .tool-versions (аналог .python-version из pyenv):

$ cat .tool-versions
python 3.7.7

Этот файл содержит версии всех утилит, которые мы настроили для директории, т.е. потенциально тут может быть не только Python. Как правило, этот файл не нужно добавлять в систему контроля версий (git), особенно если asdf в рамках проекта пользуетесь только вы.

asdf также вместо универсального .tool-versions умеет использовать файлы, специфичные для отдельных языков или инструментов, такие как .python-version (pyenv), .ruby-version (rbenv), .nvmrc и .node-version (nodejs) и другие. Это сделано для того, чтобы облегчить миграцию на asdf с других менеджеров версий. По умолчанию эта функциональность выключена, а включатся созданием файла ~/.asdfrc со следующим содержимым:

legacy_version_file = yes

При выходе из директории локально настроенная версия перестанет действовать и версия вернётся на глобальную:

$ cd ..
$ python -V
Python 3.8.2

По-моему, это очень удобно. В целом asdf работает так же как pyenv и многие другие менеджеры версий — в конце концов, они вдохновлены одной идеей. Только asdf вдохновился сильнее.

Допустим, что нужда прижала вас установить IPython:

$ pip install ipython

Чтобы IPython можно было запускать, нужно попросить asdf пересоздать шимы:

$ asdf reshim
$ ipython
Python 3.8.2 (default, May 10 2020, 22:17:35) 
Type 'copyright', 'credits' or 'license' for more information
IPython 7.14.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]: print("asdf is awesome!")

Плагин для Node.js

Установим плагин для Node.js:

$ asdf plugin add nodejs

Запросим список доступных версий:

$ asdf list all nodejs
…
12.16.3
13.0.0
13.0.1
13.1.0
13.2.0
13.3.0
13.4.0
13.5.0
13.6.0
13.7.0
13.8.0
13.9.0
13.10.0
13.10.1
13.11.0
13.12.0
13.13.0
13.14.0
14.0.0
14.1.0
14.2.0

Все инструменты устанавливаются по-разному, и плагины это учитывают. Например, Python собирался из исходников, а Node.js устанавливается простым скачиванием бинарника, так что никакие зависимости для сборки не нужны.

Но у плагина Node.js тоже есть свои тонкости. Чтобы установить версию интерпретатора Node.js, нужно добавить ключи мейнтейнеров проекта Node.js в систему. Это нужно, чтобы при установке плагин asdf-nodejs проверил цифровую подпись бинарника (в системе должна быть установлена утилита установлена gpg):

$ bash ~/.asdf/plugins/nodejs/bin/import-release-team-keyring

Теперь установим последнюю на данный момент версию Node.js:

$ asdf install nodejs 14.2.0

Назначим её глобальной и проверим работу:

$ asdf global nodejs 14.2.0
$ node
Welcome to Node.js v14.2.0.
Type ".help" for more information.
> console.log("asdf is super awesome!")
asdf is super awesome!
undefined

Давайте вернемся в директорию из предыдущего примера и добавим там ещё и локальную версию Node.js:

$ cd my_project
$ asdf local nodejs 14.2.0

Теперь в .tool-versions лежит следующее содержимое:

$ cat .tool-versions 
python 3.7.7
nodejs 14.2.0

Заключение

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

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

Обязательно подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение

Обложка: idreamlikecrazy, One Ring to rule them all

Установка нескольких версий Python параллельно при помощи pyenv

2020-05-04T11:17:51+05:00

В большинстве операционных систем Python предустановлен (ну, кроме Windows, но даже там теперь есть команда python, которая предложит установить интерпретатор из магазина приложений). В Unix-подобных операционных системах, таких как Linux и MacOS, Python пустил корни очень глубоко. Множество компонентов ОС рассчитывают, что Python установлен и работает стабильно. Это и хорошо, и плохо.

Это хорошо, потому что хотя бы какой-то Python в большинстве систем доступен из коробки — бери и пользуйся. Иногда доступно сразу несколько версий интерпретатора, например, python2 указывает на устаревшую версию 2.7, python3 — на какую-нибудь стабильную версию Python 3, типа 3.6 или 3.7, а просто python указывает либо на одно, либо на другое (в последнее время предпочтение чаще отдаётся третьей версии). Для обучения или для тестирования этого может быть вполне достаточно.

С другой стороны, это плохо, потому что, как правило, предустановленный Python настолько стабилен, что уже успел зарасти мхом. В некоторых системах до сих пор предустановлен только Python 2, но даже если вам повезёт получить Python третьей версии, то наверняка он будет отставать от последней версии на пару минорных релизов. Не факт, что вам это подойдёт.

Иногда нужно иметь сразу несколько версий Python для работы над разными проектами, например, 3.7 и 3.8. В некоторых ОС нужные версии можно установить через пакетный менеджер (например, в Fedora через dnf) — из основных репозиториев или из сторонних. Но зачастую такие репозитории содержат не все релизы интерпретаторов, а лишь выбранное мейнтейнерами репозиториев подмножество.

Решение у всех этих проблем одно — нужно установить недостающие версии интерпретатора, какими бы они ни были. Этому и посвящён пост.

pyenv

pyenv — утилита, которая позволяет легко переключаться между несколькими версиями интерпретатора Python, а также устанавливать новые. Позволяет устанавливать, наверное, вообще все известные науке версии интерпретаторов Python. Работает просто и незаметно.

pyenv — это всего лишь один из последователей аналогичного инструмента из мира Ruby — rbenv. Есть ещё и nodenv для Node.js, который тоже вдохновился rbenv.

Проект написан целиком на bash. Это значит, что он никак не зависит от Python — было бы забавно, если бы для установки Python нужен был бы Python. Также это означает, что на Windows pyenv работать не будет (тред с обсуждением). Следует отметить, что в Windows проблема установки нескольких версий и не возникает — там всегда можно скачать и установить сколько угодно интерпретаторов с официального сайта, а pylauncher поможет выбрать из них нужную версию. Кроме того, пользователи современных версий Windows могут использовать pyenv внутри WSL (Windows Subsystem for Linux). Ещё это означает, что у авторов много отваги — я бы не решился писать на bash что-то настолько сложное. Как же хорошо, что всё уже написано.

Установка

Скачаем pyenv.

Установка pyenv производится простым клонированием git-репозитория.

У проекта есть умный скрипт, который скачает pyenv и его сотоварищей:
```
$ curl https://pyenv.run | bash
```
Скрипт не требует прав суперпользователя (без sudo), потому что всё устанавливается в домашнюю директорию пользователя. Туда же будут устанавливаться и интерпретаторы. Если страшно запускать какие-то скрипты из интернета (так и должно быть), то прочитать код скрипта можно здесь.
Настроим шелл.

Предыдущая команда перед завершением должна была напечатать инструкции по настройке шелла. Допустим, в случае с bash она выводит следующее:
```
WARNING: seems you still have not added 'pyenv' to the load path.

# Load pyenv automatically by adding
# the following to ~/.bashrc:

export PATH="~/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
```
В случае с zsh нужно будет добавить те же самые строки в ~/.zshrc.

В случае с fish в связи с особенностями самого шелла инструкции отличаются:
```
# Load pyenv automatically by adding
# the following to ~/.config/fish/config.fish:

set -x PATH "~/.pyenv/bin" $PATH
status --is-interactive; and . (pyenv init -|psub)
status --is-interactive; and . (pyenv virtualenv-init -|psub)
```
Кстати, горячо рекомендую попробовать fish, очень удобный шелл.
Установим зависимости для сборки.

При установке новой версии интерпретатора через pyenv под капотом происходит сборка из исходников, поэтому для успешной установки необходимы некоторые зависимости. Полный и актуальный список для своей ОС смотрите здесь или здесь. Лучше установить всё заранее.
Перезапустим шелл и проверим установку.
```
$ pyenv --version
pyenv 1.2.18
```

Как это работает

pyenv работает благодаря манипуляциям над переменной окружения $PATH. Эта переменная содержит в себе список директорий, в которых ОС будет искать исполняемые файлы, вызванные без указания полного пути. Именно благодаря этой переменной мы можем в терминале вместо /bin/cat вызывать просто cat. Когда мы набираем в терминале имя программы (cat), ОС перебирает директории из $PATH слева направо, пока в одной из них (в данном примере /bin) не найдёт программу с именем cat, которую и запустит. Поиск прекращается после первого совпадения.

Команда pyenv init -, которую мы добавили в конфиг шелла (.bashrc или аналог) добавляет директории pyenv в самое начало переменной $PATH. Зачем это нужно? pyenv создаёт небольшие исполняемые файлы, так называемые файлы-прослойки (shims), для всех команд, которыми он собирается управлять, например, python, pip, ipython и так далее. Эти файлы-прослойки должны попасть в $PATH прежде самих управляемых программ и "затенить" системные python, pip и так далее. Эти файлы-прослойки в конечном счёте просто вызывают сам pyenv с нужными аргументами. Таким образом pyenv перехватывает обращения к некоторым именам, и анализируя поступившую к нему информацию, принимает решение о том, какую именно версию Python нужно запустить. При выборе версии pyenv принимает во внимание следующие факторы в указанном порядке:

Переменная окружения PYENV_VERSION, если указана.

В неё можно указать какую конкретно версию Python нужно использовать в рамках текущего сеанса. Удобно, если вам по какой-то причине понадобится сменить выбранную версию интерпретатора, например, в одном из окон терминала.
Локальная версия Python.

При помощи специального файла .python-version можно настроить версию интерпретатора для определенного проекта. Захо́дите внутрь директории (cd project/), и pyenv внезапно понимает, что нужно сменить Python. Выхо́дите обратно — версия Python меняется на глобальную. Это распространяется и на все поддиректории проекта — pyenv рекурсивно ищет файл .python-version вверх по файловой системе, пока не дойдёт до корня.
Глобальная версия Python.

В файле ~/.pyenv/version записана глобальная версия Python, которая будет использоваться по умолчанию, если не сконфигурирована локальная версия.

Вам вряд ли придётся вручную трогать эти файлы, потому что у pyenv есть удобные команды (pyenv local и pyenv global), чтобы ими управлять, но знать о файлах всё равно полезно.

Использование

Установка новой версии Python

Сначала посмотрим, какие версии Python pyenv может установить:

$ pyenv install --list
...
3.6.0
3.6-dev
3.6.1
3.6.2
3.6.3
3.6.4
3.6.5
3.6.6
3.6.7
3.6.8
3.6.9
3.6.10
3.7.0
3.7-dev
3.7.1
3.7.2
3.7.3
3.7.4
3.7.5
3.7.6
3.7.7
3.8.0
3.8-dev
3.8.1
3.8.2
3.9.0a6
3.9-dev
...

Список довольно длинный, поэтому я его подсократил. Обычно вас будут интересовать такие версии, как 3.8.2 или 3.7.7 — это версии самой распространённой реализации интерпретатора CPython. Но если вам нужна экзотика, то pyenv умеет устанавливать любые сорта интерпретаторов Python (pypy3.6-7.3.0, stackless-3.7.5, jython-2.7.1, ironpython-2.7.7, micropython-1.12 и т.д.). Для вас ведь не стало новостью, что существует много разных реализаций интерпретатора Python?

Установим CPython 3.8.2:

$ pyenv install 3.8.2
Downloading Python-3.8.2.tar.xz...
Installing Python-3.8.2...

Через пару минут ожидания ваш новоиспечённый Python будет готов.

Можно сразу же назначить эту версию глобальной:

$ pyenv global 3.8.2
$ python -V
Python 3.8.2

Давайте в целях демонстрации установим ещё парочку интерпретаторов:

$ pyenv install 2.7.18
$ pyenv install 3.9.0a6

Получим список установленных версий интерпретатора:

$ pyenv versions
  2.7.18
* 3.8.2 (set by /home/br0ke/.pyenv/version)
  3.9.0a6

Кстати, если нужно, то можно делать активными сразу несколько версий одновременно:

$ pyenv global 3.8.2 2.7.18

Теперь вывод версий покажет следующее:

$ pyenv versions
* 2.7.18 (set by /home/br0ke/.pyenv/version)
* 3.8.2 (set by /home/br0ke/.pyenv/version)
  3.9.0a6

А работать это будет вот таким образом:

$ python -V
Python 3.8.2
$ python3 -V
Python 3.8.2
$ python2 -V
Python 2.7.18

Грубо говоря, та версия, которая указана первой (3.8.2), имеет приоритет и занимает все нужные ей имена. Следующие версии (2.7.18) могут занять любые оставшиеся свободные имена (в данном случае, это только имя python2).

А файл глобальной версии ~/.pyenv/version на данный момент имеет вот такое содержимое:

$ cat ~/.pyenv/version
3.8.2
2.7.18

Локальная версия

Давайте создадим директорию и войдём в неё:

$ mkdir my_project
$ cd my_project

Представим, что в этой директории мы будем разрабатывать некий проект, на котором мы хотим опробовать фишки нового Python 3.9. Сообщим об этом pyenv:

$ pyenv local 3.9.0a

В директории появился файл .python-version со следующим содержимым:

$ cat .python-version
3.9.0a6

На данный момент список версий показывает следующее (удобно использовать эту команду, чтобы понять какую версию и почему pyenv активирует):

$ pyenv versions
  2.7.18
  3.8.2
* 3.9.0a6 (set by /home/br0ke/my_project/.python-version)

Изменения немедленно вступили в силу:

$ python -V
Python 3.9.0a6

Но эта конфигурация никак не влияет на работу pyenv вне директории проекта:

$ cd ..
$ python -V
3.8.2

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

Установим IPython

Часто бывает нужно установить какой-нибудь пакет так, чтобы он тоже стал доступен из командной строки. Допустим, что нам нужно установить ipython — более удобную версию REPL Python. Сделаем это:

$ cd my_project
$ pip install ipython

Запустим:

$ ipython
Python 3.9.0a6 (default, May  3 2020, 16:58:20)
Type 'copyright', 'credits' or 'license' for more information
IPython 7.14.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

Программа сразу доступна, благодаря тому, что pyenv очень умный и создал новый файл-прослойку (shim) автоматически:

$ which ipython
/home/br0ke/.pyenv/shims/ipython

Вне директории с проектом ipython будет недоступен, ведь он же установлен в локальный интерпретатор 3.9.0a6, а снаружи активирован другой интерпретатор — можете проверить самостоятельно.

Возникают ситуации, когда по какой-то причине прослойка не создалась или с ней случилось что-то ещё, например, удалилась:

$ rm $(which ipython)
$ ipython
No such file or directory

Не беда! Можно попросить pyenv пересоздать их все заново:

$ pyenv rehash

И всё работает снова:

$ ipython
Python 3.9.0a6 (default, May  3 2020, 16:58:20)
Type 'copyright', 'credits' or 'license' for more information
IPython 7.14.0 -- An enhanced Interactive Python. Type '?' for help.

In [1]:

Можно вообще добавить команду pyenv rehash в свой ~/.bashrc (или аналог), чтобы при запуске шелла гарантированно иметь рабочие файлы-прослойки (shims).

Заключение

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

Обязательно подпишитесь на уведомления о новых постах в блоге, чтобы ничего не пропустить!

Дополнительное чтение

Обложка: Schwoaze, Snakes Black Snakes Animal Free Photo

pipenv — как pip, только удобнее

2020-04-29T13:56:47+05:00

pipenv

pipenv — это замечательный проект, который призван упростить организацию рабочего процесса для Python-разработчиков. Он решает несколько наиболее актуальных для разработчика проблем (да, несколько, вопреки Unix-way). Этакий швейцарский нож для питонистов.

pipenv нельзя рассматривать как замену pip, скорее это надстройка над pip. Но даже PyPA всерьёз рекомендует рассмотреть pipenv для управления зависимостями приложений, что как минимум означает, что проект хорошо зарекомендовал себя в сообществе.

Изначальный автор проекта — Кеннет Рейц (Kenneth Reitz) — он ещё и автор requests и множества других проектов "for humans", очевидно, вдохновлялся пакетными менеджерами из других экосистем, такими как npm (JavaScript) и bundler (Ruby), так что если вы когда-то пользовались этими инструментами, то можете заметить множество параллелей.

В названии проекта кроются два основных его назначения:

pip — установка и управления зависимостями проекта;
env — создание и управление виртуальным окружением для проекта.

Грубо говоря, pipenv можно рассматривать как симбиоз утилит pip и venv (или virtualenv), которые работают вместе, пряча многие неудобные детали от конечного пользователя.

Помимо этого pipenv ещё умеет вот такое:

автоматически находить интерпретатор Python нужной версии (находит даже интерпретаторы, установленные через pyenv и asdf!);
запускать вспомогательные скрипты для разработки;
загружать переменные окружения из файла .env;
проверять зависимости на наличие известных уязвимостей.

Стоит сразу оговориться, что если вы разрабатываете библиотеку (или что-то, что устанавливается через pip, и должно работать на нескольких версиях интерпретатора), то pipenv — не ваш путь. Этот инструмент создан в первую очередь для разработчиков конечных приложений (консольных утилит, микросервисов, веб-сервисов). Формат хранения зависимостей подразумевает работу только на одной конкретной версии интерпретатора (это имеет смысл для конечных приложений, но для библиотек это, как правило, не приемлемо). Для разработчиков библиотек существует другой прекрасный инструмент — poetry.

Итак, начнём по порядку.

Установка

Как я писал в посте про виртуальные окружения, не стоит устанавливать пакеты в глобальный интерпретатор, поэтому предпочтительным способом установки является пакетный менеджер вашей ОС.

Например, на MacOS pipenv можно установить через brew:

$ brew install pipenv

А на Fedora Linux вот так:

$ sudo dnf install pipenv

На Ubuntu можно установить pipenv из специального PPA:

$ sudo apt install software-properties-common python-software-properties
$ sudo add-apt-repository ppa:pypa/ppa
$ sudo apt update
$ sudo apt install pipenv

Во всех остальных случаях, в частности на Windows, самый простой способ — это установка в домашнюю директорию пользователя (опять же, см. пост про виртуальные окружения):

$ pip install --user pipenv

Теперь проверим установку:

$ pipenv --version
pipenv, version 2018.11.26

Если вы получили похожий вывод, значит, всё в порядке.

При возникновении проблем с установкой, обратитесь к официальной документации. Если совсем беда, то напишите комментарий под этим постом, попробуем помочь 😊

Файлы `pipenv`

pipenv использует свой собственный формат файла для описания зависимостей проекта — Pipfile. Этот файл имеет формат TOML. В принципе его можно редактировать руками, но pipenv достаточно неплохо и сам умеет обновлять этот файл, когда вы просто работаете с утилитой через командную строку. Структуру этого файла рассмотрим чуть позже.

В паре с Pipfile идёт Pipfile.lock. Он имеет формат JSON и не предназначен для редактирования руками. Этот файл хранит контрольные суммы пакетов, которые вы устанавливаете в проект, что даёт гарантию, что развёрнутые на разных машинах окружения будут идентичны друг другу. pipenv автоматически обновляет контрольные суммы в этом файле, когда вы устанавливаете или обновляете зависимости. При развёртывании окружения pipenv сверит сохранённые контрольные суммы с фактически получившимися, и в случае чего уведомит вас, что развёртывание не удалось. Это очень важный плюс в копилку pipenv по сравнению с pip.

Оба этих файла можно и нужно сохранять в системе контроля версий (git).

Вообще, идею использовать два файла для описания зависимостей нельзя назвать новой. Здесь явно прослеживается параллель между Gemfile и Gemfile.lock из мира Ruby и package.json и package-lock.json из мира JavaScript. Все эти файлы имеют схожее назначение.

Использование

Инициализация проекта

Давайте создадим простой проект под управлением pipenv.

Подготовка:

$ mkdir pipenv_demo
$ cd pipenv_demo

Создать новый проект, использующий конкретную версию Python можно вот такой командой:

$ pipenv --python 3.8

Если же вам не нужно указывать версию так конкретно, то есть шорткаты:

# Создает проект с Python 3, версию выберет автоматически.
$ pipenv --three

# Аналогично с Python 2.
# В 2020 году эта опция противопоказана.
$ pipenv --two

После выполнения одной из этих команд, pipenv создал файл Pipfile и виртуальное окружение где-то в заранее определенной директории (по умолчанию вне директории проекта).

$ cat Pipfile
[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]

[requires]
python_version = "3.8"

Это минимальный образец Pipfile. В секции [[source]] перечисляются индексы пакетов — сейчас тут только PyPI, но может быть и ваш собственный индекс пакетов. В секциях [packages] и [dev-packages] перечисляются зависимости приложения — те, которые нужны для непосредственной работы приложения (минимум), и те, которые нужны для разработки (запуск тестов, линтеры и прочее). В секции [requires] указана версия интерпретатора, на которой данное приложение может работать.

Очень полезно правильно разделять зависимости на "основные" и "разработческие". Это позволит уменьшить размер окружения при развёртывании на продакшн (например, размер Docker-образа). Кроме того, чем меньше в системе, работающей на продакшне, установлено пакетов, тем меньше потенциальных уязвимостей.

Если вам нужно узнать, где именно pipenv создал виртуальное окружение (например, для настройки IDE), то сделать это можно вот так:

$ pipenv --py
/Users/and-semakin/.local/share/virtualenvs/pipenv_demo-1dgGUSFy/bin/python

Управление зависимостями через `pipenv`

Теперь давайте установим в проект первую зависимость. Делается это при помощи команды pipenv install:

$ pipenv install requests

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

$ cat Pipfile
...

[packages]
requests = "*"

...

В секцию [packages] добавилась зависимость requests с версией * (версия не фиксирована).

А теперь давайте установим зависимость, которая нужна для разработки, например, восхитительный линтер flake8, передав флаг --dev в ту же команду install:

$ pipenv install --dev flake8

$ cat Pipfile
...

[dev-packages]
flake8 = "*"

...

Теперь можно увидеть всё дерево зависимостей проекта при помощи команды pipenv graph:

$ pipenv graph
flake8==3.7.9
  - entrypoints [required: >=0.3.0,<0.4.0, installed: 0.3]
  - mccabe [required: >=0.6.0,<0.7.0, installed: 0.6.1]
  - pycodestyle [required: >=2.5.0,<2.6.0, installed: 2.5.0]
  - pyflakes [required: >=2.1.0,<2.2.0, installed: 2.1.1]
requests==2.23.0
  - certifi [required: >=2017.4.17, installed: 2020.4.5.1]
  - chardet [required: >=3.0.2,<4, installed: 3.0.4]
  - idna [required: >=2.5,<3, installed: 2.9]
  - urllib3 [required: >=1.21.1,<1.26,!=1.25.1,!=1.25.0, installed: 1.25.9]

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

Также, пока мы устанавливали пакеты, pipenv создал Pipfile.lock, но этот файл длинный и не интересный, поэтому показывать содержимое я не буду.

Удаление и обновление зависимостей происходит при помощи команд pipenv uninstall и pipenv update соответственно. Работают они довольно интуитивно, но если возникают вопросы, то вы всегда можете получить справку при помощи флага --help:

$ pipenv uninstall --help
$ pipenv update --help

Управление виртуальными окружениями

Давайте удалим созданное виртуальное окружение:

$ pipenv --rm

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

$ pipenv sync --dev

Эта команда на основе Pipfile.lock воссоздаст точно то же самое виртуальное окружение, что и у других разработчиков проекта.

Если же вам не нужны dev-зависимости (например, вы разворачиваете ваш проект на продакшн), то можно не передавать флаг --dev:

$ pipenv sync

Чтобы "войти" внутрь виртуального окружения, нужно выполнить:

$ pipenv shell
(pipenv_demo) $

В этом режиме будут доступны все установленные пакеты, а имена python и pip будут указывать на соответствующие программы внутри виртуального окружения.

Есть и другой способ запускать что-то внутри виртуального окружения без создания нового шелла:

# это запустит REPL внутри виртуального окружения
$ pipenv run python

# а вот так можно запустить какой-нибудь файл
$ pipenv run python script.py

# а так можно получить список пакетов внутри виртуального окружения
$ pipenv run pip freeze

Переменные окружения

Согласно идеологии 12-факторных приложений, конфигурацию принято хранить отдельно от кода, а лучше всего конфигурацию вообще хранить в переменных окружения (environment variables или env vars). Чтобы упростить работу с переменными окружения в процессе разработки, широкое айти-сообщество придумало сохранять их в специальный файл .env и загружать в шелл по мере необходимости. Такие файлы используются во множестве фреймворков, инструментов и экосистем. pipenv упрощает работу с переменными окружения в Python-проектах.

Давайте создадим файл .env и запишем туда какое-нибудь значение:

SECRET_VALUE=hello pipenv!

ВАЖНО: файл .env может содержать пароли для подключения к СУБД или токены для доступа к внешним сервисам. Такие данные никогда не должны попадать в git.

Давайте напишем небольшой скрипт (script.py), который будет использовать эту переменную окружения:

import os

print("Secret value:", os.environ.get("SECRET_VALUE"))

Попробуем запустить его без использования pipenv:

$ python script.py
Secret value: None

Скрипт вместо секретного значения вывел None, потому что переменная окружения так и осталась просто лежать в файле, и никак не повлияла на работу скрипта. А теперь запустим этот же скрипт через pipenv:

$ pipenv run python script.py
Loading .env environment variables…
Secret value: hello pipenv!

pipenv увидел файл .env и автоматически загрузил переменные из него. Скрипт вывел то значение, которое мы и ожидали увидеть. Команда pipenv shell тоже подгружает переменные окружения из файла.

Запуск скриптов

Часто в процессе разработки встречаются повторяющиеся задачи. Если вы работаете в команде, то ваши коллеги наверняка тоже с ними сталкиваются. Было бы разумно сохранить/задокументировать где-то команды, нужные для решения этих повторяющихся задач, чтобы их было проще найти и чтобы они всегда выполнялись одинаково. Можно, конечно, использовать обычные .sh файлы, но у pipenv тоже есть инструмент, который может в этом помочь, и даже лучше.

Допустим, что вы регулярно запускаете проверку кода flake8, но с указанием дополнительных флагов, например, вам не нужно проверять определенную директорию, а так же вы хотите пропускать один вид ошибок (правильнее было бы просто сохранить эти параметры в конфигурационный файл, но примера ради будем передавать всё через командную строку):

$ flake8 --exclude=tests --ignore=E121 .

Отредактируем Pipfile, создав там секцию [scripts] со следующим содержимым:

[scripts]
lint = "flake8 --exclude=tests --ignore=E121 ."

Теперь тот же самый скрипт можно запустить при помощи команды:

$ pipenv run lint

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

Распространённые проблемы

Перечислю проблемы, с которыми я сталкивался в процессе работы с pipenv.

Лишние зависимости в виртуальном окружении

Бывает, что кроме перечисленных в Pipfile и Pipfile.lock зависимостей в виртуальном окружении установлены и другие пакеты. Такое может случиться, например, при переключении между ветками в git, где в Pipfile.lock находятся разные зависимости. Или, банально, если внутри виртуального окружения вы установите что-то через pip помимо pipenv.

Чаще всего вам будет безразлично, есть в виртуальном окружении какие-то лишние пакеты или нет, но иногда такие лишние пакеты влияют на работу приложения. Пример из моей практики: ORM orator будет использовать тот драйвер для подключения к MySQL, который первым найдёт в виртуальном окружении, поэтому если вы хотите использовать pymysql, то нужно убедиться, что в виртуальном окружении нет MySQLdb (он приоритетнее).

Нужно учитывать, что команда pipenv sync --dev только доустанавливает пакеты в виртуальное окружение, но не удаляет оттуда уже установленные. Поэтому, если вам нужно обеспечить отсутствие в виртуальном окружении лишних пакетов, то приходится удалять его полностью и создавать заново:

$ pipenv --rm && pipenv sync --dev

Пререлизные зависимости

По умолчанию pipenv игнорирует нестабильные альфа- и бета-версии пакетов, и устанавливает только стабильные. Может случиться так, что вам нужно установить пререлизную версию пакета, например, автоформаттер black, который на данный момент всё ещё не имеет стабильных релизов вообще:

$ pipenv install --dev black
...
  Hint: try $ pipenv lock --pre if it is a pre-release dependency.
ERROR: ERROR: Could not find a version that matches black
Skipped pre-versions: 18.3a0, 18.3a0, 18.3a1, 18.3a1, 18.3a2, 18.3a2, 18.3a3, 18.3a3, 18.3a4, 18.3a4, 18.4a0, 18.4a0, 18.4a1, 18.4a1, 18.4a2, 18.4a2, 18.4a3, 18.4a3, 18.4a4, 18.4a4, 18.5b0, 18.5b0, 18.5b1, 18.5b1, 18.6b0, 18.6b0, 18.6b1, 18.6b1, 18.6b2, 18.6b2, 18.6b3, 18.6b3, 18.6b4, 18.6b4, 18.9b0, 18.9b0, 19.3b0, 19.3b0, 19.10b0, 19.10b0
There are incompatible versions in the resolved dependencies.

Команда завершилась ошибкой, но pipenv предлагает воспользоваться опцией --pre, чтобы установить пререлизную зависимость. Избегайте искушения сделать так.

Что произойдёт, если всё-таки рискнуть:

$ pipenv install --dev --pre black
...
✔ Installation Succeeded

На первый взгляд, всё хорошо. Но давайте заглянем в Pipfile:

$ cat Pipfile
...
[pipenv]
allow_prereleases = true

Там появилась директива allow_prereleases = true, которая глобально меняет поведение pipenv и разрешает ему устанавливать пререлизные версии вообще любых зависимостей, а не только той, которую вы хотели установить. Если у вас в Pipfile не ограничены версии зависимостей (как у requests = "*"), то следующий запуск pipenv install или pipenv update может принести в ваш проект кучу нестабильных зависимостей. Не факт, что приложение это переживёт.

Чтобы установить пререлизную зависимость правильно, нужно указать конкретную версию:

$ pipenv install --dev black==19.10b0

Если же вы уже попались в эту ловушку pipenv, то просто отредактируйте Pipfile и либо удалите оттуда директиву allow_prereleases вообще, либо поменяйте значение на false. После этого можно спать спокойно.

Мердж-конфликты в `Pipfile.lock`

Когда в двух параллельных ветках происходит установка или обновление пакетов, либо просто редактируется Pipfile, то при слиянии этих веток обязательно произойдет конфликт в Pipfile.lock. Git добавит в этот файл маркеры конфликтов, после чего, само собой, он перестает быть валидным JSON. В таких случаях pipenv просто превращается в тыкву и ничего не может сделать:

$ pipenv sync --dev
...
json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 3 column 8 (char 24)

План выхода из такой ситуации следующий: 1. Не пытайтесь осознанно решать конфликты в Pipfile.lock вручную, всё равно не сможете; pipenv сам создал этот файл, вот пусть сам и разбирается. 2. Разрешите конфликт в любую сторону, главное, чтобы в итоге получился валидный JSON. 3. Пересоздайте Pipfile.lock заново:

$ pipenv lock --keep-outdated

Флаг --keep-outdated позволяет избежать лишних обновлений версий — вы ведь просто хотите разрешить конфликты, а не обновить все пакеты, верно? Тем не менее, pipenv может вас проигнорировать, и всё равно обновить некоторые пакеты, будьте к этому готовы (это известный баг).

Статус проекта: пациент скорее мертв, чем жив, но надежда есть

Стоит отметить, что после какой-то драмы в сообществе, изначальный автор (Kenneth Reitz) покинул проект (и вообще все свои проекты), и проект перешёл в общественное достояние. Любые такие конфликты всегда плохо сказываются на успехе проекта, и pipenv, определенно, переживает сейчас не лучшие времена. На данный момент последний релиз был 26 ноября 2018 года. За полтора года накопилось большое количество незарелиженных баг-фиксов, что говорит о проблемах с поддержкой проекта.

Несмотря на это, я всё равно рекомендую присмотреться к pipenv, потому что он действительно хорош. Недавно проект стал проявлять признаки жизни, и я очень надеюсь, что всё с ним будет хорошо. По-моему, это очень важный для экосистемы Python проект.

Обновление от 30 мая 2020: pipenv наконец выпустил долгожданный релиз 2020.5.28.

Обновляемся:

$ pip install --user --upgrade pipenv

Проект будет жить!

Заключение

Вместо заключения оставлю вас поразмышлять над вот этой программой:

def use_pipenv():
    know_common_workflows()
    distinguish_between_main_and_dev_dependencies()
    use_dot_env_file()
    use_scripts()
    know_pitfalls()
    print("PROFIT!!!!!")


if work_on_application:
    use_pipenv()
elif work_on_library:
    use_poetry()
else:
    print("wtf")
    use_pip()

Дополнительное чтение

Подпишитесь!

Чтобы получить уведомление о новом посте можно:

подписаться на канал в Telegram (альтернативная ссылка);
подписаться на Atom-фид, если ~~вы олдфаг-старовер~~ вам так удобно.

Обложка: James Case, Victorinox Swiss Army Knife

requirements.txt — что это и зачем?

2020-04-22T22:00:00+05:00

requirements.txt

В исходниках множества Python-проектов можно встретить этот странный текстовый файл. Например, им пользуются urllib3, numpy, pandas, flake8 и куча других проектов. Давайте разберемся, что это такое, как этим пользоваться и зачем нам это нужно.

Гипотетическая предыстория

Давайте представим, что вы написали замечательный скрипт, который спрашивает у пользователя название города и выводит текущую температуру и общее состояние погоды:

Скрипт получился настолько хорош, что вы хотите поделиться им со всеми своими друзьями. К сожалению, друзья при попытке запустить вашу программу получают следующую ошибку:

Traceback (most recent call last):
  File "weather.py", line 3, in <module>
    from pyowm import OWM
ModuleNotFoundError: No module named 'pyowm'

Кажется, что скинуть только код недостаточно.

Или, допустим, что вы сами через полгода-год попытаетесь запустить эту же программу. За это время вы успели пару раз переустановить Python, переустановить ОС, отформатировать свой магнитный накопитель (используйте SSD — нет, я серьёзно!) или может быть вообще сменили компьютер. Почти уверен, что при запуске скрипта вы получите ровно ту же самую ошибку.

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

Если ваша программа небольшая (состоит из пары файлов), то можно довольно легко просмотреть её глазами, найти там все инструкции import, отсеять из них импорты из стандартной библиотеки (вы ведь знаете модули стандартной библиотеки наизусть, да?), и таким образом восстановить список внешних зависимостей программы, которые устанавливаются через pip. Чем крупнее проект, тем сложнее это сделать. Бывают ситуации, когда по коду вообще нельзя понять, что ему нужна определенная зависимость.

Я хочу сказать, что намного мудрее составлять этот список зависимостей сразу же и просто поддерживать его в актуальном состоянии по мере развития проекта.

requirements.txt — это список внешних зависимостей

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

Стоит отметить, что requirements.txt не является стандартом, т.е. нет документа, который описывал бы требования к этому файлу. Скорее, это просто распространённая практика в сообществе, которая, наверное, возникла спонтанно и хорошо прижилась.

Не обязательно называть файл именно requirements.txt, можно назвать его как угодно, лишь бы его назначение оставалось понятно. Я встречал такие вариации, как requirements-dev.txt, test-requirements.txt, requirements/docs.txt и другие.

Вот пример самого простого такого файла (кстати, именно этим файлом можно описать зависимости, которые нужны для запуска нашего скрипта с погодой):

pyowm

Если бы было несколько зависимостей, то файл выглядел бы так:

numpy
requests
pytest

Можно указать конкретную версию зависимости. Если версия не указана, то считается, что нужна последняя доступная:

numpy  # нужна последняя версия
requests==2.23.0  # нужна конкретная версия

Можно указывать диапазоны и другие более сложные "спецификаторы версий". В целом, в requirements.txt можно писать любые "запросы", которые понимает команда pip install:

requests>=2.20.0,<2.23.0  # подойдет любая версия между 2.20.0 и 2.23.0
numpy!=1.0  # подойдет любая версия, кроме 1.0

Как пользоваться

Команда pip install умеет читать такие файлы, если передать специальный флаг:

$ pip install --help
...
Install Options:
  -r, --requirement <file>    Install from the given requirements file. This option can be used multiple times.
...

Таким образом, если requirements.txt будет иметь вот такое содержимое:

pytest
flake8
black
isort

То следующие две команды будут иметь одинаковое действие:

$ pip install -r requirements.txt

$ pip install pytest flake8 black isort

Преимущества использования requirements.txt:

Краткость.

На таком маленьком примере разница может быть не очевидна, но когда список зависимостей разрастётся до определенного размера, то вам не захочется больше перечислять его в pip install напрямую.
Стабильность.

Как бы ни поменялся файл requirements.txt, команда pip install -r requirements.txt не поменяется.
Универсальность.

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

Как создать

Есть два подхода:

создавать этот файл вручную;
генерировать автоматически.

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

Но можно использовать и встроенную в pip функциональность:

(env) $ pip freeze
certifi==2020.4.5.1
chardet==3.0.4
geojson==2.5.0
idna==2.9
pyowm==2.10.0
requests==2.23.0
urllib3==1.25.9

Команда pip freeze выводит все установленные в интерпретатор сторонние пакеты. Заметьте, что в список попали не только прямые зависимости (pyowm), но и подзависимости — это даже лучше, потому что вы сможете более точно воссоздать окружение по этому файлу.

Можно перенаправить вывод этой команды в файл при помощи стандартного консольного приема (работает и на Windows), и получить валидный файл requirements.txt:

(env) $ pip freeze > requirements.txt

Обратите внимание, что pip freeze выведет список пакетов в том окружении, в котором он запущен. Не забудьте активировать виртуальное окружение перед запуском этой команды, иначе получите список пакетов, установленных в глобальный интерпретатор. Кстати, у меня есть пост про виртуальные окружения, где объясняется как ими пользоваться.

Подытожим плюсы и минусы ручного и автоматического подходов:

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

Можно использовать и смешанный подход: сгенерировать начальную версию файла при помощи pip freeze и допилить её затем руками, если у вас какая-то сложная нестандартная ситуация.

⚠️ Файл requirements.txt, конечно же, должен быть добавлен в систему контроля версий (git). Это такая же важная часть проекта, как и код. При этом виртуальное окружение не должно попадать в систему контроля версий. Оно должно воссоздаваться из requirements.txt.

Проблемы `requirements.txt`

Некоторые пакеты часто меняются, поэтому если вы не указываете конкретные версии, то в следующий раз при установке вы можете получить совсем другую среду. Это бывает особенно обидно, когда локально на машине разработчика всё работает правильно, но при деплое на боевой сервер программа либо работает иначе, либо вообще отказывается запускаться. Поэтому обязательно фиксируйте версии пакетов в requirements.txt — это сделает разные окружения хотя бы примерно похожими.

Почему "хотя бы примерно"? Практика показывает, что зафиксировать версию пакета недостаточно. Иногда случается, что под одной версией пакета в разное время может находиться совершенно разный код. PyPI, конечно, не позволит перезаписать уже опубликованную версию, но, например, ваш приватный корпоративный индекс пакетов может быть не таким строгим.

Чтобы действительно гарантировать, что вы устанавливаете те пакеты, что и ожидали, нужно рассчитывать и сверять их контрольные суммы. requirements.txt может содержать хэши пакетов, но, к сожалению, на данный момент нет простого стандартного способа как их туда положить, кроме как вручную (сложно). В качестве альтернативы опять предлагаю присмотреться к таким проектам, как poetry (хранит хэши в poetry.lock) и pipenv (хранит хэши в Pipfile.lock), где эта проблема решена хорошо, и вам не придётся переживать о воспроизводимости ваших сборок. Если всё-таки хочется добиться такого же эффекта при помощи requirements.txt, то можно посмотреть на такие проекты как pip-tools (пример использования) и hashin.

Заключение

requirements.txt — это очень популярный способ хранения списка внешних зависимостей проекта, поэтому вам определенно нужно уметь работать с такими файлами. Однако этот способ хранения списка зависимостей не лишён недостатков, поэтому если вы начинаете новый проект, то я предлагаю вам лучше использовать для этого poetry или pipenv.

Для тренировки можно попытаться запустить скрипт с погодой. Все исходники лежат здесь.

Дополнительное чтение

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

Секция PIP User Guide про requirements.txt;
А вот тут подробное описание формата requirements-файлов;
А ещё бывают constraints.txt;
Бонус: PyCharm умеет умно обновлять requirements.txt.

Подпишитесь!

Чтобы получить уведомление о новом посте можно:

подписаться на канал в Telegram (альтернативная ссылка);
подписаться на Atom-фид, если ~~вы олдфаг-старовер~~ вам так удобно.

Обложка: Joe deSousa, Gnarled Tree

Виртуальные окружения в Python

2020-04-18T20:42:16+05:00

Python знаменит своей обширной стандартной библиотекой и девизом "батарейки в комплекте" (batteries included). Даже из коробки Python позволяет удобно и быстро решить огромный пласт задач, например, например, работа с файлами, запуск простого веб-сервера, работа с электронной почтой, парсинг XML и JSON, и так далее. Во всяком случае, это намного удобнее, чем писать shell-скрипты 😅

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

Установка сторонней библиотеки

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

$ pip install requests

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

Как `pip` устанавливает пакеты

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

pip обращается в PyPI (Python Package Index) и находит там запрашиваемый пакет.
Пакет скачивается. Обычно это просто zip-архив, который содержит код библиотеки, разложенный внутри согласно формату. Современным и рекомендуемым форматом пакетов является wheel (PEP-427), но в дикой природе встречаются и другие форматы.
pip устанавливает пакет.
Библиотека установлена, ее можно импортировать и использовать.

Давайте подробнее разберем третий шаг. Установка пакета — звучит загадочно и сложно, но на самом деле ничего сложного здесь не происходит. pip просто распаковывает zip-архив в определенное место (это справедливо для формата wheel, для установки пакетов в других форматах могут потребоваться дополнительные действия, но давайте разберем самый распространённый и простой случай). Куда именно происходит установка? Это можно узнать, выполнив следующую команду:

$ python -m site
sys.path = [
    '/Users/and-semakin',
    '/Users/and-semakin/.asdf/installs/python/3.8.2/lib/python38.zip',
    '/Users/and-semakin/.asdf/installs/python/3.8.2/lib/python3.8',
    '/Users/and-semakin/.asdf/installs/python/3.8.2/lib/python3.8/lib-dynload',
    '/Users/and-semakin/env/lib/python3.8/site-packages',
]
USER_BASE: '/Users/and-semakin/.local' (exists)
USER_SITE: '/Users/and-semakin/.local/lib/python3.8/site-packages' (doesn't exist)
ENABLE_USER_SITE: False

В списке sys.path можно увидеть директорию site-packages — именно туда и будет установлена библиотека. Давайте в этом убедимся.

До установки пакета:

$ ls -l /Users/and-semakin/env/lib/python3.8/site-packages
total 8
drwxr-xr-x   3 and-semakin  awesome    96 Apr 18 17:39 __pycache__
-rw-r--r--   1 and-semakin  awesome   126 Apr 18 17:39 easy_install.py
drwxr-xr-x   7 and-semakin  awesome   224 Apr 18 17:39 pip
drwxr-xr-x   9 and-semakin  awesome   288 Apr 18 17:39 pip-19.2.3.dist-info
drwxr-xr-x   7 and-semakin  awesome   224 Apr 18 17:39 pkg_resources
drwxr-xr-x  42 and-semakin  awesome  1344 Apr 18 17:39 setuptools
drwxr-xr-x  11 and-semakin  awesome   352 Apr 18 17:39 setuptools-41.2.0.dist-info

Установим пакет:

$ pip install requests

После установки пакета:

$ ls -l /Users/and-semakin/env/lib/python3.8/site-packages
total 8
drwxr-xr-x   3 and-semakin  awesome    96 Apr 18 17:39 __pycache__
drwxr-xr-x   7 and-semakin  awesome   224 Apr 18 17:41 certifi
drwxr-xr-x   8 and-semakin  awesome   256 Apr 18 17:41 certifi-2020.4.5.1.dist-info
drwxr-xr-x  43 and-semakin  awesome  1376 Apr 18 17:41 chardet
drwxr-xr-x  10 and-semakin  awesome   320 Apr 18 17:41 chardet-3.0.4.dist-info
-rw-r--r--   1 and-semakin  awesome   126 Apr 18 17:39 easy_install.py
drwxr-xr-x  11 and-semakin  awesome   352 Apr 18 17:41 idna
drwxr-xr-x   8 and-semakin  awesome   256 Apr 18 17:41 idna-2.9.dist-info
drwxr-xr-x   7 and-semakin  awesome   224 Apr 18 17:39 pip
drwxr-xr-x   9 and-semakin  awesome   288 Apr 18 17:39 pip-19.2.3.dist-info
drwxr-xr-x   7 and-semakin  awesome   224 Apr 18 17:39 pkg_resources
drwxr-xr-x  21 and-semakin  awesome   672 Apr 18 17:41 requests
drwxr-xr-x   8 and-semakin  awesome   256 Apr 18 17:41 requests-2.23.0.dist-info
drwxr-xr-x  42 and-semakin  awesome  1344 Apr 18 17:39 setuptools
drwxr-xr-x  11 and-semakin  awesome   352 Apr 18 17:39 setuptools-41.2.0.dist-info
drwxr-xr-x  16 and-semakin  awesome   512 Apr 18 17:41 urllib3
drwxr-xr-x   8 and-semakin  awesome   256 Apr 18 17:41 urllib3-1.25.9.dist-info

Как видим, в директорию site-packages добавилась библиотека requests вместе со всеми своими зависимостями.

Важные мысли, которые я пытаюсь донести:

установка библиотеки напрямую влияет на файловую систему;
у интерпретатора Python есть только одна директория site-packages, куда pip и устанавливает пакеты.

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

Боль — это жизненный опыт

Что же будет, если вам понадобится работать над двумя проектами, которые будут требовать разных, не совместимых между собой версий одной и той же библиотеки? Возможно, между этими версиями в библиотеку были внесены какие-то крупные ломающие изменения, например, переименовались методы/функции или изменился набор аргументов.

Например, проект А:

# requirements.txt
requests==2.23.0

Проект Б:

# requirements.txt
requests==1.2.3

Вы просто не сможете работать над такими проектами одновременно. Установка зависимостей одного проекта сломает другой, и наоборот. При переключении между проектами придётся каждый раз устанавливать зависимости нужного проекта, что довольно легко забыть сделать.

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

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

Виртуальные окружения

Решение очевидно — у каждого проекта должен быть свой интерпретатор Python, со своей собственной изолированной директорией site-packages. Это и есть основная идея, стоящая за виртуальными окружениями. Виртуальное окружение — это самостоятельная копия интерпретатора со своими пакетами.

Как создавать виртуальные окружения

Начиная с Python версии 3.5 (на данный момент это самая старая из официально поддерживаемых версий языка, так что справедливо ожидать, что как минимум везде установлен Python 3.5 или новее), создать виртуальное окружение стало очень просто:

$ python -m venv <путь к виртуальному окружению>

Например, допустим, что мы работаем над проектом blog_source:

# заходим в директорию с проектом
$ cd src/blog_source

# создаем виртуальное окружение прямо рядом с кодом в директории env
$ python -m venv env

Создавать виртуальное окружения рядом с кодом — это распространённая практика, так проще ничего не перепутать, но вообще виртуальное окружение может быть где угодно, и директория тоже может называться как угодно. Обратите внимание, что если вы создаете виртуальное окружение в директории под управлением системы контроля версий (git), то его не нужно коммитить. Лучше вообще добавьте его (env/) в .gitignore.

В директорию env будет скопирован тот самый интерпретатор, при помощи которого виртуальное окружение и создавалось. Т.е. если

$ python -V
Python 3.8.2

то в виртуальном окружении будет та же самая версия:

$ env/bin/python -V
Python 3.8.2

Активируем окружение

Посмотрим, что внутри директории env:

$ ls -l env/
total 8
drwxr-xr-x  13 and-semakin  awesome  416 Apr 18 18:55 bin
drwxr-xr-x   2 and-semakin  awesome   64 Apr 18 18:55 include
drwxr-xr-x   3 and-semakin  awesome   96 Apr 18 18:55 lib
-rw-r--r--   1 and-semakin  awesome  113 Apr 18 18:55 pyvenv.cfg

$ ls -l env/bin/
total 88
-rw-r--r--  1 and-semakin  awesome  8471 Apr 18 18:55 Activate.ps1
-rw-r--r--  1 and-semakin  awesome  2218 Apr 18 18:55 activate
-rw-r--r--  1 and-semakin  awesome  1270 Apr 18 18:55 activate.csh
-rw-r--r--  1 and-semakin  awesome  2422 Apr 18 18:55 activate.fish
-rwxr-xr-x  1 and-semakin  awesome   268 Apr 18 18:55 easy_install
-rwxr-xr-x  1 and-semakin  awesome   268 Apr 18 18:55 easy_install-3.8
-rwxr-xr-x  1 and-semakin  awesome   250 Apr 18 18:55 pip
-rwxr-xr-x  1 and-semakin  awesome   250 Apr 18 18:55 pip3
-rwxr-xr-x  1 and-semakin  awesome   250 Apr 18 18:55 pip3.8
lrwxr-xr-x  1 and-semakin  awesome    59 Apr 18 18:55 python -> /Users/and-semakin/.asdf/installs/python/3.8.2/bin/python
lrwxr-xr-x  1 and-semakin  awesome     6 Apr 18 18:55 python3 -> python

Обратите внимание, что в директории bin есть некий файл activate в нескольких вариантах для разных шеллов. Это и есть "точка входа" в виртуальное окружение. Просто создать виртуальное окружение мало, нужно его активировать. Но сначала проверим, какие python и pip (исполняемые файлы) используются в обычном режиме работы:

$ which python
/Users/and-semakin/.asdf/shims/python
$ which pip
/Users/and-semakin/.asdf/shims/pip

Это мой обычный Python, вне виртуального окружения, назовём его глобальным. Теперь активируем виртуальное окружение:

$ source env/bin/activate
(env) $

Для Windows процесс активации будет отличаться (допустим, что виртуальное окружение создано в C:\src\blog_source):

# cmd
C:\src\blog_source\> env\Scripts\activate.bat

# либо в PowerShell
PS C:\src\blog_source\> env\Scripts\Activate.ps1

Обратите внимание, что приветствие шелла изменилось (добавилось (env)), чтобы показать, что мы "внутри" виртуального окружения под названием env.

Теперь проверим еще раз, какие python и pip используются:

(env) $ which python
/Users/and-semakin/src/blog_source/env/bin/python
(env) $ which pip
/Users/and-semakin/src/blog_source/env/bin/pip

Посмотрите на пути — мы внутри виртуального окружения! Теперь можно смело устанавливать любые пакеты, и это никак не повлияет на глобальный Python или на другие виртуальные окружения:

(env) $ pip install requests flask whatever-you-need

Можно запускать любые файлы, и они будут иметь доступ к установленным пакетам:

(env) $ python make_money.py
Done! You are rich!

IDE тоже нужно настроить, указав путь к bin/python внутри виртуального окружения, тогда редактор сможет лучше вам помогать.

По завершению работы с виртуальным окружением можно просто набрать deactivate, либо закрыть окно терминала:

(env) $ deactivate
$ which python
/Users/and-semakin/.asdf/shims/python

И мы видим, что команда python снова вызывает глобальный интерпретатор. При этом виртуальное окружение осталось в своей директории, оно просто не активно. В следующий раз, когда будет нужно поработать с виртуальным окружением, не забудьте снова его активировать.

Виртуальное окружение можно полностью удалить, когда оно перестанет быть нужным:

$ rm -r env/

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

Вот так можно работать с виртуальными окружениями в Python. Всегда устанавливайте зависимости проектов только в изолированные виртуальные окружения. Не смешивайте зависимости разных проектов в одном окружении.

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

Ничего не устанавливайте в глобальный интерпретатор

Иногда возникает желание установить какой-нибудь пакет прямо в глобальный интерпретатор, потому что по смыслу этот пакет вроде как должен быть вне виртуальных окружений. Например, это может быть какая-нибудь программа, типа poetry, docker-compose, youtube-dl или howdoi. Руки набирают в терминал:

$ pip install poetry

Установка начинается, прогресс-бары заполняются, но в итоге всё завершается чем-то типа такого:

error: could not create '/lib/python2.7/site-packages/poetry': Permission denied

Можно попробовать установить, используя sudo, и это сработает, но это считается очень плохой практикой, и я настоятельно рекомендую так не делать по нескольким причинам:

Угроза безопасности.

В секции про установку пакетов я упомянул, что для пакетов других форматов, кроме wheel, могут потребоваться дополнительные действия. На самом деле, при установке пакета формата sdist исполняется файлsetup.py, в котором потенциально могут содержаться любые действия — от честной установки пакета, до rm -rf / или установки криптомайнера в систему. Т.к. в PyPI пакет загрузить может кто угодно, никогда нельзя быть уверенным, что именно сделает пакет при установке. Выполнять такой скрипт с системными привилегиями (sudo) — не самый мудрый ход.
Может нарушить целостность системы.

Часто в операционных системах принято устанавливать программы через пакетный менеджер (будь то apt, dnf или pacman). Этот же пакетный менеджер затем может без следа удалить установленную программу, потому что он ведёт учёт файлов — какой программе какие файлы принадлежит. Если начать изменять файлы программ каким-либо образом, помимо пакетного менеджера, то это может нарушить его работу. pip, конечно, установит что нужно, но после этого могут возникнуть проблемы с системным пакетным менеджером.

Как правильно:

сказать pip, чтобы он установил пакет не в директорию site-packages, а в домашнюю директорию пользователя при помощи флага --user:
```
$ pip install --user poetry  # без sudo!
```
Обязательно нужно убедиться, что директория, куда установится пакет, перечислена в переменной $PATH. Путь к директории можно получить при помощи следующей команды:
```
$ python -m site --user-base
/Users/and-semakin/.local
```
К получившемуся пути нужно в конце добавить /bin для Linux и MacOS, либо \Scripts для Windows, так что в моём случае (MacOS) в $PATH нужно добавить вот такой путь: /Users/and-semakin/.local/bin.

Подробнее про этот метод установки читайте здесь.
установить программу через пакетный менеджер ОС, например:
```
$ sudo dnf install python-poetry
```
Часто мейнтейнеры ОС создают обёртки для пакетов из PyPI, которые можно установить при помощи системного пакетного менеджера. Как правило, такие обёртки называются python-<имя пакета> или python3-<имя пакета>. Это делается как раз для того, чтобы дать пользователям возможность устанавливать Python-программы, не нарушая работу пакетного менеджера ОС. Кроме того, эти пакеты проходят проверку безопасности, так что риск получить криптомайнер значительно ниже.

Выводы

всегда устанавливайте зависимости проектов в отдельные виртуальные окружения;
если нужно установить пакет "глобально", то используйте либо pip install --user ..., либо прибегните к помощи пакетного менеджера операционной системы;
никогда не используйте sudo pip ... — считайте, что это табу.

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

poetry;
pipenv.

Стабильных вам зависимостей и кода без багов!

Полезно почитать:

Документация: https://docs.python.org/3/library/venv.html

Питонические атаки

Настройка точечного обхода блокировок на роутере с OpenWRT

Роутер и прошивка

Блокировки

Шаг 1. Шифрованный DNS

Шаг 2. Настройка VPN WireGuard

Шаг 3. Скрипт для сбора списков заблокированных адресов

Шаг 4. Дальнейшая настройка

Шаг 5. Отключаем IPv6

Заключение

Эффективный обход словарей в цикле в Python

Эффективный обход словарей в цикле в Python

Что будет если просто попытаться обойти словарь в цикле?

Как обойти в цикле ключи словаря?

Как обойти в цикле значения словаря?

Как обойти в цикле и ключи, и значения словаря?

Заключение

Ссылки

Аннотации типов в Python

Аннотации типов в Python

Как это работает?

Простые типы

Контейнерные типы и дженерики

Составные типы

Проверка типов

Заключение

Дополнительное чтение:

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

Что такое символ переноса строки?

Почему перенос строки в конце файла важен?

Ещё доводы:

Настраиваем редактор

Заключение

Дополнительное чтение

Запуск Git-хуков при помощи pre-commit

Git-хуки

Пишем Git-хук на bash

Используем готовый инструмент — pre-commit

Установка

Настройка

Плагины/зависимости для проверок

Использование

Альтернативы pre-commit

Заключение

Ссылки

Форматируем код при помощи black

Почему полезно форматировать код

black — бескомпромиссный форматтер кода

Установка

Использование

Интеграция с редактором/IDE

Использование в CI

Конфигурация

Настройка flake8, чтобы он не противоречил black

Что меня бесит в стиле black

Заключение

Дополнительное чтение

Почему print("Hello") работает в Python 2

Почему print("Hello") работает в Python 2

Заключение

Дополнительное чтение

Chocolatey — пакетный менеджер для Windows

Установка

Установка программ

Обновление

Заключение

Дополнительное чтение

Линтеры в Python

Линтеры

flake8

Установка

Использование

Плагины

Конфигурация

pylint

Установка

Использование

Конфигурация

Плагины

Интеграция линтера в проект

Пишем Git-хук на `bash`

Используем готовый инструмент — `pre-commit`

Альтернативы `pre-commit`

`black` — бескомпромиссный форматтер кода

Настройка `flake8`, чтобы он не противоречил `black`

Что меня бесит в стиле `black`

Файлы `pipenv`

Управление зависимостями через `pipenv`

Мердж-конфликты в `Pipfile.lock`

Проблемы `requirements.txt`

Как `pip` устанавливает пакеты