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"

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

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

exception webbrowser.Error

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

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

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

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

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

Поднимает auditing event 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: Добавлен параметр предпочтительный только для ключевых слов.

Ряд типов браузеров предопределен. В этой таблице приведены имена типов, которые могут быть переданы в функцию 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)

Примечания:

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

  2. Только на платформах Windows.

  3. Только на macOS.

  4. Только на iOS.

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

Added in version 3.3: Добавлена поддержка Chrome/Chromium.

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

Изменено в версии 3.13: Добавлена поддержка 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)

Объекты контроллера браузера

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

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().

Сноски