ftplib --- کلاینت پروتکل FTP

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

این ماژول، کلاس FTP و چند آیتم مرتبط را تعریف می‌کند. کلاس FTP سمت کلاینت پروتکل FTP را پیاده‌سازی می‌کند. شما می‌توانید از آن برای نوشتن برنامه‌های پایتون استفاده کنید که انواع مختلفی از وظایف خودکار FTP را انجام می‌دهند، مانند آینه‌سازی سایر سرورهای FTP. همچنین توسط ماژول urllib.request برای مدیریت URLهایی که از FTP استفاده می‌کنند، استفاده می‌شود. برای اطلاعات بیشتر درباره FTP (پروتکل انتقال پرونده)، سند اینترنتی RFC 959 را ببینید.

کدگذاری پیش‌فرض UTF-8 است، مطابق با RFC 2640.

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

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

در اینجا یک نشست نمونه با استفاده از ماژول ftplib آمده است:

>>> from ftplib import FTP
>>> ftp = FTP('ftp.us.debian.org')  # connect to host, default port
>>> ftp.login()                     # user anonymous, passwd anonymous@
'230 Login successful.'
>>> ftp.cwd('debian')               # change into "debian" directory
'250 Directory successfully changed.'
>>> ftp.retrlines('LIST')           # list directory contents
-rw-rw-r--    1 1176     1176         1063 Jun 15 10:18 README
...
drwxr-sr-x    5 1176     1176         4096 Dec 19  2000 pool
drwxr-sr-x    4 1176     1176         4096 Nov 17  2008 project
drwxr-xr-x    3 1176     1176         4096 Oct 10  2012 tools
'226 Directory send OK.'
>>> with open('README', 'wb') as fp:
>>>     ftp.retrbinary('RETR README', fp.write)
'226 Transfer complete.'
>>> ftp.quit()
'221 Goodbye.'

مرجع

اشیای FTP

class ftplib.FTP(host='', user='', passwd='', acct='', timeout=None, source_address=None, *, encoding='utf-8')

یک نمونه جدید از کلاس FTP برمی‌گرداند.

پارامترها:

  • host (str) -- نام میزبان برای اتصال. اگر ارائه شود، connect(host) به‌طور ضمنی توسط سازنده فراخوانی می‌شود.

  • user (str) -- The username to log in with (default: 'anonymous'). در صورت ارائه، login(host, passwd, acct) به‌طور ضمنی توسط سازنده فراخوانی می‌شود.

  • passwd (str) -- The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

  • timeout (float | None) -- مهلت زمانی به ثانیه برای عملیات‌های مسدودکننده مانند connect() (پیش‌فرض: تنظیم مهلت زمانی پیش‌فرض سراسری).

  • source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

  • encoding (str) -- The encoding for directories and filenames (default: 'utf-8').

کلاس FTP از دستور with پشتیبانی می‌کند، برای مثال:

>>> from ftplib import FTP
>>> with FTP("ftp1.at.proftpd.org") as ftp:
...     ftp.login()
...     ftp.dir()
...
'230 Anonymous login ok, restrictions apply.'
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 .
dr-xr-xr-x   9 ftp      ftp           154 May  6 10:43 ..
dr-xr-xr-x   5 ftp      ftp          4096 May  6 10:43 CentOS
dr-xr-xr-x   3 ftp      ftp            18 Jul 10  2008 Fedora
>>>

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

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

تغییر یافته در نسخه‌ی 3.9: اگر پارامتر timeout روی صفر تنظیم شود، برای جلوگیری از ایجاد یک سوکت غیرمسدودکننده، ValueError پرتاب خواهد شد. پارامتر encoding افزوده شد و مقدار پیش‌فرض از Latin-1 به UTF-8 تغییر یافت تا از RFC 2640 پیروی شود.

چندین متد FTP در دو گونه در دسترس هستند: یکی برای کار با پرونده‌های متنی و دیگری برای پرونده‌های دودویی. این متدها به نام دستور مورد استفاده، به‌دنبال lines برای نسخه‌ی متنی یا binary برای نسخه‌ی دودویی نام‌گذاری شده‌اند.

نمونه‌های FTP دارای متدهای زیر هستند:

set_debuglevel(level)

