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

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

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

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

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