GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing python.github.io — ipaddress --- کتابخانه‌ی دستکاری IPv4/IPv6

`ipaddress` --- کتابخانه‌ی دستکاری IPv4/IPv6¶

ipaddress قابلیت‌هایی برای ایجاد، دستکاری و کار با نشانی‌ها و شبکه‌های IPv4 و IPv6 فراهم می‌کند.

توابع و کلاس‌های این ماژول، انجام وظایف مختلف مربوط به آدرس‌های IP را ساده می‌کنند؛ از جمله بررسی این که آیا دو میزبان در یک زیرشبکه هستند یا خیر، پیمایش روی تمام میزبان‌های یک زیرشبکه خاص، بررسی این که آیا یک رشته نشان‌دهنده یک آدرس IP معتبر یا تعریف شبکه است یا خیر، و غیره.

این مرجع کامل API ماژول است—برای مرور کلی و مقدمه، مقدمه‌ای بر ماژول ipaddress را ببینید.

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

توابع کارخانه‌ای سهولت‌بخش¶

ماژول ipaddress توابع کارخانه‌ای (factory functions) را برای ایجاد آسان آدرس‌های IP، شبکه‌ها و رابط‌ها ارائه می‌دهد:

ipaddress.ip_address(address)¶

یک شیء IPv4Address یا IPv6Address را بسته به نشانی IP داده‌شده به‌عنوان آرگومان برمی‌گرداند. می‌توان نشانی‌های IPv4 یا IPv6 را ارائه کرد؛ اعداد صحیح کوچک‌تر از 2**32 به‌طور پیش‌فرض IPv4 در نظر گرفته می‌شوند. اگر address نشان‌دهنده یک نشانی IPv4 یا IPv6 معتبر نباشد، یک ValueError پرتاب می‌شود.

>>> ipaddress.ip_address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.ip_address('2001:db8::')
IPv6Address('2001:db8::')

ipaddress.ip_network(address, strict=True)¶

یک شیء IPv4Network یا IPv6Network را بسته به آدرس IP ارسال‌شده به‌عنوان آرگومان بازمی‌گرداند. address یک رشته یا عدد صحیح است که نشان‌دهنده‌ی شبکه‌ی IP است. می‌توان شبکه‌های IPv4 یا IPv6 را ارائه کرد؛ اعداد صحیح کوچک‌تر از 2**32 به‌طور پیش‌فرض IPv4 در نظر گرفته می‌شوند. strict به سازنده‌ی IPv4Network یا IPv6Network ارسال می‌شود. اگر address نشان‌دهنده‌ی یک آدرس IPv4 یا IPv6 معتبر نباشد، یا اگر شبکه دارای بیت‌های میزبان تنظیم‌شده باشد، یک استثنای ValueError پرتاب می‌شود.

>>> ipaddress.ip_network('192.168.0.0/28')
IPv4Network('192.168.0.0/28')

ipaddress.ip_interface(address)¶: بسته به نشانی IP داده‌شده به‌عنوان آرگومان، یک شیء IPv4Interface یا IPv6Interface برمی‌گرداند. address یک رشته یا عدد صحیح است که نشانی IP را نشان می‌دهد. می‌توان نشانی‌های IPv4 یا IPv6 را ارائه کرد؛ اعداد صحیح کوچک‌تر از 2**32 به‌طور پیش‌فرض IPv4 در نظر گرفته می‌شوند. اگر address یک نشانی IPv4 یا IPv6 معتبر را نشان ندهد، استثنای ValueError پرتاب می‌شود.

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

آدرس‌های IP¶

اشیای نشانی¶

اشیای IPv4Address و IPv6Address ویژگی‌های مشترک زیادی دارند. برخی از ویژگی‌ها که فقط برای آدرس‌های IPv6 معنادار هستند، توسط اشیای IPv4Address نیز پیاده‌سازی شده‌اند، تا نوشتن کدی که هر دو نسخه‌ی IP را به‌درستی مدیریت می‌کند، آسان‌تر شود. اشیای آدرس هش‌پذیر (hashable) هستند، بنابراین می‌توان از آن‌ها به‌عنوان کلید در دیکشنری‌ها استفاده کرد.

class ipaddress.IPv4Address(address)¶

ساخت یک نشانی IPv4. اگر address یک نشانی IPv4 معتبر نباشد، AddressValueError پرتاب می‌شود.

عبارت زیر یک نشانی IPv4 معتبر را تشکیل می‌دهد:

رشته‌ای با نمادگذاری دهدهی-نقطه‌ای، شامل چهار عدد صحیح دهدهی در بازه‌ی بسته‌ی ۰ تا ۲۵۵ است که با نقطه از هم جدا شده‌اند (مانند 192.168.0.1). هر عدد صحیح نشان‌دهنده‌ی یک هشت‌بیتی (بایت) در نشانی است. صفرهای آغازین مجاز نیستند تا از اشتباه با نمایش مبنای هشت جلوگیری شود.
عدد صحیحی که در ۳۲ بیت جای می‌گیرد.
یک عدد صحیح که در یک شیء bytes به طول ۴ بسته‌بندی شده است (ابتدا پرارزش‌ترین هشت‌بیتی).

>>> ipaddress.IPv4Address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(3232235521)
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
IPv4Address('192.168.0.1')

تغییر یافته در نسخه‌ی 3.8: صفرهای پیشرو پذیرفته می‌شوند، حتی در موارد مبهمی که شبیه نمادگذاری مبنای هشت هستند.

