http.cookiejar --- مدیریت کوکی‌ها برای کلاینت‌های HTTP

کد منبع: Lib/http/cookiejar.py

ماژول http.cookiejar کلاس‌هایی را برای مدیریت خودکار کوکی‌های HTTP تعریف می‌کند. این ماژول برای دسترسی به وب‌سایت‌هایی مفید است که نیاز دارند که قطعات کوچکی از داده -- cookies -- توسط یک پاسخ HTTP از یک وب‌سرور بر روی ماشین کلاینت تنظیم شوند و سپس در درخواست‌های HTTP بعدی به سرور بازگردانده شوند.

هم پروتکل معمول کوکی Netscape و هم پروتکل تعریف‌شده در RFC 2965 مدیریت می‌شوند. مدیریت RFC 2965 به‌طور پیش‌فرض غیرفعال است. کوکی‌های RFC 2109 به‌عنوان کوکی‌های Netscape تجزیه می‌شوند و سپس مطابق با «سیاست» حاکم، یا به‌عنوان کوکی‌های Netscape یا به‌عنوان کوکی‌های RFC 2965 رفتار می‌شوند. توجه داشته باشید که اکثریت قریب به اتفاق کوکی‌های اینترنت، کوکی‌های Netscape هستند. http.cookiejar تلاش می‌کند از پروتکل کوکی Netscape دوفاکتو پیروی کند (که تفاوت اساسی با آنچه در مشخصات اصلی Netscape آمده است دارد)، از جمله با در نظر گرفتن ویژگی‌های کوکی max-age و port که با RFC 2965 معرفی‌شده‌اند.

توجه

پارامترهای نام‌دار مختلفی که در سرآیندهای Set-Cookie و Set-Cookie2 یافت می‌شوند (برای مثال، domain و expires) به‌طور قراردادی ویژگی‌ها <attributes> نامیده می‌شوند. برای تمایز آن‌ها از ویژگی‌های پایتون، مستندات این ماژول به‌جای آن از اصطلاح ویژگی کوکی <cookie-attribute> استفاده می‌کند.

این ماژول استثنای زیر را تعریف می‌کند:

exception http.cookiejar.LoadError

نمونه‌های FileCookieJar در صورت شکست در بارگذاری کوکی‌ها از یک پرونده، این استثنا را پرتاب می‌کنند. LoadError زیرکلاسی از OSError است.

تغییر یافته در نسخه‌ی 3.3: LoadError پیش‌تر زیرنوعی از IOError بود، که اکنون نام مستعاری از OSError است.

کلاس‌های زیر ارائه شده‌اند:

class http.cookiejar.CookieJar(policy=None)

policy یک شیء است که رابط CookiePolicy را پیاده‌سازی می‌کند.

کلاس CookieJar کوکی‌های HTTP را ذخیره می‌کند. این کلاس کوکی‌ها را از درخواست‌های HTTP استخراج می‌کند و آن‌ها را در پاسخ‌های HTTP بازمی‌گرداند. نمونه‌های CookieJar به‌طور خودکار کوکی‌های درون خود را در صورت لزوم منقضی می‌کنند. زیرکلاس‌ها نیز مسئول ذخیره و بازیابی کوکی‌ها از یک پرونده یا پایگاه داده هستند.

class http.cookiejar.FileCookieJar(filename=None, delayload=None, policy=None)

policy یک شیء است که رابط CookiePolicy را پیاده‌سازی می‌کند. برای سایر آرگومان‌ها، مستندات ویژگی‌های متناظر را ببینید.

یک CookieJar که می‌تواند کوکی‌ها را از یک پرونده روی دیسک بارگذاری کند و احتمالاً کوکی‌ها را در آن ذخیره کند. کوکی‌ها از پرونده نام‌برده بارگذاری نمی‌شوند، مگر اینکه متد load() یا revert() فراخوانی شود. زیرکلاس‌های این کلاس در بخش زیرکلاس‌های FileCookieJar و همکاری با مرورگرهای وب مستند شده‌اند.

