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)