urllib.parse --- تجزیه URLها به کامپوننت‌ها

کد منبع: Lib/urllib/parse.py

---

این ماژول یک رابط استاندارد را برای تجزیه‌ی رشته‌های مکان‌یاب منبع یکپارچه (URL) به کامپوننت‌ها (طرح‌واره آدرس‌دهی، محل شبکه، مسیر و غیره)، ترکیب مجدد کامپوننت‌ها به یک رشته‌ی URL، و تبدیل یک «URL نسبی» به یک URL مطلق با توجه به یک «URL پایه» تعریف می‌کند.

این ماژول برای مطابقت با RFC اینترنتی مربوط به Relative Uniform Resource Locators طراحی شده است. این ماژول از طرح‌های URL زیر پشتیبانی می‌کند: file، ftp، gopher، hdl، http، https، imap، itms-services، mailto، mms، news، nntp، prospero، rsync، rtsp، rtsps، rtspu، sftp، shttp، sip، sips، snews، svn، svn+ssh، telnet، wais، ws، wss.

گنجاندن طرح‌واره URL itms-services می‌تواند مانع از پذیرفته شدن یک برنامه در فرآیند بازبینی اپ‌استور اپل برای اپ‌استورهای macOS و iOS شود. مدیریت طرح‌واره itms-services همیشه در iOS حذف می‌شود؛ در macOS، ممکن است در صورتی حذف شود که CPython با گزینه‌ی --with-app-store-compliance ساخته شده باشد.

ماژول urllib.parse توابعی را تعریف می‌کند که به دو دسته کلی تقسیم می‌شوند: تجزیه‌ی URL و کدگذاری URL (URL quoting). این موارد در بخش‌های زیر با جزئیات پوشش داده شده‌اند.

توابع این ماژول از اصطلاح منسوخ‌شده netloc (یا net_loc) استفاده می‌کنند که در RFC 1808 معرفی شد. با این حال، این اصطلاح توسط RFC 3986 از رده خارج شده است، که اصطلاح authority را به‌عنوان جایگزین آن معرفی کرد. استفاده از netloc برای سازگاری با نسخه‌های پیشین ادامه دارد.

تجزیه‌ی URL

توابع تجزیه‌ی URL بر تقسیم یک رشته‌ی URL به کامپوننت‌های آن، یا ترکیب کامپوننت‌های URL در یک رشته‌ی URL تمرکز دارند.

urllib.parse.urlsplit(urlstring, scheme=None, allow_fragments=True)

یک URL را به پنج کامپوننت تجزیه می‌کند و یک named tuple با ۵ آیتم از نوع SplitResult یا SplitResultBytes را برمی‌گرداند. این با ساختار کلی یک URL مطابقت دارد: scheme://netloc/path?query#fragment. هر آیتم از تاپل یک رشته است، که ممکن است خالی باشد.

جداکننده‌های نشان‌داده‌شده در بالا بخشی از نتیجه نیستند، به‌جز اسلش آغازین در کامپوننت path که در صورت وجود حفظ می‌شود.

علاوه بر این، خصوصیت netloc به این ویژگی‌های اضافی که به شیء برگردانده‌شده افزوده شده‌اند، تفکیک می‌شود: username، password، hostname و port.

دنباله‌های کدگذاری‌شده با درصد کدگشایی نمی‌شوند.

برای مثال:

>>> from urllib.parse import urlsplit
>>> urlsplit("scheme://netloc/path?query#fragment")
SplitResult(scheme='scheme', netloc='netloc', path='/path',
            query='query', fragment='fragment')
>>> o = urlsplit("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
SplitResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html',
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

طبق مشخصات سینتکس در RFC 1808، urlsplit() تنها در صورتی یک netloc را تشخیص می‌دهد که به‌درستی با '//' معرفی شده باشد. در غیر این صورت، فرض می‌شود ورودی یک URL نسبی است و بنابراین با یک کامپوننت مسیر شروع می‌شود.

>>> from urllib.parse import urlsplit
>>> urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='', fragment='')
>>> urlsplit('www.cwi.nl/%7Eguido/Python.html')
SplitResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            query='', fragment='')
>>> urlsplit('help/Python.html')
SplitResult(scheme='', netloc='', path='help/Python.html',
            query='', fragment='')

آرگومان scheme طرح‌واره آدرس‌دهی پیش‌فرض را مشخص می‌کند و فقط زمانی استفاده می‌شود که URL طرح‌واره‌ای را مشخص نکرده باشد. این آرگومان باید هم‌نوع (متن یا بایت) با urlstring باشد، به‌جز اینکه مقدار پیش‌فرض '' همیشه مجاز است و در صورت لزوم به‌طور خودکار به b'' تبدیل می‌شود.