سطح اشکال‌زدایی نمونه را به‌عنوان یک int تنظیم کنید. این موضوع میزان خروجی اشکال‌زدایی چاپ‌شده را کنترل می‌کند. سطوح اشکال‌زدایی عبارتند از:

  • 0 (پیش‌فرض): بدون خروجی اشکال‌زدایی.

  • 1: مقدار متوسطی از خروجی اشکال‌زدایی تولید می‌کند، معمولاً یک خط به ازای هر درخواست.

  • 2 یا بالاتر: بیشترین مقدار خروجی اشکال‌زدایی تولید می‌کند و هر خط ارسال‌شده و دریافت‌شده روی اتصال کنترل را ثبت می‌کند.

connect(host='', port=0, timeout=None, source_address=None)

به میزبان و پورت داده‌شده متصل می‌شود. این تابع باید فقط یک بار برای هر نمونه فراخوانی شود؛ اگر هنگام ایجاد نمونه FTP آرگومان host داده شده باشد، نباید فراخوانی شود. سایر متدهای FTP را تنها پس از برقراری موفق اتصال می‌توان فراخوانی کرد.

پارامترها:

  • host (str) -- میزبانی که باید به آن متصل شوید.

  • port (int) -- پورت TCP برای اتصال (پیش‌فرض: 21، همان‌طور که در مشخصات پروتکل FTP آمده است). به‌ندرت لازم است شماره پورت متفاوتی را مشخص کنید.

  • timeout (float | None) -- یک مهلت زمانی بر حسب ثانیه برای تلاش اتصال (پیش‌فرض: تنظیم مهلت پیش‌فرض سراسری).

  • source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

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

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

getwelcome()

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

login(user='anonymous', passwd='', acct='')

به سرور FTP متصل‌شده وارد شوید. این تابع باید فقط یک بار برای هر نمونه، پس از برقراری اتصال فراخوانی شود؛ اگر آرگومان‌های host و user هنگام ایجاد نمونه‌ی FTP داده شده باشند، نباید فراخوانی شود. بیشتر دستورات FTP فقط پس از ورود کلاینت مجاز هستند.

پارامترها:

  • user (str) -- The username to log in with (default: 'anonymous').

  • passwd (str) -- The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

abort()

انتقال پرونده‌ای را که در حال انجام است قطع کنید. استفاده از این همیشه کارساز نیست، اما ارزش امتحان کردن دارد.

sendcmd(cmd)

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

یک رویداد حسابرسی ftplib.sendcmd را با آرگومان‌های self و cmd پرتاب می‌کند.

voidcmd(cmd)

یک رشته‌ی فرمان ساده را به سرور ارسال کنید و پاسخ را مدیریت کنید. اگر کد پاسخ متناظر با موفقیت باشد (کدها در بازه‌ی ۲۰۰ تا ۲۹۹)، رشته‌ی پاسخ را برگردانید. در غیر این صورت error_reply را پرتاب کنید.

یک رویداد حسابرسی ftplib.sendcmd را با آرگومان‌های self و cmd پرتاب می‌کند.

retrbinary(cmd, callback, blocksize=8192, rest=None)

دریافت یک پرونده در حالت انتقال دودویی.

پارامترها:

  • cmd (str) -- یک دستور RETR مناسب: "RETR filename".

  • callback (callable) -- یک شیء فراخوانی‌پذیر با یک پارامتر که برای هر بلوک داده‌ی دریافتی فراخوانی می‌شود و تنها آرگومان آن، داده به صورت bytes است.

  • blocksize (int) -- حداکثر اندازه تکه برای خواندن از شیء socket سطح پایین که برای انجام انتقال واقعی ایجاد شده است. این مقدار همچنین متناظر با بیشترین اندازه داده‌ای است که به callback ارسال می‌شود. مقدار پیش‌فرض آن 8192 است.

  • rest (int) -- یک دستور REST برای ارسال به سرور. مستندات پارامتر rest متد transfercmd() را مشاهده کنید.

retrlines(cmd, callback=None)

یک پرونده یا فهرست پوشه را با کدگذاری مشخص‌شده توسط پارامتر encoding در زمان مقداردهی اولیه بازیابی کنید. cmd باید یک فرمان RETR مناسب باشد (به retrbinary() مراجعه کنید) یا فرمانی مانند LIST یا NLST (معمولاً فقط رشته 'LIST'). LIST فهرستی از پرونده‌ها و اطلاعات مربوط به آن پرونده‌ها را بازیابی می‌کند. NLST فهرستی از نام پرونده‌ها را بازیابی می‌کند. تابع callback برای هر خط با یک آرگومان رشته‌ای حاوی همان خط بدون CRLF پایانی فراخوانی می‌شود. callback پیش‌فرض خط را در sys.stdout چاپ می‌کند.

