uuid --- اشیای UUID مطابق RFC 9562¶

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

این ماژول اشیای تغییرناپذیر UUID (کلاس UUID) و توابع را برای تولید UUIDهای متناظر با یک نسخه‌ی خاص از UUID، همان‌طور که در RFC 9562 (که جایگزین RFC 4122 شده است) مشخص شده است، فراهم می‌کند؛ برای مثال، uuid1() برای نسخه‌ی 1 UUID، uuid3() برای نسخه‌ی 3 UUID، و غیره. توجه داشته باشید که نسخه‌ی 2 UUID عمداً حذف شده است، زیرا خارج از محدوده‌ی RFC است.

اگر تنها چیزی که می‌خواهید یک شناسه‌ی یکتا است، احتمالاً باید uuid1() یا uuid4() را فراخوانی کنید. توجه داشته باشید که uuid1() ممکن است حریم خصوصی را به خطر بیندازد، زیرا یک UUID حاوی نشانی شبکه‌ی رایانه ایجاد می‌کند. uuid4() یک UUID تصادفی ایجاد می‌کند.

بسته به پشتیبانی پلتفرم زیربنایی، ممکن است uuid1() یک UUID «امن» برگرداند یا نه. UUID امن UUIDای است که با استفاده از روش‌های همگام‌سازی تولید شده است؛ این روش‌ها تضمین می‌کنند که هیچ دو فرآیندی نمی‌توانند UUID یکسانی را به دست آورند. همه نمونه‌های UUID دارای ویژگی is_safe هستند که هرگونه اطلاعات مربوط به امنیت UUID را با استفاده از این شمارش منتقل می‌کند:

class uuid.SafeUUID¶

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

safe¶

UUID توسط پلتفرم به‌صورت امن برای چندفرایندی تولید شد.

unsafe¶

UUID به‌صورت ایمن برای چندپردازشی تولید نشده است.

unknown¶

پلتفرم اطلاعاتی درباره‌ی اینکه UUID به‌صورت ایمن تولید شده است یا خیر ارائه نمی‌دهد.

class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)¶

یک UUID از یک رشته‌ی ۳۲ رقمی در مبنای شانزده، یک شیء bytes شانزده‌بایتی با ترتیب بزرگ‌اندیان به عنوان آرگومان bytes، یک شیء bytes شانزده‌بایتی با ترتیب کوچک‌اندیان به عنوان آرگومان bytes_le، یک تاپل از شش عدد صحیح (۳۲ بیتی time_low، ۱۶ بیتی time_mid، ۱۶ بیتی time_hi_version، ۸ بیتی clock_seq_hi_variant، ۸ بیتی clock_seq_low، ۴۸ بیتی node) به عنوان آرگومان fields، یا یک عدد صحیح منفرد ۱۲۸ بیتی به عنوان آرگومان int ایجاد کنید. هنگامی که یک رشته از ارقام مبنای شانزده داده می‌شود، آکولادها، خط تیره و پیشوند URN همگی اختیاری هستند. به عنوان مثال، این عبارت‌ها همگی همان UUID را تولید می‌کنند:

UUID('{12345678-1234-5678-1234-567812345678}')
UUID('12345678123456781234567812345678')
UUID('urn:uuid:12345678-1234-5678-1234-567812345678')
UUID(bytes=b'\x12\x34\x56\x78'*4)
UUID(bytes_le=b'\x78\x56\x34\x12\x34\x12\x78\x56' +
              b'\x12\x34\x56\x78\x12\x34\x56\x78')
UUID(fields=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678))
UUID(int=0x12345678123456781234567812345678)

باید دقیقاً یکی از hex، bytes، bytes_le، fields یا int داده شود. آرگومان version اختیاری است؛ اگر داده شود، UUID حاصل از نظر گونه و شماره نسخه مطابق RFC 9562 تنظیم می‌شود و بیت‌های موجود در hex، bytes، bytes_le، fields یا int داده‌شده را بازنویسی می‌کند.

مقایسه‌ی اشیای UUID از طریق مقایسه‌ی ویژگی‌های UUID.int آن‌ها انجام می‌شود. مقایسه با یک شیء غیر UUID باعث پرتاب یک TypeError می‌شود.

str(uuid) رشته‌ای به شکل 12345678-1234-5678-1234-567812345678 برمی‌گرداند که در آن ۳۲ رقم مبنای شانزده، UUID را نشان می‌دهند.

نمونه‌های UUID این ویژگی‌های فقط‌خواندنی را دارند:

UUID.bytes¶

شناسه‌ی UUID به عنوان یک شیء bytes شانزده‌بایتی (که شامل شش فیلد عدد صحیح با ترتیب بایت بزرگ‌اندیان است).

UUID.bytes_le¶

شناسه‌ی UUID به عنوان یک شیء bytes شانزده‌بایتی (با فیلدهای time_low، time_mid و time_hi_version با ترتیب بایت کوچک‌اندیان).

UUID.fields¶

تاپلی از ۶ فیلد عدد صحیحی UUID، که به‌صورت ۶ ویژگی جداگانه و ۲ ویژگی مشتق‌شده نیز در دسترس هستند:

UUID.hex¶

UUID به‌صورت یک رشته‌ی ۳۲ نویسه‌ای مبنای شانزده با حروف کوچک.

UUID.int¶

UUID به‌عنوان یک عدد صحیح ۱۲۸ بیتی.

UUID.urn¶

UUID به‌صورت URN، همان‌طور که در RFC 9562 مشخص شده است.

UUID.variant¶

گونه‌ی UUID، که چیدمان داخلی UUID را تعیین می‌کند. این یکی از ثابت‌های RESERVED_NCS، RFC_4122، RESERVED_MICROSOFT یا RESERVED_FUTURE خواهد بود.

UUID.version¶

شماره نسخه UUID (از ۱ تا ۸، فقط زمانی معنادار است که variant برابر RFC_4122 باشد).

تغییر یافته در نسخه‌ی 3.14: نسخه‌های 6، 7 و 8 UUID افزوده شدند.

UUID.is_safe¶

یک شمارش از SafeUUID که نشان می‌دهد آیا پلتفرم UUID را به‌صورت امن در چندپردازشی تولید کرده است.

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

ماژول uuid توابع زیر را تعریف می‌کند:

uuid.getnode()¶

آدرس سخت‌افزاری را به‌صورت یک عدد صحیح مثبت ۴۸‌بیتی دریافت کنید. در اولین اجرا، ممکن است برنامه‌ای جداگانه راه‌اندازی شود که می‌تواند نسبتاً کند باشد. اگر تمام تلاش‌ها برای به‌دست آوردن آدرس سخت‌افزاری ناموفق باشند، یک عدد ۴۸‌بیتی تصادفی انتخاب می‌شود که بیت چندپخشی آن (کم‌ارزش‌ترین بیت اولین هشت‌بیتی) روی ۱ تنظیم شده است، همان‌طور که در RFC 4122 توصیه شده است. منظور از «آدرس سخت‌افزاری»، آدرس MAC یک رابط شبکه است. در ماشینی با چندین رابط شبکه، آدرس‌های MAC با مدیریت جهانی (یعنی جایی که دومین بیت کوچک‌اندیان هشت‌بیتی تنظیم‌نشده است) بر آدرس‌های MAC با مدیریت محلی ترجیح داده می‌شوند، اما هیچ تضمین دیگری برای ترتیب وجود ندارد.

تغییر یافته در نسخه‌ی 3.7: نشانی‌های MAC با مدیریت جهانی بر نشانی‌های MAC با مدیریت محلی ترجیح داده می‌شوند، زیرا تضمین شده است که نشانی‌های نوع اول به‌صورت جهانی یکتا هستند، اما نشانی‌های نوع دوم این‌گونه نیستند.

uuid.uuid1(node=None, clock_seq=None)¶

یک UUID بر اساس شناسه میزبان، شماره دنباله و زمان فعلی مطابق RFC 9562, §5.1 تولید کنید.

هنگامی که node مشخص نشده باشد، از getnode() برای به‌دست آوردن آدرس سخت‌افزاری به‌عنوان یک عدد صحیح مثبت ۴۸ بیتی استفاده می‌شود. هنگامی که شماره‌ی دنباله‌ی clock_seq مشخص نشده باشد، یک عدد صحیح مثبت ۱۴ بیتی شبه‌تصادفی تولید می‌شود.

اگر node یا clock_seq از تعداد بیت مورد انتظار خود بیشتر باشند، تنها کم‌ارزش‌ترین بیت‌های آن‌ها نگه داشته می‌شوند.

uuid.uuid3(namespace, name)¶

یک UUID بر اساس هش MD5 شناسه‌ی فضای نام (که یک UUID است) و یک نام (که یک شیء bytes یا رشته‌ای است که با استفاده از UTF-8 کدگذاری خواهد شد) مطابق با RFC 9562, §5.3 تولید کنید.

uuid.uuid4()¶

یک UUID تصادفی را به روشی امن از نظر رمزنگاری، مطابق با RFC 9562, §5.4 تولید کنید.

uuid.uuid5(namespace, name)¶

یک UUID بر اساس هش SHA-1 شناسه‌ی فضای نام (که یک UUID است) و یک نام (که یک شیء bytes یا رشته‌ای است که با استفاده از UTF-8 کدگذاری می‌شود) مطابق با RFC 9562, §5.5 ایجاد کنید.

uuid.uuid6(node=None, clock_seq=None)¶

یک UUID را از یک شماره‌ی دنباله و زمان جاری مطابق RFC 9562, §5.6 تولید کنید.

این جایگزینی برای uuid1() است تا محلی بودن پایگاه داده (database locality) را بهبود بخشد.

هنگامی که node مشخص نشده باشد، از getnode() برای به‌دست آوردن آدرس سخت‌افزاری به‌عنوان یک عدد صحیح مثبت ۴۸ بیتی استفاده می‌شود. هنگامی که شماره‌ی دنباله‌ی clock_seq مشخص نشده باشد، یک عدد صحیح مثبت ۱۴ بیتی شبه‌تصادفی تولید می‌شود.