تغییر یافته در نسخه‌ی 3.9.5: صفرهای ابتدایی دیگر مجاز نیستند و به‌عنوان خطا تلقی می‌شوند. رشته‌های نشانی IPv4 اکنون به همان سخت‌گیری glibc inet_pton() تجزیه می‌شوند.

version¶: شماره‌ی نسخه‌ی مناسب: 4 برای IPv4، 6 برای IPv6.

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

max_prefixlen¶

تعداد کل بیت‌ها در نمایش نشانی برای این نسخه: 32 برای IPv4، 128 برای IPv6.

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

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

compressed¶

exploded¶

نمایش رشته‌ای در نمادگذاری دهدهی نقطه‌دار. صفرهای آغازین هرگز در این نمایش گنجانده نمی‌شوند.

از آن‌جا که IPv4 نمادگذاری کوتاه‌شده‌ای برای نشانی‌هایی که هشت‌بیتی‌های آن‌ها روی صفر تنظیم شده‌اند تعریف نمی‌کند، این دو ویژگی برای نشانی‌های IPv4 همیشه با str(addr) یکسان هستند. در دسترس قرار دادن این ویژگی‌ها، نوشتن کد نمایشی را که بتواند هر دو نشانی IPv4 و IPv6 را مدیریت کند، آسان‌تر می‌کند.

packed¶: بازنمایی دودویی این نشانی - یک شیء bytes با طول مناسب (ابتدا پرارزش‌ترین هشت‌بیتی). این مقدار برای IPv4 برابر ۴ بایت و برای IPv6 برابر ۱۶ بایت است.

reverse_pointer¶

نام رکورد PTR معکوس DNS برای نشانی IP، برای نمونه:

>>> ipaddress.ip_address("127.0.0.1").reverse_pointer
'1.0.0.127.in-addr.arpa'
>>> ipaddress.ip_address("2001:db8::1").reverse_pointer
'1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa'

این نامی است که می‌توان از آن برای انجام جست‌وجوی PTR استفاده کرد، نه خود نام میزبان حل‌شده.

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

is_multicast¶: اگر نشانی برای استفاده‌ی چندپخشی (multicast) رزرو شده باشد، True است. RFC 3171 (برای IPv4) یا RFC 2373 (برای IPv6) را ببینید.

is_private¶

True اگر نشانی توسط iana-ipv4-special-registry (برای IPv4) یا iana-ipv6-special-registry (برای IPv6) به‌عنوان غیرقابل‌دسترس به‌صورت سراسری تعریف شده باشد، با استثناهای زیر:

is_private برای فضای آدرس مشترک (100.64.0.0/10) برابر False است
برای آدرس‌های IPv6 نگاشت‌شده به IPv4، مقدار is_private بر اساس معنای آدرس‌های IPv4 زیرین تعیین می‌شود و شرط زیر برقرار است (به IPv6Address.ipv4_mapped مراجعه کنید):
```
address.is_private == address.ipv4_mapped.is_private
```

is_private مقداری مخالف is_global دارد، به‌جز فضای آدرس مشترک (محدوده‌ی 100.64.0.0/10) که در آن هر دو False هستند.

تغییر یافته در نسخه‌ی 3.13: برخی مثبت‌های کاذب و منفی‌های کاذب برطرف شدند.

192.0.0.0/24 به‌استثنای 192.0.0.9/32 و 192.0.0.10/32 خصوصی در نظر گرفته می‌شود (پیش‌تر: فقط زیرمحدوده‌ی 192.0.0.0/29 خصوصی در نظر گرفته می‌شد).
64:ff9b:1::/48 خصوصی در نظر گرفته می‌شود.
2002::/16 خصوصی در نظر گرفته می‌شود.
در 2001::/23 استثناهایی وجود دارد (که در غیر این صورت خصوصی در نظر گرفته می‌شود): 2001:1::1/128، 2001:1::2/128، 2001:3::/32، 2001:4:112::/48، 2001:20::/28، 2001:30::/28. این استثناها خصوصی در نظر گرفته نمی‌شوند.

is_global¶

True اگر نشانی توسط iana-ipv4-special-registry (برای IPv4) یا iana-ipv6-special-registry (برای IPv6) به‌عنوان قابل دسترس سراسری تعریف شده باشد، با این استثنا:

برای آدرس‌های IPv6 نگاشت‌شده به IPv4، مقدار is_private بر اساس معنای آدرس‌های IPv4 زیرین تعیین می‌شود و شرط زیر برقرار است (به IPv6Address.ipv4_mapped مراجعه کنید):

address.is_global == address.ipv4_mapped.is_global

is_global مقداری مخالف is_private دارد، به‌جز فضای آدرس مشترک (محدوده 100.64.0.0/10) که در آن هر دو False هستند.

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

تغییر یافته در نسخه‌ی 3.13: برخی مثبت‌های کاذب و منفی‌های کاذب برطرف شدند؛ برای جزئیات is_private را ببینید.

is_unspecified¶: اگر نشانی نامشخص باشد، True است. RFC 5735 (برای IPv4) یا RFC 2373 (برای IPv6) را ببینید.

is_reserved¶: اگر آدرس به‌عنوان رزروشده از سوی IETF ثبت‌شده باشد، True است. برای IPv4، این فقط 240.0.0.0/4، بلوک آدرس Reserved است. برای IPv6، این تمام آدرس‌هایی است که برای استفاده آینده به‌عنوان Reserved by IETF اختصاص‌یافته هستند.