این نباید به‌صورت مستقیم مقداردهی اولیه شود — در عوض از زیرکلاس‌های زیرِ آن استفاده کنید.

تغییر یافته در نسخه‌ی 3.8: پارامتر filename از یک path-like object پشتیبانی می‌کند.

class http.cookiejar.CookiePolicy

این کلاس مسئول تصمیم‌گیری درباره‌ی این است که آیا هر کوکی باید از سرور پذیرفته شود / به سرور بازگردانده شود.

class http.cookiejar.DefaultCookiePolicy(blocked_domains=None, allowed_domains=None, netscape=True, rfc2965=False, rfc2109_as_netscape=None, hide_cookie2=False, strict_domain=False, strict_rfc2965_unverifiable=True, strict_ns_unverifiable=False, strict_ns_domain=DefaultCookiePolicy.DomainLiberal, strict_ns_set_initial_dollar=False, strict_ns_set_path=False, secure_protocols=('https', 'wss'))

آرگومان‌های سازنده باید فقط به‌صورت آرگومان‌های کلیدواژه‌ای ارسال شوند. blocked_domains دنباله‌ای از نام‌های دامنه است که هرگز از آن‌ها کوکی نمی‌پذیریم و به آن‌ها کوکی بازنمی‌گردانیم. allowed_domains اگر None نباشد، دنباله‌ای از تنها دامنه‌هایی است که برای آن‌ها کوکی می‌پذیریم و کوکی بازمی‌گردانیم. secure_protocols دنباله‌ای از پروتکل‌هایی است که می‌توان کوکی‌های امن را به آن‌ها افزود. به‌طور پیش‌فرض، https و wss (وب‌سوکت امن) به‌عنوان پروتکل‌های امن در نظر گرفته می‌شوند. برای تمام آرگومان‌های دیگر، مستندات اشیاء CookiePolicy و DefaultCookiePolicy را ببینید.

DefaultCookiePolicy قواعد استاندارد پذیرش / رد را برای کوکی‌های Netscape و RFC 2965 پیاده‌سازی می‌کند. به‌طور پیش‌فرض، با کوکی‌های RFC 2109 (یعنی کوکی‌هایی که در یک سرآیند Set-Cookie با ویژگی کوکی version برابر 1 دریافت می‌شوند) طبق قواعد RFC 2965 رفتار می‌شود. با این حال، اگر مدیریت RFC 2965 غیرفعال باشد یا rfc2109_as_netscape برابر True باشد، کوکی‌های RFC 2109 توسط نمونه‌ی CookieJar به کوکی‌های Netscape «تنزل» داده می‌شوند؛ این کار با تنظیم ویژگی version در نمونه‌ی Cookie روی 0 انجام می‌شود. DefaultCookiePolicy همچنین برخی پارامترها را برای امکان تنظیم دقیق‌تر سیاست فراهم می‌کند.

class http.cookiejar.Cookie

این کلاس، کوکی‌های Netscape، RFC 2109 و RFC 2965 را بازنمایی می‌کند. انتظار نمی‌رود که کاربران http.cookiejar، نمونه‌های Cookie خود را بسازند. در عوض، در صورت لزوم، make_cookies() را روی یک نمونه از CookieJar فراخوانی کنید.

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

ماژول urllib.request

باز کردن URL با مدیریت خودکار کوکی‌ها.

ماژول http.cookies

کلاس‌های کوکی HTTP، عمدتاً برای کد سمت سرور مفید هستند. ماژول‌های http.cookiejar و http.cookies به یکدیگر وابسته نیستند.

https://curl.se/rfc/cookie_spec.html

مشخصات پروتکل کوکی اصلی Netscape. اگرچه این پروتکل همچنان غالب است، «پروتکل کوکی Netscape» که توسط تمام مرورگرهای اصلی (و http.cookiejar) پیاده‌سازی شده است، تنها شباهتی گذرا به آن پروتکلی دارد که در cookie_spec.html ترسیم شده است.

