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 را از یکی از این موارد ایجاد کنید: رشتهای از ۳۲ رقم مبنای شانزده، رشتهای از ۱۶ بایت به ترتیب big-endian بهعنوان آرگومان bytes، رشتهای از ۱۶ بایت به ترتیب little-endian بهعنوان آرگومان 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 بهعنوان یک رشتهی ۱۶ بایتی (شامل شش فیلد عدد صحیح با ترتیب بایت big-endian).
- UUID.bytes_le¶
UUID بهصورت یک رشتهی ۱۶ بایتی (با time_low، time_mid و time_hi_version در ترتیب بایتهای little-endian).
- UUID.fields¶
تاپلی از ۶ فیلد عدد صحیحی UUID، که بهصورت ۶ ویژگی جداگانه و ۲ ویژگی مشتقشده نیز در دسترس هستند:
فیلد |
معنی |
|
نخستین ۳۲ بیت UUID. تنها به نسخهی 1 مربوط است. |
|
۱۶ بیت بعدی UUID. فقط به نسخه 1 مرتبط است. |
|
۱۶ بیت بعدی UUID. فقط به نسخه 1 مرتبط است. |
|
۸ بیت بعدی از UUID. فقط با نسخههای 1 و 6 مرتبط است. |
|
۸ بیت بعدی از UUID. فقط با نسخههای 1 و 6 مرتبط است. |
|
۴۸ بیت پایانی UUID. فقط به نسخهی 1 مربوط است. |
|
برچسب زمانی ۶۰ بیتی بهصورت تعداد بازههای ۱۰۰ نانوثانیهای از مبدأ زمانی گرگوری (1582-10-15 00:00:00) برای نسخههای 1 و 6، یا برچسب زمانی ۴۸ بیتی بر حسب میلیثانیه از مبدأ زمانی یونیکس (1970-01-01 00:00:00) برای نسخه 7. |
|
شمارهی دنبالهی ۱۴ بیتی. فقط مربوط به نسخههای 1 و 6. |
- UUID.hex¶
UUID بهصورت یک رشتهی ۳۲ نویسهای مبنای شانزده با حروف کوچک.
- UUID.int¶
UUID بهعنوان یک عدد صحیح ۱۲۸ بیتی.
- 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.
همچنین ملاحظه نمائید
- RFC 9562 - فضای نام URN برای شناسهی یکتای جهانی (UUID)
این مشخصات یک فضای نام Uniform Resource Name برای UUIDها، قالب داخلی UUIDها و روشهای تولید UUIDها را تعریف میکند.
استفاده از خط فرمان¶
اضافه شده در نسخهی 3.12.
ماژول uuid میتواند بهعنوان یک اسکریپت از خط فرمان اجرا شود.
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]
گزینههای زیر پذیرفته میشوند:
- -h, --help¶
نمایش پیام راهنما و خروج.
- -u <uuid>¶
- --uuid <uuid>¶
نام تابع مورد استفاده برای تولید uuid را مشخص کنید. بهطور پیشفرض از
uuid4()استفاده میشود.تغییر یافته در نسخهی 3.14: امکان تولید نسخههای 6، 7 و 8 UUID.
- -n <namespace>¶
- --namespace <namespace>¶
فضای نام یک
UUIDیا@nsاست، که در آنnsیک UUID از پیش تعریفشده و شناختهشده است که با نام فضای نام به آن اشاره میشود. مانند@dns،@url،@oidو@x500. فقط برای توابعuuid3()/uuid5()لازم است.
مثال¶
در ادامه چند نمونه از کاربردهای معمول ماژول uuid آمده است:
>>> 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 string
>>> 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')
مثال خط فرمان¶
در اینجا نمونههایی از کاربرد رایج رابط خط فرمان uuid آمده است:
# 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