commit - 41ade8d4a055ad7bad218ac866557567f54d46ac
commit + 76cf8405b153026743e4ac976e30e45ad5440abd
blob - 1493767a87df1050cb9c0f176148514cbfef904c
blob + b2c0d88aaadc733897bd812c332c5192bebec79e
--- capsule/python/python3.11-tools.gmi
+++ capsule/python/python3.11-tools.gmi
# Утилиты, встроенные в Python
-На машинах, где я работаю над чем-либо в подавляющем большинстве случаев уже установлен третий пайтон. А вместе с интерпретатором устанавливаются и модули стандартной библиотеки, некоторые из которых могут работать, как самостоятельные утилиты командной строки. Я, например, давно уже пользуюсь модулем http.server для переброса файлов между машинами одной сети или json.tool для человеко-читаемого отображения json-данных.
+Почти на всех машинах (за которые отвечаю я) установлен третий пайтон. А вместе с интерпретатором устанавливаются и модули стандартной библиотеки, некоторые из которых могут работать, как самостоятельные утилиты командной строки. Я, например, давно уже пользуюсь модулем http.server для переброса файлов между машинами одной сети. Или json.tool для человеко-читаемого отображения json-данных (хотя постоянно забываю опцию --no-ensure-ascii для отображения русскоязычных строк).
-Вот я и решил погрепать стандартные модули Python 3.11 на предмет встроенных полезных утилит. Что бы получить краткую справку прямо в консоли утилиты можно запустить с аргументом -h или (если запуск с -h не поддерживается) совсем без аргументов.
+Вот я и решил погрепать стандартные модули Python 3.11 на предмет встроенных полезных утилит.
-## Модуль base64
+## Документированные модули
-Недокументированная (на текущий момент) возможность запуска модуля base64 для [рас-]кодирования данных в формате Base64:
-```
-$ python -m base64 -h
-option -h not recognized
-usage: /usr/lib/python2.7/base64.py [-d|-e|-u|-t] [file|-]
- -d, -u: decode
- -e: encode (default)
- -t: encode and decode string 'Aladdin:open sesame'
-```
+У меня нет желания дублировать здесь официальную документацию. Поэтому для модулей, имеющих описание режима утилиты командной строки на сайте docs.python.org, я просто оставлю ссылки:
-Утилита оперирует переданным файлом, значение - переключает на работу со стандартным потоком ввода. Пример:
+=> https://docs.python.org/3/library/calendar.html#command-line-usage The calendar module can be executed as a script from the command line to interactively print a calendar
+=> https://docs.python.org/3/library/profile.html The Python Profilers
+=> https://docs.python.org/3/library/dis.html dis - Disassembler for Python bytecode
+=> https://docs.python.org/3/library/gzip.html#command-line-interface The gzip module provides a simple command line interface to compress or decompress files.
+=> https://docs.python.org/3/library/http.server.html http.server - HTTP servers
+=> https://docs.python.org/3/library/json.html#command-line-options The json.tool module provides a simple command line interface to validate and pretty-print JSON objects
+=> https://docs.python.org/3/library/pickletools.html#command-line-options Tools for pickle developers
+=> https://docs.python.org/3/library/pydoc.html pydoc - Documentation generator and online help system
+=> https://docs.python.org/3/library/py_compile.html#command-line-interface py_compile - Compile Python source files
+=> https://docs.python.org/3/library/site.html#command-line-interface site - Site-specific configuration hook
+=> https://docs.python.org/3/library/tarfile.html#command-line-interface The tarfile module provides a simple command-line interface to interact with tar archives
+=> https://docs.python.org/3/library/timeit.html#command-line-interface timeit — Measure execution time of small code snippets
+=> https://docs.python.org/3/library/tokenize.html#command-line-usage tokenize — Tokenizer for Python source
+=> https://docs.python.org/3/library/trace.html#command-line-usage trace - Trace or track Python statement execution
+=> https://docs.python.org/3/library/unittest.html#command-line-interface The unittest module can be used from the command line to run tests from modules, classes or even individual test methods
+=> https://docs.python.org/3/library/venv.html#creating-virtual-environments Creation of virtual environments is done by executing the command venv
+=> https://docs.python.org/3/library/webbrowser.html webbrowser - Convenient web-browser controller
+=> https://docs.python.org/3/library/zipapp.html#zipapp-command-line-interface zipapp - Manage executable Python zip archives
+=> https://docs.python.org/3/library/zipfile.html#command-line-interface The zipfile module provides a simple command-line interface to interact with ZIP archives
+## Недокументированные модули
+
+Но существует ещё ряд встроенных в Python модулей, которые могут быть использованы в качестве утилиты командной строки, хотя это не описано в документации.
+
+### base64
+
+Недокументированная (на текущий момент) возможность запуска модуля base64 для [рас-]кодирования данных в формате Base64. Утилита оперирует переданным в качестве аргумента файлом, но встретив значение `-` переключается на работу со стандартным потоком ввода. Пример:
+
```
$ echo "Aladdin:open sesame" | python -m base64 -
QWxhZGRpbjpvcGVuIHNlc2FtZQo=
Aladdin:open sesame
```
-## Модуль calendar
+### encodings.rot_13
-Работа модуля calendar в режиме утилиты хорошо документирована:
-=> https://docs.python.org/3/library/calendar.html#command-line-usage
-
-Утилита выводит календарь в формате простого текста или HTML.
-
-## Модуль cProfile
-
-Модуль поддержки профилирования исполнения Python-кода. Работа модуля хорошо документирована:
-=> https://docs.python.org/3/library/profile.html
-
-## Модуль dis
-
-Модуль дизассемблирования python-кода. Имеет короткую справку (документацией это назвать сложно):
-=> https://docs.python.org/3/library/dis.html
-
-На вход (или в стандартный поток ввода) ожидает содержимое текстового python-скрипта (не работает со скомпилированными *.pyc файлами). Например:
-```
-$ echo "import os" | python3 -m dis -
- 1 0 LOAD_CONST 0 (0)
- 2 LOAD_CONST 1 (None)
- 4 IMPORT_NAME 0 (os)
- 6 STORE_NAME 0 (os)
- 8 LOAD_CONST 1 (None)
- 10 RETURN_VALUE
-```
-
-## Модуль encodings.rot_13
-
Утилита кодирования в ROT13: простой шифр для символов английского алфавита, реализуемый сдвигом ("rotate") на 13 позиций в алфавите. Символы не из английского алфавита остаются "как есть", например:
```
$ echo test-тест | python3 -m encodings.rot_13
test-тест
```
-## Модуль filecmp
+### filecmp
Модуль сравнения файлов двух директорий на файловой системе.
$ echo "sub2-file3" > sub2/file3
```
-Результат сравнения директорий можно получить в краткой форме:
+Результат сравнения директорий:
```
$ python3 -m filecmp sub1 sub2
diff sub1 sub2
Identical files : ['file']
Differing files : ['file1']
```
+
Указав ключ -r утилита будет сравнивать рекурсивно (все под-директории).
-## Модуль ftplib
+### ftplib
Модуль реализации FTP клиента. Как можно догадаться, утилита командной строки этого модуля реализует простой FTP клиент. Например следующая команда:
```
-$ python3.11 -m ftplib test.rebex.net -l. readme.txt -dpub/example -l.
+$ python3 -m ftplib test.rebex.net -l. readme.txt -dpub/example -l.
drwx------ 2 anonymous users 0 Mar 31 2023 pub
-rw------- 1 anonymous users 379 Sep 19 2023 readme.txt
Welcome to test.rebex.net!
* -dpub/example переходит в под-директорию pub/example
* -l. снова выводит содержимое текущей директории (pub/example)
-Данные для аутентификации (в случае необходимости) берутся из `~/.netrc`. Утилите можно задать альтернативный файл .netrc через аргумент -r.
+Данные для аутентификации (в случае необходимости) берутся из файла `~/.netrc`. Утилите можно задать альтернативный файл .netrc через аргумент -r.
-## Модуль gzip
+### mimetypes
-Модуль [де-] компрессии в формате gzip. Модуль реализует простой документированный интерфейс командной строки:
-=> https://docs.python.org/3/library/gzip.html#command-line-interface
+Модуль работы с MIME. В режиме утилиты командной строки можно как искать тип содержимого по имени файла (или его полному URL), например:
+```
+$ python3 -m mimetypes not_exist.jpg
+type: image/jpeg encoding: None
+```
-## Модуль http.server
+Так и наоборот: по типу содержимого искать подходящее расширение файла. Для этого нужно указывать аргумент -e, например:
+```
+$ python3 -m mimetypes -e image/jpeg
+.jpg
+```
-Реализация HTTP сервера и известными ограничениями. Я сам часто использую команду `python3 -m http.server` для копирования файлов между машинами в одной сети.
+### platform
-=> https://docs.python.org/3/library/http.server.html Документация на модуль http.server
+Модуль получения текущей платформы (операционная система и архитектура аппаратного обеспечения), на которой исполняется интерпретатор. Утилита командной строки печатает полученную платформу в стандартный поток вывода:
+```
+$ python3 -m platform
+OpenBSD-7.5-amd64-64bit-ELF
+```
-## Модуль inspect
+### sysconfig
-Модуль само-рефлексии python-кода. Утилита командной строки по умолчанию получает имя python-объекта в формате "module:qualname", а в стандартный поток вывода печатает исходный код реализации этого объекта. Например:
+Модуль в режиме утилиты командной строки выводит общую информацию о платформе, пути и конфигурацию, с которой был собран Python (опции из Makefile и заголовочного файла pyconfig.h).
+
+### inspect
+
+Модуль само-рефлексии python-кода.
+
+Утилита командной строки по умолчанию получает имя python-объекта в формате "module:qualname", а в стандартный поток вывода печатает исходный код реализации этого объекта. Например:
```
-$ python3.11 -m inspect inspect:ismodule
+$ python3 -m inspect inspect:ismodule
def ismodule(object):
"""Return true if the object is a module.
Если указать аргумент -d, то в стандартный поток вывода печатается мета-информация об объекте. Например:
```
-$ python3.11 -m inspect -d inspect:ismodule
+$ python3 -m inspect -d inspect:ismodule
Target: inspect:ismodule
Origin: /usr/lib/python3.11/inspect.py
Cached: /usr/lib/python3.11/__pycache__/inspect.cpython-311.pyc
Line: 282
```
-## Модуль json.tool
+### pyclbr
-Модуль человеко-читаемого форматирования JSON.
-
-=> https://docs.python.org/3/library/json.html#command-line-options Документация на модуль json
+Модуль в качестве утилиты командной строки выводит индексную информацию о python-модуле. Целевой модуль может быть задан как просто по имени, так и путём к py-файлу, например:
+```
+$ python3 -m pyclbr /usr/lib/python3.11/pyclbr.py
+class _Object [] 53
+ def __init__ 55
+class Function [<__main__.Class object at 0x7efce054fdd0>] 68
+ def __init__ 70
+class Class [<__main__.Class object at 0x7efce054fdd0>] 78
+ def __init__ 80
+def _nest_function 89
+def _nest_class 94
+def readmodule 100
+def readmodule_ex 112
+def _readmodule 122
+class _ModuleBrowser [<__main__.Class object at 0x7efce0397b10>] 186
+ def __init__ 187
+ def visit_ClassDef 195
+ def visit_FunctionDef 220
+ def visit_AsyncFunctionDef 230
+ def visit_Import 233
+ def visit_ImportFrom 248
+def _create_tree 269
+def _main 275
+```