RFC 2109 - سازوکار مدیریت وضعیت HTTP

توسط RFC 2965 از رده خارج شده است. از Set-Cookie با version=1 استفاده می‌کند.

RFC 2965 - سازوکار مدیریت وضعیت HTTP

پروتکل نت‌اسکیپ با اشکالات رفع‌شده. از Set-Cookie2 به‌جای Set-Cookie استفاده می‌کند. به‌طور گسترده استفاده نمی‌شود.

https://kristol.org/cookie/errata.html

اصلاحیه‌های ناتمام برای RFC 2965.

RFC 2964 - استفاده از مدیریت وضعیت HTTP

اشیای CookieJar و FileCookieJar

اشیای CookieJar از پروتکل iterator برای پیمایش روی اشیای Cookie موجود پشتیبانی می‌کنند.

CookieJar متدهای زیر را دارد:

سرآیند Cookie صحیح را به request اضافه کنید.

اگر سیاست اجازه دهد (یعنی ویژگی‌های rfc2965 و hide_cookie2 در نمونه‌ی CookiePolicy مربوط به CookieJar به‌ترتیب درست و نادرست باشند)، سرآیند‌ی Cookie2 نیز در صورت لزوم افزوده می‌شود.

شیء درخواست (معمولاً یک نمونه از urllib.request.Request) باید از متدهای get_full_url()، has_header()، get_header()، header_items()، add_unredirected_header() و ویژگی‌های host، type، unverifiable و origin_req_host پشتیبانی کند، همان‌طور که در urllib.request مستند شده است.

تغییر یافته در نسخه‌ی 3.3: شیء request به ویژگی origin_req_host نیاز دارد. وابستگی به متد منسوخ get_origin_req_host() حذف شده است.

CookieJar.extract_cookies(response, request)

کوکی‌ها را از پاسخ HTTP استخراج می‌کند و آن‌ها را در CookieJar ذخیره می‌کند، هر جا که سیاست اجازه دهد.

CookieJar در آرگومان response به دنبال سرآیندهای مجاز Set-Cookie و Set-Cookie2 می‌گردد و کوکی‌ها را به‌صورت مناسب ذخیره می‌کند (منوط به تأیید متد CookiePolicy.set_ok()).

شیء response (معمولاً نتیجه‌ی فراخوانی urllib.request.urlopen() یا مشابه آن) باید از متد info() پشتیبانی کند، که نمونه‌ای از email.message.Message را برمی‌گرداند.

شیء request (معمولاً یک نمونه از urllib.request.Request) باید از متد get_full_url() و ویژگی‌های host، unverifiable و origin_req_host پشتیبانی کند، همان‌طور که در urllib.request مستند شده است. از این request برای تنظیم مقادیر پیش‌فرض برای ویژگی‌های کوکی و همچنین برای بررسی مجاز بودن تنظیم کوکی استفاده می‌شود.

تغییر یافته در نسخه‌ی 3.3: شیء request به ویژگی origin_req_host نیاز دارد. وابستگی به متد منسوخ get_origin_req_host() حذف شده است.

CookieJar.set_policy(policy)

نمونه‌ی CookiePolicy را برای استفاده تنظیم کنید.

CookieJar.make_cookies(response, request)

دنباله‌ای از اشیای Cookie استخراج‌شده از شیء response را برمی‌گرداند.

برای اطلاع از رابط‌های مورد نیاز آرگومان‌های response و request، مستندات extract_cookies() را ببینید.

اگر سیاست اجازه دهد، یک Cookie تنظیم کنید.

یک Cookie را تنظیم کنید، بدون اینکه با سیاست بررسی شود که آیا باید تنظیم شود یا خیر.

CookieJar.clear([domain[, path[, name]]])

برخی کوکی‌ها را پاک کنید.

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

اگر کوکی متناظری وجود نداشته باشد، KeyError پرتاب می‌شود.

CookieJar.clear_session_cookies()

