poplib --- کلاینت پروتکل POP3

کد منبع: Lib/poplib.py

---

این ماژول یک کلاس، POP3، را تعریف می‌کند که یک اتصال به سرور POP3 را دربرمی‌گیرد و پروتکل تعریف‌شده در RFC 1939 را پیاده‌سازی می‌کند. کلاس POP3 از هر دو مجموعه‌ی دستورات حداقلی و اختیاری RFC 1939 پشتیبانی می‌کند. کلاس POP3 همچنین از دستور STLS معرفی‌شده در RFC 2595 برای فعال‌سازی ارتباط رمزگذاری‌شده بر روی یک اتصال از پیش برقرارشده پشتیبانی می‌کند.

علاوه بر این، این ماژول کلاس POP3_SSL را ارائه می‌دهد که پشتیبانی از اتصال به سرورهای POP3 را فراهم می‌کند؛ سرورهایی که از SSL به‌عنوان لایه‌ی پروتکل زیربنایی استفاده می‌کنند.

توجه داشته باشید که POP3، اگرچه به‌طور گسترده پشتیبانی می‌شود، منسوخ است. کیفیت پیاده‌سازی سرورهای POP3 بسیار متفاوت است و بسیاری از آن‌ها کاملاً ضعیف هستند. اگر سرور ایمیل شما از IMAP پشتیبانی می‌کند، بهتر است از کلاس imaplib.IMAP4 استفاده کنید، زیرا سرورهای IMAP معمولاً پیاده‌سازی بهتری دارند.

دسترس‌پذیری: not WASI.

این ماژول روی WebAssembly کار نمی‌کند یا در دسترس نیست. برای اطلاعات بیشتر سکوهای WebAssembly را ببینید.

ماژول poplib دو کلاس ارائه می‌دهد:

class poplib.POP3(host, port=POP3_PORT[, timeout])

این کلاس پروتکل POP3 واقعی را پیاده‌سازی می‌کند. اتصال در زمان مقداردهی اولیه نمونه ایجاد می‌شود. اگر port ذکر نشود، از پورت استاندارد POP3 (۱۱۰) استفاده می‌شود. پارامتر اختیاری timeout مهلت زمانی را بر حسب ثانیه برای تلاش اتصال مشخص می‌کند (اگر مشخص نشده باشد، از تنظیم پیش‌فرض سراسری مهلت زمانی استفاده خواهد شد).

یک رویداد حسابرسی poplib.connect را با آرگومان‌های self، host و port پرتاب می‌کند.

همه‌ی دستورات یک رویداد حسابرسی poplib.putline را با آرگومان‌های self و line پرتاب می‌کنند، که در آن line بایت‌هایی است که قرار است به میزبان راه‌دور ارسال شوند.

تغییر یافته در نسخه‌ی 3.9: اگر پارامتر timeout روی صفر تنظیم شود، برای جلوگیری از ایجاد یک سوکت غیرمسدودکننده، استثنای ValueError پرتاب می‌شود.

class poplib.POP3_SSL(host, port=POP3_SSL_PORT, *, timeout=None, context=None)

این یک زیرکلاس از POP3 است که از طریق یک سوکت رمزگذاری‌شده با SSL به سرور متصل می‌شود. اگر port مشخص ن‌شده باشد، از ۹۹۵، پورت استاندارد POP3-over-SSL، استفاده می‌شود. timeout همان‌گونه که در سازنده‌ی POP3 آمده است، عمل می‌کند. context یک شیء اختیاری از نوع ssl.SSLContext است که امکان قرار دادن گزینه‌های پیکربندی SSL، گواهی‌ها و کلیدهای خصوصی در یک ساختار واحد (که ممکن است طولانی‌مدت باشد) را فراهم می‌کند. لطفاً برای بهترین شیوه‌ها، ملاحظات امنیتی را مطالعه کنید.

یک رویداد حسابرسی poplib.connect را با آرگومان‌های self، host و port پرتاب می‌کند.

