`socket` --- رابط شبکه‌ای سطح پایین¶

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

این ماژول دسترسی به رابط سوکت BSD را فراهم می‌کند. این ماژول در تمام سیستم‌های یونیکس مدرن، ویندوز، مک‌اواس و احتمالاً پلتفرم‌های دیگر در دسترس است.

توجه

برخی رفتارها ممکن است وابسته به پلتفرم باشند، زیرا APIهای سوکت سیستم‌عامل فراخوانی می‌شوند.

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

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

رابط پایتون، بازنویسی مستقیمی از رابط فراخوانی سیستمی و کتابخانه‌ای یونیکس برای سوکت‌ها به سبک شیءگرای پایتون است: تابع socket() یک شیء سوکت <socket object> برمی‌گرداند که متدهای آن فراخوانی‌های سیستمی مختلف سوکت را پیاده‌سازی می‌کنند. انواع پارامترها تا حدودی سطح بالاتری نسبت به رابط C دارند: همان‌طور که در عملیات read() و write() بر پرونده‌های پایتون وجود دارد، تخصیص بافر در عملیات دریافت خودکار است و طول بافر در عملیات ارسال ضمنی است.

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

ماژول socketserver: کلاس‌هایی که نوشتن سرورهای شبکه را ساده‌تر می‌کنند.
ماژول ssl: پوششی TLS/SSL برای اشیای سوکت.

خانواده‌های سوکت¶

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

قالب نشانی مورد نیاز یک شیء سوکت خاص، به‌طور خودکار بر اساس خانواده نشانی مشخص‌شده در زمان ایجاد شیء سوکت انتخاب می‌شود. نشانی‌های سوکت به صورت زیر نمایش داده می‌شوند:

نشانی یک سوکت AF_UNIX که به یک گره سامانه فایل‌بندی مقید شده است، با استفاده از کدگذاری سامانه فایل‌بندی و هندلر خطای 'surrogateescape' به‌صورت یک رشته بازنمایی می‌شود (به PEP 383 مراجعه کنید). نشانی در فضای نام انتزاعی لینوکس به‌صورت یک شیء شبیه بایت با یک بایت null در ابتدا برگردانده می‌شود؛ توجه داشته باشید که سوکت‌ها در این فضای نام می‌توانند با سوکت‌های معمولی سامانه فایل‌بندی ارتباط برقرار کنند، بنابراین برنامه‌هایی که برای اجرا روی لینوکس در نظر گرفته شده‌اند، ممکن است نیاز داشته باشند با هر دو نوع نشانی سروکار داشته باشند. هنگامی که نشانی را به‌عنوان آرگومان ارسال می‌کنید، می‌توانید برای هر یک از دو نوع نشانی از یک رشته یا شیء شبیه بایت (bytes-like object) استفاده کنید.

تغییر یافته در نسخه‌ی 3.3: پیش‌تر، فرض می‌شد که مسیرهای سوکت AF_UNIX از کدگذاری UTF-8 استفاده می‌کنند.

تغییر یافته در نسخه‌ی 3.5: اکنون bytes-like object قابل نوشتن پذیرفته می‌شود.

از یک جفت (host, port) برای خانواده‌ی نشانی AF_INET استفاده می‌شود، که در آن host رشته‌ای است که یا یک نام میزبان با نمادگذاری دامنه‌ی اینترنتی مانند 'daring.cwi.nl' یا یک نشانی IPv4 مانند '100.50.200.5' را نشان می‌دهد، و port یک عدد صحیح است.
- برای آدرس‌های IPv4، به جای آدرس میزبان، دو شکل خاص پذیرفته می‌شوند: '' نشان‌دهنده INADDR_ANY است که برای مقیدسازی به همه رابط‌ها استفاده می‌شود، و رشته '<broadcast>' نشان‌دهنده INADDR_BROADCAST است. این رفتار با IPv6 ناسازگار است، بنابراین، اگر قصد دارید در برنامه‌های پایتون خود از IPv6 پشتیبانی کنید، ممکن است بخواهید از این موارد اجتناب کنید.
برای خانواده‌ی آدرس AF_INET6، از یک چهارتایی (host, port, flowinfo, scope_id) استفاده می‌شود، که در آن flowinfo و scope_id نشان‌دهنده‌ی اعضای sin6_flowinfo و sin6_scope_id در struct sockaddr_in6 در C هستند. برای متدهای ماژول socket، می‌توان flowinfo و scope_id را فقط برای سازگاری با نسخه‌های پیشین حذف کرد. با این حال توجه داشته باشید که حذف scope_id می‌تواند در کار با آدرس‌های IPv6 محدوده‌دار مشکل‌ساز شود.

تغییر یافته در نسخه‌ی 3.7: برای آدرس‌های چندپخشی (multicast)، که در آن‌ها scope_id معنادار است، لازم نیست address شامل بخش %scope_id (یا zone id) باشد. این اطلاعات اضافی است و می‌توان با اطمینان آن را حذف کرد (توصیه می‌شود).
سوکت‌های AF_NETLINK به‌صورت جفت‌های (pid, groups) نمایش داده می‌شوند.
پشتیبانی از TIPC فقط در لینوکس، با استفاده از خانواده‌ی نشانی AF_TIPC در دسترس است. TIPC یک پروتکل شبکه‌ای باز و غیرمبتنی بر IP است که برای استفاده در محیط‌های رایانه‌ای خوشه‌ای طراحی شده است. نشانی‌ها به‌صورت یک تاپل نمایش داده می‌شوند و فیلدها به نوع نشانی بستگی دارند. قالب کلی تاپل به‌صورت (addr_type, v1, v2, v3 [, scope]) است، که در آن:
- addr_type یکی از TIPC_ADDR_NAMESEQ، TIPC_ADDR_NAME یا TIPC_ADDR_ID است.
- scope یکی از TIPC_ZONE_SCOPE، TIPC_CLUSTER_SCOPE و TIPC_NODE_SCOPE است.
- اگر addr_type برابر TIPC_ADDR_NAME باشد، آنگاه v1 نوع سرور است، v2 شناسه درگاه است و v3 باید ۰ باشد.
  
  اگر addr_type برابر با TIPC_ADDR_NAMESEQ باشد، آنگاه v1 نوع سرور، v2 شماره پورت پایینی و v3 شماره پورت بالایی است.
  
  اگر addr_type برابر TIPC_ADDR_ID باشد، آنگاه v1 گره است، v2 مرجع است و v3 باید روی ۰ تنظیم شود.
از یک تاپل (interface, ) برای خانواده آدرس AF_CAN استفاده می‌شود، که در آن interface رشته‌ای است که نام یک رابط شبکه مانند 'can0' را نشان می‌دهد. می‌توان از نام رابط شبکه '' برای دریافت بسته‌ها از تمام رابط‌های شبکه این خانواده استفاده کرد.
- پروتکل CAN_ISOTP به یک تاپلبه صورت (interface, rx_addr, tx_addr) نیاز دارد، که در آن هر دو پارامتر اضافی، عدد صحیح بلند بدون علامت هستند و یک شناسه CAN (استاندارد یا گسترده) را نشان می‌دهند.
- پروتکل CAN_J1939 به یک تاپل (interface, name, pgn, addr) نیاز دارد، که پارامترهای اضافی آن عبارت‌اند از یک عدد صحیح بدون علامت ۶۴ بیتی نشان‌دهنده‌ی نام ECU، یک عدد صحیح بدون علامت ۳۲ بیتی نشان‌دهنده‌ی شماره گروه پارامتر (PGN)، و یک عدد صحیح ۸ بیتی نشان‌دهنده‌ی آدرس.
برای پروتکل SYSPROTO_CONTROL از خانواده‌ی PF_SYSTEM، از یک رشته یا تاپل (id, unit) استفاده می‌شود. رشته نام یک کنترل هسته است که از یک شناسه‌ی اختصاص‌داده‌شده به‌صورت پویا استفاده می‌کند. اگر شناسه و شماره‌ی واحدِ کنترل هسته مشخص باشند یا از یک شناسه‌ی ثبت‌شده استفاده شود، می‌توان از تاپل استفاده کرد.

اضافه شده در نسخه‌ی 3.3.
AF_BLUETOOTH از پروتکل‌ها و قالب‌های نشانی زیر پشتیبانی می‌کند:
- BTPROTO_L2CAP یک تاپلبا قالب (bdaddr, psm[, cid[, bdaddr_type]]) را می‌پذیرد که در آن:
  - bdaddr یک رشته است که نشانی بلوتوث را مشخص می‌کند.
  - psm یک عدد صحیح است که تسهیم‌کننده پروتکل/سرویس (Protocol/Service Multiplexer) را مشخص می‌کند.
  - cid یک عدد صحیح اختیاری است که شناسه کانال (Channel Identifier) را مشخص می‌کند. اگر داده نشود، مقدار پیش‌فرض آن صفر است.
  - bdaddr_type یک عدد صحیح اختیاری است که نوع نشانی را مشخص می‌کند؛ یکی از BDADDR_BREDR (پیش‌فرض)، BDADDR_LE_PUBLIC، BDADDR_LE_RANDOM.
  تغییر یافته در نسخه‌ی 3.14: فیلدهای cid و bdaddr_type افزوده شدند.
- BTPROTO_RFCOMM مقدار (bdaddr, channel) را می‌پذیرد، که در آن bdaddr نشانی بلوتوث به‌صورت یک رشته و channel یک عدد صحیح است.
- BTPROTO_HCI قالبی را می‌پذیرد که به سیستم‌عامل شما بستگی دارد.
  - در لینوکس، یک عدد صحیح device_id یا یک تاپل (device_id, [channel]) پذیرفته می‌شود، که در آن device_id شماره‌ی دستگاه بلوتوث را مشخص می‌کند و channel یک عدد صحیح اختیاری است که کانال HCI را مشخص می‌کند (HCI_CHANNEL_RAW به‌طور پیش‌فرض).
  - در FreeBSD، NetBSD و DragonFly BSD، bdaddr را می‌پذیرد، که bdaddr نشانی بلوتوث به‌صورت یک رشته است.
  تغییر یافته در نسخه‌ی 3.2: پشتیبانی از NetBSD و DragonFlyBSD اضافه شد.
  
  تغییر یافته در نسخه‌ی 3.13.3: پشتیبانی از FreeBSD افزوده شد.
  
  تغییر یافته در نسخه‌ی 3.14: فیلد channel افزوده شد. device_id که در یک تاپل قرار نگرفته باشد، اکنون پذیرفته می‌شود.
- BTPROTO_SCO bdaddr را می‌پذیرد، که در آن bdaddr آدرس بلوتوث به‌صورت یک رشته یا یک شیء bytes است. (برای مثال '12:23:34:45:56:67' یا b'12:23:34:45:56:67')
  
  تغییر یافته در نسخه‌ی 3.14: پشتیبانی از FreeBSD افزوده شد.
AF_ALG یک رابط مبتنی بر سوکت و فقط مخصوص لینوکس برای رمزنگاری هسته است. یک سوکت الگوریتم با یک تاپل شامل دو تا چهار المان (type, name [, feat [, mask]]) پیکربندی می‌شود، که در آن:
- type نوع الگوریتم به‌صورت رشته است، مثلاً aead، hash، skcipher یا rng.
- name نام الگوریتم و حالت عملکرد به‌صورت رشته است، برای مثال sha256، hmac(sha256)، cbc(aes) یا drbg_nopr_ctr_aes256.
- feat و mask اعداد صحیح ۳۲ بیتی بدون علامت هستند.
دسترس‌پذیری: Linux >= 2.6.38.

برخی از انواع الگوریتم به هسته‌های جدیدتر نیاز دارند.

اضافه شده در نسخه‌ی 3.6.
AF_VSOCK امکان ارتباط بین ماشین‌های مجازی و میزبان‌هایشان را فراهم می‌کند. سوکت‌ها به‌صورت یک تاپل (CID, port) نمایش داده می‌شوند که در آن شناسه زمینه یا CID و پورت، اعداد صحیح هستند.

دسترس‌پذیری: Linux >= 3.9

vsock(7) را ببینید

اضافه شده در نسخه‌ی 3.7.
AF_PACKET یک رابط سطح پایین برای دسترسی مستقیم به دستگاه‌های شبکه است. نشانی‌ها به‌صورت تاپل (ifname, proto[, pkttype[, hatype[, addr]]]) نمایش داده می‌شوند که در آن:
- ifname - رشته‌ای که نام دستگاه را مشخص می‌کند.
- proto - شماره‌ی پروتکل اترنت. می‌تواند ETH_P_ALL برای ضبط تمام پروتکل‌ها، یکی از ثابت‌های ETHERTYPE_* یا هر شماره‌ی پروتکل اترنت دیگری باشد.
- pkttype - عدد صحیح اختیاری برای مشخص کردن نوع بسته:
  - PACKET_HOST (پیش‌فرض) - بسته‌ای که مقصد آن میزبان محلی است.
  - PACKET_BROADCAST - بسته‌ی پخش در لایه‌ی فیزیکی.
  - PACKET_MULTICAST - بسته‌ی ارسالی به یک نشانی چندپخشی در لایه‌ی فیزیکی.
  - PACKET_OTHERHOST - بسته‌ای برای میزبان دیگری که توسط یک راه‌انداز دستگاه در حالت promiscuous گرفته شده است.
  - PACKET_OUTGOING - بسته‌ای که از میزبان محلی سرچشمه می‌گیرد و به یک سوکت بسته (packet socket) حلقه می‌شود.