همه‌ی کوکی‌های نشست را حذف کنید.

همه‌ی کوکی‌های موجود را که ویژگی discard آن‌ها مقدار درست دارد، حذف می‌کند (معمولاً به این دلیل که یا فاقد ویژگی کوکی max-age یا expires بودند، یا یک ویژگی کوکی discard صریح داشتند). در مرورگرهای تعاملی، پایان یک نشست معمولاً با بستن پنجره‌ی مرورگر مطابقت دارد.

توجه داشته باشید که متد save() در هر صورت کوکی‌های نشست را ذخیره نمی‌کند، مگر آنکه با ارسال یک آرگومان ignore_discard با مقدار درست، خلاف آن را درخواست کنید.

FileCookieJar متدهای اضافی زیر را پیاده‌سازی می‌کند:

FileCookieJar.save(filename=None, ignore_discard=False, ignore_expires=False)

کوکی‌ها را در یک پرونده ذخیره کنید.

این کلاس پایه NotImplementedError را پرتاب می‌کند. زیرکلاس‌ها می‌توانند این متد را پیاده‌سازی‌نشده باقی بگذارند.

filename نام پرونده‌ای است که کوکی‌ها در آن ذخیره می‌شوند. اگر filename مشخص نشده باشد، self.filename استفاده می‌شود (که مقدار پیش‌فرض آن، در صورت وجود، مقدار ارسال‌شده به سازنده است)؛ اگر self.filename برابر None باشد، ValueError پرتاب می‌شود.

ignore_discard: ذخیره کردن حتی کوکی‌های تنظیم‌شده برای دور انداختن. ignore_expires: ذخیره کردن حتی کوکی‌های منقضی‌شده

در صورتی که پرونده از قبل وجود داشته باشد، بازنویسی می‌شود و در نتیجه همه‌ی کوکی‌های موجود در آن پاک می‌شوند. کوکی‌های ذخیره‌شده را می‌توان بعداً با استفاده از متدهای load() یا revert() بازیابی کرد.

FileCookieJar.load(filename=None, ignore_discard=False, ignore_expires=False)

بارگذاری کوکی‌ها از یک پرونده.

کوکی‌های قدیمی نگه داشته می‌شوند، مگر این‌که کوکی‌های تازه بارگذاری‌شده آن‌ها را بازنویسی کنند.

آرگومان‌ها مانند save() هستند.

پرونده نام‌برده باید در قالبی باشد که کلاس آن را درک می‌کند، در غیر این صورت LoadError پرتاب خواهد شد. همچنین ممکن است OSError پرتاب شود، برای مثال اگر پرونده وجود نداشته باشد.

تغییر یافته در نسخه‌ی 3.3: IOError پیش‌تر پرتاب می‌شد، اکنون نام مستعار OSError است.

FileCookieJar.revert(filename=None, ignore_discard=False, ignore_expires=False)

تمام کوکی‌ها را پاک کنید و کوکی‌ها را از یک پرونده ذخیره‌شده بارگذاری مجدد کنید.

revert() می‌تواند همان استثناهای load() را پرتاب کند. در صورت بروز شکست، وضعیت شیء تغییر نخواهد کرد.

نمونه‌های FileCookieJar دارای ویژگی‌های عمومی زیر هستند:

FileCookieJar.filename

نام پرونده‌ی پیش‌فرض برای نگهداری کوکی‌ها. این ویژگی قابل انتساب است.

FileCookieJar.delayload

اگر true باشد، کوکی‌ها به‌صورت تنبل از دیسک بارگذاری می‌شوند. نباید به این ویژگی مقداری انتساب داده شود. این فقط یک راهنمایی است، زیرا فقط بر عملکرد تأثیر می‌گذارد، نه رفتار (مگر اینکه کوکی‌های روی دیسک در حال تغییر باشند). یک شیء CookieJar ممکن است آن را نادیده بگیرد. هیچ‌یک از کلاس‌های FileCookieJar موجود در کتابخانه استاندارد، کوکی‌ها را به‌صورت تنبل بارگذاری نمی‌کنند.