همه‌ی دستورات یک رویداد حسابرسی poplib.putline را با آرگومان‌های self و line پرتاب می‌کنند، که در آن line بایت‌هایی است که قرار است به میزبان راه‌دور ارسال شوند.

تغییر یافته در نسخه‌ی 3.2: پارامتر context اضافه شد.

تغییر یافته در نسخه‌ی 3.4: این کلاس اکنون از بررسی نام میزبان با ssl.SSLContext.check_hostname و Server Name Indication (نگاه کنید به ssl.HAS_SNI) پشتیبانی می‌کند.

تغییر یافته در نسخه‌ی 3.9: اگر پارامتر timeout روی صفر تنظیم شود، برای جلوگیری از ایجاد یک سوکت غیرمسدودکننده، استثنای ValueError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.12: پارامترهای منسوخ keyfile و certfile حذف شده‌اند.

یک استثنا به‌عنوان ویژگی‌ای از ماژول poplib تعریف شده است:

exception poplib.error_proto

در صورت بروز هرگونه خطا از این ماژول، استثنا پرتاب می‌شود (خطاهای ماژول socket گرفته نمی‌شوند). دلیل استثنا به‌صورت یک رشته به سازنده ارسال می‌شود.

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

ماژول imaplib

ماژول IMAP استاندارد پایتون.

پرسش‌های متداول درباره Fetchmail

پرسش‌های متداول کلاینت POP/IMAP fetchmail اطلاعاتی درباره‌ی تغییرات سرورهای POP3 و عدم انطباق با RFC جمع‌آوری می‌کند که ممکن است در صورت نیاز به نوشتن برنامه‌ای مبتنی بر پروتکل POP مفید باشد.

اشیای POP3

تمام دستورات POP3 به‌صورت متدهایی به همان نام و با حروف کوچک ارائه می‌شوند؛ بیشتر آن‌ها متن پاسخ ارسالی از سرور را برمی‌گردانند.

یک نمونه از POP3 دارای متدهای زیر است:

POP3.set_debuglevel(level)

سطح اشکال‌زدایی نمونه را تنظیم می‌کند. این، مقدار خروجی اشکال‌زدایی چاپ‌شده را کنترل می‌کند. مقدار پیش‌فرض، 0، هیچ خروجی اشکال‌زدایی تولید نمی‌کند. مقدار 1 مقدار متوسطی از خروجی اشکال‌زدایی را تولید می‌کند، معمولاً یک سطر در هر درخواست. مقدار 2 یا بالاتر بیشترین مقدار خروجی اشکال‌زدایی را تولید می‌کند و هر سطر ارسال‌شده و دریافت‌شده در اتصال کنترلی را ثبت می‌کند.

POP3.getwelcome()

رشته خوش‌آمد فرستاده‌شده از سوی سرور POP3 را برمی‌گرداند.

POP3.capa()

قابلیت‌های سرور را همان‌طور که در RFC 2449 مشخص شده است پرس‌وجو می‌کند. یک دیکشنری در قالب {'name': ['param'...]} برمی‌گرداند.

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

POP3.user(username)

فرمان کاربر را ارسال کنید، پاسخ باید نشان دهد که گذرواژه مورد نیاز است.

POP3.pass_(password)

گذرواژه را ارسال می‌کند؛ پاسخ شامل تعداد پیام‌ها و اندازه‌ی صندوق پستی است. توجه: صندوق پستی روی سرور تا پیش از فراخوانی quit() قفل می‌ماند.

POP3.apop(user, secret)

برای ورود به سرور POP3، از احراز هویت امن‌تر APOP استفاده کنید.

POP3.rpop(user)

از احراز هویت RPOP (مشابه r-commands در یونیکس) برای ورود به سرور POP3 استفاده کنید.

POP3.stat()

وضعیت صندوق پستی را دریافت می‌کند. نتیجه، تاپلی از ۲ عدد صحیح است: (message count, mailbox size).

POP3.list([which])

فهرست پیام‌ها را درخواست می‌کند؛ نتیجه به‌شکل (response, ['mesg_num octets', ...], octets) است. اگر which تنظیم شده باشد، پیام مورد نظر برای فهرست شدن است.