اگر آرگومان allow_fragments نادرست باشد، شناسه‌های قطعه (fragment) شناسایی نمی‌شوند. در عوض، آن‌ها به‌عنوان بخشی از مسیر، پارامترها یا کامپوننت پرس‌وجو تجزیه می‌شوند و fragment در مقدار بازگشتی روی رشته‌ی خالی تنظیم می‌شود.

مقدار بازگشتی یک named tuple است، بدین معنا که می‌توان به آیتم‌های آن با اندیس یا به‌عنوان ویژگی‌های نام‌دار دسترسی داشت، که عبارتند از:

ویژگی	اندیس	مقدار	مقدار در صورت عدم وجود
scheme	0	مشخص‌کننده‌ی طرح‌واره URL	پارامتر scheme
netloc	1	بخش موقعیت شبکه	رشته خالی
path	2	مسیر سلسله‌مراتبی	رشته خالی
query	3	کامپوننت پرس‌وجو	رشته خالی
fragment	۴	شناسه قطعه	رشته خالی
username		نام کاربری	None
password		گذرواژه	None
hostname		نام میزبان (حروف کوچک)	None
port		شماره‌ی پورت به‌صورت عدد صحیح، در صورت وجود	None

خواندن ویژگی port در صورتی که پورت نامعتبری در URL مشخص شده باشد، باعث پرتاب یک ValueError می‌شود. برای اطلاعات بیشتر درباره شیء نتیجه، بخش نتایج تجزیه‌ی ساختاریافته را ببینید.

کروشه‌های جفت‌نشده در ویژگی netloc باعث پرتاب یک ValueError می‌شود.

نویسه‌های موجود در ویژگی netloc که در نرمال‌سازی NFKC (که در رمزگذاری IDNA استفاده می‌شود) به هرکدام از /، ?، #، @ یا : تجزیه شوند، باعث ایجاد ValueError می‌شوند. اگر URL پیش از تجزیه، تجزیه‌ی نرمال‌سازی‌شده باشد، خطایی ایجاد نخواهد شد.

در پیروی از برخی از WHATWG spec که RFC 3986 را به‌روزرسانی می‌کند، نویسه‌های کنترلی C0 و نویسه‌های فاصله در ابتدای URL از URL حذف می‌شوند. نویسه‌های \n، \r و تب \t در هر جای URL از URL حذف می‌شوند.

همان‌طور که برای همه‌ی تیوپل‌های نام‌دار (named tuples) صدق می‌کند، این زیرکلاس چند متد و ویژگی اضافی دارد که به‌ویژه مفید هستند. یکی از این متدها _replace() است. متد _replace() یک شیء جدید SplitResult بازمی‌گرداند که فیلدهای مشخص‌شده در آن با مقادیر جدید جایگزین شده‌اند.

>>> from urllib.parse import urlsplit
>>> u = urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='', fragment='')
>>> u._replace(scheme='http')
SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='', fragment='')

هشدار

urlsplit() اعتبارسنجی انجام نمی‌دهد. برای جزئیات، امنیت تجزیه URL را ببینید.

تغییر یافته در نسخه‌ی 3.2: قابلیت‌های تجزیه‌ی URLهای IPv6 افزوده شد.

تغییر یافته در نسخه‌ی 3.3: قطعه (fragment) اکنون برای همه طرح‌های URL (مگر اینکه allow_fragments نادرست باشد)، مطابق با RFC 3986 تجزیه می‌شود. پیش‌تر، یک فهرست مجاز از طرح‌هایی که از قطعه‌ها پشتیبانی می‌کردند وجود داشت.

تغییر یافته در نسخه‌ی 3.6: شماره‌های پورت خارج از محدوده، اکنون به جای برگرداندن None، ValueError پرتاب می‌کنند.

تغییر یافته در نسخه‌ی 3.8: نویسه‌هایی که بر تجزیه‌ی netloc تحت نرمال‌سازی NFKC تأثیر می‌گذارند، اکنون ValueError پرتاب می‌کنند.

تغییر یافته در نسخه‌ی 3.10: نویسه‌های خط جدید و تب ASCII از URL حذف می‌شوند.

تغییر یافته در نسخه‌ی 3.12: نویسه‌های کنترلی C0 و فاصله‌ی WHATWG از ابتدای URL حذف می‌شوند.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

یک رشته‌ی کوئری داده‌شده به‌عنوان آرگومان رشته‌ای را تجزیه می‌کند (داده‌هایی از نوع application/x-www-form-urlencoded). داده‌ها به‌صورت یک دیکشنری بازگردانده می‌شوند. کلیدهای دیکشنری، نام‌های یکتای متغیرهای کوئری هستند و مقادیر، فهرست‌هایی از مقادیر برای هر نام هستند.