زیرکلاس‌های FileCookieJar و همکاری با مرورگرهای وب

زیرکلاس‌های CookieJar زیر برای خواندن و نوشتن ارائه شده‌اند.

class http.cookiejar.MozillaCookieJar(filename=None, delayload=None, policy=None)

یک FileCookieJar که می‌تواند کوکی‌ها را از دیسک در قالب پرونده cookies.txt موزیلا بارگذاری کند و با همین قالب روی دیسک ذخیره کند (این قالب توسط curl و مرورگرهای Lynx و Netscape نیز استفاده می‌شود).

توجه

این باعث از دست رفتن اطلاعات مربوط به کوکی‌های RFC 2965 و همچنین ویژگی‌های کوکی جدیدتر یا غیراستاندارد مانند port می‌شود.

هشدار

اگر کوکی‌هایی دارید که از دست رفتن / خراب شدن آن‌ها مشکل‌ساز خواهد بود، پیش از ذخیره از کوکی‌های خود پشتیبان بگیرید (ظرافت‌هایی وجود دارند که ممکن است در طول یک چرخه‌ی رفت و برگشت بارگذاری / ذخیره منجر به تغییرات جزئی در پرونده شوند).

همچنین توجه داشته باشید که کوکی‌های ذخیره‌شده در حالی که Mozilla در حال اجرا است، توسط Mozilla بازنویسی می‌شوند.

class http.cookiejar.LWPCookieJar(filename=None, delayload=None, policy=None)

یک FileCookieJar که می‌تواند کوکی‌ها را در قالبی سازگار با قالب پرونده Set-Cookie3 کتابخانه libwww-perl از دیسک بارگذاری کند و روی دیسک ذخیره کند. اگر بخواهید کوکی‌ها را در پرونده‌ای قابل‌خواندن برای انسان ذخیره کنید، این گزینه مناسب است.

تغییر یافته در نسخه‌ی 3.8: پارامتر filename از یک path-like object پشتیبانی می‌کند.

اشیای CookiePolicy

شیءهایی که رابط CookiePolicy را پیاده‌سازی می‌کنند، متدهای زیر را دارند:

CookiePolicy.set_ok(cookie, request)

مقدار بولی‌ای را برمی‌گرداند که نشان می‌دهد آیا کوکی باید از سرور پذیرفته شود.

cookie یک نمونه از Cookie است. request شیءای است که رابط تعریف‌شده در مستندات CookieJar.extract_cookies() را پیاده‌سازی می‌کند.

CookiePolicy.return_ok(cookie, request)

مقدار بولی‌ای را برمی‌گرداند که نشان می‌دهد آیا کوکی باید به سرور بازگردانده شود.

cookie یک نمونه از Cookie است. request شیءای است که رابط تعریف‌شده در مستندات CookieJar.add_cookie_header() را پیاده‌سازی می‌کند.

CookiePolicy.domain_return_ok(domain, request)

اگر کوکی‌ها نباید با توجه به دامنه‌ی کوکی برگردانده شوند، False را برگردانید.

این متد یک بهینه‌سازی است. این متد نیاز به بررسی هر کوکی با یک دامنه خاص را برطرف می‌کند (که ممکن است مستلزم خواندن پرونده‌های زیادی باشد). بازگرداندن مقدار true از domain_return_ok() و path_return_ok()، تمام کار را به return_ok() واگذار می‌کند.

اگر domain_return_ok() برای دامنه کوکی مقدار true را برگرداند، path_return_ok() برای مسیر کوکی فراخوانی می‌شود. در غیر این صورت، path_return_ok() و return_ok() هرگز برای آن دامنه کوکی فراخوانی نمی‌شوند. اگر path_return_ok() مقدار true را برگرداند، return_ok() همراه با خود شیء Cookie برای یک بررسی کامل فراخوانی می‌شود. در غیر این صورت، return_ok() هرگز برای آن مسیر کوکی فراخوانی نمی‌شود.

