`uuid` --- RFC 9562 に基づく UUID オブジェクト¶

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

このモジュールは、イミュータブルな UUID オブジェクト (UUID クラス) と、 RFC 9562 (RFC 4122 を置き換える RFC) で規定された特定のバージョンの UUID を生成する関数を提供します。例えば uuid1() はバージョン 1、uuid3() はバージョン 3 の UUID を生成します。 UUID バージョン 2 は RFC の対象外であるため、意図的に省かれています。

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

uuid1() が「安全な」UUID を返すかどうかは、基盤となるプラットフォームの対応状況によります。安全な UUID とは、2 つのプロセスが同じ UUID を取得しないよう保証する同期手段を使って生成されたものです。 UUID のすべてのインスタンスは is_safe 属性を持ち、以下の列挙値によって UUID の安全性についての情報を伝えます:

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)¶

以下のいずれかから UUID を作成します: 32 桁の 16 進数文字列、 bytes 引数に指定したビッグエンディアンの 16 バイトの bytes オブジェクト、 bytes_le 引数に指定したリトルエンディアンの 16 バイトの bytes オブジェクト、 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 ビット整数です。 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 のうち、必ず 1 つだけを指定しなければなりません。 version 引数は省略可能です。指定すると、生成される UUID のバリアントとバージョン番号が RFC 9562 に従って設定され、指定した hex、bytes、bytes_le、fields、int の該当ビットを上書きします。

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

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

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

UUID.bytes¶: 16 バイトの bytes オブジェクトとしての UUID です (6 つの整数フィールドをビッグエンディアンのバイト順で格納します)。

UUID.bytes_le¶: 16 バイトの bytes オブジェクトとしての UUID です (time_low、time_mid、time_hi_version をリトルエンディアンのバイト順で格納します)。

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

フィールド	意味
UUID.time_low¶	UUID の最初の 32 ビットです。バージョン 1 にだけ関係します。
UUID.time_mid¶	UUID の次の 16 ビットです。バージョン 1 にだけ関係します。
UUID.time_hi_version¶	UUID の次の 16 ビットです。バージョン 1 にだけ関係します。
UUID.clock_seq_hi_variant¶	UUID の次の 8 ビットです。バージョン 1 と 6 にだけ関係します。
UUID.clock_seq_low¶	UUID の次の 8 ビットです。バージョン 1 と 6 にだけ関係します。
UUID.node¶	The last 48 bits of the UUID. Only relevant to version 1.
UUID.time¶	バージョン 1 と 6 では、グレゴリオ暦の起点 (1582-10-15 00:00:00) からの経過時間を 100 ナノ秒単位で表す 60 ビットのタイムスタンプです。バージョン 7 では、Unix エポック (1970-01-01 00:00:00) からの経過時間をミリ秒単位で表す 48 ビットのタイムスタンプです。
UUID.clock_seq¶	14 ビットのシーケンス番号です。バージョン 1 と 6 にだけ関係します。

UUID.hex¶: 32 文字の小文字 16 進数文字列での UUID。

UUID.int¶: 128 ビット整数での UUID。

UUID.urn¶: RFC 9562 で規定された URN としての UUID です。

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

UUID.version¶: UUID のバージョン番号です (1 から 8 までで、バリアントが RFC_4122 の場合にだけ意味を持ちます)。

バージョン 3.14 で変更: UUID バージョン 6、7、8 を追加しました。

UUID.is_safe¶: プラットフォームが複数プロセスでの利用に対して安全な方法で UUID を生成したかどうかを示す SafeUUID の列挙値。

Added in version 3.7.

uuid モジュールは以下の関数を定義しています:

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

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

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

RFC 9562, §5.1 に従い、ホスト ID、シーケンス番号、現在時刻から UUID を生成します。

When node is not specified, getnode() is used to obtain the hardware address as a 48-bit positive integer. When a sequence number clock_seq is not specified, a pseudo-random 14-bit positive integer is generated.

node または clock_seq が想定されたビット数を超える場合は、下位のビットだけを保持します。

uuid.uuid3(namespace, name)¶: RFC 9562, §5.3 に従い、名前空間識別子 (UUID) と名前 (bytes オブジェクト、または UTF-8 でエンコードされる文字列) の MD5 ハッシュに基づいて UUID を生成します。

uuid.uuid4()¶: RFC 9562, §5.4 に従い、暗号学的に安全な方法でランダムな UUID を生成します。