آرگومان اختیاری keep_blank_values پرچمی است که نشان می‌دهد آیا مقادیر خالی در کوئری‌های کدگذاری‌شده با درصد باید به‌عنوان رشته‌های خالی در نظر گرفته شوند یا خیر. مقدار درست نشان می‌دهد که مقادیر خالی باید به‌عنوان رشته‌های خالی حفظ شوند. مقدار پیش‌فرض نادرست نشان می‌دهد که مقادیر خالی باید نادیده گرفته شوند و به‌گونه‌ای با آن‌ها رفتار شود که گویی شامل نشده‌اند.

آرگومان اختیاری strict_parsing پرچمی است که مشخص می‌کند با خطاهای تجزیه چگونه برخورد شود. اگر نادرست باشد (پیش‌فرض)، خطاها به‌طور بی‌صدا نادیده گرفته می‌شوند. اگر درست باشد، خطاها یک استثنای ValueError را پرتاب می‌کنند.

پارامترهای اختیاری encoding و errors، همان‌گونه که متد bytes.decode() آن‌ها را می‌پذیرد، چگونگی کدگشایی دنباله‌های کدگذاری‌شده با درصد به نویسه‌های یونیکد را مشخص می‌کنند.

آرگومان اختیاری max_num_fields حداکثر تعداد فیلدهایی است که خوانده می‌شوند. اگر تنظیم شده باشد، در صورتی که بیش از max_num_fields فیلد خوانده شود، ValueError پرتاب می‌کند.

آرگومان اختیاری separator نمادی است که برای جداسازی آرگومان‌های پرس‌وجو به کار می‌رود. مقدار پیش‌فرض آن & است.

برای تبدیل چنین دیکشنری‌هایی به رشته‌های پرس‌وجو (query strings)، از تابع urllib.parse.urlencode() (با تنظیم پارامتر doseq روی True) استفاده کنید.

تغییر یافته در نسخه‌ی 3.2: افزودن پارامترهای encoding و errors.

تغییر یافته در نسخه‌ی 3.8: پارامتر max_num_fields افزوده شد.

تغییر یافته در نسخه‌ی 3.10: پارامتر separator با مقدار پیش‌فرض & افزوده شد. نسخه‌های پایتون پیش از پایتون 3.10 اجازه می‌دادند که از هر دو ; و & به‌عنوان جداکننده‌ی پارامتر کوئری استفاده شود. این رفتار تغییر کرده است تا تنها یک کلید جداکننده مجاز باشد، با & به‌عنوان جداکننده‌ی پیش‌فرض.

منسوخ شده از نسخه‌ی 3.14: پذیرفتن اشیایی با مقادیر کاذب (مانند 0 و []) به‌جز رشته‌های خالی، اشیاء شبه‌بایت و None اکنون منسوخ شده است.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

یک رشته‌ی پرس‌وجو (query string) را که به‌عنوان آرگومان رشته‌ای داده شده است، تجزیه می‌کند (داده‌هایی از نوع application/x-www-form-urlencoded). داده‌ها به‌صورت فهرستی از جفت‌های نام و مقدار بازگردانده می‌شوند.

آرگومان اختیاری keep_blank_values پرچمی است که نشان می‌دهد آیا مقادیر خالی در کوئری‌های کدگذاری‌شده با درصد باید به‌عنوان رشته‌های خالی در نظر گرفته شوند یا خیر. مقدار درست نشان می‌دهد که مقادیر خالی باید به‌عنوان رشته‌های خالی حفظ شوند. مقدار پیش‌فرض نادرست نشان می‌دهد که مقادیر خالی باید نادیده گرفته شوند و به‌گونه‌ای با آن‌ها رفتار شود که گویی شامل نشده‌اند.

آرگومان اختیاری strict_parsing پرچمی است که مشخص می‌کند با خطاهای تجزیه چگونه برخورد شود. اگر نادرست باشد (پیش‌فرض)، خطاها به‌طور بی‌صدا نادیده گرفته می‌شوند. اگر درست باشد، خطاها یک استثنای ValueError را پرتاب می‌کنند.

پارامترهای اختیاری encoding و errors، همان‌گونه که متد bytes.decode() آن‌ها را می‌پذیرد، چگونگی کدگشایی دنباله‌های کدگذاری‌شده با درصد به نویسه‌های یونیکد را مشخص می‌کنند.

آرگومان اختیاری max_num_fields حداکثر تعداد فیلدهایی است که خوانده می‌شوند. اگر تنظیم شده باشد، در صورتی که بیش از max_num_fields فیلد خوانده شود، ValueError پرتاب می‌کند.

آرگومان اختیاری separator نمادی است که برای جداسازی آرگومان‌های پرس‌وجو به کار می‌رود. مقدار پیش‌فرض آن & است.

برای تبدیل چنین فهرست‌هایی از جفت‌ها به رشته‌های پرس‌وجو، از تابع urllib.parse.urlencode() استفاده کنید.

تغییر یافته در نسخه‌ی 3.2: افزودن پارامترهای encoding و errors.

