"uuid" --- UUID objects according to **RFC 9562**
*************************************************

**소스 코드:** Lib/uuid.py

======================================================================

This module provides immutable "UUID" objects (the "UUID" class) and
functions for generating UUIDs corresponding to a specific UUID
version as specified in **RFC 9562** (which supersedes **RFC 4122**),
for example, "uuid1()" for UUID version 1, "uuid3()" for UUID version
3, and so on. Note that UUID version 2 is deliberately omitted as it
is outside the scope of the RFC.

고유 ID만을 얻고자 한다면 "uuid1()" 또는 "uuid4()"를 호출하는 것이 좋
습니다. "uuid1()" 함수는 컴퓨터의 네트워크 주소를 포함하여 UUID를 생성
하므로 개인정보가 노출될 수 있음을 명심해야 합니다. "uuid4()"는 무작위
UUID를 생성합니다.

기본 플랫폼의 지원 여부에 따라, "uuid1()"은 "안전한" UUID를 반환하거나
그렇지 않을 수도 있습니다. 안전한 UUID는 두 프로세스가 같은 UUID를 얻
지 못하게 하는 동기화 메서드에 의해 생성됩니다. "UUID"의 모든 인스턴스
는 UUID의 안정성에 대한 정보를 중계하는 "is_safe" 어트리뷰트가 있고,
다음의 열거체를 사용합니다.

class uuid.SafeUUID

   Added in version 3.7.

   safe

      플랫폼이 다중 프로세스에 안전한 방식으로 UUID를 생성합니다.

   unsafe

      다중 프로세스에 안전한 방식으로 생성되지 않습니다.

   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* 인자에 여섯
   개의 정수로 이루어진 튜플(32-bit *time_low*, 16-bit *time_mid*,
   16-bit *time_hi_version*, 8-bit *clock_seq_hi_variant*, 8-bit
   *clock_seq_low*, 48-bit *node*), *int* 인자에 단일 128bit 정수 중
   하나를 이용하여 UUID를 만듭니다. 16진수 문자열로 주어졌을 경우 중괄
   호, 붙임표(hyphen), 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)

   Exactly one of *hex*, *bytes*, *bytes_le*, *fields*, or *int* must
   be given. The *version* argument is optional; if given, the
   resulting UUID will have its variant and version number set
   according to **RFC 9562**, overriding bits in the given *hex*,
   *bytes*, *bytes_le*, *fields*, or *int*.

   UUID 객체끼리 비교할 때 "UUID.int" 어트리뷰트를 비교하여 수행합니다
   . UUID가 아닌 객체와 비교하면 "TypeError"가 발생합니다.

   "str(uuid)"는 "12345678-1234-5678-1234-567812345678"과같이 32자리
   16진수 UUID로 표현합니다.

"UUID" 객체는 다음과 같은 읽기 전용 어트리뷰트를 갖습니다.

UUID.bytes

   16바이트 문자열(여섯 개의 빅 엔디안 순서 정수 필드 포함)인 UUID

UUID.bytes_le

   16바이트 문자열(리틀 엔디안 순서 *time_low*, *time_mid*,
   *time_hi_version*)인 UUID

UUID.fields

   UUID의 여섯 개의 정수 필드로 이루어진 튜플. 여섯 개의 개별 어트리뷰
   트와 두 개의 파생된 어트리뷰트도 사용 가능:

+----------------------------------------------------+----------------------------------------------------+
| 필드                                               | 의미                                               |
+----------------------------------------------------+----------------------------------------------------+
| UUID.time_low                                      | The first 32 bits of the UUID. Only relevant to    |
|                                                    | version 1.                                         |
+----------------------------------------------------+----------------------------------------------------+
| UUID.time_mid                                      | The next 16 bits of the UUID. Only relevant to     |
|                                                    | version 1.                                         |
+----------------------------------------------------+----------------------------------------------------+
| UUID.time_hi_version                               | The next 16 bits of the UUID. Only relevant to     |
|                                                    | version 1.                                         |
+----------------------------------------------------+----------------------------------------------------+
| UUID.clock_seq_hi_variant                          | The next 8 bits of the UUID. Only relevant to      |
|                                                    | versions 1 and 6.                                  |
+----------------------------------------------------+----------------------------------------------------+
| UUID.clock_seq_low                                 | The next 8 bits of the UUID. Only relevant to      |
|                                                    | versions 1 and 6.                                  |
+----------------------------------------------------+----------------------------------------------------+
| UUID.node                                          | The last 48 bits of the UUID. Only relevant to     |
|                                                    | version 1.                                         |
+----------------------------------------------------+----------------------------------------------------+
| UUID.time                                          | The 60-bit timestamp as a count of 100-nanosecond  |
|                                                    | intervals since Gregorian epoch (1582-10-15        |
|                                                    | 00:00:00) for versions 1 and 6, or the 48-bit      |
|                                                    | timestamp in milliseconds since Unix epoch         |
|                                                    | (1970-01-01 00:00:00) for version 7.               |
+----------------------------------------------------+----------------------------------------------------+
| UUID.clock_seq                                     | The 14-bit sequence number. Only relevant to       |
|                                                    | versions 1 and 6.                                  |
+----------------------------------------------------+----------------------------------------------------+

UUID.hex

   32자리 소문자 16진수 문자열 UUID.

UUID.int

   128bit 정수 UUID