POP3.retr(which)

پیام کامل شماره‌ی which را بازیابی می‌کند و پرچم دیده‌شده‌ی آن را تنظیم می‌کند. نتیجه به‌صورت (response, ['line', ...], octets) است.

POP3.dele(which)

پیام شماره which را برای حذف علامت‌گذاری می‌کند. در بیشتر سرورها، حذف‌ها در واقع تا QUIT انجام نمی‌شوند (استثنای اصلی Eudora QPOP است که عمداً با انجام حذف‌های در انتظار در هر قطع اتصال، RFCها را نقض می‌کند).

POP3.rset()

هرگونه علامت حذف برای صندوق پستی را بردارید.

POP3.noop()

هیچ کاری انجام نمی‌دهد. ممکن است به‌عنوان زنده‌نگهداشت (keep-alive) استفاده شود.

POP3.quit()

خروج: اعمال تغییرات، آزاد کردن صندوق پستی، قطع اتصال.

POP3.top(which, howmuch)

سرآیند پیام شماره‌ی which را به‌همراه howmuch سطر از پیام پس از سرآیند بازیابی می‌کند. نتیجه به‌صورت (response, ['line', ...], octets) است.

دستور TOP در POP3 که این متد از آن استفاده می‌کند، برخلاف دستور RETR، پرچم دیده‌شده پیام را تنظیم نمی‌کند؛ متأسفانه TOP در RFCها به‌خوبی مشخص نشده است و اغلب در سرورهای غیراستاندارد به‌درستی کار نمی‌کند. پیش از اعتماد به این متد، آن را به‌صورت دستی در برابر سرورهای POP3 که استفاده خواهید کرد آزمایش کنید.

POP3.uidl(which=None)

فهرست خلاصه پیام (شناسه یکتا) را برمی‌گرداند. اگر which مشخص شده باشد، نتیجه شامل شناسه یکتا برای آن پیام در قالب 'response mesgnum uid است؛ در غیر این صورت، نتیجه فهرست (response, ['mesgnum uid', ...], octets) است.

POP3.utf8()

تلاش می‌کند به حالت UTF-8 تغییر وضعیت دهد. در صورت موفقیت، پاسخ سرور را برمی‌گرداند و در غیر این صورت error_proto را پرتاب می‌کند. در RFC 6856 مشخص شده است.

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

POP3.stls(context=None)

یک نشست TLS را روی اتصال فعال، همان‌طور که در RFC 2595 مشخص شده است، آغاز کنید. این کار فقط پیش از احراز هویت کاربر مجاز است

پارامتر context یک شیء ssl.SSLContext است که امکان گردآوری گزینه‌های پیکربندی SSL، گواهی‌ها و کلیدهای خصوصی را در یک ساختار واحد (احتمالاً طولانی‌مدت) فراهم می‌کند. لطفاً برای آشنایی با بهترین شیوه‌ها، ملاحظات امنیتی را مطالعه کنید.

این متد از بررسی نام میزبان از طریق ssl.SSLContext.check_hostname و نشان‌دهی نام سرور (Server Name Indication) پشتیبانی می‌کند (به ssl.HAS_SNI مراجعه کنید).

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

نمونه‌های POP3_SSL متدهای اضافی ندارند. رابط این زیرکلاس با کلاس والد آن یکسان است.

مثال POP3

در اینجا یک مثال حداقلی (بدون بررسی خطا) آمده است که یک صندوق پستی را باز می‌کند و همه پیام‌ها را بازیابی و چاپ می‌کند:

import getpass, poplib

M = poplib.POP3('localhost')
M.user(getpass.getuser())
M.pass_(getpass.getpass())
numMessages = len(M.list()[1])
for i in range(numMessages):
    for j in M.retr(i+1)[1]:
        print(j)

در پایان ماژول، یک بخش آزمون وجود دارد که شامل نمونه‌ای مفصل‌تر از چگونگی استفاده است.