تغییر یافته در نسخه‌ی 3.8: پارامتر max_num_fields افزوده شد.

تغییر یافته در نسخه‌ی 3.10: پارامتر separator با مقدار پیش‌فرض & افزوده شد. نسخه‌های پایتون پیش از پایتون 3.10 اجازه می‌دادند که از هر دو ; و & به‌عنوان جداکننده‌ی پارامتر کوئری استفاده شود. این رفتار تغییر کرده است تا تنها یک کلید جداکننده مجاز باشد، با & به‌عنوان جداکننده‌ی پیش‌فرض.

urllib.parse.urlunsplit(parts)

یک URL را از یک تاپل که توسط urlsplit() برگردانده می‌شود بسازید. آرگومان parts می‌تواند هر پیمایش‌پذیری با پنج آیتم باشد. اگر URL اصلی تجزیه‌شده دارای جداکننده‌های غیرضروری باشد (برای مثال، یک ? با پرس‌وجوی خالی؛ RFC تصریح می‌کند که این‌ها معادل هستند)، ممکن است یک URL کمی متفاوت، اما معادل به دست آید.

urllib.parse.urlparse(urlstring, scheme=None, allow_fragments=True)

این تابع مشابه urlsplit() است، اما علاوه بر آن، کامپوننت path را به path و params تقسیم می‌کند. این تابع یک named tuple ۶ آیتمی از نوع ParseResult یا ParseResultBytes برمی‌گرداند. آیتم‌های آن همان آیتم‌های نتیجه‌ی urlsplit() هستند، با این تفاوت که params در اندیس ۳، بین path و query درج شده است.

این تابع مبتنی بر RFC 1738 و RFC 1808 منسوخ‌شده است، که params را به‌عنوان کامپوننت اصلی URL فهرست کرده بودند. سینتکس جدیدتر URL اجازه می‌دهد پارامترها به هر بخش از قسمت path URL اعمال شوند (به RFC 3986 مراجعه کنید). به‌طور کلی باید به‌جای urlparse() از urlsplit() استفاده شود. برای جدا کردن بخش‌های مسیر و پارامترها، به تابع جداگانه‌ای نیاز است.

urllib.parse.urlunparse(parts)

عناصر یک تاپل برگردانده‌شده توسط urlparse() را به یک URL کامل به‌صورت یک رشته ترکیب می‌کند. آرگومان parts می‌تواند هر پیمایش‌پذیری با شش آیتم باشد. این ممکن است منجر به URLای اندکی متفاوت، اما معادل شود، اگر URLای که در اصل تجزیه شده بود، جداکننده‌های غیرضروری داشته باشد (برای مثال، یک ? با پرس‌وجوی خالی؛ RFC بیان می‌کند که این‌ها معادل هستند).

urllib.parse.urljoin(base, url, allow_fragments=True)

با ترکیب یک «URL پایه» (base) با یک URL دیگر (url)، یک URL کامل («مطلق») بسازید. به‌طور غیررسمی، در این کار از کامپوننت‌های URL پایه، به‌ویژه طرح‌واره آدرس‌دهی، موقعیت شبکه و (بخشی از) مسیر، برای فراهم کردن کامپوننت‌های ناموجود در URL نسبی استفاده می‌شود. برای مثال:

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

آرگومان allow_fragments همان معنا و پیش‌فرض را دارد که برای urlsplit() وجود دارد.

توجه