- hatype - عدد صحیح اختیاری برای مشخص کردن نوع نشانی سخت‌افزاری ARP.
- addr - شیء اختیاری ماننده بایت (bytes-like object) که آدرس فیزیکی سخت‌افزار را مشخص می‌کند و تفسیر آن به دستگاه بستگی دارد.
دسترس‌پذیری: Linux >= 2.2.
AF_QIPCRTR یک رابط مبتنی بر سوکت، فقط مخصوص لینوکس، برای ارتباط با سرویس‌هایی است که روی پردازنده‌های کمکی در پلتفرم‌های Qualcomm اجرا می‌شوند. این خانواده آدرس به‌صورت یک تاپل (node, port) نمایش داده می‌شود که در آن node و port اعداد صحیح نامنفی هستند.

دسترس‌پذیری: Linux >= 4.7.

اضافه شده در نسخه‌ی 3.8.
IPPROTO_UDPLITE گونه‌ای از UDP است که به شما اجازه می‌دهد مشخص کنید چه بخشی از یک بسته تحت پوشش جمع‌آزما (checksum) قرار می‌گیرد. این پروتکل دو گزینه‌ی سوکت اضافه می‌کند که می‌توانید آن‌ها را تغییر دهید. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) میزان پوشش جمع‌آزما برای بسته‌های خروجی را تغییر می‌دهد و self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) بسته‌هایی را که بخش خیلی کمی از داده‌هایشان تحت پوشش جمع‌آزما قرار می‌گیرد فیلتر می‌کند. در هر دو حالت length باید در range(8, 2**16, 8) باشد.

چنین سوکتی باید برای IPv4 با socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) یا برای IPv6 با socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) ایجاد شود.

دسترس‌پذیری: Linux >= 2.6.20, FreeBSD >= 10.1

اضافه شده در نسخه‌ی 3.9.
AF_HYPERV یک رابط مختص ویندوز و مبتنی بر سوکت برای ارتباط با میزبان‌ها و مهمان‌های Hyper-V است. خانواده آدرس به‌صورت یک تاپل به شکل (vm_id, service_id) نمایش داده می‌شود که در آن vm_id و service_id رشته‌های UUID هستند.

vm_id شناسه‌ی ماشین مجازی یا، اگر هدف یک ماشین مجازی مشخص نباشد، مجموعه‌ای از مقادیر VMID شناخته‌شده است. ثابت‌های VMID شناخته‌شده که در socket تعریف شده‌اند، عبارتند از:
- HV_GUID_ZERO
- HV_GUID_BROADCAST
- HV_GUID_WILDCARD - برای مقید کردن به خودش و پذیرش اتصال‌ها از همه پارتیشن‌ها استفاده می‌شود.
- HV_GUID_CHILDREN - برای مقیدسازی روی خودش و پذیرفتن اتصال از پارتیشن‌های فرزند استفاده می‌شود.
- HV_GUID_LOOPBACK - به‌عنوان هدفی برای خودش استفاده می‌شود.
- HV_GUID_PARENT - وقتی به‌عنوان مقید کردن استفاده شود، اتصال از پارتیشن والد را می‌پذیرد. وقتی به‌عنوان نشانی هدف استفاده شود، به پارتیشن والد متصل می‌شود.
service_id شناسه‌ی سرویس ثبت‌شده است.

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

اگر در بخش host نشانی سوکت IPv4/v6 از یک نام میزبان استفاده کنید، ممکن است برنامه رفتاری غیرقطعی نشان دهد، زیرا پایتون از اولین نشانی بازگشتی از حل DNS استفاده می‌کند. نشانی سوکت بسته به نتایج حل DNS و/یا پیکربندی میزبان، به‌شکل متفاوتی به یک نشانی IPv4/v6 واقعی حل می‌شود. برای رفتار قطعی، از یک نشانی عددی در بخش host استفاده کنید.

همه‌ی خطاها استثنا پرتاب می‌کنند. استثناهای معمول برای انواع نامعتبر آرگومان و شرایط کمبود حافظه ممکن است پرتاب شوند. خطاهای مربوط به معنای سوکت یا آدرس، OSError یا یکی از زیرکلاس‌های آن را پرتاب می‌کنند.

حالت غیرمسدود از طریق setblocking() پشتیبانی می‌شود. تعمیمی از این حالت بر اساس مهلت‌های زمانی از طریق settimeout() پشتیبانی می‌شود.

محتویات ماژول¶

ماژول socket عناصر زیر را اکسپورت می‌کند.

استثناها¶

exception socket.error¶: نام مستعار منسوخی از OSError.

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

exception socket.herror¶: این استثنا که زیرکلاسی از OSError است، برای خطاهای مرتبط با نشانی پرتاب می‌شود، یعنی برای توابعی که از h_errno در API C POSIX استفاده می‌کنند، از جمله gethostbyname_ex() و gethostbyaddr(). مقدار همراه، یک جفت (h_errno, string) است که نشان‌دهنده‌ی خطایی است که توسط یک فراخوانی کتابخانه برگردانده شده است. h_errno یک مقدار عددی است، در حالی که string بیانگر توضیح h_errno است، همان‌طور که توسط تابع C hstrerror() برگردانده می‌شود.

تغییر یافته در نسخه‌ی 3.3: این کلاس به زیرکلاسی از OSError تبدیل شد.

exception socket.gaierror¶: این استثنا زیرکلاسی از OSError است و برای خطاهای مرتبط با نشانی توسط getaddrinfo() و getnameinfo() پرتاب می‌شود. مقدار همراه آن یک جفت (error, string) است که نشان‌دهنده‌ی خطایی است که از یک فراخوانی کتابخانه برگردانده شده است. string شرح error را نشان می‌دهد، همان‌طور که توسط تابع C gai_strerror() برگردانده شده است. مقدار عددی error با یکی از ثابت‌های EAI_* تعریف‌شده در این ماژول مطابقت خواهد داشت.

تغییر یافته در نسخه‌ی 3.3: این کلاس به زیرکلاسی از OSError تبدیل شد.

exception socket.timeout¶

یک نام مستعار منسوخ برای TimeoutError.

این استثنا زیرکلاسی از OSError است و زمانی پرتاب می‌شود که یک مهلت زمانی در سوکتی رخ دهد که مهلت زمانی برای آن از طریق فراخوانی پیشین settimeout() (یا به‌طور ضمنی از طریق setdefaulttimeout()) فعال شده است. مقدار همراه، رشته‌ای است که مقدار آن در حال حاضر همیشه "timed out" است.

تغییر یافته در نسخه‌ی 3.3: این کلاس به زیرکلاسی از OSError تبدیل شد.

تغییر یافته در نسخه‌ی 3.10: این کلاس به‌عنوان نام مستعاری از TimeoutError درآمده است.

ثابت‌ها¶

ثابت‌های AF_* و SOCK_* اکنون مجموعه‌های AddressFamily و SocketKind از نوع IntEnum هستند.

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

socket.AF_UNIX¶
socket.AF_INET¶
socket.AF_INET6¶: این ثابت‌ها نشان‌دهنده‌ی خانواده‌های آدرس (و پروتکل) هستند و برای اولین آرگومان socket() استفاده می‌شوند. اگر ثابت AF_UNIX تعریف نشده باشد، این پروتکل پشتیبانی نمی‌شود. بسته به سیستم، ممکن است ثابت‌های بیشتری در دسترس باشند.

socket.AF_UNSPEC¶: AF_UNSPEC به این معنا است که getaddrinfo() باید آدرس‌های سوکت را برای هر خانواده آدرسی (IPv4، IPv6 یا هر خانواده دیگری) که قابل استفاده باشد، برگرداند.

socket.SOCK_STREAM¶
socket.SOCK_DGRAM¶
socket.SOCK_RAW¶
socket.SOCK_RDM¶
socket.SOCK_SEQPACKET¶: این ثابت‌ها انواع سوکت را نشان می‌دهند و برای آرگومان دوم socket() استفاده می‌شوند. بسته به سامانه، ممکن است ثابت‌های بیشتری در دسترس باشند. (به نظر می‌رسد تنها SOCK_STREAM و SOCK_DGRAM به‌طور کلی مفید هستند.)

socket.SOCK_CLOEXEC¶
socket.SOCK_NONBLOCK¶: این دو ثابت، در صورت تعریف‌شدن، می‌توانند با انواع سوکت ترکیب شوند و به شما اجازه می‌دهند برخی پرچم‌ها را به‌صورت اتمی تنظیم کنید (بنابراین از شرایط رقابتی احتمالی و نیاز به فراخوانی‌های جداگانه جلوگیری می‌شود).

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

برای توضیح کامل‌تر، Secure File Descriptor Handling.

دسترس‌پذیری: Linux >= 2.6.27.

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

SO_*
socket.SOMAXCONN¶
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*: بسیاری از ثابت‌های این قالب‌ها، که در مستندات یونیکس در مورد سوکت‌ها و/یا پروتکل IP مستند شده‌اند، در ماژول socket نیز تعریف شده‌اند. آن‌ها عموماً به‌عنوان آرگومان‌هایی برای متدهای setsockopt() و getsockopt() اشیای سوکت استفاده می‌شوند. در بیشتر موارد، تنها نمادهایی تعریف شده‌اند که در پرونده‌های سرآیند یونیکس تعریف شده باشند؛ برای تعداد کمی از نمادها، مقادیر پیش‌فرض ارائه شده‌اند.

تغییر یافته در نسخه‌ی 3.6: SO_DOMAIN، SO_PROTOCOL، SO_PEERSEC، SO_PASSSEC، TCP_USER_TIMEOUT و TCP_CONGESTION افزوده شدند.

تغییر یافته در نسخه‌ی 3.6.5: پشتیبانی از TCP_FASTOPEN و TCP_KEEPCNT در پلتفرم‌های ویندوزی در صورت موجود بودن افزوده شد.

تغییر یافته در نسخه‌ی 3.7: TCP_NOTSENT_LOWAT اضافه شد.

پشتیبانی از TCP_KEEPIDLE و TCP_KEEPINTVL در سکوهای ویندوزی، در صورت در دسترس بودن، افزوده شد.

تغییر یافته در نسخه‌ی 3.10: IP_RECVTOS افزوده شد. TCP_KEEPALIVE افزوده شد. در MacOS، این ثابت را می‌توان به همان شیوه‌ای که TCP_KEEPIDLE در لینوکس استفاده می‌شود، به کار برد.

تغییر یافته در نسخه‌ی 3.11: TCP_CONNECTION_INFO افزوده شد. در MacOS می‌توان از این ثابت به همان شیوه‌ای که از TCP_INFO در لینوکس و BSD استفاده می‌شود، استفاده کرد.

تغییر یافته در نسخه‌ی 3.12: SO_RTABLE و SO_USER_COOKIE افزوده شدند. در OpenBSD و FreeBSD به‌ترتیب می‌توان از این ثابت‌ها به همان شیوه‌ای استفاده کرد که SO_MARK در لینوکس استفاده می‌شود. همچنین گزینه‌های سوکت TCP لینوکس که وجود نداشتند افزوده شدند: TCP_MD5SIG، TCP_THIN_LINEAR_TIMEOUTS، TCP_THIN_DUPACK، TCP_REPAIR، TCP_REPAIR_QUEUE، TCP_QUEUE_SEQ، TCP_REPAIR_OPTIONS، TCP_TIMESTAMP، TCP_CC_INFO، TCP_SAVE_SYN، TCP_SAVED_SYN، TCP_REPAIR_WINDOW، TCP_FASTOPEN_CONNECT، TCP_ULP، TCP_MD5SIG_EXT، TCP_FASTOPEN_KEY، TCP_FASTOPEN_NO_COOKIE، TCP_ZEROCOPY_RECEIVE، TCP_INQ، TCP_TX_DELAY. IP_PKTINFO، IP_UNBLOCK_SOURCE، IP_BLOCK_SOURCE، IP_ADD_SOURCE_MEMBERSHIP، IP_DROP_SOURCE_MEMBERSHIP افزوده شدند.

تغییر یافته در نسخه‌ی 3.13: SO_BINDTOIFINDEX افزوده شد. در لینوکس، می‌توان از این ثابت به همان شیوه‌ای که از SO_BINDTODEVICE استفاده می‌شود، اما با اندیس یک رابط شبکه به جای نام آن استفاده کرد.

تغییر یافته در نسخه‌ی 3.14: IP_FREEBIND، IP_RECVERR، IPV6_RECVERR، IP_RECVTTL و IP_RECVORIGDSTADDR که در لینوکس وجود نداشتند، اضافه شدند.

تغییر یافته در نسخه‌ی 3.14: پشتیبانی از TCP_QUICKACK در سکوهای ویندوزی در صورت در دسترس بودن افزوده شد.

socket.AF_CAN¶
socket.PF_CAN¶
SOL_CAN_*
CAN_*: بسیاری از ثابت‌های این قالب‌ها، که در مستندات لینوکس مستند شده‌اند، در ماژول socket نیز تعریف شده‌اند.

دسترس‌پذیری: Linux >= 2.6.25, NetBSD >= 8.

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

تغییر یافته در نسخه‌ی 3.11: پشتیبانی از NetBSD اضافه شد.

تغییر یافته در نسخه‌ی 3.14: CAN_RAW_ERR_FILTER ازقلم‌افتاده در لینوکس بازگردانده شد.

