webbrowser --- Trình điều khiển trình duyệt web tiện lợi

Source code: Lib/webbrowser.py

Mô-đun webbrowser cung cấp giao diện cấp cao cho phép hiển thị các tài liệu dựa trên web cho người dùng. Trong hầu hết các trường hợp, chỉ cần gọi hàm open() từ mô-đun này sẽ thực hiện đúng.

Trong Unix, trình duyệt đồ họa được ưu tiên trong X11, nhưng trình duyệt ở chế độ văn bản sẽ được sử dụng nếu không có trình duyệt đồ họa hoặc không có màn hình X11. Nếu sử dụng trình duyệt ở chế độ văn bản, quá trình gọi sẽ chặn cho đến khi người dùng thoát khỏi trình duyệt.

Nếu biến môi trường BROWSER tồn tại, nó sẽ được hiểu là danh sách các trình duyệt được phân tách bằng os.pathsep để thử trước các giá trị mặc định của nền tảng. Khi giá trị của một phần danh sách chứa chuỗi %s thì nó được hiểu là một dòng lệnh trình duyệt theo nghĩa đen được sử dụng với đối số URL được thay thế cho %s; nếu giá trị là một từ duy nhất đề cập đến một trong các trình duyệt đã được đăng ký thì trình duyệt này sẽ được thêm vào đầu danh sách tìm kiếm; nếu phần đó không chứa %s, nó chỉ được hiểu đơn giản là tên của trình duyệt sẽ khởi chạy. [1]

Thay đổi trong phiên bản 3.14: Biến BROWSER hiện cũng có thể được sử dụng để sắp xếp lại danh sách mặc định của nền tảng. Điều này đặc biệt hữu ích trên macOS nơi mặc định của nền tảng không đề cập đến các công cụ dòng lệnh trên PATH.

Đối với các nền tảng không phải Unix hoặc khi có trình duyệt từ xa trên Unix, quy trình kiểm soát sẽ không đợi người dùng kết thúc trình duyệt mà cho phép trình duyệt từ xa duy trì các cửa sổ riêng của nó trên màn hình. Nếu trình duyệt từ xa không có sẵn trên Unix, quá trình kiểm soát sẽ khởi chạy một trình duyệt mới và chờ đợi.

Trên iOS, biến môi trường BROWSER, cũng như mọi đối số kiểm soát tính năng tự động nâng, tùy chọn trình duyệt và việc tạo tab/cửa sổ mới sẽ bị bỏ qua. Các trang web always sẽ được mở trong trình duyệt ưa thích của người dùng, trong một tab mới, với trình duyệt được đưa lên nền trước. Việc sử dụng mô-đun webbrowser trên iOS yêu cầu mô-đun ctypes. Nếu ctypes không có sẵn, các cuộc gọi tới open() sẽ không thành công.

Giao diện dòng lệnh

Tập lệnh webbrowser có thể được sử dụng làm giao diện dòng lệnh cho mô-đun. Nó chấp nhận URL làm đối số. Nó chấp nhận các tham số tùy chọn sau:

-n, --new-window

Mở URL trong cửa sổ trình duyệt mới, nếu có thể.

-t, --new-tab

Mở URL trong tab trình duyệt mới.

Các lựa chọn tất nhiên là loại trừ lẫn nhau. Ví dụ sử dụng:

python -m trình duyệt web -t "https://www.python.org"

sẵn có: not WASI, not Android.

Ngoại lệ sau đây được xác định:

exception webbrowser.Error

Ngoại lệ nảy sinh khi xảy ra lỗi kiểm soát trình duyệt.

Các chức năng sau được xác định:

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

Hiển thị url bằng trình duyệt mặc định. Nếu new bằng 0, url sẽ được mở trong cùng cửa sổ trình duyệt nếu có thể. Nếu new là 1, một cửa sổ trình duyệt mới sẽ được mở nếu có thể. Nếu new là 2, một trang trình duyệt mới ("tab") sẽ được mở nếu có thể. Nếu autoraise là True, cửa sổ sẽ được nâng lên nếu có thể (lưu ý rằng trong nhiều trình quản lý cửa sổ, điều này sẽ xảy ra bất kể cài đặt của biến này).

Trả về True nếu trình duyệt được khởi chạy thành công, ngược lại là False.

Lưu ý rằng trên một số nền tảng, việc cố gắng mở tên tệp bằng chức năng này có thể hoạt động và khởi động chương trình liên kết của hệ điều hành. Tuy nhiên, điều này không được hỗ trợ cũng như không di động.

Tăng một auditing event webbrowser.open với đối số url.

webbrowser.open_new(url)