نکته

برای IPv4، is_reserved به مقدار بلوک آدرسِ ستون Reserved-by-Protocol در iana-ipv4-special-registry مربوط نیست.

احتیاط

برای IPv6، fec0::/10، پیشوند نشانی سابق با محدوده‌ی Site-Local، در حال حاضر از آن فهرست مستثنی شده است (به is_site_local و RFC 3879 مراجعه کنید).

is_loopback¶: اگر این یک نشانی حلقه‌ای (loopback) باشد، True است. RFC 3330 (برای IPv4) یا RFC 2373 (برای IPv6) را ببینید.

is_link_local¶: اگر نشانی برای استفاده‌ی محلی پیوند (link-local) رزرو شده باشد، True است. RFC 3927 را ببینید.

ipv6_mapped¶: شیء IPv6Address که نشان‌دهنده‌ی نشانی IPv6 با نگاشت IPv4 است. RFC 4291 را ببینید.

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

IPv4Address.__format__(fmt)¶

یک نمایش رشته‌ای از نشانی IP را، که با یک رشته‌ی قالب‌بندی صریح کنترل می‌شود، برمی‌گرداند. fmt می‌تواند یکی از موارد زیر باشد: 's'، گزینه‌ی پیش‌فرض، معادل str()، 'b' برای رشته‌ی دودویی که با صفر پر شده است، 'X' یا 'x' برای نمایش مبنای شانزده با حروف بزرگ یا کوچک، یا 'n'، که برای نشانی‌های IPv4 معادل 'b' و برای IPv6 معادل 'x' است. برای نمایش‌های دودویی و مبنای شانزده، مشخص‌کننده‌ی قالب '#' و گزینه‌ی گروه‌بندی '_' در دسترس هستند. __format__ توسط format، str.format و اف‌استرینگ‌ها استفاده می‌شود.