socket.CAN_BCM¶
CAN_BCM_*: CAN_BCM، در خانواده پروتکل CAN، پروتکل مدیر پخش (BCM) است. ثابت‌های مدیر پخش، که در مستندات لینوکس توضیح داده شده‌اند، نیز در ماژول socket تعریف شده‌اند.

دسترس‌پذیری: Linux >= 2.6.25.

توجه

پرچم CAN_BCM_CAN_FD_FRAME فقط در لینوکس 4.8 به بالا در دسترس است.

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

socket.CAN_RAW_FD_FRAMES¶

پشتیبانی از CAN FD را در یک سوکت CAN_RAW فعال می‌کند. این قابلیت به‌طور پیش‌فرض غیرفعال است. این قابلیت به برنامه شما اجازه می‌دهد هر دو فریم CAN و CAN FD را ارسال کند؛ با این حال، هنگام خواندن از سوکت باید هر دو فریم CAN و CAN FD را بپذیرید.

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

دسترس‌پذیری: Linux >= 3.6.

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

socket.CAN_RAW_JOIN_FILTERS¶

فیلترهای CAN اعمال‌شده را به‌گونه‌ای ترکیب می‌کند که تنها فریم‌های CAN مطابق با همه فیلترهای CAN داده‌شده، به فضای کاربر (user space) منتقل شوند.

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

دسترس‌پذیری: Linux >= 4.1.

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

socket.CAN_ISOTP¶: CAN_ISOTP، در خانواده‌ی پروتکل CAN، پروتکل ISO-TP (ISO 15765-2) است. ثابت‌های ISO-TP، مستندشده در مستندات لینوکس.

دسترس‌پذیری: Linux >= 2.6.25.

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

socket.CAN_J1939¶: CAN_J1939، در خانواده‌ی پروتکل CAN، پروتکل SAE J1939 است. ثابت‌های J1939، مستندشده در مستندات لینوکس.

دسترس‌پذیری: Linux >= 5.4.

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

socket.AF_DIVERT¶
socket.PF_DIVERT¶: این دو ثابت، که در صفحه‌ی راهنمای FreeBSD divert(4) مستند شده‌اند، در ماژول socket نیز تعریف شده‌اند.

دسترس‌پذیری: FreeBSD >= 14.0.

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

socket.AF_PACKET¶
socket.PF_PACKET¶
PACKET_*: بسیاری از ثابت‌های این قالب‌ها، که در مستندات لینوکس مستند شده‌اند، در ماژول socket نیز تعریف شده‌اند.

دسترس‌پذیری: Linux >= 2.2.

socket.ETH_P_ALL¶

می‌توانید از ETH_P_ALL در سازنده‌ی socket به‌عنوان proto برای خانواده‌ی AF_PACKET استفاده کنید تا هر بسته را، صرف‌نظر از پروتکل، ضبط کنید.

برای اطلاعات بیشتر، صفحه راهنمای packet(7) را ببینید.

دسترس‌پذیری: Linux.

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

socket.AF_RDS¶
socket.PF_RDS¶
socket.SOL_RDS¶
RDS_*: بسیاری از ثابت‌های این قالب‌ها، که در مستندات لینوکس مستند شده‌اند، در ماژول socket نیز تعریف شده‌اند.

دسترس‌پذیری: Linux >= 2.6.30.

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

socket.SIO_RCVALL¶
socket.SIO_KEEPALIVE_VALS¶
socket.SIO_LOOPBACK_FAST_PATH¶
RCVALL_*: ثابت‌های مربوط به WSAIoctl() ویندوز. این ثابت‌ها به‌عنوان آرگومان‌هایی برای متد ioctl() اشیای سوکت استفاده می‌شوند.

تغییر یافته در نسخه‌ی 3.6: SIO_LOOPBACK_FAST_PATH افزوده شد.

TIPC_*: ثابت‌های مرتبط با TIPC، مطابق با آن‌هایی که توسط API سوکت C اکسپورت شده‌اند. برای اطلاعات بیشتر، مستندات TIPC را ببینید.

socket.AF_ALG¶
socket.SOL_ALG¶
ALG_*: ثابت‌های رمزنگاری هسته لینوکس.

دسترس‌پذیری: Linux >= 2.6.38.

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

socket.AF_VSOCK¶
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID¶
VMADDR*
SO_VM*: ثابت‌های ارتباط میزبان/مهمان در لینوکس.

دسترس‌پذیری: Linux >= 4.8.

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

socket.AF_LINK¶: دسترس‌پذیری: BSD, macOS.

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

socket.has_ipv6¶: این ثابت حاوی یک مقدار بولی است که نشان می‌دهد آیا IPv6 در این پلتفرم پشتیبانی می‌شود.

socket.AF_BLUETOOTH¶
socket.BTPROTO_L2CAP¶
socket.BTPROTO_RFCOMM¶
socket.BTPROTO_HCI¶
socket.BTPROTO_SCO¶: ثابت‌های عدد صحیح برای استفاده با آدرس‌های بلوتوث.

socket.BDADDR_ANY¶
socket.BDADDR_LOCAL¶: این‌ها ثابت‌های رشته‌ای حاوی آدرس‌های بلوتوث با معانی ویژه هستند. برای مثال، می‌توان از BDADDR_ANY برای نشان دادن هر آدرسی هنگام مشخص کردن سوکت مقیدسازی با BTPROTO_RFCOMM استفاده کرد.

socket.BDADDR_BREDR¶
socket.BDADDR_LE_PUBLIC¶
socket.BDADDR_LE_RANDOM¶: این ثابت‌ها نوع نشانی بلوتوث را هنگام پیوند دادن یا اتصال دادن یک سوکت BTPROTO_L2CAP توصیف می‌کنند.

دسترس‌پذیری: Linux, FreeBSD

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

socket.SOL_RFCOMM¶

socket.SOL_L2CAP¶

socket.SOL_HCI¶

socket.SOL_SCO¶

socket.SOL_BLUETOOTH¶

در آرگومان level متدهای setsockopt() و getsockopt() اشیای سوکت بلوتوث استفاده می‌شود.

SOL_BLUETOOTH تنها در لینوکس در دسترس است. ثابت‌های دیگر در صورتی در دسترس هستند که پروتکل متناظر پشتیبانی شود.

SO_L2CAP_*

socket.L2CAP_LM¶

L2CAP_LM_*

SO_RFCOMM_*

RFCOMM_LM_*

SO_SCO_*

SO_BTH_*

BT_*

در آرگومان‌های نام گزینه و مقدار برای متدهای setsockopt() و getsockopt() اشیاء سوکت بلوتوث استفاده می‌شود.

BT_* و L2CAP_LM تنها در لینوکس در دسترس هستند. SO_BTH_* تنها در ویندوز در دسترس هستند. سایر ثابت‌ها ممکن است در لینوکس و پلتفرم‌های مختلف BSD در دسترس باشند.

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

socket.HCI_FILTER¶
socket.HCI_TIME_STAMP¶
socket.HCI_DATA_DIR¶
socket.SO_HCI_EVT_FILTER¶
socket.SO_HCI_PKT_FILTER¶: نام گزینه‌ها برای استفاده با BTPROTO_HCI. دسترس‌پذیری و قالب مقادیر گزینه‌ها به پلتفرم بستگی دارد.

تغییر یافته در نسخه‌ی 3.14: SO_HCI_EVT_FILTER و SO_HCI_PKT_FILTER در NetBSD و DragonFly BSD افزوده شدند. HCI_DATA_DIR در FreeBSD، NetBSD و DragonFly BSD افزوده شد.

socket.HCI_DEV_NONE¶: مقدار device_id استفاده‌شده برای ایجاد یک سوکت HCI که به یک آداپتور بلوتوث واحد اختصاص ندارد.

دسترس‌پذیری: Linux

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

socket.HCI_CHANNEL_RAW¶
socket.HCI_CHANNEL_USER¶
socket.HCI_CHANNEL_MONITOR¶
socket.HCI_CHANNEL_CONTROL¶
socket.HCI_CHANNEL_LOGGING¶: مقادیر ممکن برای فیلد channel در نشانی BTPROTO_HCI.

دسترس‌پذیری: Linux

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

socket.AF_QIPCRTR¶: ثابت برای پروتکل مسیریاب IPC شرکت Qualcomm، که برای ارتباط با پردازنده‌های راه دور ارائه‌دهنده سرویس استفاده می‌شود.

دسترس‌پذیری: Linux >= 4.7.

socket.SCM_CREDS2¶
socket.LOCAL_CREDS¶
socket.LOCAL_CREDS_PERSISTENT¶: LOCAL_CREDS و LOCAL_CREDS_PERSISTENT را می‌توان با سوکت‌های SOCK_DGRAM و SOCK_STREAM استفاده کرد؛ این دو معادل SO_PASSCRED در Linux/DragonFlyBSD هستند. در حالی که LOCAL_CREDS مشخصات اعتباری را در نخستین خوانش ارسال می‌کند، LOCAL_CREDS_PERSISTENT مشخصات اعتباری را برای هر خوانش ارسال می‌کند؛ بنابراین برای دومی باید از SCM_CREDS2 به‌عنوان نوع پیام استفاده شود.

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

دسترس‌پذیری: FreeBSD.

socket.SO_INCOMING_CPU¶: ثابتی برای بهینه‌سازی محلی بودن پردازنده، که باید همراه با SO_REUSEPORT استفاده شود.

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

دسترس‌پذیری: Linux >= 3.9

socket.SO_REUSEPORT_LB¶: ثابت برای فعال‌سازی اتصال‌های تکراری نشانی و پورت با موازنه بار.

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

دسترس‌پذیری: FreeBSD >= 12.0

socket.AF_HYPERV¶
socket.HV_PROTOCOL_RAW¶
socket.HVSOCKET_CONNECT_TIMEOUT¶
socket.HVSOCKET_CONNECT_TIMEOUT_MAX¶
socket.HVSOCKET_CONNECTED_SUSPEND¶
socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU¶
socket.HV_GUID_ZERO¶
socket.HV_GUID_WILDCARD¶
socket.HV_GUID_BROADCAST¶
socket.HV_GUID_CHILDREN¶
socket.HV_GUID_LOOPBACK¶
socket.HV_GUID_PARENT¶: ثابت‌های سوکت‌های Hyper-V ویندوز برای ارتباطات میزبان/مهمان.

دسترس‌پذیری: Windows.

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

socket.ETHERTYPE_ARP¶
socket.ETHERTYPE_IP¶
socket.ETHERTYPE_IPV6¶
socket.ETHERTYPE_VLAN¶: شماره پروتکل IEEE 802.3. ثابت‌ها.

دسترس‌پذیری: Linux, FreeBSD, macOS.

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

socket.SHUT_RD¶
socket.SHUT_WR¶
socket.SHUT_RDWR¶: این ثابت‌ها توسط متد shutdown() اشیای سوکت استفاده می‌شوند.

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

توابع¶

ایجاد سوکت‌ها¶

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

سازنده‌ی کلاس socket مستقیماً یک سوکت جدید ایجاد می‌کند؛ برای پارامترها و توضیح کامل آن، اشیای سوکت را ببینید.

socket.socketpair([family[, type[, proto]]])¶

با استفاده از خانواده آدرس، نوع سوکت و شماره پروتکل داده‌شده، یک جفت شیء سوکت متصل به هم بسازید. خانواده آدرس، نوع سوکت و شماره پروتکل همانند تابع socket() هستند. خانواده پیش‌فرض AF_UNIX است، اگر روی سکو تعریف‌شده باشد؛ در غیر این صورت، پیش‌فرض AF_INET است.

سوکت‌های به‌تازگی ایجادشده غیرقابل ارث‌بری هستند.

تغییر یافته در نسخه‌ی 3.2: اشیای سوکت برگردانده‌شده اکنون به جای یک زیرمجموعه، از کل API سوکت پشتیبانی می‌کنند.

تغییر یافته در نسخه‌ی 3.4: سوکت‌های برگردانده‌شده اکنون غیرقابل ارث‌بری هستند.

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

socket.create_connection(address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)¶

به یک سرویس TCP که به نشانی اینترنتی (یک دوتایی (2-tuple) به شکل (host, port)) گوش می‌دهد متصل می‌شود و شیء سوکت را برمی‌گرداند. این تابع سطح بالاتری نسبت به socket.connect() است: اگر host یک نام میزبان غیرعددی باشد، تلاش می‌کند آن را برای هر دو AF_INET و AF_INET6 حل کند و سپس تلاش می‌کند به‌ترتیب به تمام نشانی‌های ممکن متصل شود تا اتصالی با موفقیت برقرار شود. این کار نوشتن کلاینت‌هایی را که با هر دو IPv4 و IPv6 سازگار باشند، آسان می‌کند.

با ارسال پارامتر اختیاری timeout، مهلت روی نمونه سوکت پیش از تلاش برای اتصال تنظیم می‌شود. اگر timeout ارائه نشود، از تنظیم مهلت پیش‌فرض سراسری که توسط getdefaulttimeout() برگردانده می‌شود، استفاده خواهد شد.

اگر ارائه شود، source_address باید یک تاپل دوتایی (2-tuple) به‌صورت (host, port) باشد تا سوکت پیش از اتصال، آن را به‌عنوان نشانی مبدأ خود مقید کند . اگر host یا port به‌ترتیب '' یا 0 باشند، رفتار پیش‌فرض سیستم‌عامل استفاده خواهد شد.