توجه داشته باشید که domain_return_ok() برای هر دامنه‌ی کوکی فراخوانی می‌شود، نه فقط برای دامنه‌ی درخواست. برای مثال، اگر دامنه‌ی درخواست "www.example.com" باشد، ممکن است این تابع با هر دو ".example.com" و "www.example.com" فراخوانی شود. همین موضوع برای path_return_ok() نیز صدق می‌کند.

آرگومان request همان‌گونه است که برای return_ok() مستند شده است.

CookiePolicy.path_return_ok(path, request)

با توجه به مسیر کوکی، اگر کوکی‌ها نباید برگردانده شوند، False برمی‌گرداند.

مستندات domain_return_ok() را ببینید.

علاوه بر پیاده‌سازی متدهای بالا، پیاده‌سازی‌های رابط CookiePolicy باید ویژگی‌های زیر را نیز فراهم کنند، که نشان می‌دهند از کدام پروتکل‌ها باید استفاده شود و چگونه. می‌توان به همه‌ی این ویژگی‌ها مقداری انتساب داد.

CookiePolicy.netscape

پیاده‌سازی پروتکل Netscape.

CookiePolicy.rfc2965

پیاده‌سازی پروتکل RFC 2965.

CookiePolicy.hide_cookie2

سرآیند Cookie2 را به درخواست‌ها اضافه نکنید (وجود این سرآیند به سرور نشان می‌دهد که ما کوکی‌های RFC 2965 را درک می‌کنیم).

مفیدترین راه برای تعریف یک کلاس CookiePolicy، ایجاد زیرکلاس از DefaultCookiePolicy و بازتعریف برخی یا همه متدهای بالا است. خود CookiePolicy می‌تواند به‌عنوان یک «سیاست null» برای مجاز کردن تنظیم و دریافت هر کوکی و همه کوکی‌ها استفاده شود (بعید است این حالت مفید باشد).

اشیاء DefaultCookiePolicy

قواعد استاندارد برای پذیرش و بازگرداندن کوکی‌ها را پیاده‌سازی می‌کند.

هم RFC 2965 و هم کوکی‌های Netscape پوشش داده می‌شوند. پردازش RFC 2965 به‌طور پیش‌فرض غیرفعال است.

ساده‌ترین راه برای ارائه سیاست خودتان این است که این کلاس را بازنویسی کنید و متدهای آن را در پیاده‌سازی‌های بازنویسی‌شده‌ی خود، پیش از افزودن بررسی‌های اضافی خودتان، فراخوانی کنید:

import http.cookiejar
class MyCookiePolicy(http.cookiejar.DefaultCookiePolicy):
    def set_ok(self, cookie, request):
        if not http.cookiejar.DefaultCookiePolicy.set_ok(self, cookie, request):
            return False
        if i_dont_want_to_store_this_cookie(cookie):
            return False
        return True

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

یک فهرست مسدودی و یک فهرست مجاز برای دامنه‌ها ارائه شده است (هر دو به‌طور پیش‌فرض غیرفعال هستند). فقط دامنه‌هایی که در فهرست مسدودی نیستند و در فهرست مجاز وجود دارند (اگر فهرست مجاز فعال باشد)، در تنظیم و بازگشت کوکی‌ها مشارکت می‌کنند. از آرگومان سازنده‌ی blocked_domains و متدهای blocked_domains() و set_blocked_domains() (و آرگومان و متدهای متناظر برای allowed_domains) استفاده کنید. اگر یک فهرست مجاز تنظیم کنید، می‌توانید دوباره آن را با تنظیم روی None غیرفعال کنید.