اگر node یا clock_seq از تعداد بیت مورد انتظار خود بیشتر باشند، تنها کم‌ارزش‌ترین بیت‌های آن‌ها نگه داشته می‌شوند.

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

uuid.uuid7()¶

یک UUID مبتنی بر زمان مطابق با RFC 9562, §5.7 تولید کنید.

برای قابلیت حمل بین سکوهای فاقد دقت زیرمیلی‌ثانیه، UUIDهای تولیدشده توسط این تابع، یک برچسب زمانی ۴۸ بیتی را تعبیه می‌کنند و از یک شمارنده ۴۲ بیتی برای تضمین یکنواختی در یک میلی‌ثانیه استفاده می‌کنند.

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

uuid.uuid8(a=None, b=None, c=None)¶

یک UUID شبه‌تصادفی مطابق با RFC 9562, §5.8 تولید کنید.

در صورت مشخص شدن، انتظار می‌رود پارامترهای a، b و c به‌ترتیب اعداد صحیح مثبت ۴۸ بیتی، ۱۲ بیتی و ۶۲ بیتی باشند. اگر از تعداد بیت مورد انتظارشان بیشتر باشند، تنها کم‌ارزش‌ترین بیت‌های آن‌ها نگه داشته می‌شود؛ آرگومان‌های مشخص‌نشده با یک عدد صحیح شبه‌تصادفی با اندازه‌ی مناسب جایگزین می‌شوند.

به‌طور پیش‌فرض، a، b و c توسط یک تولیدگر عدد شبه‌تصادفی امن از نظر رمزنگاری (CSPRNG) تولید نمی‌شوند. هرگاه نیاز به استفاده از یک UUID در زمینه‌ای حساس به امنیت باشد، از uuid4() استفاده کنید.

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

ماژول uuid شناسه‌های فضای نام زیر را برای استفاده با uuid3() یا uuid5() تعریف می‌کند.

uuid.NAMESPACE_DNS¶

هنگامی که این فضای نام مشخص شده باشد، رشته‌ی name یک نام دامنه‌ی کاملاً واجد شرایط (fully qualified domain name) است.

uuid.NAMESPACE_URL¶

هنگامی که این فضای نام مشخص شده باشد، رشته name یک نشانی وب (URL) است.

uuid.NAMESPACE_OID¶

هنگامی که این فضای نام مشخص شده باشد، رشته‌ی name یک ISO OID است.

uuid.NAMESPACE_X500¶

هنگامی که این فضای نام مشخص شده باشد، رشته‌ی name یک X.500 DN در قالب DER یا قالب خروجی متنی است.

ماژول uuid ثابت‌های زیر را برای مقادیر ممکنِ ویژگی variant تعریف می‌کند:

uuid.RESERVED_NCS¶

برای سازگاری با NCS رزرو شده است.

uuid.RFC_4122¶

چیدمان UUID ارائه‌شده در RFC 4122 را مشخص می‌کند. این ثابت برای سازگاری با عقب‌گرد نگه داشته شده است، حتی با وجود اینکه RFC 4122 با RFC 9562 جایگزین شده است.

uuid.RESERVED_MICROSOFT¶

برای سازگاری با مایکروسافت رزروشده است.

uuid.RESERVED_FUTURE¶

برای تعریف آینده محفوظ است.

ماژول uuid مقادیر خاص Nil و Max UUID را تعریف می‌کند:

uuid.NIL¶

شکل ویژه‌ای از UUID که طبق RFC 9562, §5.9، تمام ۱۲۸ بیت آن صفر تعیین شده‌اند.

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

uuid.MAX¶

شکل ویژه‌ای از UUID که طبق RFC 9562, §5.10 مشخص شده است که تمام ۱۲۸ بیت آن روی مقدار ۱ تنظیم شده‌اند.

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

python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]

>>> import uuid

>>> # make a UUID based on the host ID and current time
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # make a UUID using an MD5 hash of a namespace UUID and a name
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # make a random UUID
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # make a UUID using a SHA-1 hash of a namespace UUID and a name
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # make a UUID from a string of hex digits (braces and hyphens ignored)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')

>>> # convert a UUID to a string of hex digits in standard form
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # get the raw 16 bytes of the UUID
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # make a UUID from a 16-byte bytes object
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

>>> # get the Nil UUID
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

>>> # get the Max UUID
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

>>> # same as UUIDv1 but with fields reordered to improve DB locality
>>> uuid.uuid6()
UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')

>>> # get UUIDv7 creation (local) time as a timestamp in milliseconds
>>> u = uuid.uuid7()
>>> u.time
1743936859822

>>> # get UUIDv7 creation (local) time as a datetime object
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)

>>> # make a UUID with custom blocks
>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
UUID('00001234-5678-8ef0-8000-000011223344')

# generate a random UUID - by default uuid4() is used
$ python -m uuid

# generate a UUID using uuid1()
$ python -m uuid -u uuid1

# generate a UUID using uuid5
$ python -m uuid -u uuid5 -n @url -N example.com

# generate 42 random UUIDs
$ python -m uuid -C 42