هنگامی که ایجاد یک اتصال ممکن نباشد، یک استثنا پرتاب می‌شود. به‌طور پیش‌فرض، این استثنا مربوط به آخرین نشانی در فهرست است. اگر all_errors برابر True باشد، یک ExceptionGroup حاوی خطاهای تمام تلاش‌ها خواهد بود.

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

تغییر یافته در نسخه‌ی 3.11: all_errors افزوده شد.

socket.create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)¶

تابع سهولت‌بخشی که یک سوکت TCP مقید به address (یک ۲-تایی (host, port)) را ایجاد می‌کند و شیء سوکت را برمی‌گرداند.

family باید یکی از AF_INET یا AF_INET6 باشد. backlog اندازه صفی است که به socket.listen() داده می‌شود؛ اگر مشخص نشده باشد، یک مقدار پیش‌فرض مناسب انتخاب می‌شود. reuse_port تعیین می‌کند که آیا گزینه سوکت SO_REUSEPORT تنظیم شود یا خیر.

اگر dualstack_ipv6 درست باشد، family برابر با AF_INET6 باشد و سکو از آن پشتیبانی کند، سوکت می‌تواند هر دو اتصال IPv4 و IPv6 را بپذیرد؛ در غیر این صورت، استثنای ValueError پرتاب می‌شود. انتظار می‌رود بیشتر سکوهای POSIX و ویندوز از این قابلیت پشتیبانی کنند. هنگامی که این قابلیت فعال باشد، آدرس برگردانده‌شده توسط socket.getpeername() در صورت وقوع یک اتصال IPv4، یک آدرس IPv6 خواهد بود که به‌صورت آدرس IPv6 نگاشت‌شده به IPv4 (IPv4-mapped IPv6 address) نمایش داده می‌شود. اگر dualstack_ipv6 نادرست باشد، این قابلیت در سکوهای که آن را به‌طور پیش‌فرض فعال می‌کنند (مانند لینوکس) به‌صراحت غیرفعال می‌شود. این پارامتر می‌تواند همراه با has_dualstack_ipv6() استفاده شود:

import socket

addr = ("", 8080)  # all interfaces, port 8080
if socket.has_dualstack_ipv6():
    s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
    s = socket.create_server(addr)

توجه

در پلتفرم‌های POSIX، گزینه‌ی سوکت SO_REUSEADDR تنظیم می‌شود تا امکان استفاده‌ی فوری از سوکت‌های پیشینی که به همان آدرس پیوند داده شده‌اند و در وضعیت TIME_WAIT باقی مانده‌اند، فراهم شود.

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

socket.has_dualstack_ipv6()¶: اگر سکو از ایجاد یک سوکت TCP که بتواند هر دو اتصال IPv4 و IPv6 را مدیریت کند پشتیبانی کند، True را برمی‌گرداند.

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

socket.fromfd(fd, family, type, proto=0)¶

توصیف‌گر پرونده fd (یک عدد صحیح که توسط متد fileno() یک شیء پرونده برگردانده می‌شود) تکثیر می‌شود و از نتیجه، یک شیء سوکت ساخته می‌شود. خانواده آدرس، نوع سوکت و شماره پروتکل همانند تابع socket() هستند. توصیف‌گر پرونده باید به یک سوکت ارجاع دهد، اما این موضوع بررسی نمی‌شود --- عملیات‌های بعدی روی شیء ممکن است در صورت نامعتبر بودن توصیف‌گر پرونده با شکست مواجه شوند. این تابع به‌ندرت مورد نیاز است، اما می‌توان از آن برای دریافت یا تنظیم گزینه‌های سوکت روی سوکتی که به‌عنوان ورودی یا خروجی استاندارد به برنامه داده شده است استفاده کرد (مانند سروری که توسط دیمن inet در یونیکس راه‌اندازی شده است). فرض می‌شود سوکت در حالت مسدودکننده قرار دارد.

سوکت تازه‌ایجادشده غیرقابل ارث‌بری است.

تغییر یافته در نسخه‌ی 3.4: سوکت برگردانده‌شده اکنون غیرقابل ارث‌بردن است.

socket.fromshare(data)¶: نمونه‌سازی یک سوکت از داده‌های به‌دست‌آمده از متد socket.share(). فرض می‌شود که سوکت در حالت مسدودکننده باشد.

دسترس‌پذیری: Windows.

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

توابع دیگر¶

ماژول socket همچنین خدمات مختلف مرتبط با شبکه را ارائه می‌دهد:

socket.close(fd)¶: بستن توصیف‌گر پرونده سوکت. این مانند os.close() است، اما برای سوکت‌ها. در برخی سکوها (به‌ویژه ویندوز) os.close() برای توصیف‌گرهای پرونده سوکت کار نمی‌کند.

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

socket.getaddrinfo(host, port, family=AF_UNSPEC, type=0, proto=0, flags=0)¶

این تابع، پوششی برای تابع getaddrinfo زبان C در سیستم زیرین است.

آرگومان host/port را به دنباله‌ای از تاپل‌های ۵تایی تبدیل می‌کند که شامل همه آرگومان‌های لازم برای ایجاد سوکتی متصل به آن سرویس است. host یک نام دامنه، نمایش رشته‌ای از یک آدرس IPv4/v6 یا None است. port یک نام سرویس رشته‌ای مانند 'http'، یک شماره پورت عددی یا None است. با ارسال None به‌عنوان مقدار host و port، می‌توانید NULL را به API زیربنایی C ارسال کنید.

آرگومان‌های family، type و proto را می‌توان به‌صورت اختیاری مشخص کرد تا گزینه‌ها فراهم شوند و فهرست نشانی‌های بازگردانده‌شده محدود شود. برای اینکه نتایج محدود نشوند، مقادیر پیش‌فرض آن‌ها (به‌ترتیب AF_UNSPEC، 0 و 0) را ارسال کنید. برای جزئیات، یادداشت زیر را ببینید.

آرگومان flags می‌تواند یک یا چند مورد از ثابت‌های AI_* باشد و بر چگونگی محاسبه و برگرداندن نتایج تأثیر می‌گذارد. برای مثال، AI_NUMERICHOST حل نام دامنه را غیرفعال می‌کند و اگر host یک نام دامنه باشد، خطایی پرتاب می‌کند.

این تابع فهرستی از ۵-تاپل‌ها با ساختار زیر برمی‌گرداند:

(family, type, proto, canonname, sockaddr)

در این تاپل‌ها، family، type و proto همگی اعداد صحیح هستند و باید به تابع socket() فرستاده شوند. اگر AI_CANONNAME بخشی از آرگومان flags باشد، canonname رشته‌ای خواهد بود که نام متعارف host را نشان می‌دهد؛ در غیر این صورت canonname خالی خواهد بود. sockaddr تاپلی است که نشانی سوکت را توصیف می‌کند و قالب آن به family برگردانده‌شده بستگی دارد (یک تاپل ۲تایی (address, port) برای AF_INET، یک تاپل ۴تایی (address, port, flowinfo, scope_id) برای AF_INET6) و باید به متد socket.connect() فرستاده شود.

توجه

اگر قصد دارید از نتایج getaddrinfo() برای ایجاد یک سوکت استفاده کنید (نه مثلاً برای بازیابی canonname)، در نظر بگیرید که نتایج را بر اساس type (مثلاً SOCK_STREAM یا SOCK_DGRAM) و/یا proto (مثلاً IPPROTO_TCP یا IPPROTO_UDP) که برنامه شما می‌تواند از آن‌ها پشتیبانی کند، محدود کنید.

رفتار با مقادیر پیش‌فرض family، type، proto و flags وابسته به سیستم است.

بسیاری از سیستم‌ها (برای مثال، بیشتر پیکربندی‌های لینوکس) فهرست مرتب‌شده‌ای از همه‌ی نشانی‌های منطبق برمی‌گردانند. این نشانی‌ها معمولاً باید به‌ترتیب امتحان شوند تا اتصال با موفقیت برقرار شود (ممکن است به‌صورت موازی نیز امتحان شوند، برای مثال با استفاده از یک الگوریتم Happy Eyeballs). در این موارد، محدود کردن type و/یا proto می‌تواند به حذف تلاش‌های اتصال بی‌نتیجه یا غیرقابل‌استفاده کمک کند.

با این حال، برخی سیستم‌ها تنها یک نشانی را برمی‌گردانند. (برای مثال، این مورد در پیکربندی‌های Solaris و AIX گزارش شده است.) در این سیستم‌ها، محدود کردن type و/یا proto کمک می‌کند اطمینان حاصل شود که این نشانی قابل استفاده باشد.

یک رویداد حسابرسی socket.getaddrinfo را با آرگومان‌های host، port، family، type و protocol پرتاب می‌کند.

مثال زیر اطلاعات نشانی را برای یک اتصال TCP فرضی به example.org در پورت ۸۰ واکشی می‌کند (اگر IPv6 فعال نباشد، ممکن است نتایج در سیستم شما متفاوت باشند):

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(socket.AF_INET6, socket.SOCK_STREAM,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (socket.AF_INET, socket.SOCK_STREAM,
 6, '', ('93.184.216.34', 80))]

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

تغییر یافته در نسخه‌ی 3.7: برای نشانی‌های چندپخشی (multicast) در IPv6، رشته‌ی نشان‌دهنده‌ی یک نشانی حاوی بخش %scope_id نخواهد بود.

socket.getfqdn([name])¶: یک نام دامنه کامل (fully qualified domain name) برای name برمی‌گرداند. اگر name حذف‌شده یا خالی باشد، به‌عنوان میزبان محلی در نظر گرفته می‌شود. برای یافتن نام کامل، نام میزبان برگردانده‌شده توسط gethostbyaddr() بررسی می‌شود و سپس نام‌های مستعار میزبان، در صورت موجود بودن، بررسی می‌شوند. اولین نامی که شامل یک نقطه باشد انتخاب می‌شود. در صورتی که هیچ نام دامنه کاملی در دسترس نباشد و name ارائه شده باشد، بدون تغییر برگردانده می‌شود. اگر name خالی یا برابر با '0.0.0.0' باشد، نام میزبان حاصل از gethostname() برگردانده می‌شود.

socket.gethostbyname(hostname)¶

نام میزبان را به قالب نشانی IPv4 ترجمه می‌کند. نشانی IPv4 به‌صورت یک رشته برگردانده می‌شود، مانند '100.50.200.5'. اگر نام میزبان خودش یک نشانی IPv4 باشد، بدون تغییر برگردانده می‌شود. برای یک رابط کامل‌تر gethostbyname_ex() را ببینید. gethostbyname() از حل نام IPv6 پشتیبانی نمی‌کند، و برای پشتیبانی از پشته دوگانه IPv4/v6 باید به‌جای آن از getaddrinfo() استفاده شود.

یک رویداد حسابرسی socket.gethostbyname را با آرگومان hostname پرتاب می‌کند.

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

socket.gethostbyname_ex(hostname)¶

یک نام میزبان را به قالب نشانی IPv4 ترجمه می‌کند؛ رابط گسترش‌یافته. یک ۳‌تایی (hostname, aliaslist, ipaddrlist) برمی‌گرداند که در آن hostname نام میزبان اصلی آن میزبان است، aliaslist فهرستی (احتمالاً خالی) از نام‌های میزبان جایگزین برای همان نشانی است، و ipaddrlist فهرستی از نشانی‌های IPv4 برای همان رابط در همان میزبان است (اغلب، اما نه همیشه، یک نشانی واحد). gethostbyname_ex() از حل نام IPv6 پشتیبانی نمی‌کند، و برای پشتیبانی از پشته دوگانه‌ی IPv4/v6 باید به‌جای آن از getaddrinfo() استفاده شود.

یک رویداد حسابرسی socket.gethostbyname را با آرگومان hostname پرتاب می‌کند.

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

socket.gethostname()¶

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

یک رویداد حسابرسی socket.gethostname را بدون هیچ آرگومانی پرتاب می‌کند.

توجه: gethostname() همیشه نام دامنه‌ی کاملاً مشخص (fully qualified domain name) را برنمی‌گرداند؛ برای این کار از getfqdn() استفاده کنید.

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

socket.gethostbyaddr(ip_address)¶

یک تاپل ۳-تایی (hostname, aliaslist, ipaddrlist) برمی‌گرداند که در آن hostname نام میزبان اصلی پاسخ‌دهنده به ip_address داده‌شده است، aliaslist فهرستی (احتمالاً خالی) از نام‌های میزبان جایگزین برای همان نشانی است، و ipaddrlist فهرستی از نشانی‌های IPv4/v6 برای همان رابط در همان میزبان است (که به احتمال زیاد فقط شامل یک نشانی می‌شود). برای یافتن نام دامنه‌ی کامل، از تابع getfqdn() استفاده کنید. gethostbyaddr() از هر دو IPv4 و IPv6 پشتیبانی می‌کند.

یک رویداد حسابرسی socket.gethostbyaddr را با آرگومان ip_address پرتاب می‌کند.

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

socket.getnameinfo(sockaddr, flags)¶

نشانی سوکت sockaddr را به یک تاپل دوتایی (host, port) تبدیل می‌کند. بسته به تنظیمات flags، نتیجه می‌تواند شامل یک نام دامنه‌ی کامل یا نمایش عددی نشانی در host باشد. به‌طور مشابه، port می‌تواند شامل یک نام پورت به‌صورت رشته یا یک شماره پورت عددی باشد.

