webbrowser — Удобный контроллер веб-браузера

Исходный код: Lib/webbrowser.py

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

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

Если переменная среды BROWSER существует, она интерпретируется как список браузеров, разделённых os.pathsep, которые будут опробованы перед использованием платформенных значений по умолчанию. Когда значение части списка содержит строку %s, она интерпретируется как буквальная командная строка браузера, в которой аргумент URL подставляется вместо %s; если часть не содержит %s, она просто интерпретируется как имя запускаемого браузера. 1

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

Скрипт webbrowser может быть использован как командная строка для модуля. Он принимает URL в качестве аргумента. Он принимает следующие необязательные параметры: -n открывает URL в новом окне браузера, если это возможно; -t открывает URL на новой странице браузера («вкладке»). Опции, естественно, взаимоисключающие. Пример использования:

python -m webbrowser -t "https://www.python.org"

Определяется следующая исключительная ситуация:

exception webbrowser.Error

Исключение, выбрасываемое при возникновении ошибки управления браузером.

Определены следующие функции:

webbrowser.open(url, new=0, autoraise=True)

Отобразить url с помощью браузера по умолчанию. Если new равно 0, url открывается в том же окне браузера, если это возможно. Если new равно 1, открывается новое окно браузера, если это возможно. Если new равно 2, открывается новая страница браузера («вкладка»), если это возможно. Если autoraise равно True, окно поднимается, если это возможно (обратите внимание, что во многих менеджерах окон это произойдёт независимо от установки этой переменной).

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

Вызывает событие аудита webbrowser.open с аргументом url.

webbrowser.open_new(url)

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

webbrowser.open_new_tab(url)

Открыть url на новой странице («вкладке») браузера по умолчанию, если возможно, в противном случае эквивалентно open_new().

webbrowser.get(using=None)

Возвращает объект-контроллер для типа браузера using. Если using равно None, возвращает контроллер для браузера по умолчанию, подходящий для среды вызывающего.

webbrowser.register(name, constructor, instance=None, *, preferred=False)

Регистрирует тип браузера name. После регистрации типа браузера функция get() может вернуть контроллер для этого типа браузера. Если instance не предоставлен или равен None, constructor будет вызван без параметров для создания экземпляра при необходимости. Если instance предоставлен, constructor никогда не будет вызван и может быть None.

Установление preferred в значение True делает этот браузер предпочтительным результатом для вызова get() без аргументов. В противном случае этот входной пункт полезен только если вы планируете установить переменную BROWSER или вызвать get() с непустым аргументом, соответствующим имени обработчика, который вы объявляете.

Изменено в версии 3.7: Параметр preferred стал ключевым параметром только.

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

Примечания:

1. “Konqueror” — это менеджер файлов для среды рабочего стола KDE в Unix, и использовать его имеет смысл только при запуске KDE. Было бы неплохо иметь надёжный способ обнаружения KDE; переменная KDEDIR не подходит. Также обратите внимание, что имя “kfm” используется даже при использовании команды konqueror с KDE 2 — реализация выбирает лучшую стратегию для запуска Konqueror.
2. Только на платформах Windows.
3. Только на платформе macOS.

Вот несколько простых примеров:

url = 'https://docs.python.org/'

# Open URL in a new tab, if a browser window is already open.
webbrowser.open_new_tab(url)

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)