دامنه‌های موجود در فهرست‌های مسدودسازی یا مجاز که با نقطه آغاز نمی‌شوند، برای مطابقت باید دقیقاً برابر با دامنه کوکی باشند. برای مثال، "example.com" با ورودی "example.com" در فهرست مسدودسازی مطابقت دارد، اما "www.example.com" مطابقت ندارد. دامنه‌هایی که با نقطه آغاز می‌شوند، با دامنه‌های مشخص‌تر نیز مطابقت داده می‌شوند. برای مثال، هر دو "www.example.com" و "www.coyote.example.com" با ".example.com" مطابقت دارند (اما خود "example.com" مطابقت ندارد). نشانی‌های IP یک استثنا هستند و باید دقیقاً مطابقت داشته باشند. برای مثال، اگر blocked_domains شامل "192.168.1.2" و ".168.1.2" باشد، 192.168.1.2 مسدود می‌شود، اما 193.168.1.2 مسدود نمی‌شود.

DefaultCookiePolicy متدهای اضافی زیر را پیاده‌سازی می‌کند:

DefaultCookiePolicy.blocked_domains()

دنباله‌ای از دامنه‌های مسدودشده را برمی‌گرداند (به‌صورت یک تاپل).

DefaultCookiePolicy.set_blocked_domains(blocked_domains)

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

DefaultCookiePolicy.is_blocked(domain)

اگر domain در فهرست مسدودی برای تنظیم یا دریافت کوکی‌ها باشد، True را برمی‌گرداند.

DefaultCookiePolicy.allowed_domains()

None، یا دنباله‌ای از دامنه‌های مجاز (به‌صورت یک تاپل) را برمی‌گرداند.

DefaultCookiePolicy.set_allowed_domains(allowed_domains)

دنباله‌ای از دامنه‌های مجاز، یا None را تنظیم کنید.

DefaultCookiePolicy.is_not_allowed(domain)

اگر domain در فهرست مجاز برای تنظیم یا دریافت کوکی‌ها نباشد، True را برمی‌گرداند.

نمونه‌های DefaultCookiePolicy دارای ویژگی‌های زیر هستند که همگی از آرگومان‌های سازنده با همین نام مقداردهی اولیه شده‌اند و می‌توان به همه‌ی آن‌ها مقدار نسبت داد.

DefaultCookiePolicy.rfc2109_as_netscape

اگر درست باشد، از نمونه‌ی CookieJar درخواست می‌شود که کوکی‌های RFC 2109 (یعنی کوکی‌هایی که در سرآیند Set-Cookie با ویژگی کوکی version برابر با 1 دریافت می‌شوند) را با تنظیم ویژگی version نمونه‌ی Cookie روی 0 به کوکی‌های Netscape تنزل دهد. مقدار پیش‌فرض None است، که در این صورت کوکی‌های RFC 2109 فقط و فقط در صورتی تنزل داده می‌شوند که مدیریت RFC 2965 غیرفعال باشد. بنابراین، کوکی‌های RFC 2109 به‌طور پیش‌فرض تنزل داده می‌شوند.

سوئیچ‌های سخت‌گیری عمومی:

DefaultCookiePolicy.strict_domain

اجازه ندهید سایت‌ها دامنه‌های دوبخشی با دامنه‌های سطح‌بالای کد کشور مانند .co.uk، .gov.uk، .co.nz و غیره را تنظیم کنند. این روش اصلاً کامل نیست و تضمینی برای کار کردن آن وجود ندارد!

کلیدهای سخت‌گیری پروتکل RFC 2965:

DefaultCookiePolicy.strict_rfc2965_unverifiable

از قوانین RFC 2965 درباره‌ی تراکنش‌های غیرقابل‌تأیید پیروی کنید (معمولاً یک تراکنش غیرقابل‌تأیید تراکنشی است که از یک تغییرمسیر یا درخواست برای تصویری که در سایت دیگری میزبانی شده است، ناشی می‌شود). اگر این مقدار نادرست باشد، کوکی‌ها هرگز بر اساس قابلیت تأیید مسدود نمی‌شوند

سوئیچ‌های سخت‌گیری پروتکل Netscape:

DefaultCookiePolicy.strict_ns_unverifiable