برای آدرس‌های IPv6، اگر sockaddr شامل scope_id معناداری باشد، %scope_id به بخش میزبان افزوده می‌شود. معمولاً این حالت برای آدرس‌های چندپخشی (multicast) رخ می‌دهد.

برای اطلاعات بیشتر درباره‌ی flags می‌توانید به getnameinfo(3) مراجعه کنید.

یک رویداد حسابرسی socket.getnameinfo را با آرگومان sockaddr پرتاب می‌کند.

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

socket.getprotobyname(protocolname)¶: نام پروتکل اینترنتی (برای مثال، 'icmp') را به ثابتی تبدیل می‌کند که برای ارسال به‌عنوان آرگومان سوم (اختیاری) به تابع socket() مناسب است. این معمولاً فقط برای سوکت‌هایی که در حالت خام (raw) باز شده‌اند (SOCK_RAW) لازم است؛ برای حالت‌های عادی سوکت، اگر پروتکل ذکر نشود یا صفر باشد، پروتکل صحیح به‌طور خودکار انتخاب می‌شود.

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

socket.getservbyname(servicename[, protocolname])¶

نام یک سرویس اینترنتی و نام پروتکل را به شماره پورت آن سرویس ترجمه می‌کند. نام پروتکل اختیاری، در صورت ارائه، باید 'tcp' یا 'udp' باشد، در غیر این صورت هر پروتکلی مطابقت خواهد داشت.

یک رویداد حسابرسی socket.getservbyname را با آرگومان‌های servicename و protocolname پرتاب می‌کند.

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

socket.getservbyport(port[, protocolname])¶

شماره پورت اینترنتی و نام پروتکل را به نام سرویس برای آن سرویس ترجمه می‌کند. نام پروتکل اختیاری، در صورت ارائه، باید 'tcp' یا 'udp' باشد، در غیر این صورت هر پروتکلی مطابقت خواهد داشت.

یک رویداد حسابرسی socket.getservbyport را با آرگومان‌های port و protocolname پرتاب می‌کند.

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

socket.ntohl(x)¶: تبدیل اعداد صحیح مثبت ۳۲ بیتی از ترتیب بایت‌های شبکه به ترتیب بایت‌های میزبان. در ماشین‌هایی که ترتیب بایت‌های میزبان همان ترتیب بایت‌های شبکه است،این یک عملیات بی‌اثر (no-op) است؛ در غیر این صورت، یک عملیات جابه‌جایی ۴ بایتی انجام می‌شود.

socket.ntohs(x)¶: اعداد صحیح مثبت ۱۶ بیتی را از ترتیب بایت شبکه به ترتیب بایت میزبان تبدیل می‌کند. در ماشین‌هایی که ترتیب بایت میزبان همان ترتیب بایت شبکه است، این عملیات بی‌اثر (no-op) است؛ در غیر این صورت، یک عملیات جابه‌جایی ۲ بایتی انجام می‌دهد.

تغییر یافته در نسخه‌ی 3.10: اگر x در یک عدد صحیح بدون علامت ۱۶‌بیتی نگنجد، OverflowError را پرتاب می‌کند.

socket.htonl(x)¶: اعداد صحیح مثبت ۳۲ بیتی را از ترتیب بایت میزبان به ترتیب بایت شبکه تبدیل می‌کند. در ماشین‌هایی که ترتیب بایت میزبان با ترتیب بایت شبکه یکسان است، اینیک عملیات بی‌اثر (no-op) است؛ در غیر این صورت، یک عملیات جابجایی ۴ بایتی را انجام می‌دهد.

socket.htons(x)¶: اعداد صحیح مثبت ۱۶‌بیتی را از ترتیب بایت میزبان به ترتیب بایت شبکه تبدیل می‌کند. در ماشین‌هایی که ترتیب بایت میزبان همان ترتیب بایت شبکه است، این یک عملیات بدون اثر (no-op) است؛ در غیر این صورت، یک عملیات جابه‌جایی ۲‌بایتی انجام می‌دهد.

تغییر یافته در نسخه‌ی 3.10: اگر x در یک عدد صحیح بدون علامت ۱۶‌بیتی نگنجد، OverflowError را پرتاب می‌کند.

socket.inet_aton(ip_string)¶

نشانی IPv4 را از قالب رشته‌ای چهاربخشی نقطه‌دار (برای مثال، '123.45.67.89') به قالب دودویی فشرده‌ی ۳۲ بیتی تبدیل می‌کند، به‌صورت یک شیء bytes به طول ۴ نویسه. این کار هنگام ارتباط با برنامه‌ای که از کتابخانه‌ی استاندارد C استفاده می‌کند و به اشیایی از نوع in_addr، نوع C برای داده‌ی دودویی فشرده‌ی ۳۲ بیتی که این تابع برمی‌گرداند، نیاز دارد، مفید است.

inet_aton() همچنین رشته‌هایی با کمتر از ۳ نقطه را می‌پذیرد؛ برای جزئیات، صفحه راهنمای یونیکس inet(3) را ببینید.

اگر رشته‌ی نشانی IPv4 داده‌شده به این تابع نامعتبر باشد، OSError پرتاب خواهد شد. توجه داشته باشید که دقیقاً این‌که چه چیزی معتبر است، به پیاده‌سازی C زیرینِ inet_aton() بستگی دارد.

inet_aton() از IPv6 پشتیبانی نمی‌کند و برای پشتیبانی از پشته‌ی دوگانه IPv4/v6 باید به‌جای آن از inet_pton() استفاده شود.

socket.inet_ntoa(packed_ip)¶

یک نشانی IPv4 بسته‌بندی‌شده‌ی ۳۲ بیتی (یک شیء شبه‌بایت به طول ۴ بایت) را به نمایش رشته‌ای استاندارد به‌صورت چهارتایی نقطه‌دار (برای مثال، '123.45.67.89') تبدیل می‌کند. این کار هنگام ارتباط با برنامه‌ای که از کتابخانه‌ی استاندارد C استفاده می‌کند و به اشیایی از نوع in_addr نیاز دارد، مفید است. این، نوع C برای داده‌ی دودویی بسته‌بندی‌شده‌ی ۳۲ بیتی است که این تابع آن را به‌عنوان آرگومان دریافت می‌کند.

اگر طول دنباله بایت داده‌شده به این تابع دقیقاً ۴ بایت نباشد، OSError پرتاب خواهد شد. inet_ntoa() از IPv6 پشتیبانی نمی‌کند و برای پشتیبانی از پشته دوگانه IPv4/v6 باید به‌جای آن از inet_ntop() استفاده شود.

تغییر یافته در نسخه‌ی 3.5: اکنون bytes-like object قابل نوشتن پذیرفته می‌شود.

socket.inet_pton(address_family, ip_string)¶

یک نشانی IP را از قالب رشته‌ای مختص خانواده‌اش به قالب دودویی فشرده تبدیل می‌کند. inet_pton() زمانی مفید است که یک کتابخانه یا پروتکل شبکه به یک شیء از نوع in_addr (مشابه inet_aton()) یا in6_addr نیاز داشته باشد.

مقادیر پشتیبانی‌شده برای address_family در حال حاضر AF_INET و AF_INET6 هستند. اگر رشته‌ی نشانی IP ip_string نامعتبر باشد، OSError پرتاب می‌شود. توجه داشته باشید که دقیقاً آنچه معتبر است، هم به مقدار address_family و هم به پیاده‌سازی زیربنایی inet_pton() بستگی دارد.

دسترس‌پذیری: Unix, Windows.

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

socket.inet_ntop(address_family, packed_ip)¶

یک نشانی IP فشرده (یک شیء شبه‌بایت با تعدادی بایت) را به نمایش رشته‌ای استاندارد و مختص خانواده‌ی آن (برای مثال، '7.10.0.5' یا '5aef:2b::8') تبدیل می‌کند. inet_ntop() هنگامی مفید است که یک کتابخانه یا پروتکل شبکه شیءای از نوع in_addr (مشابه inet_ntoa()) یا in6_addr برمی‌گرداند.

مقادیر پشتیبانی‌شده برای address_family در حال حاضر AF_INET و AF_INET6 هستند. اگر طول شیء bytes packed_ip برای خانواده‌ی نشانی مشخص‌شده صحیح نباشد، ValueError پرتاب خواهد شد. OSError برای خطاهای ناشی از فراخوانی inet_ntop() پرتاب می‌شود.

دسترس‌پذیری: Unix, Windows.

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

تغییر یافته در نسخه‌ی 3.5: اکنون bytes-like object قابل نوشتن پذیرفته می‌شود.

socket.CMSG_LEN(length)¶: طول کل یک آیتم داده‌ی جانبی با داده‌ی مرتبط به طول length داده‌شده را، بدون پرکننده‌ی انتهایی (padding)، برمی‌گرداند. این مقدار اغلب می‌تواند به‌عنوان اندازه‌ی بافربرای دریافت یک آیتم داده‌ی جانبی از طریق recvmsg() استفاده شود، اما RFC 3542 برنامه‌های قابل‌حمل را ملزم می‌کند که از CMSG_SPACE() استفاده کنند و بنابراین فضایی برای پرکننده (padding) در نظر بگیرند، حتی وقتی آیتم آخرین آیتم در بافر باشد. اگر length خارج از محدوده‌ی مجاز مقادیر باشد، OverflowError پرتاب می‌شود.

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

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

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

socket.CMSG_SPACE(length)¶

اندازه‌ی بافر موردنیاز برای recvmsg() را برمی‌گرداند تا یک آیتم داده‌ی جانبی با داده‌ی مرتبط به طول length داده‌شده، به‌همراه هرگونه پرکننده‌ی انتهایی (padding) دریافت شود. فضای بافر موردنیاز برای دریافت چند آیتم، مجموع مقادیر CMSG_SPACE() برای طول‌های داده‌ی مرتبط آن‌ها است. اگر length خارج از محدوده‌ی مجاز مقادیر باشد، OverflowError پرتاب می‌شود.

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

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

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

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

socket.getdefaulttimeout()¶: بازگرداندن مهلت پیش‌فرض بر حسب ثانیه (float) برای اشیاء سوکت جدید. مقدار None نشان می‌دهد که اشیاء سوکت جدید بدون مهلت هستند. هنگامی که ماژول socket برای نخستین بار ایمپورت می‌شود، مقدار پیش‌فرض None است.

socket.setdefaulttimeout(timeout)¶: مهلت پیش‌فرض را بر حسب ثانیه (float) برای اشیای جدید سوکت تنظیم کنید. هنگامی که ماژول socket برای اولین بار ایمپورت می‌شود، مقدار پیش‌فرض None است. برای مقادیر ممکن و معانی مربوط به آن‌ها settimeout() را ببینید.

socket.sethostname(name)¶

نام میزبان ماشین را روی name تنظیم می‌کند. اگر دسترسی کافی نداشته باشید، این کار یک OSError را پرتاب می‌کند.

یک رویداد حسابرسی socket.sethostname را با آرگومان name پرتاب می‌کند.

دسترس‌پذیری: Unix, not Android.

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

socket.if_nameindex()¶

فهرستی از تاپل‌های اطلاعات رابط شبکه (index int، name string) را برمی‌گرداند. در صورت شکست فراخوانی سیستمی، OSError.

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

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

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

توجه

در ویندوز، رابط‌های شبکه نام‌های متفاوتی در زمینه‌های مختلف دارند (همه‌ی نام‌ها مثال هستند):

UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}
نام: ethernet_32770
نام دوستانه: vEthernet (nat)
توضیح: Hyper-V Virtual Ethernet Adapter

این تابع نام‌های صورت دوم را از فهرست برمی‌گرداند؛ در این مثال، ethernet_32770 برگردانده می‌شود.

socket.if_nametoindex(if_name)¶: شماره‌ی اندیس رابط شبکه متناظر با نام رابط را برمی‌گرداند. اگر رابطی با نام داده‌شده وجود نداشته باشد، OSError پرتاب می‌شود.

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

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

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

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

«نام رابط» یک نام است، همان‌طور که در if_nameindex() مستند شده است.

socket.if_indextoname(if_index)¶: نام رابط شبکه متناظر با شماره اندیس رابط را برمی‌گرداند. اگر رابطی با اندیس داده‌شده وجود نداشته باشد، OSError رخ می‌دهد.

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

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

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

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

«نام رابط» یک نام است، همان‌طور که در if_nameindex() مستند شده است.

socket.send_fds(sock, buffers, fds[, flags[, address]])¶: فهرست توصیف‌گرهای پرونده fds را از طریق یک سوکت AF_UNIX با نام sock ارسال کنید. پارامتر fds یک دنباله از توصیف‌گرهای پرونده است. برای مستندات این پارامترها به sendmsg() مراجعه کنید.

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

سکوهای یونیکسی که از sendmsg() و سازوکار SCM_RIGHTS پشتیبانی می‌کنند.

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

socket.recv_fds(sock, bufsize, maxfds[, flags])¶: حداکثر maxfds توصیف‌گر پرونده را از یک سوکت AF_UNIX به نام sock دریافت می‌کند. مقدار (msg, list(fds), flags, addr) را برمی‌گرداند. برای مستندات این پارامترها به recvmsg() مراجعه کنید.

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

سکوهای یونیکسی که از recvmsg() و سازوکار SCM_RIGHTS پشتیبانی می‌کنند.

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

توجه

