uuid --- RFC 4122 に従った UUID オブジェクト

ソースコード: Lib/uuid.py


このモジュールでは immutable (変更不能) な UUID オブジェクト (UUID クラス) と RFC 4122 の定めるバージョン 1、3、4、5 の UUID を生成するための uuid1(), uuid3(), uuid4(), uuid5(), が提供されています。

もしユニークな ID が必要なだけであれば、おそらく uuid1()uuid4() を呼び出せば良いでしょう。 uuid1() はコンピュータのネットワークアドレスを含む UUID を生成するためにプライバシーを侵害するかもしれない点に注意してください。 uuid4() はランダムな UUID を生成します。

Depending on support from the underlying platform, uuid1() may or may not return a "safe" UUID. A safe UUID is one which is generated using synchronization methods that ensure no two processes can obtain the same UUID. All instances of UUID have an is_safe attribute which relays any information about the UUID's safety, using this enumeration:

class uuid.SafeUUID

Added in version 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)

32 桁の 16 進数文字列、bytes に 16 バイトのビッグエンディアンの文字列、bytes_le 引数に 16 バイトのリトルエンディアンの文字列、fields 引数に 6 つの整数のタプル(32ビット time_low, 16 ビット time_mid, 16ビット time_hi_version, 8ビット clock_seq_hi_variant, 8ビット clock_seq_low, 48ビット node )、または int に一つの 128 ビット整数のいずれかから UUID を生成します。16 進数が与えられた時、波括弧、ハイフン、それと 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 は与えられた hex, bytes, bytes_le, fields, または int をオーバーライドして、RFC 4122 に準拠した variant と version ナンバーのセットを持つことになります。bytes_le, fields, or int.

2つのUUIDオブジェクトの比較は、UUID.int 属性の比較によって行われます。UUIDではないオブジェクトとの比較は、 TypeError を送出します。

str(uuid) は 32桁の16進でUUIDを表す``12345678-1234-5678-1234-567812345678`` 形式の文字列を返します。

UUID インスタンスは以下の読み出し専用属性を持ちます:

UUID.bytes

16 バイト文字列(バイトオーダーがビッグエンディアンの 6 つの整数フィールドを持つ)のUUID。

UUID.bytes_le

16 バイト文字列( time_low, time_mid, time_hi_version をリトルエンディアンで持つ)の UUID。

UUID.fields

UUID の 6 つの整数フィールドを持つタプルで、これは 6 つの個別の属性と 2 つの派生した属性としても取得可能です:

フィールド

意味

UUID.time_low

The first 32 bits of the UUID.

UUID.time_mid

The next 16 bits of the UUID.

UUID.time_hi_version

The next 16 bits of the UUID.

UUID.clock_seq_hi_variant

The next 8 bits of the UUID.

UUID.clock_seq_low

The next 8 bits of the UUID.

UUID.node

The last 48 bits of the UUID.

UUID.time

The 60-bit timestamp.

UUID.clock_seq

The 14-bit sequence number.

UUID.hex

32 文字の小文字 16 進数文字列での UUID。

UUID.int

128 ビット整数での UUID。

UUID.urn

RFC 4122 で規定される URN での UUID。

UUID.variant

UUID の内部レイアウトを決定する UUID の variant。これは定数 RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, RESERVED_FUTURE のいずれかです。

UUID.version

UUID の version 番号(1 から 5、variant が RFC_4122 である場合だけ意味があります)。

UUID.is_safe

SafeUUID の列挙で、UUID は並列処理に対して安全なプラットフォームで生成されたかを示す。

Added in version 3.7.

The uuid モジュールには以下の関数があります:

uuid.getnode()

48 ビットの正の整数としてハードウェアアドレスを取得します。最初にこれを起動すると、別個のプログラムが立ち上がって非常に遅くなることがあります。もしハードウェアを取得する試みが全て失敗すると、ランダムな 48 ビットを、RFC 4122 で推奨されているように、マルチキャストビット (最初のオクテットの最下位ビット) を 1 に設定して使います。"ハードウェアアドレス" とはネットワークインターフェースの MAC アドレスを指します。複数のネットワークインターフェースを持つマシンの場合、全域管理されたMACアドレス (最初のオクテットの下位より2番目のビットが 設定されていない MACアドレス) が、他の個別管理アドレスよりも優先的に使用されます。この優先順序は保証されません。

バージョン 3.7 で変更: 全域管理されたMACアドレスは、グローバルに固有であると保証されるため、固有である保証のない個別管理アドレスよりも好ましいです。

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

UUID をホスト ID、シーケンス番号、現在時刻から生成します。 node が与えられなければ、 getnode() がハードウェアアドレス取得のために使われます。 clock_seq が与えられると、これはシーケンス番号として使われます; さもなくば 14 ビットのランダムなシーケンス番号が選ばれます。

uuid.uuid3(namespace, name)

Generate a UUID based on the MD5 hash of a namespace identifier (which is a UUID) and a name (which is a bytes object or a string that will be encoded using UTF-8).

uuid.uuid4()

ランダムな UUID を生成します。

uuid.uuid5(namespace, name)

Generate a UUID based on the SHA-1 hash of a namespace identifier (which is a UUID) and a name (which is a bytes object or a string that will be encoded using UTF-8).

uuid モジュールは uuid3() または uuid5() で利用するために次の名前空間識別子を定義しています。

uuid.NAMESPACE_DNS

この名前空間が指定された場合、name 文字列は完全修飾ドメイン名です。

uuid.NAMESPACE_URL

この名前空間が指定された場合、name 文字列は URL です。

uuid.NAMESPACE_OID

この名前空間が指定された場合、name 文字列は ISO OID です。

uuid.NAMESPACE_X500

この名前空間が指定された場合、name 文字列は X.500 DN の DER またはテキスト出力形式です。

The uuid module defines the following constants for the possible values of the variant attribute:

uuid.RESERVED_NCS

NCS 互換性のために予約されています。

uuid.RFC_4122

RFC 4122 で与えられた UUID レイアウトを指定します。

uuid.RESERVED_MICROSOFT

Microsoft の互換性のために予約されています。

uuid.RESERVED_FUTURE

将来のために予約されています。

参考

RFC 4122 - Universally Unique IDentifier (UUID) の URN 名前空間

この仕様は UUID のための Uniform Resource Name 名前空間、UUID の内部フォーマットと UUID の生成方法を定義しています。

コマンドラインからの使用

Added in version 3.12.

The uuid module can be executed as a script from the command line.

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

以下のオプションが使用できます:

-h, --help

ヘルプメッセージを表示して終了します。

-u <uuid>
--uuid <uuid>

Specify the function name to use to generate the uuid. By default uuid4() is used.

-n <namespace>
--namespace <namespace>

The namespace is a UUID, or @ns where ns is a well-known predefined UUID addressed by namespace name. Such as @dns, @url, @oid, and @x500. Only required for uuid3() / uuid5() functions.

-N <name>
--name <name>

The name used as part of generating the uuid. Only required for uuid3() / uuid5() functions.

使用例

典型的な 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')

Command-Line Example

Here are some examples of typical usage of the uuid command line interface:

# 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