Mở url trong cửa sổ mới của trình duyệt mặc định, nếu có thể, nếu không, hãy mở url trong cửa sổ trình duyệt duy nhất.

Trả về True nếu trình duyệt được khởi chạy thành công, ngược lại là False.

webbrowser.open_new_tab(url)

Mở url trong một trang mới ("tab") của trình duyệt mặc định, nếu có thể, nếu không thì tương đương với open_new().

Trả về True nếu trình duyệt được khởi chạy thành công, ngược lại là False.

webbrowser.get(using=None)

Trả về đối tượng điều khiển cho loại trình duyệt using. Nếu using là None, hãy trả về bộ điều khiển cho trình duyệt mặc định phù hợp với môi trường của người gọi.

webbrowser.register(name, constructor, instance=None, *, preferred=False)

Đăng ký loại trình duyệt name. Khi một loại trình duyệt được đăng ký, hàm get() có thể trả về bộ điều khiển cho loại trình duyệt đó. Nếu instance không được cung cấp hoặc là None, constructor sẽ được gọi mà không có tham số để tạo phiên bản khi cần. Nếu instance được cung cấp, constructor sẽ không bao giờ được gọi và có thể là None.

Việc đặt preferred thành True làm cho trình duyệt này trở thành kết quả ưu tiên cho lệnh gọi get() không có đối số. Mặt khác, điểm nhập này chỉ hữu ích nếu bạn dự định đặt biến BROWSER hoặc gọi get() với một đối số không trống khớp với tên của trình xử lý mà bạn khai báo.

Thay đổi trong phiên bản 3.7: Tham số chỉ từ khóa preferred đã được thêm vào.

Một số loại trình duyệt được xác định trước. Bảng này cung cấp các tên loại có thể được chuyển đến hàm get() và các phiên bản tương ứng cho các lớp bộ điều khiển, tất cả đều được xác định trong mô-đun này.

Tên loại

Tên lớp

Ghi chú

'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)

Ghi chú:

  1. "Konqueror" là trình quản lý tệp cho môi trường máy tính để bàn KDE dành cho Unix và chỉ sử dụng hợp lý nếu KDE đang chạy. Một số cách phát hiện KDE một cách đáng tin cậy sẽ tốt; biến KDEDIR là không đủ. Cũng lưu ý rằng tên "kfm" được sử dụng ngay cả khi sử dụng lệnh konqueror với KDE 2 --- quá trình triển khai sẽ chọn chiến lược tốt nhất để chạy Konqueror.

  2. Chỉ trên nền tảng Windows.

  3. Chỉ có trên macOS.

  4. Chỉ có trên iOS.

Added in version 3.2: Một lớp MacOSXOSAScript mới đã được thêm vào và được sử dụng trên Mac thay vì lớp MacOSX trước đó. Điều này bổ sung hỗ trợ cho việc mở các trình duyệt hiện không được đặt làm mặc định của hệ điều hành.

Added in version 3.3: Hỗ trợ cho Chrome/Chromium đã được thêm vào.

Thay đổi trong phiên bản 3.12: Support for several obsolete browsers has been removed. Các trình duyệt bị xóa bao gồm Grail, Khảm, Netscape, Galeon, Skipstone, Iceape và Firefox phiên bản 35 trở xuống.

Thay đổi trong phiên bản 3.13: Hỗ trợ cho iOS đã được thêm vào.

Dưới đây là một số ví dụ đơn giản:

url = 'https://python.go-mizu.dev/'

# Open URL trong tab mới, nếu cửa sổ trình duyệt đã mở.
webbrowser.open_new_tab(url)

# Open URL trong cửa sổ mới, nâng cửa sổ lên nếu có thể.
webbrowser.open_new(url)

Đối tượng điều khiển trình duyệt

Bộ điều khiển trình duyệt cung cấp thuộc tính name và ba phương thức sau đây có chức năng tiện lợi cấp mô-đun song song:

controller.name

Tên phụ thuộc vào hệ thống cho trình duyệt.

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

Hiển thị url bằng trình duyệt được xử lý bởi bộ điều khiển này. Nếu new là 1, một cửa sổ trình duyệt mới sẽ được mở nếu có thể. Nếu new là 2, một trang trình duyệt mới ("tab") sẽ được mở nếu có thể.

controller.open_new(url)

Mở url trong một cửa sổ mới của trình duyệt do bộ điều khiển này xử lý, nếu có thể, nếu không, hãy mở url trong cửa sổ trình duyệt duy nhất. Bí danh open_new().

controller.open_new_tab(url)

Mở url trong một trang mới ("tab") của trình duyệt do bộ điều khiển này xử lý, nếu có thể, nếu không thì tương đương với open_new().

Chú thích cuối trang