هرگونه عدد صحیح بریده‌شده در انتهای فهرست توصیف‌گرهای پرونده.

اشیای سوکت¶

class socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)¶

با استفاده از خانواده آدرس، نوع سوکت و شماره پروتکل داده‌شده، یک سوکت جدید ایجاد کنید. خانواده آدرس باید AF_INET (پیش‌فرض)، AF_INET6، AF_UNIX، AF_CAN، AF_PACKET یا AF_RDS باشد. نوع سوکت باید SOCK_STREAM (پیش‌فرض)، SOCK_DGRAM، SOCK_RAW یا شاید یکی از سایر ثابت‌های SOCK_ باشد. شماره پروتکل معمولاً صفر است و می‌تواند حذف شود، یا در صورتی که خانواده آدرس AF_CAN باشد، پروتکل باید یکی از CAN_RAW، CAN_BCM، CAN_ISOTP یا CAN_J1939 باشد.

If fileno is specified, the values for family, type, and proto are auto-detected from the specified file descriptor. Auto-detection can be overruled by calling the function with explicit family, type, or proto arguments. This only affects how Python represents e.g. the return value of socket.getpeername() but not the actual OS resource. Unlike socket.fromfd(), fileno will return the same socket and not a duplicate. This may help close a detached socket using close().

سوکت تازه‌ایجادشده غیرقابل ارث‌بری است.

یک رویداد حسابرسی socket.__new__ را با آرگومان‌های self، family، type، protocol پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.3: خانواده AF_CAN افزوده شد. خانواده AF_RDS افزوده شد.

تغییر یافته در نسخه‌ی 3.4: پروتکل CAN_BCM افزوده شد.

تغییر یافته در نسخه‌ی 3.4: سوکت برگردانده‌شده اکنون غیرقابل ارث‌بردن است.

تغییر یافته در نسخه‌ی 3.7: پروتکل CAN_ISOTP افزوده شد.

تغییر یافته در نسخه‌ی 3.7: هنگامی که پرچم‌های بیتی SOCK_NONBLOCK یا SOCK_CLOEXEC به type اعمال شوند، این پرچم‌ها پاک می‌شوند و socket.type آن‌ها را بازتاب نخواهد داد. آن‌ها همچنان به فراخوانی سیستمی زیربنایی socket() ارسال می‌شوند. بنابراین،

sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

همچنان در سیستم‌عامل‌هایی که از SOCK_NONBLOCK پشتیبانی می‌کنند، یک سوکت غیرمسدودکننده ایجاد خواهد کرد، اما sock.type روی socket.SOCK_STREAM تنظیم خواهد شد.

تغییر یافته در نسخه‌ی 3.9: پروتکل CAN_J1939 افزوده شد.

تغییر یافته در نسخه‌ی 3.10: پروتکل IPPROTO_MPTCP افزوده شد.

اشیای سوکت متدهای زیر را دارند. به‌جز makefile()، این متدها معادل فراخوانی‌های سیستمی یونیکس هستند که برای سوکت‌ها کاربرد دارند.

تغییر یافته در نسخه‌ی 3.2: Support for the context manager protocol was added. Exiting the context manager is equivalent to calling close().

accept()¶

پذیرش یک اتصال. سوکت باید به یک آدرس مقید شده و در حال گوش‌دادن به اتصال‌ها باشد. مقدار بازگشتی یک جفت (conn, address) است که در آن conn یک شیء سوکت جدید است که می‌توان از آن برای ارسال و دریافت داده روی اتصال استفاده کرد، و address آدرسی است که به سوکت در سمت دیگر اتصال مقید شده است.

سوکت تازه‌ایجادشده غیرقابل ارث‌بری است.

تغییر یافته در نسخه‌ی 3.4: سوکت اکنون غیرقابل ارث‌بری است.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

bind(address)¶

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

یک رویداد حسابرسی socket.bind را با آرگومان‌های self و address پرتاب می‌کند.

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

close()¶

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

سوکت‌ها هنگامی که زباله‌روبی می‌شوند، به‌طور خودکار بسته می‌شوند، اما توصیه می‌شود آن‌ها را به‌صراحت با close() ببندید، یا از یک دستور with در اطراف آن‌ها استفاده کنید.

تغییر یافته در نسخه‌ی 3.6: OSError اکنون در صورتی پرتاب می‌شود که خطایی هنگام فراخوانی زیربنایی close() رخ دهد.

توجه

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

connect(address)¶

به یک سوکتدوردست در address متصل شوید. قالب address به خانواده‌ی نشانی (address family) وابسته است — خانواده‌های سوکت را ببینید.

اگر یک سیگنال اتصال را قطع کند، در صورتی که هندلر سیگنال استثنایی پرتاب نکند و سوکت مسدودکننده یا دارای مهلت زمانی باشد، متد تا کامل شدن اتصال صبر می‌کند یا در صورت مهلت زمانی، TimeoutError پرتاب می‌کند. برای سوکت‌های غیرمسدودکننده، اگر یک سیگنال اتصال را قطع کند، متد استثنای InterruptedError (یا استثنای پرتاب‌شده توسط هندلر سیگنال) را پرتاب می‌کند.

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

تغییر یافته در نسخه‌ی 3.5: این متد اکنون به‌جای پرتاب استثنای InterruptedError، تا تکمیل شدن اتصال منتظر می‌ماند؛ مشروط بر اینکه اتصال با یک سیگنال قطع شده باشد، هندلر سیگنال استثنایی پرتاب نکند و سوکت مسدودکننده باشد یا مهلت زمانی داشته باشد (برای علت آن PEP 475 را ببینید).

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

connect_ex(address)¶

مانند connect(address) است، اما به جای پرتاب استثنا برای خطاهای برگردانده‌شده از فراخوانی connect() در سطح C، یک نشانگر خطا برمی‌گرداند (مشکلات دیگر، مانند «میزبان یافت نشد»، همچنان می‌توانند استثنا پرتاب کنند). اگر عملیات موفق باشد، نشانگر خطا 0 است، در غیر این صورت مقدار متغیر errno است. این برای پشتیبانی از اتصال‌های ناهمگام، برای مثال، مفید است.

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

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

detach()¶: شیء سوکت را در وضعیت بسته قرار می‌دهد، بدون آنکه توصیف‌گر پرونده زیرین را واقعاً ببندد. توصیف‌گر پرونده بازگردانده می‌شود و می‌تواند برای اهداف دیگر دوباره استفاده شود.

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

dup()¶

سوکت را تکثیر کنید.

سوکت تازه‌ایجادشده غیرقابل ارث‌بری است.

تغییر یافته در نسخه‌ی 3.4: سوکت اکنون غیرقابل ارث‌بری است.

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

fileno()¶

توصیف‌گر پرونده سوکت (یک عدد صحیح کوچک) را برمی‌گرداند، یا در صورت شکست -1 را. این همراه با select.select() مفید است.

در ویندوز، عدد صحیح کوچکی که این متد بازمی‌گرداند نمی‌تواند در مواردی که یک توصیف‌گر پرونده قابل استفاده است (مانند os.fdopen()) به کار رود. یونیکس این محدودیت را ندارد.

get_inheritable()¶: پرچم ارث‌پذیری توصیف‌گر پرونده سوکت یا دسته‌ی سوکت را دریافت کنید: اگر سوکت بتواند در فرآیندهای فرزند به ارث برده شود، True و اگر نتواند، False.

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

getpeername()¶: نشانی راه دوری را که سوکت به آن متصل است برمی‌گرداند. برای مثال، این موضوع برای پیدا کردن شماره‌ی پورت یک سوکت راه دور IPv4/v6 مفید است. قالب نشانی برگردانده‌شده به خانواده‌ی نشانی بستگی دارد --- خانواده‌های سوکت را ببینید. در برخی سیستم‌ها این تابع پشتیبانی نمی‌شود.

getsockname()¶: نشانی خود سوکت را برمی‌گرداند. این کار برای مثال برای یافتن شماره پورت یک سوکت IPv4/v6 مفید است. قالب نشانی برگردانده‌شده به خانواده نشانی بستگی دارد --- خانواده‌های سوکت را ببینید.

getsockopt(level, optname[, buflen])¶: مقدار گزینه‌ی سوکت داده‌شده را برمی‌گرداند (به صفحه‌ی man یونیکس getsockopt(2) مراجعه کنید). ثابت‌های نمادین مورد نیاز (SO_* etc.) در این ماژول تعریف شده‌اند. اگر buflen وجود نداشته باشد، یک گزینه از نوع عدد صحیح فرض می‌شود و مقدار عدد صحیح آن توسط تابع بازگردانده می‌شود. اگر buflen وجود داشته باشد، حداکثر طول بافری را که برای دریافت گزینه استفاده می‌شود، مشخص می‌کند و این بافر به‌عنوان یک شیء bytes بازگردانده می‌شود. کدگشایی محتویات بافر بر عهده‌ی فراخواننده است (برای آشنایی با روشی برای کدگشایی ساختارهای C کدگذاری‌شده به‌صورت رشته‌های بایتی، ماژول توکار اختیاری struct را ببینید).

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

getblocking()¶

اگر سوکت در حالت مسدودکننده باشد، True و اگر در حالت غیرمسدودکننده باشد، False بازمی‌گرداند.

این معادل بررسی socket.gettimeout() != 0 است.

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

gettimeout()¶: مهلت زمانی مرتبط با عملیات سوکت را به ثانیه (float) برمی‌گرداند، یا در صورتی که هیچ مهلت زمانی‌ای تنظیم‌نشده باشد، None را برمی‌گرداند. این مقدار نشان‌دهنده‌ی آخرین فراخوانی setblocking() یا settimeout() است.

ioctl(control, option)¶

متد ioctl() رابط محدودی برای رابط سیستمی WSAIoctl است. برای اطلاعات بیشتر، به مستندات Win32 مراجعه کنید.

در سکوهای دیگر، می‌توان از توابع عام fcntl.fcntl() و fcntl.ioctl() استفاده کرد؛ آن‌ها یک شیء سوکت را به‌عنوان اولین آرگومان خود می‌پذیرند.

در حال حاضر فقط کدهای کنترلی زیر پشتیبانی می‌شوند: SIO_RCVALL، SIO_KEEPALIVE_VALS و SIO_LOOPBACK_FAST_PATH.

دسترس‌پذیری: Windows

تغییر یافته در نسخه‌ی 3.6: SIO_LOOPBACK_FAST_PATH افزوده شد.

listen([backlog])¶: یک سرور را برای پذیرش اتصال‌ها فعال می‌کند. اگر backlog مشخص شده باشد، باید حداقل ۰ باشد (اگر کمتر باشد، روی ۰ تنظیم می‌شود)؛ این مقدار تعداد اتصال‌های پذیرفته‌نشده‌ای را مشخص می‌کند که سیستم پیش از رد کردن اتصال‌های جدید مجاز می‌داند. اگر مشخص نشده باشد، یک مقدار پیش‌فرض معقول انتخاب می‌شود.

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

تغییر یافته در نسخه‌ی 3.5: پارامتر backlog اکنون اختیاری است.

makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)¶

یک file object مرتبط با سوکت را برمی‌گرداند. نوع دقیق بازگشتی به آرگومان‌های داده‌شده به makefile() بستگی دارد. این آرگومان‌ها به همان شیوه‌ای که تابع توکار open() آن‌ها را تفسیر می‌کند، تفسیر می‌شوند، با این تفاوت که تنها مقادیر پشتیبانی‌شده برای mode، 'r' (پیش‌فرض)، 'w'، 'b' یا ترکیبی از آن‌ها هستند.

سوکت باید در حالت مسدودکننده باشد؛ می‌تواند مهلت زمانی داشته باشد، اما اگر مهلت زمانی رخ دهد، بافر داخلی شیء پرونده ممکن است در وضعیت ناسازگار قرار گیرد.

Closing the file object returned by makefile() won't close the original socket unless all other file objects have been closed and close() has been called on the socket object.

توجه

در ویندوز، نمی‌توان از شیء شبه‌پرونده ایجادشده توسط makefile() در مواردی که یک شیء پرونده دارای توصیف‌گر پرونده انتظار می‌رود استفاده کرد، مانند آرگومان‌های جریان subprocess.Popen().

recv(bufsize[, flags])¶: داده‌ها را از سوکت دریافت می‌کند. مقدار بازگشتی یک شیء bytes است که داده‌های دریافت‌شده را نشان می‌دهد. حداکثر مقدار داده‌ای که یکجا دریافت می‌شود، با bufsize مشخص می‌شود. بازگشت یک شیء bytes خالی نشان می‌دهد که کلاینت قطع شده است. برای معنای آرگومان اختیاری flags، صفحه راهنمای Unix recv(2) را ببینید؛ مقدار پیش‌فرض آن صفر است.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

recvfrom(bufsize[, flags])¶: داده‌ها را از سوکت دریافت می‌کند. مقدار بازگشتی یک جفت (bytes, address) است که در آن bytes یک شیء bytes است که داده‌های دریافتی را نشان می‌دهد و address نشانی سوکت ارسال‌کننده‌ی داده‌ها است. برای معنای آرگومان اختیاری flags، صفحه‌ی راهنمای Unix recv(2) را ببینید؛ مقدار پیش‌فرض آن ۰ است. قالب address به خانواده‌ی نشانی بستگی دارد --- خانواده‌های سوکت را ببینید.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

