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

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

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

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

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

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

В iOS переменная окружения BROWSER, а также любые аргументы, управляющие автоматическим поднятием окна, предпочтением браузера и созданием новой вкладки или окна, игнорируются. Веб-страницы всегда будут открываться в предпочтительном для пользователя браузере, в новой вкладке, а браузер будет выведен на передний план. Для использования модуля webbrowser в iOS требуется модуль ctypes. Если модуль ctypes недоступен, вызовы open() завершатся ошибкой.

Скрипт webbrowser можно использовать как интерфейс командной строки для модуля. В качестве аргумента он принимает URL-адрес. Поддерживаются следующие необязательные параметры:

-n, --new-window

Открывает URL-адрес в новом окне браузера, если это возможно.

-t, --new-tab

Открывает 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, окно выводится на передний план, если это возможно (обратите внимание, что во многих оконных менеджерах это происходит независимо от значения этой переменной).

Возвращает True, если браузер был успешно запущен, и False в противном случае.

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

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

webbrowser.open_new(url)

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

Возвращает True, если браузер был успешно запущен, и False в противном случае.

webbrowser.open_new_tab(url)

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

Возвращает True, если браузер был успешно запущен, и False в противном случае.

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.
4. Только в iOS.

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

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)