>>> format(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> '{:#b}'.format(ipaddress.IPv4Address('192.168.0.1'))
'0b11000000101010000000000000000001'
>>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
'2001:db8::1000'
>>> format(ipaddress.IPv6Address('2001:db8::1000'), '_X')
'2001_0DB8_0000_0000_0000_0000_0000_1000'
>>> '{:#_n}'.format(ipaddress.IPv6Address('2001:db8::1000'))
'0x2001_0db8_0000_0000_0000_0000_0000_1000'

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

class ipaddress.IPv6Address(address)¶

یک نشانی IPv6 می‌سازد. اگر address یک نشانی IPv6 معتبر نباشد، AddressValueError پرتاب می‌شود.

مورد زیر یک نشانی IPv6 معتبر را تشکیل می‌دهد:

رشته‌ای متشکل از هشت گروه چهارتایی از ارقام مبنای شانزده است، که هر گروه بیانگر ۱۶ بیت است. گروه‌ها با دونقطه از یکدیگر جدا می‌شوند. این یک نمادگذاری بازشده (نوشتار کامل) را توصیف می‌کند. این رشته همچنین می‌تواند با روش‌های مختلف به‌صورت فشرده (نمادگذاری کوتاه‌نویسی) درآید. برای جزئیات، RFC 4291 را ببینید. برای مثال، "0000:0000:0000:0000:0000:0abc:0007:0def" می‌تواند به "::abc:7:def" فشرده شود.

به‌صورت اختیاری، رشته ممکن است یک شناسه‌ی ناحیه‌ی محدوده (scope zone ID) نیز داشته باشد که با پسوند %scope_id بیان می‌شود. در صورت وجود، شناسه‌ی محدوده باید غیرخالی باشد و نباید شامل % باشد. برای جزئیات، RFC 4007 را ببینید. برای مثال، fe80::1234%1 ممکن است نشانی fe80::1234 را در اولین پیوند گره مشخص کند.
یک عدد صحیح که در ۱۲۸ بیت جای می‌گیرد.
یک عدد صحیح بسته‌بندی‌شده در یک شیء bytes به طول ۱۶، به صورت بزرگ‌اندیان (big-endian).

>>> ipaddress.IPv6Address('2001:db8::1000')
IPv6Address('2001:db8::1000')
>>> ipaddress.IPv6Address('ff02::5678%1')
IPv6Address('ff02::5678%1')

compressed¶

شکل کوتاه نمایش نشانی، که در آن صفرهای پیشرو در گروه‌ها حذف شده‌اند و طولانی‌ترین دنباله از گروه‌هایی که کاملاً از صفر تشکیل شده‌اند به یک گروه خالی فشرده می‌شود.

این نیز مقداری است که توسط str(addr) برای نشانی‌های IPv6 برگردانده می‌شود.

exploded¶

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

برای ویژگی‌ها و متدهای زیر، مستندات مربوط به کلاس IPv4Address را ببینید:

packed¶

reverse_pointer¶

version¶

max_prefixlen¶

is_multicast¶

is_private¶

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

is_unspecified¶

is_reserved¶

is_loopback¶

is_link_local¶

is_site_local¶: اگر نشانی برای استفاده‌ی محلی سایت (site-local) رزرو شده باشد، True است. توجه داشته باشید که فضای نشانی محلی سایت (site-local) در RFC 3879 منسوخ شده است. برای بررسی اینکه آیا این نشانی در فضای نشانی‌های محلی یکتا (unique local addresses) تعریف‌شده در RFC 4193 قرار دارد، از is_private استفاده کنید.

ipv4_mapped¶: برای نشانی‌هایی که به نظر می‌رسد نشانی‌های IPv4 نگاشت‌شده در محدوده ::FFFF:0:0/96 مطابق تعریف RFC 4291 باشند، این ویژگی نشانی IPv4 تعبیه‌شده را گزارش می‌دهد. برای هر نشانی دیگر، این ویژگی None خواهد بود.

scope_id¶: برای نشانی‌های دارای محدوده، همان‌طور که در RFC 4007 تعریف شده‌اند، این ویژگی منطقه‌ی خاصی از محدوده‌ی نشانی را که نشانی به آن تعلق دارد، به‌صورت یک رشته مشخص می‌کند. وقتی هیچ منطقه‌ی محدوده‌ای مشخص نشده باشد، این ویژگی None خواهد بود.

sixtofour¶: برای نشانی‌هایی که به نظر می‌رسد نشانی‌های 6to4 باشند (با شروع 2002::/16)، همان‌طور که در RFC 3056 تعریف شده‌اند، این ویژگی نشانی IPv4 تعبیه‌شده را برمی‌گرداند. برای هر نشانی دیگر، این ویژگی None خواهد بود.

teredo¶: برای نشانی‌هایی که به نظر می‌رسد نشانی‌های Teredo باشند (با 2001::/32 شروع می‌شوند) و طبق RFC 4380 تعریف شده‌اند، این ویژگی جفت نشانی IP نهفته (server, client) را گزارش می‌دهد. برای هر نشانی دیگر، این ویژگی None خواهد بود.

IPv6Address.__format__(fmt)¶: به مستندات متد مربوطه در IPv4Address مراجعه کنید.

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

تبدیل به رشته‌ها و اعداد صحیح¶

برای تعامل با رابط‌های شبکه‌ای مانند ماژول socket، نشانی‌ها باید به رشته‌ها یا اعداد صحیح تبدیل شوند. این کار با استفاده از توابع توکار str() و int() انجام می‌شود:

>>> str(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> int(ipaddress.IPv4Address('192.168.0.1'))
3232235521
>>> str(ipaddress.IPv6Address('::1'))
'::1'
>>> int(ipaddress.IPv6Address('::1'))
1

توجه داشته باشید که آدرس‌های IPv6 محدوده‌دار بدون شناسه ناحیه محدوده (scope zone ID) به عدد صحیح تبدیل می‌شوند.

عملگرها¶

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

عملگرهای مقایسه¶

می‌توان اشیای نشانی را با مجموعه‌ی معمول عملگرهای مقایسه مقایسه کرد. نشانی‌های IPv6 یکسان با شناسه‌های متفاوت منطقه‌ی محدوده (scope zone IDs) برابر نیستند. چند نمونه:

>>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
True
>>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
False
>>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
True
>>> IPv6Address('fe80::1234') == IPv6Address('fe80::1234%1')
False
>>> IPv6Address('fe80::1234%1') != IPv6Address('fe80::1234%2')
True

عملگرهای حسابی¶

می‌توان اعداد صحیح را به اشیای نشانی افزود یا از آن‌ها کم کرد. برخی مثال‌ها:

>>> IPv4Address('127.0.0.2') + 3
IPv4Address('127.0.0.5')
>>> IPv4Address('127.0.0.2') - 3
IPv4Address('126.255.255.255')
>>> IPv4Address('255.255.255.255') + 1
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address

تعاریف شبکه IP¶

اشیاء IPv4Network و IPv6Network سازوکاری برای تعریف و بررسی تعاریف شبکه‌ی IP فراهم می‌کنند. یک تعریف شبکه شامل یک mask و یک آدرس شبکه است و به همین صورت بازه‌ای از آدرس‌های IP را تعریف می‌کند که با اعمال نقاب بر آن‌ها (AND دودویی) برابر با آدرس شبکه می‌شوند. برای مثال، یک تعریف شبکه با نقاب 255.255.255.0 و آدرس شبکه 192.168.1.0 شامل آدرس‌های IP در بازه‌ی بسته‌ی 192.168.1.0 تا 192.168.1.255 است.

پیشوند، نقاب شبکه و نقاب میزبان¶

چندین روش معادل برای مشخص کردن نقاب‌های شبکه IP وجود دارد. پیشوند /<nbits> نمادگذاری است که نشان می‌دهد چند بیت مرتبه بالا در نقاب شبکه روشن هستند. نقاب شبکه نشانی IP است که تعدادی از بیت‌های مرتبه بالای آن روشن هستند. بنابراین پیشوند /24 معادل نقاب شبکه 255.255.255.0 در IPv4، یا ffff:ff00:: در IPv6 است. علاوه بر این، نقاب میزبان معکوس منطقی نقاب شبکه است و گاهی (برای مثال در فهرست‌های کنترل دسترسی سیسکو) برای نشان دادن یک نقاب شبکه به کار می‌رود. نقاب میزبان معادل /24 در IPv4 برابر 0.0.0.255 است.

اشیاء شبکه¶

همه‌ی ویژگی‌های پیاده‌سازی‌شده در اشیاء آدرس، در اشیاء شبکه نیز پیاده‌سازی شده‌اند. علاوه بر این، اشیاء شبکه ویژگی‌های اضافی را پیاده‌سازی می‌کنند. همه‌ی این موارد بین IPv4Network و IPv6Network مشترک هستند، بنابراین برای جلوگیری از تکرار، فقط برای IPv4Network مستند شده‌اند. اشیاء شبکه hashable هستند، بنابراین می‌توان از آن‌ها به‌عنوان کلید در دیکشنری‌ها استفاده کرد.

class ipaddress.IPv4Network(address, strict=True)¶

یک تعریف شبکه‌ی IPv4 ایجاد می‌کند. address می‌تواند یکی از موارد زیر باشد:

رشته‌ای شامل یک نشانی IP و یک نقاب اختیاری است که با یک اسلش (/) از هم جدا شده‌اند. نشانی IP، نشانی شبکه است و نقاب می‌تواند یک عدد تنها باشد که در این صورت یک پیشوند محسوب می‌شود، یا نمایش رشته‌ای یک نشانی IPv4 باشد. اگر حالت دوم باشد، چنانچه نقاب با یک فیلد غیرصفر آغاز شود، به‌عنوان نقاب شبکه تفسیر می‌شود؛ و اگر با یک فیلد صفر آغاز شود، به‌عنوان نقاب میزبان تفسیر می‌شود. تنها استثنا نقابی است که کاملاً صفر است و به‌عنوان نقاب شبکه در نظر گرفته می‌شود. اگر هیچ نقابی ارائه نشود، به‌صورت /32 در نظر گرفته می‌شود.

برای مثال، مشخصات نشانی زیر معادل هستند: 192.168.1.0/24، 192.168.1.0/255.255.255.0 و 192.168.1.0/0.0.0.255.
عدد صحیحی که در ۳۲ بیت جای می‌گیرد. این معادل یک شبکه‌ی تک‌نشانی است که در آن نشانی شبکه address و نقاب /32 است.
یک عدد صحیح بسته‌بندی‌شده در یک شیء bytes به طول ۴، بزرگ‌اندیان (big-endian). تفسیر آن مشابه یک نشانی از نوع عدد صحیح است.
یک تاپل دوتایی از توصیف نشانی و نقاب شبکه، که توصیف نشانی می‌تواند یک رشته، یک عدد صحیح ۳۲ بیتی، یک عدد صحیح ۴ بایتی بسته‌بندی‌شده، یا یک شیء IPv4Address موجود باشد؛ و نقاب شبکه می‌تواند یک عدد صحیح نشان‌دهنده‌ی طول پیشوند (برای نمونه 24) یا یک رشته نشان‌دهنده‌ی نقاب پیشوند (برای نمونه 255.255.255.0) باشد.

اگر address یک نشانی IPv4 معتبر نباشد، یک AddressValueError پرتاب می‌شود. اگر نقاب برای یک نشانی IPv4 معتبر نباشد، یک NetmaskValueError پرتاب می‌شود.

اگر strict برابر True باشد و بیت‌های میزبان در نشانی ارائه‌شده برقرار باشند، ValueError پرتاب می‌شود. در غیر این صورت، بیت‌های میزبان نقاب می‌شوند تا نشانی شبکه مناسب تعیین شود.

مگر اینکه خلاف آن ذکر شده باشد، همه‌ی متدهای شبکه‌ای که دیگر اشیاء شبکه/نشانی را می‌پذیرند، در صورتی که نسخه‌ی IP آرگومان با self ناسازگار باشد، TypeError را پرتاب می‌کنند.

تغییر یافته در نسخه‌ی 3.5: قالب دو-تایی (two-tuple) برای پارامتر address در سازنده افزوده شد.

version¶

max_prefixlen¶: به مستندات ویژگی متناظر در IPv4Address مراجعه کنید.

is_multicast¶

is_private¶

is_unspecified¶

is_reserved¶

is_loopback¶

is_link_local¶: این ویژگی‌ها برای کل شبکه برقرار هستند اگر برای هر دو نشانی شبکه و نشانی پخش (broadcast) برقرار باشند.

network_address¶: نشانی شبکه برای شبکه. نشانی شبکه و طول پیشوند با هم به‌طور یکتا یک شبکه را تعریف می‌کنند.

broadcast_address¶: نشانی پخش شبکه. بسته‌های ارسال‌شده به نشانی پخش باید توسط هر میزبان در شبکه دریافت شوند.

hostmask¶: نقاب میزبان، به‌صورت یک شیء IPv4Address.

netmask¶: نقاب شبکه، به‌صورت یک شیء IPv4Address.

with_prefixlen¶

compressed¶

exploded¶

نمایش رشته‌ای از شبکه، با نقاب در نماد پیشوندی.

with_prefixlen و compressed همیشه با str(network) یکسان هستند. exploded از شکل گسترش‌یافته‌ی نشانی شبکه استفاده می‌کند.

with_netmask¶: یک نمایش رشته‌ای از شبکه، با نقاب در نمادگذاری نقاب شبکه.

with_hostmask¶: یک نمایش رشته‌ای از شبکه، با نقاب در نمادگذاری نقاب میزبان (host mask notation).

num_addresses¶: تعداد کل آدرس‌های شبکه.

prefixlen¶: طول پیشوند شبکه، بر حسب بیت.

hosts()¶

پیمایش‌گری بر روی میزبان‌های قابل‌استفاده در شبکه برمی‌گرداند. میزبان‌های قابل‌استفاده همه آدرس‌های IP متعلق به شبکه هستند، به‌جز خود آدرس شبکه و آدرس پخش شبکه (broadcast). برای شبکه‌هایی با طول نقاب ۳۱، آدرس شبکه و آدرس پخش شبکه (broadcast) نیز در نتیجه قرار می‌گیرند. شبکه‌هایی با نقاب ۳۲، فهرستی شامل تنها آدرس میزبان را برمی‌گردانند.

>>> list(ip_network('192.0.2.0/29').hosts())
[IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),
 IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),
 IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')]
>>> list(ip_network('192.0.2.0/31').hosts())
[IPv4Address('192.0.2.0'), IPv4Address('192.0.2.1')]
>>> list(ip_network('192.0.2.1/32').hosts())
[IPv4Address('192.0.2.1')]

overlaps(other)¶: True اگر این شبکه به‌طور جزئی یا کلی در other قرار داشته باشد یا other به‌طور کلی در این شبکه قرار داشته باشد.

address_exclude(network)¶

تعریف‌های شبکه حاصل از حذف network داده‌شده از این شبکه را محاسبه می‌کند. پیمایش‌گری از اشیاء شبکه برمی‌گرداند. اگر network به‌طور کامل در این شبکه قرار نداشته باشد، استثنای ValueError را پرتاب می‌کند.

>>> n1 = ip_network('192.0.2.0/28')
>>> n2 = ip_network('192.0.2.1/32')
>>> list(n1.address_exclude(n2))
[IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),
 IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')]

subnets(prefixlen_diff=1, new_prefix=None)¶

زیرشبکه‌هایی که بسته به مقادیر آرگومان، با هم ترکیب می‌شوند تا تعریف شبکه‌ی جاری را بسازند. prefixlen_diff مقداری است که طول پیشوند ما باید به اندازه‌ی آن افزایش یابد. new_prefix پیشوند جدید موردنظر برای زیرشبکه‌هاست؛ باید بزرگ‌تر از پیشوند ما باشد. یکی و فقط یکی از prefixlen_diff و new_prefix باید تنظیم شود. یک پیمایش‌گر از اشیای شبکه برمی‌گرداند.

>>> list(ip_network('192.0.2.0/24').subnets())
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
>>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise ValueError('new prefix must be longer')
ValueError: new prefix must be longer
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]