اگر url یک URL مطلق باشد (یعنی با // یا scheme:// شروع شود)، نام میزبان و/یا طرح‌واره‌ی url در نتیجه وجود خواهد داشت. برای مثال:

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

اگر آن رفتار را نمی‌خواهید، url را با urlsplit() و urlunsplit() پیش‌پردازش کنید و بخش‌های احتمالی scheme و netloc را حذف کنید.

هشدار

از آنجا که ممکن است یک نشانی وب مطلق (URL) به‌عنوان پارامتر url ارسال شود، استفاده از urljoin با url تحت کنترل مهاجم عموماً امن نیست. برای مثال، در urljoin("https://website.com/users/", username)، اگر username بتواند شامل یک نشانی وب مطلق باشد، نتیجه‌ی urljoin همان نشانی وب مطلق خواهد بود.

تغییر یافته در نسخه‌ی 3.5: رفتار به‌روزرسانی شد تا با معناشناسی تعریف‌شده در RFC 3986 مطابقت کند.

urllib.parse.urldefrag(url)

اگر url شامل یک شناسه‌ی قطعه باشد، نسخه‌ی تغییرکرده‌ای از url را بدون شناسه‌ی قطعه، و شناسه‌ی قطعه را به‌صورت یک رشته‌ی جداگانه برمی‌گرداند. اگر شناسه‌ی قطعه‌ای در url وجود نداشته باشد، url را بدون تغییر و یک رشته‌ی خالی برمی‌گرداند.

مقدار بازگشتی یک named tuple است؛ می‌توان به آیتم‌های آن با اندیس یا به‌عنوان ویژگی‌های نام‌دار دسترسی پیدا کرد:

ویژگی	اندیس	مقدار	مقدار در صورت عدم وجود
url	0	URL بدون قطعه (fragment)	رشته خالی
fragment	1	شناسه قطعه	رشته خالی

برای اطلاعات بیشتر درباره‌ی شیء نتیجه، بخش نتایج تجزیه‌ی ساختاریافته را ببینید.

تغییر یافته در نسخه‌ی 3.2: نتیجه یک شیء ساختاریافته است، نه یک تاپل دوتایی ساده.

urllib.parse.unwrap(url)

URL را از یک URL پوشیده‌شده استخراج می‌کند (یعنی رشته‌ای که به‌صورت <URL:scheme://host/path>، <scheme://host/path>، URL:scheme://host/path یا scheme://host/path قالب‌بندی‌شده باشد). اگر url یک URL پوشیده‌شده نباشد، بدون تغییر بازگردانده می‌شود.

امنیت تجزیه‌ی URL

APIهای urlsplit() و urlparse() اعتبارسنجی ورودی‌ها را انجام نمی‌دهند. ممکن است این APIها برای ورودی‌هایی که سایر برنامه‌ها آن‌ها را نامعتبر می‌دانند، خطا پرتاب نکنند. همچنین ممکن است برای برخی ورودی‌ها که ممکن است در جاهای دیگر به‌عنوان URL در نظر گرفته نشوند، با موفقیت عمل کنند. هدف آن‌ها عملکرد کاربردی است، نه خلوص.

به‌جای پرتاب یک استثنا برای ورودی غیرمعمول، ممکن است در عوض برخی از اجزای کامپوننت‌ها را به‌صورت رشته‌های خالی برگردانند. یا ممکن است کامپوننت‌ها دارای محتوای بیشتری نسبت به آنچه شاید باید داشته باشند.

توصیه می‌کنیم کاربران این APIها، در مواردی که مقادیر ممکن است در هر جایی با پیامدهای امنیتی استفاده شوند، به‌صورت دفاعی کد بنویسند. پیش از اعتماد به یک کامپوننت بازگشتی، در کد خود مقداری اعتبارسنجی انجام دهید. آیا آن scheme منطقی است؟ آیا آن path معقول است؟ آیا مورد عجیبی درباره آن hostname وجود دارد؟ و غیره.

اینکه چه چیزی یک URL را تشکیل می‌دهد، به‌طور جهانی به‌خوبی تعریف نشده است. برنامه‌های کاربردی مختلف، نیازها و محدودیت‌های مطلوب متفاوتی دارند. برای نمونه، سند زنده‌ی WHATWG spec آنچه را کلاینت‌های وب رو به کاربر، مانند یک مرورگر وب، نیاز دارند توصیف می‌کند. در حالی که RFC 3986 کلی‌تر است. این توابع برخی جنبه‌های هر دو را در بر می‌گیرند، اما نمی‌توان ادعا کرد که با هیچ‌کدام از آن‌ها منطبق هستند. APIها و کد کاربر موجود با انتظارهایی نسبت به رفتارهای مشخص، پیش از هر دو استاندارد وجود داشته‌اند؛ این موضوع ما را در تغییر رفتار API بسیار محتاط می‌سازد.

تجزیه بایت‌های کدگذاری‌شده با ASCII

توابع تجزیه URL در ابتدا فقط برای کار با رشته‌های نویسه‌ای طراحی شده بودند. در عمل، مفید است که بتوان URLهایی را که به‌درستی نقل‌قول‌شده و کدگذاری‌شده‌اند، به‌صورت دنباله‌هایی از بایت‌های ASCII دستکاری کرد. بر همین اساس، توابع تجزیه URL در این ماژول همگی علاوه بر اشیاء str روی اشیاء bytes و bytearray نیز عمل می‌کنند.

اگر داده‌ای از نوع str ارسال شود، نتیجه نیز فقط شامل داده‌های str خواهد بود. اگر داده‌ای از نوع bytes یا bytearray ارسال شود، نتیجه فقط شامل داده‌های bytes خواهد بود.

تلاش برای ترکیب داده‌های str با bytes یا bytearray در یک فراخوانی تابع واحد، باعث پرتاب شدن TypeError می‌شود، در حالی که تلاش برای ارسال مقادیر بایتی غیر ASCII باعث پرتاب شدن UnicodeDecodeError می‌شود.

برای پشتیبانی از تبدیل آسان‌تر اشیای نتیجه بین str و bytes، همه‌ی مقادیر بازگشتی توابع تجزیه‌ی URL، یا یک متد encode() را ارائه می‌دهند (هنگامی که نتیجه شامل داده‌ی str باشد) یا یک متد decode() را (هنگامی که نتیجه شامل داده‌ی bytes باشد). امضای این متدها با امضای متدهای متناظر str و bytes مطابقت دارد (به‌جز اینکه کدگذاری پیش‌فرض 'ascii' است، نه 'utf-8'). هر یک مقداری از نوع متناظر تولید می‌کند که یا شامل داده‌ی bytes است (برای متدهای encode()) یا داده‌ی str (برای متدهای decode()).

برنامه‌های کاربردی که نیاز دارند URLهایی را پردازش کنند که ممکن است به‌طور نادرست نقل‌قول‌شده باشند و حاوی داده‌های غیر ASCII باشند، باید پیش از فراخوانی متدهای تجزیه‌ی URL، خود کدگشایی از بایت‌ها به نویسه‌ها را انجام دهند.

رفتار توصیف‌شده در این بخش فقط به توابع تجزیه‌ی URL اعمال می‌شود. توابع نقل‌قول URL (URL quoting) هنگام تولید یا مصرف دنباله‌های بایت از قوانین خود استفاده می‌کنند، همان‌طور که در مستندات هر یک از توابع نقل‌قول URL به تفصیل آمده است.

تغییر یافته در نسخه‌ی 3.2: توابع تجزیه‌ی URL اکنون دنباله‌های بایتی کدگذاری‌شده با ASCII را می‌پذیرند

نتایج تجزیه‌ی ساختاریافته

اشیاء نتیجه‌ی توابع urlsplit()، urlparse() و urldefrag() زیرکلاس‌هایی از نوع tuple هستند. این زیرکلاس‌ها ویژگی‌های فهرست‌شده در مستندات آن توابع، پشتیبانی از کدگذاری و کدگشایی توصیف‌شده در بخش پیشین، و نیز یک متد اضافی را اضافه می‌کنند:

urllib.parse.SplitResult.geturl()

نسخه‌ی بازترکیب‌شده‌ی URL اصلی را به‌صورت یک رشته برمی‌گرداند. این ممکن است با URL اصلی متفاوت باشد، به این صورت که طرح‌واره ممکن است به حروف کوچک نرمال‌سازی شود و کامپوننت‌های خالی ممکن است حذف شوند. به‌طور مشخص، پارامترهای خالی، پرس‌وجوهای خالی (queries) و شناسه‌های خالی قطعه (fragment identifiers) حذف خواهند شد.

برای نتایج urldefrag()، فقط شناسه‌های قطعه خالی حذف خواهند شد. برای نتایج urlsplit() و urlparse()، همه تغییرات ذکرشده روی URL برگردانده‌شده توسط این متد اعمال خواهند شد.

نتیجه‌ی این متد در صورتی که دوباره به تابع تجزیه‌ی اصلی داده شود، بدون تغییر باقی می‌ماند:

>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

کلاس‌های زیر پیاده‌سازی‌های نتایج تجزیه‌ی ساختاریافته را هنگام کار با اشیای str فراهم می‌کنند:

class urllib.parse.DefragResult(url, fragment)

کلاس مشخص برای نتایج urldefrag() که حاوی داده‌های str هستند. متد encode() نمونه‌ای از DefragResultBytes را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

کلاس عینی برای نتایج urlparse() که شامل داده‌های str هستند. متد encode() یک نمونه از ParseResultBytes را برمی‌گرداند.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

کلاس عینی برای نتایج urlsplit() که حاوی داده‌های str است. متد encode() نمونه‌ای از SplitResultBytes را برمی‌گرداند.

کلاس‌های زیر پیاده‌سازی‌های نتایج تجزیه را هنگام کار بر روی اشیای bytes یا bytearray ارائه می‌دهند:

class urllib.parse.DefragResultBytes(url, fragment)

کلاس عینی برای نتایج urldefrag() که حاوی داده‌های bytes هستند. متد decode() یک نمونه از DefragResult را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

کلاس مشخص برای نتایج urlparse() که حاوی داده‌های bytes هستند. متد decode() یک نمونه از ParseResult را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

کلاس مشخص برای نتایج urlsplit() که شامل داده‌های bytes است. متد decode() یک نمونه SplitResult را برمی‌گرداند.

اضافه شده در نسخه‌ی 3.2.

کدگذاری URL (URL Quoting)

توابع نقل‌قول URL بر گرفتن داده‌های برنامه و ایمن کردن آن‌ها برای استفاده به‌عنوان کامپوننت‌های URL از طریق نقل‌قول کردن نویسه‌های خاص و کدگذاری مناسب متن غیر ASCII تمرکز دارند. آن‌ها همچنین از معکوس کردن این عملیات برای بازسازی داده‌های اصلی از محتوای یک کامپوننت URL پشتیبانی می‌کنند، اگر آن کار از قبل توسط توابع تجزیه URL بالا پوشش داده نشده باشد.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

نویسه‌های ویژه در string با استفاده از خنثی‌سازی %xx جایگزین می‌شوند. حروف، ارقام و نویسه‌های '_.-~' هرگز کدگذاری نمی‌شوند. به‌طور پیش‌فرض، این تابع برای کدگذاری بخش مسیر یک URL در نظر گرفته شده است. پارامتر اختیاری safe نویسه‌های ASCII اضافی را مشخص می‌کند که نباید کدگذاری شوند — مقدار پیش‌فرض آن '/' است.

string ممکن است یک شیء str یا bytes باشد.

تغییر یافته در نسخه‌ی 3.7: برای کدگذاری (quoting) رشته‌های URL، از RFC 2396 به RFC 3986 منتقل شد. اکنون «~» در مجموعه نویسه‌های بدون رزرو گنجانده شده است.

پارامترهای اختیاری encoding و errors مشخص می‌کنند که چگونه با نویسه‌های غیر ASCII برخورد شود، همان‌گونه که متد str.encode() آن‌ها را می‌پذیرد. اگرچه این پارامترها در امضای تابع مقدار پیش‌فرض None دارند، هنگام پردازش ورودی‌های str، مقدار پیش‌فرض encoding عملاً 'utf-8' و مقدار پیش‌فرض errors عملاً 'strict' است، به این معنا که نویسه‌های پشتیبانی‌نشده موجب پرتاب UnicodeEncodeError می‌شوند. اگر string یک bytes باشد، نباید encoding و errors ارائه شوند، در غیر این صورت یک TypeError پرتاب می‌شود.

توجه داشته باشید که quote(string, safe, encoding, errors) معادل quote_from_bytes(string.encode(encoding, errors), safe) است.

مثال: quote('/El Niño/') مقدار '/El%20Ni%C3%B1o/' را برمی‌گرداند.

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)

مانند quote()، اما فاصله‌ها را نیز با علامت‌های جمع جایگزین می‌کند، همان‌طور که برای نقل‌قول کردن مقادیر فرم HTML هنگام ساخت رشته‌ی پرس‌وجو (query string) برای قرار گرفتن در URL لازم است. علامت‌های جمع در رشته‌ی اصلی خنثی می‌شوند، مگر اینکه در safe گنجانده شده باشند. همچنین مقدار پیش‌فرض safe برابر با '/' نیست.

مثال: quote_plus('/El Niño/') مقدار '%2FEl+Ni%C3%B1o%2F' را نتیجه می‌دهد.

urllib.parse.quote_from_bytes(bytes, safe='/')

مانند quote()، اما یک شیء bytes را به‌جای یک str می‌پذیرد و کدگذاری رشته به بایت را انجام نمی‌دهد.

مثال: quote_from_bytes(b'a&\xef') مقدار 'a%26%EF' را برمی‌گرداند.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

گریزهای %xx را با معادل تک‌نویسه‌ای آن‌ها جایگزین می‌کند. پارامترهای اختیاری encoding و errors مشخص می‌کنند که دنباله‌های کدگذاری‌شده با درصد چگونه به نویسه‌های یونیکد کدگشایی شوند، همان‌گونه که متد bytes.decode() می‌پذیرد.

string ممکن است یک شیء str یا bytes باشد.

encoding به‌طور پیش‌فرض 'utf-8' است. errors به‌طور پیش‌فرض 'replace' است، به این معنا که دنباله‌های نامعتبر با یک نویسه جایگزین جایگزین می‌شوند.

مثال: unquote('/El%20Ni%C3%B1o/') '/El Niño/' را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.9: پارامتر string از شیءهای bytes و str پشتیبانی می‌کند (پیش‌تر فقط str).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

مانند unquote() است، اما همچنین علامت‌های مثبت را با فاصله جایگزین می‌کند، همان‌طور که برای کدگشایی مقادیر فرم HTML لازم است.

string باید یک str باشد.

مثال: unquote_plus('/El+Ni%C3%B1o/') '/El Niño/' را برمی‌گرداند.

urllib.parse.unquote_to_bytes(string)

دنباله‌های خنثی‌سازی %xx را با معادل تک‌بایتی آن‌ها جایگزین می‌کند و یک شیء bytes را برمی‌گرداند.

string ممکن است یک شیء str یا bytes باشد.

اگر یک str باشد، نویسه‌های غیر ASCII خنثی‌نشده در string به بایت‌های UTF-8 کدگذاری می‌شوند.

مثال: unquote_to_bytes('a%26%EF') b'a&\xef' را برمی‌گرداند.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

یک شیء نگاشت یا دنباله‌ای از تاپل‌های دو عنصری را، که ممکن است شامل اشیای str یا bytes باشد، به یک رشته متنی ASCII با کدگذاری درصدی تبدیل می‌کند. اگر رشته حاصل قرار باشد به‌عنوان data برای عملیات POST با تابع urlopen() استفاده شود، باید به بایت کدگذاری شود؛ در غیر این صورت منجر به TypeError خواهد شد.

رشته‌ی حاصل، مجموعه‌ای از جفت‌های key=value است که با نویسه‌های '&' از هم جدا شده‌اند؛ در آن هم کلید و هم مقدار با استفاده از تابع quote_via کدگذاری می‌شوند. به‌طور پیش‌فرض، quote_plus() برای کدگذاری مقدارها استفاده می‌شود، به این معنا که فاصله‌ها به‌صورت نویسه‌ی '+' کدگذاری می‌شوند و نویسه‌های '/' به‌صورت %2F کدگذاری می‌شوند، که از استاندارد درخواست‌های GET (application/x-www-form-urlencoded) پیروی می‌کند. تابع جایگزینی که می‌توان به‌عنوان quote_via ارسال کرد، quote() است که فاصله‌ها را به‌صورت %20 کدگذاری می‌کند و نویسه‌های '/' را کدگذاری نمی‌کند. برای حداکثر کنترل بر آنچه کدگذاری می‌شود، از quote استفاده کنید و مقداری برای safe مشخص کنید.

هنگامی که از یک دنباله از تاپل‌های دو عنصری به‌عنوان آرگومان query استفاده شود، اولین المان هر تاپل یک کلید و دومین المان یک مقدار است. خود المان مقدار می‌تواند یک دنباله باشد و در این صورت، اگر پارامتر اختیاری doseq به True ارزیابی شود، برای هر المان از دنباله‌ی مقدارِ آن کلید، جفت‌های key=value جداگانه‌ای تولید می‌شوند که با '&' از هم جدا شده‌اند. ترتیب پارامترها در رشته‌ی کدگذاری‌شده با ترتیب تاپل‌های پارامتر در دنباله مطابقت خواهد کرد.

پارامترهای safe، encoding و errors به quote_via منتقل می‌شوند (پارامترهای encoding و errors فقط زمانی منتقل می‌شوند که یک المان پرس‌وجو از نوع str باشد).

برای معکوس کردن این فرایند کدگذاری، parse_qs() و parse_qsl() در این ماژول ارائه شده‌اند تا رشته‌های پرس‌وجو را به ساختارهای داده پایتون تجزیه کنند.

برای اینکه ببینید چگونه می‌توان از متد urllib.parse.urlencode() برای تولید رشته‌ی پرس‌وجوی یک URL یا داده‌های یک درخواست POST استفاده کرد، به مثال‌های urllib مراجعه کنید.

تغییر یافته در نسخه‌ی 3.2: query از اشیای bytes و اشیای رشته‌ای پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.5: پارامتر quote_via افزوده شد.

منسوخ شده از نسخه‌ی 3.14: پذیرفتن اشیایی با مقادیر کاذب (مانند 0 و []) به‌جز رشته‌های خالی، اشیاء شبه‌بایت و None اکنون منسوخ شده است.

همچنین ملاحظه نمائید

WHATWG - استاندارد زنده‌ی URL

گروه کاری استاندارد URL که URLها، دامنه‌ها، آدرس‌های IP، قالب application/x-www-form-urlencoded و API آن‌ها را تعریف می‌کند.

RFC 3986 - شناسه‌های یکنواخت منبع

این استاندارد کنونی (STD66) است. هرگونه تغییری در ماژول urllib.parse باید با این استاندارد مطابقت داشته باشد. ممکن است برخی انحراف‌ها مشاهده شوند که عمدتاً برای اهداف سازگاری با نسخه‌های پیشین و برای برخی الزامات دوفاکتوی تجزیه هستند، همان‌گونه که معمولاً در مرورگرهای اصلی مشاهده می‌شود.

RFC 2732 - قالب آدرس‌های IPv6 به‌صورت متنی در URLها.

این الزامات تجزیه‌ی URLهای IPv6 را مشخص می‌کند.

RFC 2396 - شناسه‌های منبع یکنواخت (URI): سینتکس عام

سندی که الزامات نحوی عام برای هر دو نام منبع یکدست (URN) و مکان‌یاب منبع یکدست (URL) را توصیف می‌کند.

RFC 2368 - طرح‌واره URL mailto.

الزامات تجزیه برای طرح‌واره‌های URL mailto.

RFC 1808 - نشانی‌های نسبی منابع یکنواخت

این درخواست برای نظر (Request For Comments) شامل قواعد پیوند دادن یک URL مطلق و یک URL نسبی است، از جمله تعداد قابل‌توجهی «مثال‌های غیرعادی» که نحوه‌ی برخورد با موارد مرزی را تعیین می‌کنند.

RFC 1738 - مکان‌یاب‌های یکپارچه منابع (URL)

این، سینتکس و معناشناسی رسمی URLهای مطلق را مشخص می‌کند.