آموزش جامع کتابخانه urllib در پایتون

ماژول urllib یکی از کتابخانه‌های استاندارد و بسیار قدرتمند پایتون برای کار با URLها (Uniform Resource Locators) است. برخلاف کتابخانه‌های خارجی مانند requests، این ماژول به‌صورت پیش‌فرض در پایتون نصب است و نیازی به نصب اضافی ندارد. این کتابخانه ابزارهایی برای باز کردن URLها، پردازش آن‌ها، مدیریت خطاها و حتی بررسی فایل robots.txt فراهم می‌کند.

این ماژول از چهار زیربخش اصلی تشکیل شده است:

1. urllib.request: برای باز کردن و خواندن URLها.
2. urllib.error: شامل کلاس‌های خطا که توسط request ایجاد می‌شوند.
3. urllib.parse: برای تجزیه و ترکیب آدرس‌های اینترنتی.
4. urllib.robotparser: برای بررسی فایل‌های robots.txt.

سطح مقدماتی (Beginner Level)

در این سطح با نحوه ارسال درخواست‌های ساده GET، خواندن محتوای صفحات وب، دانلود فایل و تجزیه ساختار URLها آشنا می‌شویم.

۱. ارسال درخواست ساده (GET Request)

ساده‌ترین کاری که با urllib می‌توان انجام داد، باز کردن یک صفحه وب و دریافت کد HTML آن است. برای این کار از متد urlopen استفاده می‌کنیم.

مثال اول: دریافت HTML یک صفحه

در این مثال، کد HTML صفحه اصلی پایتون را دریافت کرده و ۲۰۰ کاراکتر اول آن را چاپ می‌کنیم. این کد کامل و قابل اجرا است.

مثال دوم: بررسی اطلاعات هدر (Headers)

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

مثال سوم: استفاده از Context Manager (توصیه شده)

استفاده از with باعث می‌شود که اتصال پس از اتمام کار به‌صورت خودکار بسته شود.

# Static Snippet: Best practice syntax
import urllib.request

def fetch_page(url):
    with urllib.request.urlopen(url) as response:
        return response.read()

۲. تجزیه و تحلیل URLها (Parsing)

ماژول urllib.parse به شما اجازه می‌دهد اجزای مختلف یک آدرس اینترنتی (مانند دامنه، مسیر، و پارامترها) را از هم جدا کنید.

مثال اول: جداسازی اجزای URL

استفاده از urlparse برای شکستن آدرس به بخش‌های سازنده.

مثال دوم: ترکیب مجدد اجزا (urlunparse)

گاهی نیاز دارید اجزا را تغییر داده و دوباره یک URL بسازید.

۳. مدیریت خطاهای پایه

هنگام کار با شبکه، خطاها اجتناب‌ناپذیرند. دو خطای اصلی URLError (مشکلات شبکه) و HTTPError (مشکلات سمت سرور مثل 404) هستند.

مثال اول: مدیریت خطای 404

این کد سعی می‌کند صفحه‌ای که وجود ندارد را باز کند و خطا را مدیریت می‌کند.

مثال دوم: ساختار کلی مدیریت خطا

یک تابع کمکی برای مدیریت امن درخواست‌ها (Static Code).

from urllib.error import URLError

def safe_request(url):
    try:
        # کد درخواست اینجا قرار می‌گیرد
        pass
    except URLError as e:
        if hasattr(e, 'reason'):
            print('We failed to reach a server.')
            print('Reason: ', e.reason)
        elif hasattr(e, 'code'):
            print('The server couldn\'t fulfill the request.')
            print('Error code: ', e.code)

سطح پیشرفته (Professional Level)

در این بخش به مباحث عمیق‌تر مانند جعل User-Agent، ارسال داده با متد POST، مدیریت کوکی‌ها، رمزگذاری پارامترها و استفاده از پروکسی می‌پردازیم.

۱. تغییر User-Agent و هدرهای سفارشی

بسیاری از وب‌سایت‌ها درخواست‌هایی که از طرف اسکریپت‌های پایتون (با User-Agent پیش‌فرض Python-urllib/x.y) ارسال می‌شوند را مسدود می‌کنند (ارور 403). برای حل این مشکل باید Request object بسازیم و هدر را تغییر دهیم.

مثال اول: دور زدن محدودیت‌های امنیتی ساده

در این مثال وانمود می‌کنیم که یک مرورگر واقعی (مثلاً موزیلا) هستیم.

مثال دوم: افزودن هدرهای خاص (API Keys)

گاهی برای احراز هویت نیاز به ارسال توکن در هدر دارید.

# Static: Example of adding Authorization header
import urllib.request

req = urllib.request.Request("https://api.example.com/data")
req.add_header('Authorization', 'Bearer YOUR_ACCESS_TOKEN')
req.add_header('Content-Type', 'application/json')

۲. ارسال داده (POST Request) و اینکودینگ پارامترها

برای ارسال فرم‌ها یا داده به سرور، از متد POST استفاده می‌شود. داده‌ها باید قبل از ارسال توسط urllib.parse.urlencode به فرمت مناسب تبدیل و سپس به بایت (bytes) تبدیل شوند.

مثال اول: ارسال فرم Login (شبیه‌سازی)

در این مثال نام کاربری و رمز عبور را به یک سرور تست ارسال می‌کنیم.

مثال دوم: مدیریت پارامترهای فارسی در URL

اگر پارامترهای GET شما شامل کاراکترهای غیر اسکی (مثل فارسی) باشد، باید از quote استفاده کنید.

۳. دانلود فایل‌های حجیم

برای دانلود فایل‌ها می‌توان از urlretrieve استفاده کرد، اما این متد قدیمی است (Legacy). روش حرفه‌ای‌تر، خواندن استریم داده به‌صورت تکه‌تکه (Chunk) است تا حافظه RAM اشغال نشود.

مثال اول: استفاده از urlretrieve (روش سریع)

این روش برای اسکریپت‌های ساده و فایل‌های کوچک مناسب است.

# Static: Simple download logic
from urllib.request import urlretrieve

def download_logo():
    url = "https://www.python.org/static/img/python-logo.png"
    # فایل در مسیر جاری ذخیره می‌شود
    filename, headers = urlretrieve(url, "python_logo.png")
    print(f"File downloaded to {filename}")

مثال دوم: دانلود حرفه‌ای با Chunk (روش پیشرفته)

این روش برای فایل‌های چند گیگابایتی الزامی است.

۴. مدیریت کوکی‌ها (Cookies)

برخی سایت‌ها برای حفظ نشست کاربری (Session) نیاز به کوکی دارند. urllib به تنهایی کوکی را ذخیره نمی‌کند و باید از http.cookiejar و build_opener استفاده کنید.

مثال اول: ذخیره و ارسال کوکی

در این مثال، یک Opener می‌سازیم که توانایی نگهداری کوکی‌ها را در طول چندین درخواست دارد.

مثال دوم: چیدمان معماری Opener (Static)

برای تنظیمات پیچیده‌تر مثل پروکسی و کوکی همزمان.

# Static: Proxy and Cookie Handler setup
import urllib.request
import http.cookiejar

def create_advanced_opener():
    cj = http.cookiejar.CookieJar()
    
    # تنظیم پروکسی (در صورت نیاز)
    proxy_handler = urllib.request.ProxyHandler({'http': 'http://10.10.1.10:3128'})
    
    # تنظیم کوکی
    cookie_handler = urllib.request.HTTPCookieProcessor(cj)
    
    opener = urllib.request.build_opener(proxy_handler, cookie_handler)
    return opener