uuid.uuid5(namespace, name)¶: RFC 9562, §5.5 に従い、名前空間識別子 (UUID) と名前 (bytes オブジェクト、または UTF-8 でエンコードされる文字列) の SHA-1 ハッシュに基づいて UUID を生成します。

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

RFC 9562, §5.6 に従い、シーケンス番号と現在時刻から UUID を生成します。

データベース内での局所性を改善するための、uuid1() の代替です。

When node is not specified, getnode() is used to obtain the hardware address as a 48-bit positive integer. When a sequence number clock_seq is not specified, a pseudo-random 14-bit positive integer is generated.

node または clock_seq が想定されたビット数を超える場合は、下位のビットだけを保持します。

Added in version 3.14.

uuid.uuid7()¶

RFC 9562, §5.7 に従い、時刻に基づく UUID を生成します。

ミリ秒未満の精度を持たないプラットフォームでも使えるように、この関数が生成する UUID は 48 ビットのタイムスタンプを埋め込み、 42 ビットのカウンターによって同一ミリ秒内での単調性を保証します。

Added in version 3.14.

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

RFC 9562, §5.8 に従い、疑似乱数の UUID を生成します。

When specified, the parameters a, b and c are expected to be positive integers of 48, 12 and 62 bits respectively. If they exceed their expected bit count, only their least significant bits are kept; non-specified arguments are substituted for a pseudo-random integer of appropriate size.

デフォルトでは、a、b、c は暗号学的に安全な疑似乱数生成器 (CSPRNG) では生成されません。セキュリティが重要な用途で UUID を使う必要がある場合は、uuid4() を使ってください。

Added in version 3.14.

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 またはテキスト出力形式です。

uuid モジュールは、variant 属性が取り得る値として、以下の定数を定義しています:

uuid.RESERVED_NCS¶: NCS 互換性のために予約されています。

uuid.RFC_4122¶: RFC 4122 で規定された UUID のレイアウトを指定します。 RFC 4122 は RFC 9562 に置き換えられましたが、後方互換性のためにこの定数は残されています。

uuid.RESERVED_MICROSOFT¶: Microsoft の互換性のために予約されています。

uuid.RESERVED_FUTURE¶: 将来のために予約されています。

uuid モジュールは、特殊な UUID 値である Nil と Max を定義しています:

uuid.NIL¶: RFC 9562, §5.9 に従い、128 ビットすべてを 0 に設定するよう規定された特殊な形式の UUID です。

Added in version 3.14.

uuid.MAX¶: RFC 9562, §5.10 に従い、128 ビットすべてを 1 に設定するよう規定された特殊な形式の UUID です。

Added in version 3.14.

参考

RFC 9562 - 汎用一意識別子 (UUID) の URN 名前空間: この仕様は UUID のための Uniform Resource Name 名前空間、UUID の内部フォーマットと UUID の生成方法を定義しています。

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

Added in version 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 で変更: UUID バージョン 6、7、8 を生成できるようになりました。

-n <namespace>¶
--namespace <namespace>¶: 名前空間には UUID、または名前空間名で指定する既知の定義済み UUID を表す @ns を指定します。例えば @dns、@url、@oid、@x500 です。 uuid3() と uuid5() の関数でだけ必要です。

-N <name>¶
--name <name>¶: UUID の生成に使う名前です。 uuid3() と uuid5() の関数でだけ必要です。

-C <num>¶
--count <num>¶: 新しい UUID を num 個生成します。

Added in version 3.14.

使用例¶

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 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')

コマンドラインでの使用例¶

uuid のコマンドラインインターフェースの典型的な使用例を示します:

# ランダムな UUID を生成する。
# デフォルトでは uuid4() を使用する
$ python -m uuid

# uuid1() で UUID を生成する
$ python -m uuid -u uuid1

# uuid5 で UUID を生成する
$ python -m uuid -u uuid5 -n @url -N example.com

# ランダムな UUID を 42 個生成する
$ python -m uuid -C 42

`uuid` --- RFC 9562 に基づく UUID オブジェクト¶

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

使用例¶

コマンドラインでの使用例¶

目次

前のトピックへ

次のトピックへ

このページ

uuid --- RFC 9562 に基づく UUID オブジェクト¶

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

使用例¶

コマンドラインでの使用例¶

`uuid` --- RFC 9562 に基づく UUID オブジェクト¶