UUID.urn

   The UUID as a URN as specified in **RFC 9562**.

UUID.variant

   UUID 변종은 UUID의 내부 레이아웃을 결정합니다. 이는 상수
   "RESERVED_NCS", "RFC_4122", "RESERVED_MICROSOFT", 및
   "RESERVED_FUTURE" 중 하나입니다.

UUID.version

   The UUID version number (1 through 8, meaningful only when the
   variant is "RFC_4122").

   버전 3.14에서 변경: Added UUID versions 6, 7 and 8.

UUID.is_safe

   플랫폼이 UUID를 다중 프로세스에 안전한 방식으로 생성했는지를 나타내
   는 "SafeUUID"의 열거체입니다.

   Added in version 3.7.

The "uuid" module defines the following functions:

uuid.getnode()

   하드웨어 주소를 48bit 양의 정수로 가져옵니다. 최초 실행 시 별도의
   프로그램으로 실행될 수 있고, 매우 느려질 수 있습니다. 하드웨어 주소
   를 얻기 위한 시도가 모두 실패하면, **RFC 4122**가 권장하는 대로 멀
   티캐스트 비트(첫 옥텟의 최하위 비트)가 1로 설정된 무작위 48bit 숫자
   를 선택합니다. "하드웨어 주소"는 네트워크 인터페이스의 MAC 주소를
   뜻합니다. 여러 네트워크 인터페이스를 가진 머신에서 보편적으로 관리
   하는 MAC 주소(즉, 첫 번째 옥텟의 두 번째 최하위 비트가 *unset*인 경
   우)는 로컬에서 관리하는 MAC 주소보다 우선하지만, 순서를 보장하지는
   않습니다.

   버전 3.7에서 변경: 보편적으로 관리하는 MAC 주소는 로컬로 관리하는
   MAC 주소보다 우선합니다. 전자는 주소가 전 세계적으로 고유함을 보장
   하지만, 후자는 그렇지 않기 때문입니다.

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

   Generate a UUID from a host ID, sequence number, and the current
   time according to **RFC 9562, §5.1**.

   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.

   If *node* or *clock_seq* exceed their expected bit count, only
   their least significant bits are kept.

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) according to **RFC 9562, §5.3**.

uuid.uuid4()

   Generate a random UUID in a cryptographically-secure method
   according to **RFC 9562, §5.4**.

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) according to **RFC 9562, §5.5**.

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

   Generate a UUID from a sequence number and the current time
   according to **RFC 9562, §5.6**.

   This is an alternative to "uuid1()" to improve database locality.

   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.

   If *node* or *clock_seq* exceed their expected bit count, only
   their least significant bits are kept.

   Added in version 3.14.

uuid.uuid7()

   Generate a time-based UUID according to **RFC 9562, §5.7**.

   For portability across platforms lacking sub-millisecond precision,
   UUIDs produced by this function embed a 48-bit timestamp and use a
   42-bit counter to guarantee monotonicity within a millisecond.

   Added in version 3.14.

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

   Generate a pseudo-random UUID according to **RFC 9562, §5.8**.

   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.

   By default, *a*, *b* and *c* are not generated by a
   cryptographically secure pseudo-random number generator (CSPRNG).
   Use "uuid4()" when a UUID needs to be used in a security-sensitive
   context.

   Added in version 3.14.

The "uuid" module defines the following namespace identifiers for use
with "uuid3()" or "uuid5()".

uuid.NAMESPACE_DNS

   이 이름 공간이 지정되면 *name* 문자열은 전체 도메인 이름(FQDN)입니
   다.

uuid.NAMESPACE_URL

   이 이름 공간이 지정되면 *name* 문자열은 URL입니다.

uuid.NAMESPACE_OID

   이 이름 공간이 지정되면 *name* 문자열은 ISO OID입니다.

uuid.NAMESPACE_X500

   이 이름 공간이 지정되면 *name* 문자열은 DER이나 텍스트 출력 형식의
   X.500 DN입니다.

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

uuid.RESERVED_NCS

   NCS 호환성을 위해 예약됨.

uuid.RFC_4122

   Specifies the UUID layout given in **RFC 4122**. This constant is
   kept for backward compatibility even though **RFC 4122** has been
   superseded by **RFC 9562**.

uuid.RESERVED_MICROSOFT

   마이크로소프트 호환성을 위해 예약됨.

uuid.RESERVED_FUTURE

   추후 정의를 위해 예약됨.

The "uuid" module defines the special Nil and Max UUID values:

uuid.NIL

   A special form of UUID that is specified to have all 128 bits set
   to zero according to **RFC 9562, §5.9**.

   Added in version 3.14.

uuid.MAX

   A special form of UUID that is specified to have all 128 bits set
   to one according to **RFC 9562, §5.10**.

   Added in version 3.14.

더 보기:

  **RFC 9562** - A Universally Unique IDentifier (UUID) URN Namespace
     이 명세는 UUID를 위한 통합 자원 식별자 이름 공간, 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,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]

The following options are accepted:

-h, --help

   Show the help message and exit.

-u <uuid>
--uuid <uuid>

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

   버전 3.14에서 변경: Allow generating UUID versions 6, 7 and 8.

-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.

-C <num>
--count <num>

   Generate *num* fresh UUIDs.

   Added in version 3.14.


예제
====

Here are some examples of typical usage of the "uuid" module:

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


명령줄 예제
===========

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

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