webbrowser --- کنترل‌کننده‌ی کمکی مرورگر وب

کد منبع: Lib/webbrowser.py

ماژول webbrowser رابط سطح بالایی را فراهم می‌کند که امکان نمایش اسناد مبتنی بر وب به کاربران را می‌دهد. در بیشتر شرایط، صرفاً فراخوانی تابع open() از این ماژول کار درست را انجام می‌دهد.

در یونیکس، مرورگرهای گرافیکی تحت X11 ترجیح داده می‌شوند، اما اگر مرورگرهای گرافیکی در دسترس نباشند یا یک نمایش X11 در دسترس نباشد، از مرورگرهای حالت متنی استفاده خواهد شد. اگر از مرورگرهای حالت متنی استفاده شود، فرآیند فراخوان تا زمانی که کاربر از مرورگر خارج شود مسدود خواهد شد.

اگر متغیر محیطی BROWSER وجود داشته باشد، به‌عنوان فهرستی از مرورگرها تفسیر می‌شود که با os.pathsep جدا شده است و باید پیش از پیش‌فرض‌های سکو امتحان شود. هنگامی که مقدار یک بخش از فهرست شامل رشته‌ی %s باشد، به‌عنوان یک خط فرمان مرورگر به‌صورت لفظی تفسیر می‌شود که باید با جایگزینی آرگومان URL به‌جای %s استفاده شود؛ اگر مقدار یک کلمه باشد که به یکی از مرورگرهای از قبل ثبت‌شده اشاره کند، این مرورگر به ابتدای فهرست جستجو اضافه می‌شود؛ اگر بخش شامل %s نباشد، به‌سادگی به‌عنوان نام مرورگر برای اجرا تفسیر می‌شود. [1]

تغییر یافته در نسخه‌ی 3.14: اکنون می‌توان از متغیر BROWSER نیز برای تغییر ترتیب فهرست پیش‌فرض‌های پلتفرم استفاده کرد. این موضوع به‌ویژه در macOS مفید است، جایی که پیش‌فرض‌های پلتفرم به ابزارهای خط فرمان موجود در PATH ارجاع نمی‌دهند.

در سکوهای غیر یونیکسی، یا هنگامی که یک مرورگر از راه دور در یونیکس در دسترس باشد، فرایند کنترل‌کننده منتظر نمی‌ماند تا کاربر کار با مرورگر را تمام کند، بلکه به مرورگر از راه دور اجازه می‌دهد پنجره‌های خود را بر روی نمایشگر نگه دارد. اگر مرورگرهای از راه دور در یونیکس در دسترس نباشند، فرایند کنترل‌کننده یک مرورگر جدید را راه‌اندازی می‌کند و منتظر می‌ماند.

در iOS، متغیر محیطی BROWSER و همچنین هر آرگومانی که autoraise، ترجیح مرورگر و ایجاد زبانه/پنجره جدید را کنترل می‌کند، نادیده گرفته می‌شود. صفحات وب همیشه در مرورگر مورد ترجیح کاربر، در یک زبانه جدید باز خواهند شد و مرورگر به پیش‌زمینه آورده خواهد شد. استفاده از ماژول webbrowser در iOS به ماژول ctypes نیاز دارد. اگر ctypes در دسترس نباشد، فراخوانی‌های open() شکست خواهند خورد.

رابط خط فرمان

اسکریپت webbrowser می‌تواند به‌عنوان یک رابط خط فرمان برای این ماژول استفاده شود. این اسکریپت یک URL را به‌عنوان آرگومان می‌پذیرد و پارامترهای اختیاری زیر را قبول می‌کند:

-n, --new-window

URL را در صورت امکان در یک پنجره‌ی مرورگر جدید باز می‌کند.

-t, --new-tab

URL را در یک زبانه‌ی جدید مرورگر باز می‌کند.

این گزینه‌ها، طبیعتاً، مانعة‌الجمع هستند. مثال استفاده:

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

دسترس‌پذیری: not WASI, not Android.

استثنای زیر تعریف شده است:

exception webbrowser.Error

استثنایی که هنگام وقوع خطای کنترل مرورگر پرتاب می‌شود.

توابع زیر تعریف شده‌اند:

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