supernet(prefixlen_diff=1, new_prefix=None)¶

ابرشبکه‌ای که شامل این تعریف شبکه است، بسته به مقدارهای آرگومان‌ها. prefixlen_diff مقداری است که طول پیشوند ما باید به اندازه آن کاهش یابد. new_prefix پیشوند جدید دلخواه ابرشبکه است؛ باید از پیشوند ما کوچک‌تر باشد. یکی و فقط یکی از prefixlen_diff و new_prefix باید تنظیم شود. یک شیء شبکه واحد را برمی‌گرداند.

>>> ip_network('192.0.2.0/24').supernet()
IPv4Network('192.0.2.0/23')
>>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)
IPv4Network('192.0.0.0/22')
>>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
IPv4Network('192.0.0.0/20')

subnet_of(other)¶

اگر این شبکه زیرشبکه‌ای از other باشد، True را برمی‌گرداند.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True

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

supernet_of(other)¶

اگر این شبکه، ابرشبکه‌ای از other باشد، True را برمی‌گرداند.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True

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

compare_networks(other)¶

این شبکه را با other مقایسه می‌کند. در این مقایسه فقط نشانی‌های شبکه در نظر گرفته می‌شوند؛ بیت‌های میزبان در نظر گرفته نمی‌شوند. یکی از -1، 0 یا 1 را برمی‌گرداند.

