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, *, missing_as_none=False)

Parse a URL into five components, returning a 5-item named tuple SplitResult or SplitResultBytes. This corresponds to the general structure of a URL: scheme://netloc/path?query#fragment. Each tuple item is a string, possibly empty, or None if missing_as_none is true. Not defined component are represented an empty string (by default) or None if missing_as_none is true. The delimiters as shown above are not part of the result, except for a leading slash in the path component, which is retained if present.

علاوه بر این، خصوصیت 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'
>>> urlsplit("http://docs.python.org?")
SplitResult(scheme='http', netloc='docs.python.org', path='',
            query='', fragment='')
>>> urlsplit("http://docs.python.org?", missing_as_none=True)
SplitResult(scheme='http', netloc='docs.python.org', path='',
            query='', fragment=None)

طبق مشخصات سینتکس در 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='')
>>> urlsplit('help/Python.html', missing_as_none=True)
SplitResult(scheme=None, netloc=None, path='help/Python.html',
            query=None, fragment=None)

The scheme argument gives the default addressing scheme, to be used only if the URL does not specify one. It should be the same type (text or bytes) as urlstring or None, except that the '' is always allowed, and is automatically converted to b'' if appropriate.

If the allow_fragments argument is false, fragment identifiers are not recognized. Instead, they are parsed as part of the path or query component, and fragment is set to None or the empty string (depending on the value of missing_as_none) in the return value.

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

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

[1] (1,2,3,4)

Depending on the value of the missing_as_none argument.

خواندن ویژگی 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: Out-of-range port numbers now raise ValueError, instead of returning None.

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

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

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

تغییر یافته در نسخه‌ی 3.15: Added the missing_as_none parameter.

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)

urllib.parse.urlunsplit(parts, *, keep_empty)

Construct a URL from a tuple as returned by urlsplit(). The parts argument can be any five-item iterable.

This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent).

If keep_empty is true, empty strings are kept in the result (for example, a ? for an empty query), only None components are omitted. This allows rebuilding a URL that was parsed with option missing_as_none=True. By default, keep_empty is true if parts is the result of the urlsplit() call with missing_as_none=True.

تغییر یافته در نسخه‌ی 3.15: Added the keep_empty parameter.

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

این تابع مشابه 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)

urllib.parse.urlunparse(parts, *, keep_empty)

Combine the elements of a tuple as returned by urlparse() into a complete URL as a string. The parts argument can be any six-item iterable.

This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent).

If keep_empty is true, empty strings are kept in the result (for example, a ? for an empty query), only None components are omitted. This allows rebuilding a URL that was parsed with option missing_as_none=True. By default, keep_empty is true if parts is the result of the urlparse() call with missing_as_none=True.

تغییر یافته در نسخه‌ی 3.15: Added the keep_empty parameter.

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, *, missing_as_none=False)

If url contains a fragment identifier, return a modified version of url with no fragment identifier, and the fragment identifier as a separate string. If there is no fragment identifier in url, return url unmodified and an empty string (by default) or None if missing_as_none is true.

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

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

[3]

Depending on the value of the missing_as_none argument.

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

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

تغییر یافته در نسخه‌ی 3.15: Added the missing_as_none parameter.

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 در نظر گرفته نشوند، با موفقیت عمل کنند. هدف آن‌ها عملکرد کاربردی است، نه خلوص.

Instead of raising an exception on unusual input, they may instead return some component parts as empty strings or None (depending on the value of the missing_as_none argument). Or components may contain more than perhaps they should.

توصیه می‌کنیم کاربران این 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()

Return the re-combined version of the original URL as a string. This may differ from the original URL in that the scheme may be normalized to lower case and empty components may be dropped. Specifically, empty parameters, queries, and fragment identifiers will be removed unless the URL was parsed with missing_as_none=True.

برای نتایج 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/'
>>> r3 = urlsplit(url, missing_as_none=True)
>>> r3.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های مطلق را مشخص می‌کند.