اشیای CookieJar و FileCookieJar¶

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

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

CookieJar.add_cookie_header(request)¶

سرآیند 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() را ببینید.

CookieJar.set_cookie_if_ok(cookie, request)¶

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

CookieJar.set_cookie(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.

اشیای Cookie¶

نمونه‌های Cookie دارای ویژگی‌های پایتون هستند که تقریباً با ویژگی‌های استاندارد کوکی مشخص‌شده در استانداردهای مختلف کوکی متناظرند. این تناظر یک‌به‌یک نیست، زیرا قواعد پیچیده‌ای برای تخصیص مقادیر پیش‌فرض وجود دارد، زیرا ویژگی‌های کوکی max-age و expires حاوی اطلاعات معادل هستند، و زیرا ممکن است کوکی‌های RFC 2109 توسط http.cookiejar از کوکی‌های نسخه 1 به کوکی‌های نسخه 0 (Netscape) تنزل داده شوند.

انتساب به این ویژگی‌ها نباید به‌جز در موارد نادر در یک متد از CookiePolicy ضروری باشد. این کلاس سازگاری داخلی را تضمین نمی‌کند، بنابراین اگر این کار را انجام می‌دهید، باید بدانید چه می‌کنید.

Cookie.version¶

عدد صحیح یا None. کوکی‌های Netscape دارای version برابر 0 هستند. کوکی‌های RFC 2965 و RFC 2109 دارای ویژگی کوکی version با مقدار 1 هستند. با این حال، توجه داشته باشید که http.cookiejar ممکن است کوکی‌های RFC 2109 را به کوکی‌های Netscape «تنزل» دهد، که در این صورت version برابر 0 است.

Cookie.name¶

نام کوکی (یک رشته).

Cookie.value¶

مقدار کوکی (یک رشته)، یا None.

Cookie.port¶

رشته‌ای که یک پورت یا مجموعه‌ای از پورت‌ها را نشان می‌دهد (برای مثال، '80' یا '80,8080')، یا None.

Cookie.domain¶

دامنه کوکی (یک رشته).

Cookie.path¶

مسیر کوکی (یک رشته، برای مثال، '/acme/rocket_launchers').

Cookie.secure¶

True اگر کوکی فقط باید از طریق یک اتصال امن بازگردانده شود.

Cookie.expires¶

تاریخ انقضا به‌صورت عدد صحیح بر حسب ثانیه از مبدأ زمان، یا None. همچنین متد is_expired() را ببینید.

Cookie.discard¶

اگر این یک کوکی نشست باشد، True است.

Cookie.comment¶

رشته‌ی کامنت از سرور که عملکرد این کوکی را توضیح می‌دهد، یا None.

Cookie.comment_url¶

URLای که به توضیحی از سرور در مورد کارکرد این کوکی پیوند می‌دهد، یا None.

Cookie.rfc2109¶

اگر این کوکی به‌عنوان یک کوکی RFC 2109 دریافت شده باشد، True است (یعنی کوکی در یک سرآیند Set-Cookie دریافت شده است و مقدار ویژگی Version کوکی در آن سرآیند برابر 1 بوده است). این ویژگی به این دلیل فراهم شده است که http.cookiejar ممکن است کوکی‌های RFC 2109 را به کوکی‌های Netscape «تنزل دهد»؛ در این صورت version برابر 0 است.

Cookie.port_specified¶

True اگر یک پورت یا مجموعه‌ای از پورت‌ها به‌صراحت توسط سرور مشخص شده باشد (در سرآیند Set-Cookie / Set-Cookie2).

Cookie.domain_specified¶

True اگر دامنه به‌صراحت توسط سرور مشخص شده باشد.

Cookie.domain_initial_dot¶

True اگر دامنه‌ای که به‌صراحت توسط سرور مشخص شده است با یک نقطه ('.') شروع شده باشد.

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

Cookie.has_nonstandard_attr(name)¶

اگر کوکی دارای ویژگی کوکی با نام مشخص باشد، True برمی‌گرداند.

Cookie.get_nonstandard_attr(name, default=None)¶

اگر کوکی دارای ویژگی کوکی با نام مشخص باشد، مقدار آن را برمی‌گرداند. در غیر این صورت، default را برمی‌گرداند.

Cookie.set_nonstandard_attr(name, value)¶

مقدار ویژگی کوکی نام‌گذاری‌شده را تنظیم کنید.

کلاس Cookie همچنین متد زیر را تعریف می‌کند:

Cookie.is_expired(now=None)¶

True اگر کوکی از زمانی که سرور درخواست کرده بود منقضی شود، گذشته باشد. اگر now داده‌شده باشد (به ثانیه از مبدأ زمانی)، برمی‌گرداند که آیا کوکی در زمان مشخص‌شده منقضی شده است یا خیر.

مثال‌ها¶

نخستین مثال رایج‌ترین کاربرد 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/")