الفرق بين المراجعتين ل"Python/urllib/request/urlretrieve"
(أنشأ الصفحة ب'<noinclude>{{DISPLAYTITLE:الدالة <code>urllib.request.urlretrieve()</code> في بايثون}}</noinclude> تنسخ الدالة كائن شبكة network ob...') |
|||
| سطر 10: | سطر 10: | ||
== المعاملات == | == المعاملات == | ||
| − | === filename === | + | === <code>filename</code> === |
معامل اختياري، يحدّد موقع الملف الذي ستُجرى عملية النسخ إليه (وإن لم يكن الملف موجودًا، فإنّ الموقع سيكون ملفًّا مؤقتًا tempfile يحمل اسمًا تُنشئه الدالة). | معامل اختياري، يحدّد موقع الملف الذي ستُجرى عملية النسخ إليه (وإن لم يكن الملف موجودًا، فإنّ الموقع سيكون ملفًّا مؤقتًا tempfile يحمل اسمًا تُنشئه الدالة). | ||
| − | === reporthook === | + | === <code>reporthook</code> === |
معامل اختياري وهو كائن قابل للاستدعاء ويُستدعى لمرة واحدة عند إجراء الاتصال بالشبكة ومرة بعد كل قراءة لقطعة من البيانات بعدئذٍ. | معامل اختياري وهو كائن قابل للاستدعاء ويُستدعى لمرة واحدة عند إجراء الاتصال بالشبكة ومرة بعد كل قراءة لقطعة من البيانات بعدئذٍ. | ||
| − | تمرّر ثلاثة وسائط إلى الكائن القابل للاستدعاء وهي عدد الكتل المنقولة لحدّ الآن، حجم الكتلة بالبايتات، والحجم الكلي للملف. يمكن أن يحمل الوسيط الثالث القيمة -1 في مخدّمات FTP القديمة والتي لا تعيد حجم الملف عند الاستجابة لطلبات جلب البيانات. | + | تمرّر ثلاثة وسائط إلى الكائن القابل للاستدعاء وهي عدد الكتل المنقولة لحدّ الآن، حجم الكتلة بالبايتات، والحجم الكلي للملف. يمكن أن يحمل الوسيط الثالث القيمة <code>-1</code> في مخدّمات FTP القديمة والتي لا تعيد حجم الملف عند الاستجابة لطلبات جلب البيانات. |
| − | |||
| − | |||
== القيمة المعادة == | == القيمة المعادة == | ||
| − | تعيد الدالة صفًّا بهيئة (filename, headers) حيث يمثّل filename اسم الملف المحلي الذي يمكن العثور على الكائن فيه، وتمثّل headers ما يعيده التابع info() الخاص بالكائن الذي تعيده الدالة urlopen() (لكائن بعيد). تُطلق هذه الدالة نفس الاستثناءات التي تُطلقها الدالة urlopen(). | + | تعيد الدالة [[Python/tuples|صفًّا]] بهيئة <code>(filename, headers)</code> حيث يمثّل <code>filename</code> اسم الملف المحلي الذي يمكن العثور على الكائن فيه، وتمثّل <code>headers</code> ما يعيده التابع <code>info()</code> الخاص بالكائن الذي تعيده الدالة <code>[[Python/urllib/request/urlopen|urlopen()]]</code> (لكائن بعيد). تُطلق هذه الدالة نفس الاستثناءات التي تُطلقها الدالة <code>[[Python/urllib/request/urlopen|urlopen()]]</code>. |
| − | إن استخدم المعامل url المخطط http: فيمكن حينئذٍ إعطاء قيمة للوسيط الاختياري data لجعل الطلب من نوع POST (يكون الطلب من نوع GET عادةً). يجب أن تكون قيمة الوسيط data كائن بايتات بالصيغة القياسية application/x-www-form-urlencoded. راجع الدالة urllib.parse.urlencode(). | + | إن استخدم المعامل <code>url</code> المخطط <code>http:</code> فيمكن حينئذٍ إعطاء قيمة للوسيط الاختياري <code>data</code> لجعل الطلب من نوع POST (يكون الطلب من نوع GET عادةً). يجب أن تكون قيمة الوسيط <code>data</code> كائن بايتات بالصيغة القياسية <code>application/x-www-form-urlencoded</code>. راجع توثيق الدالة <code>[[Python/urllib/parse/urlencode|urllib.parse.urlencode()]]</code>. |
| − | تُطلق الدالة urlretrieve() الاستثناء ContentTooShortError عندما تكتشف أنّ كمية البيانات المتاحة أقل من الكمية المتوقعة (وهو الحجم المحدّد بواسطة الترويسة Content-Length). يمكن لهذا أن يحدث عند قطع عملية التنزيل. | + | تُطلق الدالة <code>urlretrieve()</code> الاستثناء <code>ContentTooShortError</code> عندما تكتشف أنّ كمية البيانات المتاحة أقل من الكمية المتوقعة (وهو الحجم المحدّد بواسطة الترويسة <code>Content-Length</code>). يمكن لهذا أن يحدث عند قطع عملية التنزيل. |
| − | تعامل قيمة الترويسة Content-Length على أنّها الحدّ الأدنى، بمعنى أنّه إن كان هناك المزيد من البيانات فإنّ الدالة ستقرأها، ولكن إن كان البيانات أقلّ من الحدّ الأدنى فإنّ الدالة تُطلق استثناءً.، ومع ذلك يمكن جلب البيانات المحمّلة في هذه الحالة، إذ تخزّن في خاصية content في نسخة الاستثناء. | + | تعامل قيمة الترويسة <code>Content-Length</code> على أنّها الحدّ الأدنى، بمعنى أنّه إن كان هناك المزيد من البيانات فإنّ الدالة ستقرأها، ولكن إن كان البيانات أقلّ من الحدّ الأدنى فإنّ الدالة تُطلق استثناءً.، ومع ذلك يمكن جلب البيانات المحمّلة في هذه الحالة، إذ تخزّن في خاصية <code>content</code> في نسخة الاستثناء. |
| − | في حال عدم وجود الترويسة Content-Length فإنّ الدالة urlretrieve() لن تكون قادرة على التحقق من حجم البيانات التي يجب تنزيلها، وتعيدها فقط، وفي هذه الحالة يجب أن نفترض أن عملية التحميل قد تمّت بنجاح. | + | في حال عدم وجود الترويسة <code>Content-Length</code> فإنّ الدالة <code>urlretrieve()</code> لن تكون قادرة على التحقق من حجم البيانات التي يجب تنزيلها، وتعيدها فقط، وفي هذه الحالة يجب أن نفترض أن عملية التحميل قد تمّت بنجاح. |
== أمثلة == | == أمثلة == | ||
| سطر 44: | سطر 42: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | |||
| − | |||
== مصادر == | == مصادر == | ||
* [https://docs.python.org/3/library/urllib.request.html#urllib.request.urlretrieve صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.] | * [https://docs.python.org/3/library/urllib.request.html#urllib.request.urlretrieve صفحة Extensible library for opening URLs في توثيق بايثون الرسمي.] | ||
مراجعة 21:11، 2 فبراير 2019
تنسخ الدالة كائن شبكة network object المشار إليه بواسطة عنوان URL إلى ملف محلّي. إن أشار عنوان URL إلى ملف محلي، فإنّ الكائن لن يُنسخ إلا إذا زُوّدت الدالة باسم للملف.
البنية العامة
urllib.request.urlretrieve(url, filename=None, reporthook=None, data=None)
المعاملات
filename
معامل اختياري، يحدّد موقع الملف الذي ستُجرى عملية النسخ إليه (وإن لم يكن الملف موجودًا، فإنّ الموقع سيكون ملفًّا مؤقتًا tempfile يحمل اسمًا تُنشئه الدالة).
reporthook
معامل اختياري وهو كائن قابل للاستدعاء ويُستدعى لمرة واحدة عند إجراء الاتصال بالشبكة ومرة بعد كل قراءة لقطعة من البيانات بعدئذٍ.
تمرّر ثلاثة وسائط إلى الكائن القابل للاستدعاء وهي عدد الكتل المنقولة لحدّ الآن، حجم الكتلة بالبايتات، والحجم الكلي للملف. يمكن أن يحمل الوسيط الثالث القيمة -1 في مخدّمات FTP القديمة والتي لا تعيد حجم الملف عند الاستجابة لطلبات جلب البيانات.
القيمة المعادة
تعيد الدالة صفًّا بهيئة (filename, headers) حيث يمثّل filename اسم الملف المحلي الذي يمكن العثور على الكائن فيه، وتمثّل headers ما يعيده التابع info() الخاص بالكائن الذي تعيده الدالة urlopen() (لكائن بعيد). تُطلق هذه الدالة نفس الاستثناءات التي تُطلقها الدالة urlopen().
إن استخدم المعامل url المخطط http: فيمكن حينئذٍ إعطاء قيمة للوسيط الاختياري data لجعل الطلب من نوع POST (يكون الطلب من نوع GET عادةً). يجب أن تكون قيمة الوسيط data كائن بايتات بالصيغة القياسية application/x-www-form-urlencoded. راجع توثيق الدالة urllib.parse.urlencode().
تُطلق الدالة urlretrieve() الاستثناء ContentTooShortError عندما تكتشف أنّ كمية البيانات المتاحة أقل من الكمية المتوقعة (وهو الحجم المحدّد بواسطة الترويسة Content-Length). يمكن لهذا أن يحدث عند قطع عملية التنزيل.
تعامل قيمة الترويسة Content-Length على أنّها الحدّ الأدنى، بمعنى أنّه إن كان هناك المزيد من البيانات فإنّ الدالة ستقرأها، ولكن إن كان البيانات أقلّ من الحدّ الأدنى فإنّ الدالة تُطلق استثناءً.، ومع ذلك يمكن جلب البيانات المحمّلة في هذه الحالة، إذ تخزّن في خاصية content في نسخة الاستثناء.
في حال عدم وجود الترويسة Content-Length فإنّ الدالة urlretrieve() لن تكون قادرة على التحقق من حجم البيانات التي يجب تنزيلها، وتعيدها فقط، وفي هذه الحالة يجب أن نفترض أن عملية التحميل قد تمّت بنجاح.
أمثلة
يعرض المثال التالي الطريقة الشائعة لاستخدام هذه الدالة:
>>> import urllib.request
>>> local_filename, headers = urllib.request.urlretrieve('http://python.org/')
>>> html = open(local_filename)
>>> html.close()