عرض مصدر Python/webbrowser

<noinclude>{{DISPLAYTITLE:الوحدة <code>webbrowser</code> في بايثون}}</noinclude>

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

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

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

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

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

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

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

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

يبين المثال التالي طريقة استخدام هذا الأمر في سطر الأوامر:<syntaxhighlight lang="bash">
python -m webbrowser -t "http://www.python.org"
</syntaxhighlight>

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

=== الاستثناء <code>webbrowser.Error</code> ===
يُطلق هذا الاستثناء عند حدوث خطأ في المتصفّح.

== دوال الوحدة <code>webbrowser</code> ==
تقدّم الوحدة الدوال التالية:

=== الدالة <code>[[Python/webbrowser/open|webbrowser.open()‎]]</code> ===
يؤدي استدعاء الدالة إلى عرض العنوان المعطى في المتصفّح الافتراضي.

=== الدالة <code>[[Python/webbrowser/open new|webbrowser.open_new()‎]]</code> ===
تفتح الدالة العنوان المعطى في نافذة جديدة في المتصفّح الافتراضي، إن كان ذلك ممكنًا، وإلا فإنّها ستفتح العنوان المعطى في النافذة الموجودة فقط.

=== الدالة <code>[[Python/webbrowser/open new tab|webbrowser.open_new_tab()]]‎</code> ===
تفتح الدالة العنوان المعطى في تبويب جديد (tab) في المتصفّح الافتراضي، إن كان ذلك ممكنًا، وإلّا فإنّ الدالة تكون مكافئة للدالة <code>[[Python/webbrowser/open new|open_new()‎]]</code>.

=== الدالة <code>[[Python/webbrowser/get|webbrowser.get()]]‎</code> ===
تعيد الدالة كائن <code>controller</code> لنوع المتصفّح المعطى.

=== الدالة <code>[[Python/webbrowser/register|webbrowser.register()]]‎</code> ===
تسجّل الدالة نوع المتصفّح المعطى، وبعد تسجيل نوع المتصفّح باستخدام هذه الدالة يصبح بإمكان الدالة <code>[[Python/webbrowser/get|get()‎]]</code> أن تعيد كائن <code>controller</code> لنوع المتصفّح المسجَّل.

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

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

=== التابع <code>[[Python/controller/open|controller.open()‎]]</code> ===
يعرض التابع العنوان المعطى باستخدام المتصفّح الذي يتحكّم فيه هذا المتحكّم.

=== التابع <code>[[Python/controller/open new|controller.open_new()‎]]</code> ===
يفتح التابع العنوان المعطى في نافذة جديدة في المتصفّح الذي يتحكّم به هذا المتحكّم، إن كان ذلك ممكنًا.

=== التابع <code>[[Python/controller/open new tab|controller.open_new_tab()‎]]</code> ===
يفتح التابع العنوان المعطى في تبويب جديد في المتصفّح الذي يتحكّم به هذا المتحكّم، إن كان ذلك ممكنًا.

== مصادر ==
* [https://docs.python.org/3/library/webbrowser.html صفحة Convenient Web-browser controller في توثيق بايثون الرسمي.]
[[تصنيف:Python]]
[[تصنيف:Python Modules]]