Содержание страницы

`webbrowser` – Удобный контроллер веб-браузера¶webbrowser – Convenient web-browser controller

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

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

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

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

Изменено в версии 3.14: Переменная BROWSER теперь также может использоваться для изменения порядка списка платформенных значений по умолчанию. Это особенно полезно в macOS, где платформенные значения по умолчанию не ссылаются на инструменты командной строки на PATH.

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

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

Интерфейс командной строки¶Command-line interface

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

-n, --new-window¶: Открывает URL в новом окне браузера, если это возможно.

-t, --new-tab¶: Открывает URL в новой вкладке браузера.

Эти параметры, очевидно, являются взаимоисключающими. Пример использования:

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

Доступность: не WASI, не Android.

Определено следующее исключение:

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(), и соответствующие экземпляры классов контроллеров, определённые в этом модуле.

Имя типа	Имя класса	Примечания
`'mozilla'`	`Mozilla('mozilla')`
`'firefox'`	`Mozilla('mozilla')`
`'epiphany'`	`Epiphany('epiphany')`
`'kfmclient'`	`Konqueror()`	(1)
`'konqueror'`	`Konqueror()`	(1)
`'kfm'`	`Konqueror()`	(1)
`'opera'`	`Opera()`
`'links'`	`GenericBrowser('links')`
`'elinks'`	`Elinks('elinks')`
`'lynx'`	`GenericBrowser('lynx')`
`'w3m'`	`GenericBrowser('w3m')`
`'windows-default'`	`WindowsDefault`	(2)
`'macosx'`	`MacOSXOSAScript('default')`	(3)
`'safari'`	`MacOSXOSAScript('safari')`	(3)
`'google-chrome'`	`Chrome('google-chrome')`
`'chrome'`	`Chrome('chrome')`
`'chromium'`	`Chromium('chromium')`
`'chromium-browser'`	`Chromium('chromium-browser')`
`'iosbrowser'`	`IOSBrowser`	(4)

Примечания:

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

Добавлено в версии 3.2: Добавлен новый класс MacOSXOSAScript, который используется на Mac вместо прежнего класса MacOSX. Это добавляет поддержку открытия браузеров, не установленных в качестве системного по умолчанию.

Добавлено в версии 3.3: Добавлена поддержка Chrome/Chromium.

Изменено в версии 3.12: Удалена поддержка нескольких устаревших браузеров. Удалённые браузеры включают Grail, Mosaic, Netscape, Galeon, Skipstone, Iceape и Firefox версии 35 и ниже.

Изменено в версии 3.13: Добавлена поддержка iOS.

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

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

# Открыть URL в новой вкладке, если окно браузера уже открыто.
webbrowser.open_new_tab(url)

# Открыть URL в новом окне, по возможности поднимая окно на передний план.
webbrowser.open_new(url)

Объекты контроллеров браузера¶Browser controller objects

Контроллеры браузера предоставляют атрибут name, и следующие три метода, соответствующие функциям удобства уровня модуля:

controller.name¶: Системно-зависимое имя браузера.

controller.open(url, new=0, autoraise=True)¶: Отображает url с использованием браузера, управляемого этим контроллером. Если new равно 1, открывается новое окно браузера, если это возможно. Если new равно 2, открывается новая страница браузера («вкладка»), если это возможно.

controller.open_new(url)¶: Открывает url в новом окне браузера, управляемого этим контроллером, если это возможно; в противном случае открывает url в единственном окне браузера. Синоним open_new().

controller.open_new_tab(url)¶: Открывает url на новой странице («вкладке») браузера, управляемого этим контроллером, если это возможно; в противном случае эквивалентно open_new().

Сноски

webbrowser – Удобный контроллер веб-браузера¶webbrowser – Convenient web-browser controller

Интерфейс командной строки¶Command-line interface

Объекты контроллеров браузера¶Browser controller objects

`webbrowser` – Удобный контроллер веб-браузера¶webbrowser – Convenient web-browser controller