set_pasv(val)

اگر val درست باشد، حالت «passive» را فعال کنید، در غیر این صورت حالت passive را غیرفعال کنید. حالت passive به‌طور پیش‌فرض فعال است.

storbinary(cmd, fp, blocksize=8192, callback=None, rest=None)

یک پرونده را در حالت انتقال دودویی ذخیره کنید.

پارامترها:

  • cmd (str) -- یک فرمان STOR مناسب: "STOR filename".

  • fp (file object) -- یک شیء پرونده (بازشده در حالت دودویی) که تا EOF، با استفاده از متد read() خود و در بلوک‌هایی به اندازه‌ی blocksize خوانده می‌شود تا داده‌های موردنیاز برای ذخیره را فراهم کند.

  • blocksize (int) -- اندازه‌ی بلوک خواندن. پیش‌فرض آن 8192 است.

  • callback (callable) -- یک فراخوانی‌پذیر با یک پارامتر که برای هر بلوک داده‌ی ارسالی فراخوانی می‌شود و تنها آرگومان آن داده به‌صورت bytes است.

  • rest (int) -- یک دستور REST برای ارسال به سرور. مستندات پارامتر rest متد transfercmd() را مشاهده کنید.

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

storlines(cmd, fp, callback=None)

یک پرونده را در حالت سطری ذخیره می‌کند. cmd باید یک دستور STOR مناسب باشد (به storbinary() مراجعه کنید). سطرها تا EOF از file object fp (که در حالت دودویی باز شده است) با استفاده از متد readline() آن خوانده می‌شوند تا داده‌های موردنیاز برای ذخیره فراهم شوند. callback یک کال‌بک اختیاری با یک پارامتر است که پس از ارسال هر خط، برای آن خط فراخوانی می‌شود.

transfercmd(cmd, rest=None)

یک انتقال را بر روی اتصال داده آغاز می‌کند. اگر انتقال فعال باشد، یک فرمان EPRT یا PORT و فرمان انتقال مشخص‌شده با cmd را ارسال می‌کند و اتصال را می‌پذیرد. اگر سرور غیرفعال باشد، یک فرمان EPSV یا PASV را ارسال می‌کند، به آن متصل می‌شود و فرمان انتقال را آغاز می‌کند. در هر صورت، سوکت اتصال را برمی‌گرداند.

اگر آرگومان اختیاری rest داده شود، یک دستور REST به سرور ارسال می‌شود و rest به‌عنوان آرگومان به آن گذرانده می‌شود. rest معمولاً یک آفست بایتی در پرونده درخواستی است و به سرور می‌گوید که ارسال بایت‌های پرونده را از آفست درخواستی از سر بگیرد و بایت‌های ابتدایی را رد کند. با این حال توجه داشته باشید که متد transfercmd()، rest را با پارامتر encoding مشخص‌شده در مقداردهی اولیه به یک رشته تبدیل می‌کند، اما هیچ بررسی‌ای روی محتوای رشته انجام نمی‌شود. اگر سرور دستور REST را نشناسد، استثنای error_reply پرتاب خواهد شد. اگر این اتفاق افتاد، کافی است transfercmd() را بدون آرگومان rest فراخوانی کنید.

ntransfercmd(cmd, rest=None)

مانند transfercmd()، اما تاپلی از اتصال داده و اندازه‌ی مورد انتظار داده برمی‌گرداند. اگر اندازه‌ی مورد انتظار قابل محاسبه نباشد، None به‌عنوان اندازه‌ی مورد انتظار بازگردانده می‌شود. cmd و rest همان معنایی را دارند که در transfercmd() دارند.

mlsd(path='', facts=[])

فهرست کردن یک پوشه در قالبی استاندارد با استفاده از دستور MLSD (RFC 3659). اگر path حذف شود، پوشه فعلی فرض می‌شود. facts فهرستی از رشته‌ها است که نوع اطلاعات مورد نظر را نشان می‌دهد (مثلاً ["type", "size", "perm"]). یک شیء تولیدگر برمی‌گرداند که برای هر پرونده یافت‌شده در مسیر، یک تاپلبا دو المان تولید می‌کند. المان اول نام پرونده است، المان دوم یک دیکشنری حاوی اطلاعاتی درباره نام پرونده است. محتوای این دیکشنری ممکن است با آرگومان facts محدود شود، اما تضمینی نیست که سرور تمام اطلاعات درخواست‌شده را برگرداند.

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