>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))
-1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))
1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))
0

منسوخ شده از نسخه‌ی 3.7: از همان الگوریتم ترتیب‌دهی و مقایسه مانند "<"، "==" و ">" استفاده می‌کند.

class ipaddress.IPv6Network(address, strict=True)¶

یک تعریف شبکه IPv6 ایجاد کنید. address می‌تواند یکی از موارد زیر باشد:

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

توجه داشته باشید که در حال حاضر از نقاب‌های شبکه‌ی گسترش‌یافته (netmask) پشتیبانی نمی‌شود. این بدان معناست که 2001:db00::0/24 یک آرگومان معتبر است، در حالی که 2001:db00::0/ffff:ff00:: معتبر نیست.
عدد صحیحی که در ۱۲۸ بیت جای می‌گیرد. این معادل یک شبکه تک‌نشانی است که نشانی شبکه آن address و نقاب آن /128 است.
یک عدد صحیح بسته‌بندی‌شده در یک شیء bytes به طول ۱۶، با ترتیب بزرگ‌اندیان (big-endian). تفسیر آن مشابه یک نشانی عدد صحیحی است.
یک تاپل دوتایی شامل یک توصیف نشانی و یک نقاب شبکه، که در آن توصیف نشانی می‌تواند یک رشته، یک عدد صحیح ۱۲۸ بیتی، یک عدد صحیح فشرده ۱۶ بایتی، یا یک شیء IPv6Address موجود باشد؛ و نقاب شبکه یک عدد صحیح است که طول پیشوند را نشان می‌دهد.

اگر address یک نشانی IPv6 معتبر نباشد، یک AddressValueError پرتاب می‌شود. اگر نقاب برای یک نشانی IPv6 معتبر نباشد، یک NetmaskValueError پرتاب می‌شود.

تغییر یافته در نسخه‌ی 3.5: قالب دو-تایی (two-tuple) برای پارامتر address در سازنده افزوده شد.

version¶

max_prefixlen¶

is_multicast¶

is_private¶

is_unspecified¶

is_reserved¶

is_loopback¶

is_link_local¶

network_address¶

broadcast_address¶

hostmask¶

netmask¶

with_prefixlen¶

compressed¶

exploded¶

with_netmask¶

