Python/webbrowser

تقدّم وحدة webbrowser واجهة متطوّرة تسمح بعرض مستندات الويب على المستخدمين. في أغلب الحالات يكفي استدعاء الدالة open()‎ ببساطة للقيام بكلّ شيء على نحو سليم.

تكون متصفّحات الويب الرسومية graphical browser مفضّلة مع محرّك العرض X11، ولكنّ تستخدم الوحدة المتصفّحات النصية text-mode browsers إن كانت المتصفّحات الرسومية غير متوفّرة، أو كان محرّك العرض X11 غير متاح لاستخدام. وعند استخدام المتصفّحات النصية تتوقّف عملية الاستدعاء إلى حين خروج المستخدم من المتصفّح.

إن كان متغيّر البيئة BROWSER موجودًا، فإنّه سيفسّر كقائمة os.pathsep من المتصفّحات التي سيجري تجربتها قبل المتصفّحات الافتراضية الخاصّة بالمنصّة التي تنفّذ فيها الشيفرة. إن تضمّنت القيمة في هذه القائمة على السلسلة النصية ‎%s فإنّ القيمة ستفسّر على أنّها أحد أوامر سطر الأوامر الخاصّ بالمتصفّح ويُستخدم مع الوسيط URL الذي سيحلّ محلّ ‎%s، أما إن لم تتضمّن القيمة السلسلة النصية ‎%s فستفسّر القيمة على أنّها اسم المتصفّح الذي سيجري تشغيله.

لن تنتظر العملية المتحكّمة controlling process المستخدم لإغلاق المتصفّح في الأنظمة الأخرى (غير يونكس) أو في المتصفّحات البعيدة التي تكون متاحة للاستخدام في أنظمة يونكس، بل تسمح العملية المتحكّمة للمتصفّح البعيد بأن يبقي على نوافذه الخاصّة ويعرضها للمستخدم. وفي حال لم تكن المتصفّحات البعيدة متوفّرة في يونكس، فإنّ العملية المتحكّمة ستفتح متصفّحًا جديدًا وتدخل وضع الانتظار.

واجهة سطر الأوامر

يمكن استخدام شيفرة webbrowser كواجهة سطر الأوامر للوحدة. يستقبل هذا الأمر عنوان URL كوسيط، ويستقبل المعاملات الاختيارية التالية:

‎-n‎ : يفتح عنوان URL في نافذة متصفّح جديدة إن كان ذلك ممكنًا.

‎-t: يفتح عنوان URL في تبويب ("tab") جديد في المتصفّح.

يجدر التنبيه إلى أنّه لا يمكن استخدام هذه الخيارات مع بعضها البعض.

يبين المثال التالي طريقة استخدام هذا الأمر في سطر الأوامر:

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

استثناءات الوحدة

تقدّم الوحدة الاستثناءات التالية:

الاستثناء webbrowser.Error

يُطلق هذا الاستثناء عند حدوث خطأ في المتصفّح.

دوال الوحدة webbrowser

تقدّم الوحدة الدوال التالية:

الدالة webbrowser.open()‎

يؤدي استدعاء الدالة إلى عرض العنوان المعطى في المتصفّح الافتراضي.

الدالة webbrowser.open_new()‎

تفتح الدالة العنوان المعطى في نافذة جديدة في المتصفّح الافتراضي، إن كان ذلك ممكنًا، وإلا فإنّها ستفتح العنوان المعطى في النافذة الموجودة فقط.

الدالة webbrowser.open_new_tab()‎

تفتح الدالة العنوان المعطى في تبويب جديد (tab) في المتصفّح الافتراضي، إن كان ذلك ممكنًا، وإلّا فإنّ الدالة تكون مكافئة للدالة open_new()‎.

الدالة webbrowser.get()‎

تعيد الدالة كائن controller لنوع المتصفّح المعطى.

الدالة webbrowser.register()‎

تسجّل الدالة نوع المتصفّح المعطى، وبعد تسجيل نوع المتصفّح باستخدام هذه الدالة يصبح بإمكان الدالة get()‎ أن تعيد كائن controller لنوع المتصفّح المسجَّل.

كائنات التحكم في المتصفّح Browser Controller

تقدّم كائنات Browser controllers التوابع الثلاثة التالية التي تؤدي وظائف مشابهة للدوال المقابلة لها في الوحدة:

التابع controller.open()‎

يعرض التابع العنوان المعطى باستخدام المتصفّح الذي يتحكّم فيه هذا المتحكّم.

التابع controller.open_new()‎

يفتح التابع العنوان المعطى في نافذة جديدة في المتصفّح الذي يتحكّم به هذا المتحكّم، إن كان ذلك ممكنًا.

التابع controller.open_new_tab()‎

يفتح التابع العنوان المعطى في تبويب جديد في المتصفّح الذي يتحكّم به هذا المتحكّم، إن كان ذلك ممكنًا.

مصادر

• صفحة Convenient Web-browser controller في توثيق بايثون الرسمي.