url را با مرورگر پیش‌فرض نمایش می‌دهد. اگر new برابر ۰ باشد، url در صورت امکان در همان پنجره‌ی مرورگر باز می‌شود. اگر new برابر ۱ باشد، در صورت امکان یک پنجره‌ی مرورگر جدید باز می‌شود. اگر new برابر ۲ باشد، در صورت امکان یک صفحه‌ی مرورگر جدید («زبانه») باز می‌شود. اگر autoraise برابر True باشد، در صورت امکان پنجره بالا آورده می‌شود (توجه داشته باشید که در بسیاری از مدیران پنجره، این اتفاق صرف‌نظر از تنظیم این متغیر رخ خواهد داد).

اگر مرورگر با موفقیت راه‌اندازی شده باشد، True و در غیر این صورت False برمی‌گرداند.

توجه داشته باشید که در برخی سکوها، تلاش برای باز کردن یک نام پرونده با استفاده از این تابع، ممکن است کار کند و برنامه مرتبط سیستم‌عامل را اجرا کند. با این حال، این کار نه پشتیبانی می‌شود و نه قابل‌حمل است.

یک رویداد حسابرسی webbrowser.open را با آرگومان url پرتاب می‌کند.

webbrowser.open_new(url)

url را، در صورت امکان، در یک پنجره‌ی جدید از مرورگر پیش‌فرض باز می‌کند؛ در غیر این صورت، url را در تنها پنجره‌ی مرورگر باز می‌کند.

اگر مرورگر با موفقیت راه‌اندازی شده باشد، True و در غیر این صورت False برمی‌گرداند.

webbrowser.open_new_tab(url)

در صورت امکان، url را در یک صفحه جدید («tab») در مرورگر پیش‌فرض باز می‌کند، در غیر این صورت معادل 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)

یادداشت‌ها:

  1. «Konqueror» مدیر پرونده‌ی محیط دسکتاپ KDE برای یونیکس است و استفاده از آن تنها زمانی منطقی است که KDE در حال اجرا باشد. وجود روشی قابل‌اطمینان برای تشخیص KDE مطلوب است؛ متغیر KDEDIR کافی نیست. همچنین توجه داشته باشید که حتی هنگام استفاده از دستور konqueror در KDE 2 نیز از نام «kfm» استفاده می‌شود — پیاده‌سازی بهترین راهبرد را برای اجرای Konqueror انتخاب می‌کند.

  2. فقط در سکوهای ویندوزی.

  3. فقط در macOS.

  4. فقط در iOS.

اضافه شده در نسخه‌ی 3.2: کلاس جدید MacOSXOSAScript اضافه شده است و در مک به جای کلاس MacOSX قبلی استفاده می‌شود. این موضوع پشتیبانی از باز کردن مرورگرهایی را اضافه می‌کند که در حال حاضر به‌عنوان پیش‌فرض سیستم‌عامل تنظیم نشده‌اند.

اضافه شده در نسخه‌ی 3.3: پشتیبانی از Chrome/Chromium افزوده شد.

تغییر یافته در نسخه‌ی 3.12: پشتیبانی از چند مرورگر منسوخ حذف شده است. مرورگرهای حذف‌شده شامل Grail، Mosaic، Netscape، Galeon، Skipstone، Iceape و نسخه‌های 35 و پایین‌تر Firefox هستند.

تغییر یافته در نسخه‌ی 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)

اشیای کنترل‌کننده مرورگر

کنتترل‌کننده‌های مرورگر، ویژگی name و سه متد زیر را فراهم می‌کنند که معادل توابع کمکی سطح ماژول هستند:

controller.name

نام وابسته به سیستم برای مرورگر.

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

url را با استفاده از مرورگر مدیریت‌شده توسط این کنترل‌کننده نمایش می‌دهد. اگر new برابر ۱ باشد، در صورت امکان یک پنجره‌ی جدید مرورگر باز می‌شود. اگر new برابر ۲ باشد، در صورت امکان یک صفحه‌ی جدید مرورگر («زبانه») باز می‌شود.

controller.open_new(url)

در صورت امکان، url را در یک پنجره‌ی جدید از مرورگر تحت مدیریت این کنترل‌کننده باز کنید؛ در غیر این صورت، url را در تنها پنجره‌ی مرورگر باز کنید. نام مستعار open_new().

controller.open_new_tab(url)

در صورت امکان، url را در یک صفحه‌ی جدید («زبانه») از مرورگر تحت مدیریت این کنترل‌کننده باز می‌کند؛ در غیر این صورت، معادل open_new() است.

پانویس‌ها