with_hostmask¶

num_addresses¶

prefixlen¶

hosts()¶: پیمایش‌گری بر روی میزبان‌های قابل‌استفاده در شبکه برمی‌گرداند. میزبان‌های قابل‌استفاده، تمام آدرس‌های IP متعلق به شبکه هستند، به‌جز آدرس Subnet-Router anycast. برای شبکه‌هایی با طول نقاب ۱۲۷، آدرس Subnet-Router anycast نیز در نتیجه گنجانده می‌شود. شبکه‌هایی با نقاب ۱۲۸، فهرستی حاوی آدرس میزبان واحد را برمی‌گردانند.

overlaps(other)¶

address_exclude(network)¶

subnets(prefixlen_diff=1, new_prefix=None)¶

supernet(prefixlen_diff=1, new_prefix=None)¶

subnet_of(other)¶

supernet_of(other)¶

compare_networks(other)¶: به مستندات ویژگی متناظر در IPv4Network مراجعه کنید.

is_site_local¶: این ویژگی برای کل شبکه درست است، اگر برای هر دو آدرس شبکه و آدرس پخش درست باشد.

عملگرها¶

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

عملگرهای منطقی¶

اشیای شبکه را می‌توان با مجموعه‌ی معمول عملگرهای منطقی مقایسه کرد. اشیای شبکه ابتدا بر اساس نشانی شبکه و سپس بر اساس نقاب شبکه مرتب می‌شوند.

پیمایش¶

می‌توان اشیای شبکه را پیمایش کرد تا همه‌ی آدرس‌های متعلق به شبکه فهرست شوند. در پیمایش، همه میزبان‌ها برگردانده می‌شوند، از جمله میزبان‌های غیرقابل استفاده (برای میزبان‌های قابل استفاده، از متد hosts() استفاده کنید). یک مثال:

>>> for addr in IPv4Network('192.0.2.0/28'):
...     addr
...
IPv4Address('192.0.2.0')
IPv4Address('192.0.2.1')
IPv4Address('192.0.2.2')
IPv4Address('192.0.2.3')
IPv4Address('192.0.2.4')
IPv4Address('192.0.2.5')
IPv4Address('192.0.2.6')
IPv4Address('192.0.2.7')
IPv4Address('192.0.2.8')
IPv4Address('192.0.2.9')
IPv4Address('192.0.2.10')
IPv4Address('192.0.2.11')
IPv4Address('192.0.2.12')
IPv4Address('192.0.2.13')
IPv4Address('192.0.2.14')
IPv4Address('192.0.2.15')

شبکه‌ها به‌عنوان ظرف‌هایی از آدرس‌ها¶

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

>>> IPv4Network('192.0.2.0/28')[0]
IPv4Address('192.0.2.0')
>>> IPv4Network('192.0.2.0/28')[15]
IPv4Address('192.0.2.15')
>>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
True
>>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
False

اشیای رابط¶

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

class ipaddress.IPv4Interface(address)¶

یک رابط IPv4 بسازید. معنای address همانند سازنده‌ی IPv4Network است، با این تفاوت که آدرس‌های میزبان دلخواه همیشه پذیرفته می‌شوند.

IPv4Interface زیرکلاسی از IPv4Address است، بنابراین تمام ویژگی‌ها را از آن کلاس به ارث می‌برد. علاوه بر این، ویژگی‌های زیر در دسترس هستند:

ip¶

نشانی (IPv4Address) بدون اطلاعات شبکه.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.ip
IPv4Address('192.0.2.5')

network¶

شبکه (IPv4Network) که این رابط به آن تعلق دارد.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.network
IPv4Network('192.0.2.0/24')

with_prefixlen¶

نمایش رشته‌ای رابط با نقاب در نماد پیشوندی.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_prefixlen
'192.0.2.5/24'

with_netmask¶

یک نمایش رشته‌ای از رابط، با شبکه به‌صورت نقاب شبکه.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_netmask
'192.0.2.5/255.255.255.0'

with_hostmask¶

یک نمایش رشته‌ای از رابط با شبکه به‌صورت نقاب میزبان.

>>> interface = IPv4Interface('192.0.2.5/24')
>>> interface.with_hostmask
'192.0.2.5/0.0.0.255'

class ipaddress.IPv6Interface(address)¶

یک رابط IPv6 بسازید. معنای address همانند سازنده‌ی IPv6Network است، با این تفاوت که نشانی‌های میزبان دلخواه همیشه پذیرفته می‌شوند.

IPv6Interface یک زیرکلاس از IPv6Address است، بنابراین تمام ویژگی‌های آن کلاس را به ارث می‌برد. علاوه بر این، ویژگی‌های زیر نیز در دسترس هستند:

ip¶

network¶

with_prefixlen¶

with_netmask¶

with_hostmask¶: به مستندات ویژگی مربوطه در IPv4Interface مراجعه کنید.

عملگرها¶

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

عملگرهای منطقی¶

اشیاء رابط را می‌توان با مجموعه‌ی معمول عملگرهای منطقی مقایسه کرد.

برای مقایسه‌ی برابری (== و !=)، برای این که اشیاء برابر باشند، هم آدرس IP و هم شبکه باید یکسان باشند. یک رابط با هیچ شیء آدرس یا شبکه‌ای برابر مقایسه نخواهد شد.