nlst(argument[, ...])

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

توجه

اگر سرور شما از این فرمان پشتیبانی کند، mlsd() API بهتری ارائه می‌دهد.

dir(argument[, ...])

فهرستی از پوشه را مانند آنچه دستور LIST برمی‌گرداند تولید می‌کند و آن را در خروجی استاندارد چاپ می‌کند. آرگومان اختیاری، پوشه‌ای برای فهرست کردن است (پیش‌فرض، پوشه‌ی جاری سرور است). می‌توان از آرگومان‌های متعدد برای ارسال گزینه‌های غیراستاندارد به دستور LIST استفاده کرد. اگر آخرین آرگومان یک تابع باشد، از آن به‌عنوان تابع کال‌بک مانند retrlines() استفاده می‌شود؛ در حالت پیش‌فرض در sys.stdout چاپ می‌شود. این متد None را برمی‌گرداند.

توجه

اگر سرور شما از این فرمان پشتیبانی کند، mlsd() API بهتری ارائه می‌دهد.

rename(fromname, toname)

نام پرونده fromname را روی سرور به toname تغییر می‌دهد.

delete(filename)

پرونده‌ای به نام filename را از سرور حذف می‌کند. در صورت موفقیت، متن پاسخ را برمی‌گرداند؛ در غیر این صورت، در خطاهای دسترسی error_perm یا در سایر خطاها error_reply را پرتاب می‌کند.

cwd(pathname)

پوشه جاری را روی سرور تنظیم می‌کند.

mkd(pathname)

یک پوشه‌ی جدید روی سرور ایجاد کنید.

pwd()

مسیر پوشه‌ی فعلی روی سرور را برمی‌گرداند.

rmd(dirname)

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

size(filename)

اندازه پرونده‌ای به نام filename را از سرور درخواست می‌کند. در صورت موفقیت، اندازه پرونده به‌عنوان یک عدد صحیح برگردانده می‌شود، در غیر این صورت None برگردانده می‌شود. توجه داشته باشید که دستور SIZE استانداردسازی نشده است، اما توسط بسیاری از پیاده‌سازی‌های رایج سرور پشتیبانی می‌شود.

quit()

یک دستور QUIT به سرور بفرستید و اتصال را ببندید. این روش «مؤدبانه» برای بستن اتصال است، اما اگر سرور به دستور QUIT با خطا پاسخ دهد، ممکن است استثنایی پرتاب شود. این مستلزم فراخوانی متد close() است که نمونه FTP را برای فراخوانی‌های بعدی بی‌استفاده می‌کند (در زیر ببینید).

close()

اتصال را به‌صورت یک‌طرفه ببندید. این نباید بر اتصال از پیش بسته‌شده اعمال شود، برای نمونه پس از فراخوانی موفق quit(). پس از این فراخوانی، دیگر نباید از نمونه‌ی FTP استفاده شود (پس از فراخوانی close() یا quit() نمی‌توانید با فراخوانی دوباره‌ی متد login()، اتصال را بازگشایی کنید).

اشیای FTP_TLS

class ftplib.FTP_TLS(host='', user='', passwd='', acct='', *, context=None, timeout=None, source_address=None, encoding='utf-8')

زیرکلاسی از FTP که پشتیبانی از TLS را مطابق RFC 4217 به FTP می‌افزاید. هنگام اتصال به پورت ۲۱، اتصال کنترلی FTP را پیش از احراز هویت به‌طور ضمنی ایمن می‌کند.

توجه

کاربر باید با فراخوانی متد prot_p()، اتصال داده را به‌صراحت ایمن کند.

