الدالة urllib.request.urlretrieve() في بايثون
تنسخ الدالة كائن شبكة 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()
انظر أيضًا
- الدالة
urllib.request.urlcleanup(): تحذف الدالة الملفات المؤقتة التي خلّفتها الاستدعاءات السابقة للدالةurlretrieve().