برای مرتب‌سازی (<، >، و غیره) قواعد متفاوت است. اشیاء رابط و نشانی با نسخه‌ی IP یکسان قابل مقایسه هستند و اشیاء نشانی همیشه پیش از اشیاء رابط مرتب می‌شوند. دو شیء رابط ابتدا بر اساس شبکه‌هایشان مقایسه می‌شوند و اگر آن‌ها یکسان باشند، سپس بر اساس آدرس‌های IP آن‌ها.

سایر توابع سطح ماژول¶

این ماژول همچنین توابع زیر را در سطح ماژول فراهم می‌کند:

ipaddress.v4_int_to_packed(address)¶

یک نشانی را به‌صورت ۴ بایت فشرده در ترتیب شبکه (big-endian) بازنمایی می‌کند. address یک بازنمایی از یک نشانی IP IPv4 به‌صورت عدد صحیح است. اگر عدد صحیح منفی باشد یا برای یک نشانی IP IPv4 بیش از حد بزرگ باشد، یک ValueError پرتاب می‌شود.

>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.v4_int_to_packed(3221225985)
b'\xc0\x00\x02\x01'

ipaddress.v6_int_to_packed(address)¶: یک نشانی را به‌صورت ۱۶ بایت فشرده با ترتیب شبکه (big-endian) نمایش می‌دهد. address نمایش یک نشانی IPv6 به‌صورت عدد صحیح است. اگر عدد صحیح منفی یا بیش از حد بزرگ برای یک نشانی IPv6 باشد، ValueError پرتاب می‌شود.

ipaddress.summarize_address_range(first, last)¶

یک پیمایش‌گر از محدوده شبکه خلاصه‌شده بر اساس اولین و آخرین آدرس IP برمی‌گرداند. first اولین IPv4Address یا IPv6Address در محدوده است و last آخرین IPv4Address یا IPv6Address در محدوده است. در صورتی که first یا last آدرس IP نباشند یا نسخه یکسانی نداشته باشند، یک TypeError پرتاب می‌شود. در صورتی که last بزرگ‌تر از first نباشد یا نسخه آدرس first ۴ یا ۶ نباشد، یک ValueError پرتاب می‌شود.

>>> [ipaddr for ipaddr in ipaddress.summarize_address_range(
...    ipaddress.IPv4Address('192.0.2.0'),
...    ipaddress.IPv4Address('192.0.2.130'))]
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]

ipaddress.collapse_addresses(addresses)¶

یک پیمایش‌گر از اشیای جمع‌شده‌ی IPv4Network یا IPv6Network برمی‌گرداند. addresses یک پیمایش‌پذیر از اشیای IPv4Network یا IPv6Network است. اگر addresses شامل اشیایی با نسخه‌های مختلط باشد، یک TypeError پرتاب می‌شود.

>>> [ipaddr for ipaddr in
... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
... ipaddress.IPv4Network('192.0.2.128/25')])]
[IPv4Network('192.0.2.0/24')]

ipaddress.get_mixed_type_key(obj)¶

کلیدی مناسب برای مرتب‌سازی میان شبکه‌ها و آدرس‌ها برمی‌گرداند. اشیاء Address و Network به‌طور پیش‌فرض قابل مرتب‌سازی نیستند؛ آن‌ها اساساً با هم متفاوت‌اند، بنابراین عبارت:

IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')

معنایی ندارد. با این حال، گاهی اوقات ممکن است بخواهید ipaddress این‌ها را به هر صورت مرتب‌سازی کند. اگر نیاز به این کار دارید، می‌توانید از این تابع به‌عنوان آرگومان key برای sorted() استفاده کنید.

obj یا یک شیء شبکه است یا یک شیء نشانی.

استثناهای سفارشی¶

برای پشتیبانی از گزارش‌دهی دقیق‌تر خطا از سازنده‌های کلاس، این ماژول استثناهای زیر را تعریف می‌کند:

exception ipaddress.AddressValueError(ValueError)¶: هر خطای مقدار مرتبط با نشانی.

exception ipaddress.NetmaskValueError(ValueError)¶: هر خطای مقدار مربوط به نقاب شبکه (net mask).

© حق نشر 2001 Python Software Foundation.
این صفحه تحت مجوز بنیاد نرم‌افزار پایتون نسخه ۲ منتشر شده است.
مثال‌ها، دستورالعمل‌ها، و سایر کدهای موجود در مستندات همچنین تحت مجوز بدون بند BSD منتشر شده‌اند.
برای اطلاعات بیشتر به تاریخچه و مجوز مراجعه کنید.

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

آخرین به‌روزرسانی در نوامبر 12, 2026 (06:19 UTC). آیا اشکالی یافتید؟
ساخته شده با Sphinx 9.1.0.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

GeezerVison

ipaddress --- کتابخانه‌ی دستکاری IPv4/IPv6¶

توابع کارخانه‌ای سهولت‌بخش¶

آدرس‌های IP¶

اشیای نشانی¶

تبدیل به رشته‌ها و اعداد صحیح¶

عملگرها¶

عملگرهای مقایسه¶

عملگرهای حسابی¶

تعاریف شبکه IP¶

پیشوند، نقاب شبکه و نقاب میزبان¶

اشیاء شبکه¶

عملگرها¶

عملگرهای منطقی¶

پیمایش¶

شبکه‌ها به‌عنوان ظرف‌هایی از آدرس‌ها¶

اشیای رابط¶

عملگرها¶

عملگرهای منطقی¶

سایر توابع سطح ماژول¶

استثناهای سفارشی¶

`ipaddress` --- کتابخانه‌ی دستکاری IPv4/IPv6¶