commit - eff4b1c9e488561f70d19ce729bdb949787f020e
commit + caae6ab346b1b8d1b958924257e61c00a7a93438
blob - /dev/null
blob + 0b19688e4c45be34b9bbaedb9e3236aa98af76e1 (mode 644)
--- /dev/null
+++ capsule/python/python3.11-tools.gmi
+# Утилиты, встроенные в Python
+
+Почти на всех машинах (за которые отвечаю я) установлен третий пайтон. А вместе с интерпретатором устанавливаются и модули стандартной библиотеки, некоторые из которых могут работать как самостоятельные утилиты командной строки. Я, например, давно уже пользуюсь модулем http.server для переброса файлов между машинами одной сети. Или json.tool для человеко-читаемого отображения json-данных (хотя постоянно забываю опцию --no-ensure-ascii для отображения русскоязычных строк).
+
+Вот я и решил погрепать стандартные модули Python 3.11 на предмет встроенных полезных утилит.
+
+## Документированные модули
+
+У меня нет желания дублировать здесь официальную документацию. Поэтому для модулей, имеющих описание режима утилиты командной строки на сайте 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=
+$ echo QWxhZGRpbjpvcGVuIHNlc2FtZQo= | python -m base64 -d -
+Aladdin:open sesame
+```
+
+### encodings.rot_13
+
+Утилита кодирования в ROT13: простой шифр для символов английского алфавита, реализуемый сдвигом ("rotate") на 13 позиций в алфавите. Символы не из английского алфавита остаются "как есть", например:
+```
+$ echo test-тест | python3 -m encodings.rot_13
+grfg-тест
+$ echo grfg-тест | python3 -m encodings.rot_13
+test-тест
+```
+
+### filecmp
+
+Модуль сравнения файлов двух директорий на файловой системе.
+
+Например создадим тестовые данные:
+```
+$ mkdir sub1
+$ echo "" > sub1/file
+$ echo "sub1-file1" > sub1/file1
+$ echo "sub1-file2" > sub1/file2
+$ mkdir sub2
+$ echo "" > sub2/file
+$ echo "sub2-file1" > sub2/file1
+$ echo "sub2-file3" > sub2/file3
+```
+
+Результат сравнения директорий:
+```
+$ python3 -m filecmp sub1 sub2
+diff sub1 sub2
+Only in sub1 : ['file2']
+Only in sub2 : ['file3']
+Identical files : ['file']
+Differing files : ['file1']
+```
+
+Указав ключ -r утилита будет сравнивать рекурсивно (все под-директории).
+
+### ftplib
+
+Модуль реализации FTP клиента. Как можно догадаться, утилита командной строки этого модуля реализует простой FTP клиент. Например следующая команда:
+
+```
+$ 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!
+
+You are connected to an FTP or SFTP server used for testing purposes
+by Rebex FTP/SSL or Rebex SFTP sample code. Only read access is allowed.
+
+For information about Rebex FTP/SSL, Rebex SFTP and other Rebex libraries
+for .NET, please visit our website at https://www.rebex.net/
+
+For feedback and support, contact support@rebex.net
+
+Thanks!
+-r-------- 1 anonymous users 19156 Feb 16 2007 imap-console-client.png
+-rw------- 1 anonymous users 36672 Mar 19 2007 KeyGenerator.png
+-rw------- 1 anonymous users 24029 Mar 19 2007 KeyGeneratorSmall.png
+-r-------- 1 anonymous users 16471 Feb 16 2007 mail-editor.png
+-r-------- 1 anonymous users 35414 Feb 16 2007 mail-send-winforms.png
+-r-------- 1 anonymous users 49011 Feb 16 2007 mime-explorer.png
+-rw------- 1 anonymous users 58024 Mar 19 2007 pocketftp.png
+-rw------- 1 anonymous users 20197 Mar 19 2007 pocketftpSmall.png
+-r-------- 1 anonymous users 20472 Feb 16 2007 pop3-browser.png
+-r-------- 1 anonymous users 11205 Feb 16 2007 pop3-console-client.png
+-rw------- 1 anonymous users 379 Sep 19 2023 readme.txt
+-rw------- 1 anonymous users 11546 Mar 19 2007 ResumableTransfer.png
+-rw------- 1 anonymous users 2635 Mar 19 2007 winceclient.png
+-rw------- 1 anonymous users 6146 Mar 19 2007 winceclientSmall.png
+-rw------- 1 anonymous users 80000 Mar 19 2007 WinFormClient.png
+-rw------- 1 anonymous users 17911 Mar 19 2007 WinFormClientSmall.png
+```
+
+* -l. выводит содержимое текущей директории
+* readme.txt выводит содержимое файла readme.txt в текущей директории
+* -dpub/example переходит в под-директорию pub/example
+* -l. снова выводит содержимое текущей директории (pub/example)
+
+Данные для аутентификации (в случае необходимости) берутся из файла `~/.netrc`. Утилите можно задать альтернативный файл .netrc через аргумент -r.
+
+### mimetypes
+
+Модуль работы с MIME. В режиме утилиты командной строки можно как искать тип содержимого по имени файла (или его полному URL), например:
+```
+$ python3 -m mimetypes not_exist.jpg
+type: image/jpeg encoding: None
+```
+
+Так и наоборот: по типу содержимого искать подходящее расширение файла. Для этого нужно указывать аргумент -e, например:
+```
+$ python3 -m mimetypes -e image/jpeg
+.jpg
+```
+
+### platform
+
+Модуль получения текущей платформы (операционная система и архитектура аппаратного обеспечения), на которой исполняется интерпретатор. Утилита командной строки печатает полученную платформу в стандартный поток вывода:
+```
+$ python3 -m platform
+OpenBSD-7.5-amd64-64bit-ELF
+```
+
+### sysconfig
+
+Модуль в режиме утилиты командной строки выводит общую информацию о платформе, пути и конфигурацию, с которой был собран Python (опции из Makefile и заголовочного файла pyconfig.h).
+
+### inspect
+
+Модуль само-рефлексии python-кода. Утилита командной строки по умолчанию получает имя python-объекта в формате "module:qualname", а в стандартный поток вывода печатает исходный код реализации этого объекта. Например:
+```
+$ python3 -m inspect inspect:ismodule
+def ismodule(object):
+ """Return true if the object is a module.
+
+ Module objects provide these attributes:
+ __cached__ pathname to byte compiled file
+ __doc__ documentation string
+ __file__ filename (missing for built-in modules)"""
+ return isinstance(object, types.ModuleType)
+```
+
+Если указать аргумент -d, то в стандартный поток вывода печатается мета-информация об объекте. Например:
+```
+$ 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
+```
+
+### pyclbr
+
+Модуль в качестве утилиты командной строки выводит индексную информацию о 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
+```
