Сообщить об ошибке.

Специальные аргументы, меняющие поведение команды

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

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

Содержание:


Управление выводом.

_out=None:

Ключевой аргумент _out определяет куда перенаправить/выводить STDOUT.

  • если это строка, она будет рассматриваться как имя файла.
  • можно передать файловый объект (или подобный файлу объект),
  • если это int - будет интерпретироваться как файловый дескриптор, например результат os.pipe(), объект io.StringIO или вызываемый объект.
import sh
sh.ls(_out="/tmp/output")

Дополнительно смотрите раздел "Перенаправление вывода команды модуля sh в Python".

_err=None:

Ключевой аргумент _err определяет, на что перенаправить STDERR. Смотрите ключевой аргумент _out.

_err_to_out=False:

Если True, то дублирует файловый дескриптор, привязанный к STDOUT процесса, и к STDERR, фактически заставляя STDERR и STDOUT делать вывод в одно и то же место.

_encoding=sh.DEFAULT_ENCODING:

Ключевой аргумент _encoding определяет кодировку символов STDOUT процесса. По умолчанию это кодировка локали по умолчанию.

_decode_errors='strict':

Ключевой аргумент _decode_errors определяет как Python должен обрабатывать ошибки декодирования выходных данных процесса. По умолчанию это "strict", но можно использовать любое значение, допустимое для bytes.decode(), например "ignore".

Новое в версии sh 1.07.0.

_tee=None:

Начиная с версии 1.07.0, при любом использовании перенаправления, будь то для STDOUT или STDERR, соответствующие внутренние буферы не заполняются. Например, если загружать файл и использовать обратный вызов на STDOUT, то внутренний буфер STDOUT или буфер канала не будут заполнены данными из STDOUT. Эта опция заставляет один из stderr (tee='err') илиstdout(tee='out'или_tee=True`) заполняться в любом случае, фактически “разбивая” вывод на два места (обработчик обратного вызова/перенаправления и внутренние буферы).

_truncate_exc=True:

Ключевой аргумент _truncate_exc определяет, следует ли усекать вывод исключения или нет. Новое в версии sh 1.12.0.

Управление выполнением команд терминала.

_fg=False:

Ключевой аргумент _fg запускает команду на переднем плане, то есть она порождается с помощью os.spawnle(). STDIN/OUT/ERR текущего процесса - это os.dup2()’ для нового процесса, и поэтому новый процесс становится передним планом оболочки, выполняющей сценарий. Это действительно полезно только тогда, когда надо запустить интерактивный процесс, в которомshиспытывает проблемы с запуском, например команда терминалаssh`.

Предупреждение. _fg=True скрывает большую часть функциональности модуля sh, следовательно не будет возвращен объект процесса и, скорее всего все другие специальные ключевые аргументы не будут работать.

Если необходима аналогичная функциональность, то используйте следующее:

import sh
import sys
sh.bash_command(_in=sys.stdin, _out=sys.stdout, _err=sys.stderr)

New in version 1.12.0.

_bg=False:

По умолчанию каждая запущенная команда терминала через модуль sh блокируется до ее завершения (получения результатов).

При установке _bg=True модуль sh запускает команду в фоновом режиме (отдельном процессе). Чтобы убедиться, что команда завершилась необходимо вызвать метод RunningCommand.wait().

Смотрите также раздел "Фоновое выполнение команды".

_bg_exc=True:

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

Новое в версии 1.12.9.

_env=None:

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

import sh
sh.google_chrome(_env={"SOCKS_SERVER": "localhost:1234"})

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

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

import os
import sh

new_env = os.environ.copy()
new_env["SOCKS_SERVER"] = "localhost:1234"

sh.google_chrome(_env=new_env)

_timeout=None:

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

_timeout_signal=signal.SIGKILL:

Ключевой аргумент _timeout_signal - это сигнал по умолчанию, который будет отправлен процессу, если _timeout не является None.

_cwd=None:

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

_ok_code=0:

Ключевой аргумент _ok_code принимает либо целое число, либо список, либо кортеж, содержащий код(ы) выхода, которые считаются “ОК”, или другими словами: не вызывайте исключение.

import sh
sh.bash_program(_ok_code=[0,3,5])

Дополнительно смотрите "Коды выхода и исключения".

_new_session=True:

Ключевой аргумент _new_session определяет, будет ли раздвоенный процесс выполняться в своем собственном сеансе через os.setsid().

Примечание. Если _new_session=False, то раздвоенный процесс будет помещен в свою собственную группу через os.setpgrp(). Таким образом, раздвоенный процесс и все его дочерние элементы всегда остаются одни в своей собственной группе, о которой можно напрямую сигнализировать, независимо от значения _new_session.

_uid=None:

Ключевой аргумент _uid определяет идентификатор пользователя, который должен быть принят до того, как дочерний процесс вызовет os.execv().

New in version 1.12.0.

_preexec_fn=None:

Ключевой аргумент _preexec_fn определяет функцию, которая запускается непосредственно перед тем, как дочерний процесс вызовет os.execv().

Обычно не используется обычными пользователями. Новое в версии 1.12.0.

_pass_fds={}:

Ключевой аргумент _pass_fds определяет итерируемый белый список целочисленных файловых дескрипторов, которые наследуются потомком. Передача чего-либо в этом аргументе приводит к тому, что _close_fds принимает значение True.

Значение по умолчанию: пустое множество set. (НЕ СЛОВАРЬ!)

Новое в версии 1.13.0.

_close_fds=True:

Ключевой аргумент _close_fds вызывает автоматическое закрытие всех унаследованных файловых дескрипторов, кроме stdin, stdout и stderr. Эта опция автоматически включается, когда задается значение _pass_fds.

Новое в версии 1.13.0.

Управление передачей параметров командам.

_in=None:

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

import sh
print(sh.cat(_in="test"))
# test
stdin = ["sh", "is", "awesome"]
out = sh.tr("[:lower:]", "[:upper:]", _in=stdin)
print(out)
#SHISAWESOME

_piped=None:

Ключевой аргумент _piped может быть True, out или err. Сообщает команде терминала, что она используется в качестве входных данных для другой команды, поэтому она должна возвращать свой вывод постепенно по мере его получения, а не агрегировать все сразу.

Примеры смотрите в разделе "Конвейер в стиле Bash ".

_iter=None:

Ключевой аргумент _iter может быть True, out или err. Переводит команду в режим итерирования. В этом режиме можно использовать цикл for/in или while для перебора вывода команды в реальном времени.

import sh
for line in sh.cat("/tmp/file", _iter=True):
    print(line)

Дополнительные примеры смотрите в разделе "Фоновое выполнение команд терминала".

_iter_noblock=None:

Ключевой аргумент _iter_noblock делает то же самое, что и _iter, за исключением того, что цикл не будет блокироваться, если нет выходных данных для итерации. Вместо этого вывод команды будет errno.EWOULDBLOCK.

import sh
import errno
import time

for line in sh.tail("-f", "stuff.log", _iter_noblock=True):
    if line == errno.EWOULDBLOCK:
        print("делать что-то еще...")
        time.sleep(0.5)
    else:
        print("processing line!")

Дополнительно смотрите раздел "Фоновое выполнение команд терминала".

_with=False:

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

Популярные команды, использующие контекст, это sudo или fakeroot:

import sh
with sh.contrib.sudo(password="abc123", _with=True):
    print(sh.ls("/root"))

_done=None:

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

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

Вот пример использования _done для создания многопроцессного пула, где sh.your_parallel_command выполняется одновременно не более чем 10 раз:

import sh
from threading import Semaphore

pool = Semaphore(10)

def done(cmd, success, exit_code):
    pool.release()

def do_thing(arg):
    pool.acquire()
    return sh.your_parallel_command(arg, _bg=True, _done=done)

procs = []
for arg in range(100):
    procs.append(do_thing(arg))

# дожидаемся окончания всех процессов
[p.wait() for p in procs]

Новое в версии 1.11.0.

Управление Производительностью и оптимизацией.

_in_bufsize=0:

Ключевой аргумент _in_bufsize определяет размер буфера STDIN. Значение 1 для строчной буферизации, 0 для отключения буферизации, другое значение для буфера указанного размера.

_out_bufsize=1:

Ключевой аргумент _out_bufsize определяет размер буфера STDOUT. Значение 1 для строчной буферизации, 0 для отключения буферизации, другое значение для буфера указанного размера.

_err_bufsize=1:

Ключевой аргумент _err_bufsize определяет определяет размер буфера STDERR. Значение 1 для строчной буферизации, 0 для отключения буферизации, другое значение для буфера указанного размера.

_internal_bufsize=3 * 1024**2:

Ключевой аргумент _internal_bufsize определяет сколько команда будет хранить внутри STDOUT/ERR. Это значение представляет количество блоков bufsize, а не общее количество байтов.

Например, если это значение равно 100, а STDOUT буферизуется по строкам, то можно получить 100 строк из STDOUT. Если STDOUT не буферизован, то можно получить только 100 символов.

_no_out=False:

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

Новое в версии 1.07.0.

_no_err=False:

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

Новое в версии 1.07.0.

_no_pipe=False:

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

Новое в версии 1.07.0.

Ведение журнала (логирование)

_log_msg=None:

Ключевой аргумент _log_msg позволяет настраивать заголовок журнала для экземпляров класса Command. Например, ведение журнала по умолчанию выглядит так:

import logging
import sh

logging.basicConfig(level=logging.INFO)

sh.ls("-l")

# INFO:sh.command:<Command '/bin/ls -l', pid 13561>: process started
# INFO:sh.command:<Command '/bin/ls -l', pid 13561>: process completed

Пользователи могут найти раздел <Command... длинным и не относящимся к делу. Ключевой аргумент _log_msg позволяет это настроить:

import logging
import sh

logging.basicConfig(level=logging.INFO)

def custom_log(run, call_args, pid=None):
    return run

sh.ls("-l", _log_msg=custom_log)

# INFO:sh.command:/bin/ls -l: process started
# INFO:sh.command:/bin/ls -l: process completed

Первый аргумент run, - это строка выполнения программы и аргументы, максимально приближенные к тому, как вводятся в оболочке. Аргумент call_args - это словарь всех специальных kwargs, переданных команде. А pid - это идентификатор разветвленного процесса. По умолчанию он имеет значение None, потому что обратный вызов _log_msg фактически вызывается дважды: сначала для создания регистратора для экземпляра класса RunningCommand, прежде чем сам процесс будет порожден, затем второй раз после того, как процесс будет порожден через класс OProc, когда уже есть pid.