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

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

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

• نشانی یک سوکت 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 عناصر زیر را اکسپورت می‌کند.

اشیای سوکت¶

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 باشد.

اگر fileno مشخص شود، مقادیر برای family، type، و proto به‌صورت خودکار از توصیف‌گر پرونده مشخص‌شده تشخیص داده می‌شوند. تشخیص خودکار می‌تواند با فراخوانی تابع با آرگومان‌های صریح family، type، یا proto لغو شود. این تنها بر نحوه نمایش پایتون تأثیر می‌گذارد، مانند مقدار بازگشتیِ socket.getpeername()، نه بر منبع واقعی سیستم‌عامل. برخلاف socket.fromfd()، fileno همان سوکت را برمی‌گرداند و نه یک کپی. این می‌تواند به بستن یک سوکت جدا شده با استفاده از 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: پشتیبانی از پروتکل مدیر زمینه اضافه شد. خروج از مدیر زمینه معادل فراخوانی 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' یا ترکیبی از آن‌ها هستند.

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

بستن شیء پرونده که توسط makefile() برگردانده شده، سوکت اصلی را نخواهد بستن، مگر اینکه تمام دیگر اشیاء پرونده بسته شده باشند و close() روی شیء سوکت فراخوانی شده باشد.

نکته

در ویندوز، نمی‌توان از شیء شبه‌پرونده ایجادشده توسط 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 تغییر وضعیت نمی‌دهد.

تغییر یافته در نسخه‌ی 3.15: هر عدد حقیقی را می‌پذیرد، نه فقط عدد صحیح یا عدد اعشاری را.

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 را پرتاب می‌کنند) یا اگر سیستم خطایی برگرداند.

مثال¶

در اینجا چهار برنامه‌ی نمونه‌ی کمینه با استفاده از پروتکل 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 دوباره استفاده کند، بدون آنکه منتظر بماند مهلت زمانی طبیعی آن منقضی شود.