قوانین RFC 2965 را در تراکنش‌های تأییدناپذیر حتی بر کوکی‌های Netscape اعمال کنید.

DefaultCookiePolicy.strict_ns_domain

پرچم‌هایی که میزان سخت‌گیری در قوانین تطبیق دامنه برای کوکی‌های Netscape را نشان می‌دهند. برای مقادیر مجاز، در زیر ببینید.

DefaultCookiePolicy.strict_ns_set_initial_dollar

کوکی‌های موجود در سرآیندهای Set-Cookie: را که نام‌هایشان با '$' آغاز می‌شود، نادیده بگیرید.

DefaultCookiePolicy.strict_ns_set_path

اجازه ندهید کوکی‌هایی تنظیم شوند که مسیرشان با URI درخواست مطابقت مسیر (path-match) ندارد.

strict_ns_domain مجموعه‌ای از پرچم‌ها است. مقدار آن با OR بیتی پرچم‌ها با یکدیگر ساخته می‌شود (برای مثال، DomainStrictNoDots|DomainStrictNonDomain به این معناست که هر دو پرچم تنظیم شده‌اند).

DefaultCookiePolicy.DomainStrictNoDots

هنگام تنظیم کوکی‌ها، «پیشوند میزبان» نباید شامل نقطه باشد (برای مثال، www.foo.bar.com نمی‌تواند کوکی‌ای را برای .bar.com تنظیم کند، زیرا www.foo شامل نقطه است).

DefaultCookiePolicy.DomainStrictNonDomain

کوکی‌هایی که ویژگی کوکی domain را به‌صراحت مشخص نکرده‌اند، فقط می‌توانند به دامنه‌ای برابر با دامنه‌ای که کوکی را تنظیم کرده است بازگردانده شوند (برای مثال، کوکی‌های example.com که ویژگی کوکی domain را ندارند، به spam.example.com بازگردانده نخواهند شد).

DefaultCookiePolicy.DomainRFC2965Match

هنگام تنظیم کوکی‌ها، تطابق کامل دامنه با RFC 2965 الزامی است.

ویژگی‌های زیر برای سهولت ارائه شده‌اند و مفیدترین ترکیب‌های پرچم‌های بالا هستند:

DefaultCookiePolicy.DomainLiberal

معادل ۰ (یعنی همه‌ی پرچم‌های سخت‌گیری دامنه‌ی Netscape که در بالا ذکر شدند، غیرفعال شده‌اند).

DefaultCookiePolicy.DomainStrict

معادل DomainStrictNoDots|DomainStrictNonDomain.

مثال‌ها

نخستین مثال رایج‌ترین کاربرد http.cookiejar را نشان می‌دهد:

import http.cookiejar, urllib.request
cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

این مثال نشان می‌دهد که چگونه با استفاده از کوکی‌های Netscape، Mozilla یا Lynx خود، یک URL را باز کنید (فرض می‌کند که قرارداد Unix/Netscape برای محل پرونده کوکی‌ها برقرار است):

import os, http.cookiejar, urllib.request
cj = http.cookiejar.MozillaCookieJar()
cj.load(os.path.join(os.path.expanduser("~"), ".netscape", "cookies.txt"))
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")

مثال بعدی استفاده از DefaultCookiePolicy را نشان می‌دهد. کوکی‌های RFC 2965 فعال می‌شوند، هنگام تنظیم و بازگرداندن کوکی‌های Netscape درباره دامنه‌ها سخت‌گیری بیشتری اعمال می‌شود و برخی دامنه‌ها از تنظیم کوکی‌ها یا بازگرداندن آن‌ها مسدود می‌شوند:

import urllib.request
from http.cookiejar import CookieJar, DefaultCookiePolicy
policy = DefaultCookiePolicy(
    rfc2965=True, strict_ns_domain=Policy.DomainStrict,
    blocked_domains=["ads.net", ".ads.net"])
cj = CookieJar(policy)
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))
r = opener.open("http://example.com/")