پارامترها:

  • host (str) -- نام میزبان برای اتصال. اگر ارائه شود، connect(host) به‌طور ضمنی توسط سازنده فراخوانی می‌شود.

  • user (str) -- The username to log in with (default: 'anonymous'). در صورت ارائه، login(host, passwd, acct) به‌طور ضمنی توسط سازنده فراخوانی می‌شود.

  • passwd (str) -- The password to use when logging in. If not given, and if passwd is the empty string or "-", a password will be automatically generated.

  • acct (str) -- Account information to be used for the ACCT FTP command. Few systems implement this. See RFC-959 for more details.

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

  • timeout (float | None) -- مهلت زمانی بر حسب ثانیه برای عملیات‌های مسدودکننده مانند connect() (پیش‌فرض: تنظیم پیش‌فرض سراسری مهلت زمانی).

  • source_address (tuple | None) -- A 2-tuple (host, port) for the socket to bind to as its source address before connecting.

  • encoding (str) -- The encoding for directories and filenames (default: 'utf-8').

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

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

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

تغییر یافته در نسخه‌ی 3.9: اگر پارامتر timeout روی صفر تنظیم شود، برای جلوگیری از ایجاد یک سوکت غیرمسدودکننده، ValueError پرتاب خواهد شد. پارامتر encoding افزوده شد و مقدار پیش‌فرض از Latin-1 به UTF-8 تغییر یافت تا از RFC 2640 پیروی شود.

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

در ادامه یک نشست نمونه با استفاده از کلاس FTP_TLS آمده است:

>>> ftps = FTP_TLS('ftp.pureftpd.org')
>>> ftps.login()
'230 Anonymous user logged in'
>>> ftps.prot_p()
'200 Data protection level set to "private"'
>>> ftps.nlst()
['6jack', 'OpenBSD', 'antilink', 'blogbench', 'bsdcam', 'clockspeed', 'djbdns-jedi', 'docs', 'eaccelerator-jedi', 'favicon.ico', 'francotone', 'fugu', 'ignore', 'libpuzzle', 'metalog', 'minidentd', 'misc', 'mysql-udf-global-user-variables', 'php-jenkins-hash', 'php-skein-hash', 'php-webdav', 'phpaudit', 'phpbench', 'pincaster', 'ping', 'posto', 'pub', 'public', 'public_keys', 'pure-ftpd', 'qscan', 'qtc', 'sharedance', 'skycache', 'sound', 'tmp', 'ucarp']

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

ssl_version

نسخه‌ی SSL برای استفاده (به‌طور پیش‌فرض ssl.PROTOCOL_SSLv23).

auth()

بسته به آنچه در ویژگی ssl_version مشخص شده است، با استفاده از TLS یا SSL یک اتصال کنترلی امن برقرار کنید.

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

ccc()

کانال کنترل را به متن آشکار بازمی‌گرداند. این می‌تواند برای بهره‌گیری از فایروال‌هایی که می‌دانند چگونه NAT را با FTP غیرامن بدون باز کردن پورت‌های ثابت مدیریت کنند، مفید باشد.

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

prot_p()

اتصال امن داده را راه‌اندازی کنید.

prot_c()

اتصال داده‌ی متن آشکار (clear text) را برقرار کنید.

متغیرهای ماژول

exception ftplib.error_reply

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

exception ftplib.error_temp

استثنایی که هنگام دریافت کد خطایی که نشان‌دهنده‌ی یک خطای موقت است (کدهای پاسخ در بازه‌ی ۴۰۰--۴۹۹) پرتاب می‌شود.

exception ftplib.error_perm

استثنایی که هنگام دریافت کد خطایی که نشان‌دهنده خطای دائمی است (کدهای پاسخ در بازه ۵۰۰--۵۹۹) پرتاب می‌شود.

exception ftplib.error_proto

استثنایی که هنگامی پرتاب می‌شود که پاسخی از سرور دریافت شود که با مشخصات پاسخ پروتکل انتقال پرونده مطابقت ندارد، یعنی با رقمی در بازه‌ی ۱--۵ آغاز نمی‌شود.

ftplib.all_errors

مجموعه‌ی تمام استثناها (به‌صورت یک تاپل ) که متدهای نمونه‌های FTP ممکن است آن‌ها را در اثر مشکلات اتصال FTP (در مقابل خطاهای برنامه‌نویسی ایجادشده توسط فراخواننده) پرتاب کنند. این مجموعه شامل چهار استثنای فهرست‌شده در بالا و همچنین OSError و EOFError است.

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

ماژول netrc

پارسری برای قالب پرونده .netrc. پرونده .netrc معمولاً توسط کلاینت‌های FTP برای بارگذاری اطلاعات احراز هویت کاربر پیش از پرسش از کاربر استفاده می‌شود.