تغییر یافته در نسخه‌ی 3.7: برای نشانی چندپخشی IPv6، اولین آیتم address دیگر شامل بخش %scope_id نمی‌شود. برای دریافت نشانی کامل IPv6 از getnameinfo() استفاده کنید.

recvmsg(bufsize[, ancbufsize[, flags]])¶

داده‌های عادی (تا bufsize بایت) و داده‌های کمکی را از سوکت دریافت می‌کند. آرگومان ancbufsize اندازه‌ی بافر داخلی را بر حسب بایت برای دریافت داده‌های کمکی تعیین می‌کند؛ مقدار پیش‌فرض آن ۰ است، به این معنا که هیچ داده‌ی کمکی دریافت نخواهد شد. اندازه‌های مناسب بافر برای داده‌های کمکی را می‌توان با استفاده از CMSG_SPACE() یا CMSG_LEN() محاسبه کرد، و آیتم‌هایی که در بافر نمی‌گنجند ممکن است بریده یا دور ریخته شوند. آرگومان flags به‌طور پیش‌فرض مقدار ۰ دارد و همان معنایی را دارد که برای recv() دارد.

مقدار بازگشتی یک تاپل ۴تایی است: (data, ancdata, msg_flags, address). آیتم data یک شیء bytes حاوی داده‌های غیرجانبی دریافت‌شده است. آیتم ancdata فهرستی از صفر یا چند تاپل (cmsg_level, cmsg_type, cmsg_data) است که داده‌های جانبی (پیام‌های کنترلی) دریافت‌شده را نشان می‌دهد: cmsg_level و cmsg_type اعداد صحیحی هستند که به ترتیب سطح پروتکل و نوع مختص پروتکل را مشخص می‌کنند، و cmsg_data یک شیء bytes حاوی داده مرتبط است. آیتم msg_flags حاصل یای بیتی (bitwise OR) پرچم‌های مختلفی است که شرایط پیام دریافتی را نشان می‌دهند؛ برای جزئیات، مستندات سیستم خود را ببینید. اگر سوکت دریافت‌کننده متصل نباشد، address نشانی سوکت فرستنده است، در صورتی که در دسترس باشد؛ در غیر این صورت، مقدار آن نامشخص است.

در برخی از سیستم‌ها، می‌توان از sendmsg() و recvmsg() برای انتقال توصیف‌گرهای پرونده بین فرآیندها از طریق یک سوکت AF_UNIX استفاده کرد. هنگامی که از این قابلیت استفاده شود (که اغلب به سوکت‌های SOCK_STREAM محدود است)، recvmsg() در داده‌های جانبی خود، آیتم‌هایی را به شکل (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds) برمی‌گرداند، که در آن fds یک شیء bytes است که توصیف‌گرهای پرونده جدید را به‌صورت یک آرایه دودویی از نوع بومی int در C نشان می‌دهد. اگر recvmsg() پس از بازگشت فراخوانی سیستم، استثنایی پرتاب کند، ابتدا تلاش می‌کند هر توصیف‌گر پرونده دریافت‌شده از طریق این سازوکار را ببندد.

برخی سیستم‌ها طول بریده‌شده‌ی آیتم‌های داده‌ی جانبی را که تنها به‌طور ناقص دریافت شده‌اند، نشان نمی‌دهند. اگر به نظر برسد آیتمی از انتهای بافر فراتر می‌رود، recvmsg() یک RuntimeWarning صادر می‌کند و بخشی از آن را که درون بافر است برمی‌گرداند، به شرطی که پیش از شروع داده‌ی مرتبط آن بریده نشده باشد.

در سیستم‌هایی که از سازوکار SCM_RIGHTS پشتیبانی می‌کنند، تابع زیر حداکثر maxfds توصیف‌گر پرونده را دریافت می‌کند و داده پیام و فهرستی حاوی توصیف‌گرها را برمی‌گرداند (در حالی که شرایط غیرمنتظره‌ای مانند دریافت پیام‌های کنترلی نامرتبط را نادیده می‌گیرد). همچنین sendmsg() را ببینید.

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

دسترس‌پذیری: Unix.

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

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

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

recvmsg_into(buffers[, ancbufsize[, flags]])¶

داده‌های عادی و داده‌های جانبی را از سوکت دریافت می‌کند، همان‌گونه که recvmsg() عمل می‌کند، اما داده‌های غیرجانبی را به‌جای برگرداندن یک شیء bytes جدید، در مجموعه‌ای از بافرها پخش می‌کند. آرگومان buffers باید یک پیمایش‌پذیر از اشیایی باشد که بافرهای قابل‌نوشتن را در دسترس قرار می‌دهند (مانند اشیاء bytearray)؛ این بافرها با تکه‌های متوالی از داده‌های غیرجانبی پر می‌شوند تا همه آن داده‌ها نوشته شوند یا دیگر بافری باقی نمانده باشد. ممکن است سیستم‌عامل محدودیتی (مقدار sysconf() یعنی SC_IOV_MAX) برای تعداد بافرهایی که می‌توان از آن‌ها استفاده کرد تعیین کند. آرگومان‌های ancbufsize و flags همان معنایی را دارند که برای recvmsg() دارند.

مقدار بازگشتی یک تاپل ۴تایی است: (nbytes, ancdata, msg_flags, address)، که در آن nbytes تعداد کل بایت‌های داده غیرجانبی نوشته‌شده در بافرها است، و ancdata، msg_flags و address همانند recvmsg() هستند.

مثال:

>>> import socket
>>> s1, s2 = socket.socketpair()
>>> b1 = bytearray(b'----')
>>> b2 = bytearray(b'0123456789')
>>> b3 = bytearray(b'--------------')
>>> s1.send(b'Mary had a little lamb')
22
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
(22, [], 0, None)
>>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]

دسترس‌پذیری: Unix.

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

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

recvfrom_into(buffer[, nbytes[, flags]])¶: داده‌ها را از سوکت دریافت می‌کند و به‌جای ایجاد یک رشته بایتی جدید، آن‌ها را در buffer می‌نویسد. مقدار بازگشتی یک جفت (nbytes, address) است که در آن nbytes تعداد بایت‌های دریافت‌شده و address نشانی سوکت ارسال‌کننده داده‌ها است. برای آگاهی از معنای آرگومان اختیاری flags، به صفحه راهنمای Unix recv(2) مراجعه کنید؛ مقدار پیش‌فرض آن صفر است. قالب address به خانواده نشانی بستگی دارد — به خانواده‌های سوکت مراجعه کنید.

recv_into(buffer[, nbytes[, flags]])¶: حداکثر nbytes بایت را از سوکت دریافت می‌کند و داده‌ها را به جای ایجاد یک رشته بایتی جدید، در یک بافر ذخیره می‌کند. اگر nbytes مشخص نشده باشد (یا ۰)، حداکثر به اندازه فضای موجود در بافر داده‌شده دریافت می‌شود. تعداد بایت‌های دریافت‌شده را برمی‌گرداند. برای معنای آرگومان اختیاری flags، به صفحه راهنمای یونیکس recv(2) مراجعه کنید؛ مقدار پیش‌فرض آن صفر است.

send(bytes[, flags])¶: داده‌ها را به سوکت ارسال کنید. سوکت باید به یک سوکت راه‌دور متصل باشد. آرگومان اختیاری flags همان معنای مورد استفاده در recv() را دارد. تعداد بایت‌های ارسال‌شده را برمی‌گرداند. برنامه‌ها مسئول بررسی این هستند که همه داده‌ها ارسال شده‌اند؛ اگر تنها بخشی از داده‌ها منتقل شد، برنامه باید برای ارسال داده‌های باقی‌مانده تلاش کند. برای اطلاعات بیشتر درباره این موضوع، به راهنمای عملی برنامه‌نویسی سوکت مراجعه کنید.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

sendall(bytes[, flags])¶: داده‌ها را به سوکت ارسال می‌کند. سوکت باید به یک سوکت راه دور متصل باشد. آرگومان اختیاری flags همان معنایی را دارد که برای recv() دارد. برخلاف send()، این متد به ارسال داده از bytes ادامه می‌دهد تا اینکه یا همه داده‌ها ارسال شوند یا خطایی رخ دهد. در صورت موفقیت، None برگردانده می‌شود. در صورت خطا، استثنایی پرتاب می‌شود و هیچ راهی برای تعیین اینکه چه مقدار داده، در صورت وجود، با موفقیت ارسال شده است، وجود ندارد.

تغییر یافته در نسخه‌ی 3.5: مهلت زمانی سوکت دیگر هر بار که داده با موفقیت ارسال می‌شود، بازنشانی نمی‌شود. مهلت زمانی سوکت اکنون حداکثر مدت‌زمان کل برای ارسال تمام داده‌ها است.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

sendto(bytes, address)¶

sendto(bytes, flags, address)

داده را به سوکت ارسال می‌کند. سوکت نباید به یک سوکت دوردست متصل باشد، زیرا سوکت مقصد توسط address مشخص می‌شود. آرگومان اختیاری flags همان معنایی را دارد که برای recv() دارد. تعداد بایت‌های ارسال‌شده را برمی‌گرداند. قالب address به خانواده‌ی نشانی بستگی دارد — خانواده‌های سوکت را ببینید.

یک رویداد حسابرسی socket.sendto را با آرگومان‌های self و address پرتاب می‌کند.

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

sendmsg(buffers[, ancdata[, flags[, address]]])¶

داده‌های عادی و جانبی را به سوکت ارسال می‌کند؛ داده‌های غیرجانبی را از مجموعه‌ای از بافرها گردآوری کرده و در یک پیام واحد به هم می‌چسباند. آرگومان buffers داده‌های غیرجانبی را به‌صورت یک پیمایش‌پذیر از اشیاء شبه‌بایت مشخص می‌کند (برای مثال اشیاء bytes)؛ سیستم‌عامل ممکن است محدودیتی (مقدار SC_IOV_MAX از sysconf()) بر تعداد بافرهای قابل استفاده تعیین کند. آرگومان ancdata داده‌های جانبی (پیام‌های کنترلی) را به‌صورت یک پیمایش‌پذیر از صفر یا چند تاپل (cmsg_level, cmsg_type, cmsg_data) مشخص می‌کند، که در آن cmsg_level و cmsg_type اعداد صحیحی هستند که به‌ترتیب سطح پروتکل و نوع خاص پروتکل را مشخص می‌کنند، و cmsg_data یک شیء شبه‌بایت حاوی داده مرتبط است. توجه داشته باشید که برخی سیستم‌ها (به‌ویژه سیستم‌های بدون CMSG_SPACE()) ممکن است تنها از ارسال یک پیام کنترلی در هر فراخوانی پشتیبانی کنند. آرگومان flags به‌طور پیش‌فرض ۰ است و همان معنای send() را دارد. اگر address ارائه شود و None نباشد، آدرس مقصدی برای پیام تنظیم می‌کند. مقدار بازگشتی تعداد بایت‌های داده غیرجانبی ارسال‌شده است.

تابع زیر فهرست توصیف‌گرهای پرونده fds را از طریق یک سوکت AF_UNIX در سیستم‌هایی که از سازوکار SCM_RIGHTS پشتیبانی می‌کنند، ارسال می‌کند. همچنین recvmsg() را ببینید.

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

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

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

یک رویداد حسابرسی socket.sendmsg را با آرگومان‌های self و address پرتاب می‌کند.

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

تغییر یافته در نسخه‌ی 3.5: اگر فراخوانی سیستمی قطع شود و هندلر سیگنال استثنایی پرتاب نکند، متد اکنون به‌جای پرتاب استثنای InterruptedError، فراخوانی سیستمی را دوباره تلاش می‌کند (برای دلیل آن PEP 475 را ببینید).

sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])¶: نسخه‌ی تخصصی sendmsg() برای سوکت AF_ALG است. حالت، IV، طول داده‌های مرتبط با AEAD و پرچم‌ها را برای سوکت AF_ALG تنظیم می‌کند.

دسترس‌پذیری: Linux >= 2.6.38.

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

sendfile(file, offset=0, count=None)¶: یک پرونده را تا رسیدن به EOF با استفاده از os.sendfile با کارایی بالا ارسال می‌کند و تعداد کل بایت‌های ارسال‌شده را برمی‌گرداند. file باید یک شیء پرونده معمولی باشد که در حالت دودویی باز شده است. اگر os.sendfile در دسترس نباشد (برای مثال ویندوز) یا file یک پرونده معمولی نباشد، به‌جای آن از send() استفاده خواهد شد. offset مشخص می‌کند که خواندن پرونده از کجا آغاز شود. در صورت تعیین شدن، count تعداد کل بایت‌هایی است که باید منتقل شوند، برخلاف ارسال پرونده تا رسیدن به EOF. موقعیت پرونده هنگام بازگشت و همچنین در صورت بروز خطا به‌روزرسانی می‌شود؛ در این صورت می‌توان از file.tell() برای تشخیص تعداد بایت‌های ارسال‌شده استفاده کرد. سوکت باید از نوع SOCK_STREAM باشد. سوکت‌های غیرمسدودکننده پشتیبانی نمی‌شوند.

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

set_inheritable(inheritable)¶: پرچم ارث‌پذیری توصیف‌گر پرونده سوکت یا دسته‌ی سوکت را تنظیم کنید.

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

setblocking(flag)¶

حالت مسدودکننده یا غیرمسدودکننده‌ی سوکت را تنظیم می‌کند: اگر flag نادرست باشد، سوکت در حالت غیرمسدودکننده تنظیم می‌شود، در غیر این صورت در حالت مسدودکننده تنظیم می‌شود.

این متد میان‌بری برای برخی فراخوانی‌های settimeout() است:

sock.setblocking(True) معادل sock.settimeout(None) است
sock.setblocking(False) معادل sock.settimeout(0.0) است

تغییر یافته در نسخه‌ی 3.7: این متد دیگر پرچم SOCK_NONBLOCK را روی socket.type اعمال نمی‌کند.

settimeout(value)¶

برای عملیات‌های مسدودکننده سوکت یک مهلت تنظیم کنید. آرگومان value می‌تواند یک عدد حقیقی نامنفی بیان‌کننده ثانیه‌ها، یا None باشد. اگر مقدار غیرصفر داده شود، در عملیات‌های بعدی سوکت، چنانچه دوره مهلت value پیش از تکمیل عملیات سپری شده باشد، استثنای timeout پرتاب خواهد شد. اگر ۰ داده شود، سوکت در حالت غیرمسدودکننده قرار می‌گیرد. اگر None داده شود، سوکت در حالت مسدودکننده قرار می‌گیرد.

برای اطلاعات بیشتر، لطفاً یادداشت‌های مربوط به مهلت‌های زمانی سوکت را مطالعه کنید.

تغییر یافته در نسخه‌ی 3.7: این متد دیگر پرچم SOCK_NONBLOCK را روی socket.type تغییر وضعیت نمی‌دهد.

setsockopt(level, optname, value: int | Buffer)¶
setsockopt(level, optname, None, optlen: int): مقدار گزینه‌ی سوکت داده‌شده را تنظیم می‌کند (صفحه‌ی راهنمای یونیکس setsockopt(2) را ببینید). ثابت‌های نمادین مورد نیاز در این ماژول تعریف شده‌اند (SO_* etc. <socket-unix-constants>). مقدار می‌تواند یک عدد صحیح، None یا یک bytes-like object باشد که نشان‌دهنده‌ی یک بافر است. در حالت آخر، این بر عهده‌ی فراخواننده است که اطمینان حاصل کند رشته‌بایت حاوی بیت‌های مناسب است (برای راهی جهت کدگذاری ساختارهای C به‌صورت رشته‌بایت‌ها، ماژول توکار اختیاری struct را ببینید). هنگامی که value روی None تنظیم شود، آرگومان optlen الزامی است. این معادل فراخوانی تابع C setsockopt() با optval=NULL و optlen=optlen است.

تغییر یافته در نسخه‌ی 3.5: اکنون bytes-like object قابل نوشتن پذیرفته می‌شود.

تغییر یافته در نسخه‌ی 3.6: شکل setsockopt(level, optname, None, optlen: int) اضافه شد.

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

shutdown(how)¶: یک یا هر دو نیمه‌ی اتصال را خاموش کنید. اگر how برابر SHUT_RD باشد، دریافت‌های بعدی مجاز نیستند. اگر how برابر SHUT_WR باشد، ارسال‌های بعدی مجاز نیستند. اگر how برابر SHUT_RDWR باشد، ارسال‌ها و دریافت‌های بعدی مجاز نیستند.

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

share(process_id)¶: سوکت را تکثیر می‌کند و آن را برای اشتراک‌گذاری با یک فرایند هدف آماده می‌کند. فرایند هدف باید با process_id مشخص شود. سپس می‌توان شیء bytes حاصل را با استفاده از نوعی ارتباط بین‌فرایندی به فرایند هدف منتقل کرد و سوکت را در آن‌جا با استفاده از fromshare() دوباره ایجاد کرد. پس از فراخوانی این متد، بستن سوکت بی‌خطر است، زیرا سیستم‌عامل پیش‌تر آن را برای فرایند هدف تکثیر کرده است.

دسترس‌پذیری: Windows.

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

توجه داشته باشید که متدهای read() یا write() وجود ندارند؛ در عوض از recv() و send() بدون آرگومان flags استفاده کنید.

اشیای سوکت همچنین دارای این ویژگی‌های (فقط‌خواندنی) هستند که با مقادیر داده‌شده به سازنده‌ی socket مطابقت دارند.

family¶: خانواده سوکت.

type¶: نوع سوکت.

proto¶: پروتکل سوکت.

class socket.SocketType¶: کلاس پایه‌ی نوع socket، دوباره اکسپورت‌شده (re-exported) از _socket. یک بررسی نمونه مانند isinstance(socket(...), SocketType) صحیح است، اما SocketType با type(socket(...)) یکسان نیست، که خودِ socket است.

نکاتی درباره مهلت‌های زمانی سوکت¶

یک شیء سوکت می‌تواند در یکی از سه حالت باشد: مسدودکننده، غیرمسدودکننده، یا مهلت زمانی . سوکت‌ها به‌طور پیش‌فرض همیشه در حالت مسدودکننده ایجاد می‌شوند، اما می‌توان این حالت را با فراخوانی setdefaulttimeout() تغییر داد.

در حالت مسدودکننده، عملیات‌ها تا زمانی که کامل شوند یا سیستم خطایی برگرداند، مسدود می‌شوند (مانند اتمام مهلت اتصال).
در حالت غیرمسدود، عملیات‌ها در صورتی شکست می‌خورند که نتوانند بلافاصله کامل شوند (با خطایی که متأسفانه به سیستم وابسته است): برای تشخیص اینکه چه زمانی و آیا یک سوکت برای خواندن یا نوشتن در دسترس است، می‌توان از توابع ماژول select استفاده کرد.
در حالت مهلت، عملیات‌ها ناموفق می‌شوند اگر نتوانند در مهلت تعیین‌شده برای سوکت تکمیل شوند (آن‌ها استثانای timeout را پرتاب می‌کنند) یا اگر سیستم خطایی برگرداند.

توجه

در سطح سیستم‌عامل، سوکت‌هایی که در حالت مهلت زمانی هستند، به‌صورت داخلی در حالت غیرمسدودکننده تنظیم می‌شوند. همچنین حالت‌های مسدودکننده و مهلت زمانی بین توصیف‌گرهای پرونده و اشیای سوکتی که به یک پایانه شبکه یکسان اشاره می‌کنند، مشترک هستند. این جزئیات پیاده‌سازی می‌تواند پیامدهای قابل‌مشاهده‌ای داشته باشد، برای مثال اگر تصمیم بگیرید از fileno() یک سوکت استفاده کنید.

مهلت‌ها و متد `connect`¶

عملیات connect() نیز تابع تنظیم مهلت زمانی است، و به‌طور کلی توصیه می‌شود پیش از فراخوانی connect()، settimeout() را فراخوانی کنید یا یک پارامتر timeout به create_connection() بدهید. با این حال، پشته شبکه سیستم ممکن است صرف‌نظر از هرگونه تنظیم مهلت زمانی سوکت پایتون، خطای مهلت زمانی اتصال خاص خود را نیز برگرداند.

مهلت‌های زمانی و متد `accept`¶

اگر getdefaulttimeout() برابر None نباشد، سوکت‌های برگردانده‌شده توسط متد accept() آن مهلت زمانی را به ارث می‌برند. در غیر این صورت، رفتار به تنظیمات سوکت گوش‌دهنده بستگی دارد:

اگر سوکت گوش‌کننده در حالت مسدودکننده یا در حالت timeout باشد، سوکت برگردانده‌شده توسط accept() در حالت مسدودکننده است؛
اگر سوکت شنونده در حالت غیرمسدود باشد، مسدود یا غیرمسدود بودن سوکتی که accept() برمی‌گرداند، به سیستم‌عامل وابسته است. اگر می‌خواهید رفتار بین‌سکویی را تضمین کنید، توصیه می‌شود این تنظیم را به‌صورت دستی بازنویسی کنید.

مثال¶

در اینجا چهار برنامه‌ی نمونه‌ی کمینه با استفاده از پروتکل TCP/IP آمده است: سروری که تمام داده‌هایی را که دریافت می‌کند، بازپس می‌فرستد (فقط به یک کلاینت سرویس می‌دهد)، و کلاینتی که از آن استفاده می‌کند. توجه داشته باشید که یک سرور باید دنباله‌ی socket()، bind()، listen()، accept() را اجرا کند (احتمالاً با تکرار accept() برای سرویس‌دهی به بیش از یک کلاینت)، در حالی که یک کلاینت فقط به دنباله‌ی socket()، connect() نیاز دارد. همچنین توجه داشته باشید که سرور sendall()/recv() را روی سوکتی که روی آن گوش می‌دهد فراخوانی نمی‌کند، بلکه آن‌ها را روی سوکت جدیدی فراخوانی می‌کند که توسط accept() برگردانده شده است.

دو مثال اول فقط از IPv4 پشتیبانی می‌کنند.

# Echo server program
import socket

HOST = ''                 # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

دو مثال بعدی مشابه دو مثال بالا هستند، اما از هر دو IPv4 و IPv6 پشتیبانی می‌کنند. سمت سرور به اولین خانواده آدرس در دسترس گوش می‌دهد (در عوض باید به هر دو گوش دهد). در بیشتر سیستم‌های آماده‌ی IPv6، IPv6 اولویت دارد و ممکن است سرور ترافیک IPv4 را نپذیرد. سمت کلاینت تلاش می‌کند به تمام آدرس‌های برگردانده‌شده در نتیجه‌ی حل نام متصل شود و ترافیک را به اولین آدرسی که با موفقیت به آن متصل شد ارسال می‌کند.

# Echo server program
import socket
import sys

HOST = None               # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)

# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

مثال بعدی نشان می‌دهد که چگونه می‌توان یک شنودگر شبکه (network sniffer) بسیار ساده را با سوکت‌های خام (raw sockets) در ویندوز نوشت. این مثال برای تغییر رابط به اختیارات مدیر نیاز دارد:

import socket

# the public network interface
HOST = socket.gethostbyname(socket.gethostname())

# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# receive all packets
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a packet
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

مثال بعدی نشان می‌دهد که چگونه از رابط سوکت برای ارتباط با شبکه CAN با استفاده از پروتکل سوکت خام استفاده کنید. در عوض، برای استفاده از CAN با پروتکل مدیر پخش (broadcast manager)، یک سوکت با ... باز کنید:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

پس از مقید کردن سوکت (CAN_RAW) یا متصل کردن سوکت (CAN_BCM)، می‌توانید مانند معمول از عملیات socket.send() و socket.recv() (و همتاهای آن‌ها) روی شیء سوکت استفاده کنید.

این آخرین مثال ممکن است به دسترسی‌های ویژه‌ای نیاز داشته باشد:

import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')

اجرای یک مثال چندین بار با تأخیر بسیار کوتاه میان اجراها، ممکن است منجر به این خطا شود:

OSError: [Errno 98] نشانی از قبل در حال استفاده است

دلیل این امر آن است که اجرای قبلی، سوکت را در وضعیت TIME_WAIT باقی گذاشته است و نمی‌توان بلافاصله دوباره از آن استفاده کرد.

برای جلوگیری از این موضوع، یک پرچم socket برای تنظیم وجود دارد: socket.SO_REUSEADDR:

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))

پرچم SO_REUSEADDR به هسته می‌گوید که از یک سوکت محلی در وضعیت TIME_WAIT دوباره استفاده کند، بدون آنکه منتظر بماند مهلت زمانی طبیعی آن منقضی شود.

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

برای آشنایی با برنامه‌نویسی سوکت (به زبان C)، مقاله‌های زیر را ببینید:

آموزش مقدماتی ارتباط بین‌فرایندی 4.3BSD، اثر Stuart Sechrest
آموزش پیشرفته ارتباط بین‌فرایندی 4.3BSD، اثر Samuel J. Leffler و دیگران،

هر دو در UNIX Programmer's Manual، Supplementary Documents 1 (بخش‌های PS1:7 و PS1:8). مستندات مرجع مختص هر سکو برای فراخوانی‌های سیستمی مختلف مرتبط با سوکت نیز منبع ارزشمندی برای اطلاعات درباره‌ی جزئیات معناشناسی سوکت است. برای Unix، به صفحات راهنما مراجعه کنید؛ برای Windows، مشخصات WinSock (یا Winsock 2) را ببینید. برای APIهای آماده برای IPv6، خوانندگان ممکن است بخواهند به RFC 3493 با عنوان Basic Socket Interface Extensions for IPv6 مراجعه کنند.

`socket` --- رابط شبکه‌ای سطح پایین¶

خانواده‌های سوکت¶

محتویات ماژول¶

استثناها¶

ثابت‌ها¶

توابع¶

ایجاد سوکت‌ها¶

توابع دیگر¶

اشیای سوکت¶

نکاتی درباره مهلت‌های زمانی سوکت¶

مهلت‌ها و متد `connect`¶

مهلت‌های زمانی و متد `accept`¶

مثال¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه

socket --- رابط شبکه‌ای سطح پایین¶

خانواده‌های سوکت¶

محتویات ماژول¶

استثناها¶

ثابت‌ها¶

توابع¶

ایجاد سوکت‌ها¶

توابع دیگر¶

اشیای سوکت¶

نکاتی درباره مهلت‌های زمانی سوکت¶

مهلت‌ها و متد connect¶

مهلت‌های زمانی و متد accept¶

مثال¶

`socket` --- رابط شبکه‌ای سطح پایین¶

مهلت‌ها و متد `connect`¶

مهلت‌های زمانی و متد `accept`¶