uuid — RFC 9562에 따른 UUID 객체

uuid — RFC 9562에 따른 UUID 객체

uuid 모듈은 불변(immutable) UUID 객체(UUID 클래스)와, RFC 9562(구 RFC 4122를 대체)에 명시된 특정 UUID 버전에 대응하는 UUID 생성 함수를 제공해요. 예를 들어 uuid1()은 UUID 버전 1, uuid3()은 버전 3 등이죠. UUID 버전 2는 RFC 범위 밖이라 의도적으로 생략된 점을 알아 두세요.

출처: Python 표준 라이브러리

본문

uuid 모듈은 불변 UUID 객체(UUID 클래스)와, RFC 9562(구 RFC 4122를 대체)에 따른 특정 UUID 버전을 생성하는 함수들을 제공해요. 예를 들어 uuid1()은 UUID 버전 1, uuid3()은 버전 3 같은 식이죠. UUID 버전 2는 RFC 범위 밖이라 의도적으로 생략되어 있습니다.

그냥 유일한 ID만 필요하다면 uuid1()이나 uuid4()를 호출하는 게 좋아요. 단, uuid1()은 컴퓨터의 네트워크 주소를 담은 UUID를 만들기 때문에 개인정보를 침해할 수 있습니다. uuid4()는 무작위 UUID를 만들어요.

플랫폼의 지원 여부에 따라 uuid1()은 "안전한(safe)" UUID를 반환할 수도, 아닐 수도 있어요. 안전한 UUID는 두 프로세스가 같은 UUID를 얻을 수 없음을 보장하는 동기화 방식으로 생성된 것입니다. 모든 UUID 인스턴스는 UUID의 안전성 정보를 전달하는 is_safe 속성을 가지며, 다음 열거형을 사용합니다.

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를 만듭니다: 32자리 16진수 문자열, bytes 인자로 준 big-endian 순서의 16바이트 문자열, bytes_le 인자로 준 little-endian 순서의 16바이트 문자열, fields 인자로 준 여섯 정수 튜플 (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 중 정확히 하나를 주어야 해요. version 인자는 선택적이며, 주어지면 결과 UUID의 variant와 버전 번호가 RFC 9562에 따라 설정되어 주어진 hex·bytes·bytes_le·fields·int의 비트를 덮어씁니다.

UUID 객체의 비교는 UUID.int 속성을 비교하는 방식으로 이루어져요. UUID가 아닌 객체와 비교하면 TypeError가 발생합니다.

str(uuid)는 32자리 16진수가 UUID를 나타내는 12345678-1234-5678-1234-567812345678 형태의 문자열을 반환합니다.

UUID 인스턴스는 다음 읽기 전용 속성을 가져요.

  • UUID.bytes — 16바이트 문자열로 표현한 UUID (여섯 정수 필드를 big-endian 바이트 순서로 담음).
  • UUID.bytes_le — 16바이트 문자열로 표현한 UUID (time_low, time_mid, time_hi_version이 little-endian 바이트 순서).
  • UUID.fields — UUID의 여섯 정수 필드 튜플. 다음 여섯 개별 속성과 두 파생 속성으로도 접근할 수 있어요.
필드 의미
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 UUID의 마지막 48비트. 버전 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의 내부 배치를 결정하는 variant. RESERVED_NCS, RFC_4122, RESERVED_MICROSOFT, RESERVED_FUTURE 상수 중 하나.
UUID.version UUID 버전 번호 (1~8, variant가 RFC_4122일 때만 의미 있음).

버전 3.14에서 변경: UUID 버전 6, 7, 8이 추가되었습니다.

  • UUID.is_safe — 플랫폼이 멀티프로세스 안전한 방식으로 UUID를 생성했는지를 나타내는 SafeUUID 열거형. (버전 3.7에서 추가)

uuid 모듈은 다음 함수들을 정의해요.

uuid.getnode()

하드웨어 주소를 48비트 양의 정수로 가져옵니다. 처음 실행할 때는 별도 프로그램을 실행할 수 있어 상당히 느릴 수 있어요. 하드웨어 주소를 얻는 모든 시도가 실패하면 RFC 4122에서 권장하는 대로 첫 옥텟의 최하위 비트(멀티캐스트 비트)가 1로 설정된 무작위 48비트 숫자를 고릅니다. "하드웨어 주소"는 네트워크 인터페이스의 MAC 주소를 의미해요. 네트워크 인터페이스가 여러 개인 머신에서는 로컬 관리 MAC 주소보다 범용 관리(universally administered) MAC 주소(첫 옥텟의 두 번째 최하위 비트가 설정되지 않은)를 선호하지만, 그 외의 정렬 보장은 없습니다.

버전 3.7에서 변경: 로컬 관리보다 범용 관리 MAC 주소를 선호합니다. 전자는 전역적으로 유일함이 보장되는 반면 후자는 그렇지 않기 때문이에요.

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

RFC 9562 §5.1에 따라 호스트 ID, 시퀀스 번호, 현재 시간으로부터 UUID를 생성합니다. node를 지정하지 않으면 getnode()로 하드웨어 주소를 48비트 양의 정수로 얻어요. 시퀀스 번호 clock_seq를 지정하지 않으면 의사 난수 14비트 양의 정수가 생성됩니다.

node나 clock_seq가 예상 비트 수를 초과하면 최하위 비트만 유지해요.

uuid.uuid3(namespace, name)

RFC 9562 §5.3에 따라 네임스페이스 식별자(UUID)와 이름(UTF-8로 인코딩될 bytes 객체 또는 문자열)의 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를 생성합니다. 데이터베이스 지역성(locality)을 개선하기 위한 uuid1()의 대안이에요.

node를 지정하지 않으면 getnode()로 하드웨어 주소를 48비트 양의 정수로 얻습니다. 시퀀스 번호 clock_seq를 지정하지 않으면 의사 난수 14비트 양의 정수가 생성돼요. node나 clock_seq가 예상 비트 수를 초과하면 최하위 비트만 유지합니다.

버전 3.14에서 추가.

uuid.uuid7()

RFC 9562 §5.7에 따라 시간 기반 UUID를 생성합니다. 서브 밀리초 정밀도가 없는 플랫폼 간 이식성을 위해, 이 함수가 만드는 UUID는 48비트 타임스탬프를 포함하고 42비트 카운터를 사용해 밀리초 내 단조성(monotonicity)을 보장해요.

버전 3.14에서 추가.

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

RFC 9562 §5.8에 따라 의사 난수 UUID를 생성합니다. 매개변수 a, b, c를 지정하면 각각 48, 12, 62비트의 양의 정수여야 해요. 예상 비트 수를 초과하면 최하위 비트만 유지하고, 지정하지 않은 인자는 적절한 크기의 의사 난수 정수로 대체됩니다.

기본적으로 a, b, c는 암호학적으로 안전한 의사 난수 생성기(CSPRNG)로 생성되지 않아요. 보안에 민감한 맥락에서 UUID가 필요하면 uuid4()를 사용하세요.

버전 3.14에서 추가.

uuid 모듈은 uuid3() 또는 uuid5()와 함께 쓸 다음 네임스페이스 식별자를 정의합니다.

  • uuid.NAMESPACE_DNS — 이 네임스페이스를 지정하면 이름 문자열이 완전한 도메인 이름(FQDN)입니다.
  • uuid.NAMESPACE_URL — 이 네임스페이스를 지정하면 이름 문자열이 URL입니다.
  • uuid.NAMESPACE_OID — 이 네임스페이스를 지정하면 이름 문자열이 ISO OID입니다.
  • uuid.NAMESPACE_X500 — 이 네임스페이스를 지정하면 이름 문자열이 DER 또는 텍스트 출력 형식의 X.500 DN입니다.

uuid 모듈은 variant 속성의 가능한 값에 대한 다음 상수를 정의합니다.

  • uuid.RESERVED_NCS — NCS 호환용으로 예약됨.
  • uuid.RFC_4122 — RFC 4122에 주어진 UUID 배치를 지정. RFC 4122가 RFC 9562로 대체되었음에도 하위 호환을 위해 유지되는 상수.
  • uuid.RESERVED_MICROSOFT — Microsoft 호환용으로 예약됨.
  • uuid.RESERVED_FUTURE — 향후 정의를 위해 예약됨.

uuid 모듈은 특별한 Nil과 Max UUID 값을 정의합니다.

  • uuid.NIL — RFC 9562 §5.9에 따라 128비트가 모두 0으로 설정되도록 지정된 특별한 형태의 UUID. (버전 3.14에서 추가)
  • uuid.MAX — RFC 9562 §5.10에 따라 128비트가 모두 1로 설정되도록 지정된 특별한 형태의 UUID. (버전 3.14에서 추가)

참고 자료 — RFC 9562 "A Universally Unique IDentifier (UUID) URN Namespace"는 UUID용 URN 네임스페이스, UUID의 내부 형식, UUID 생성 방법을 정의합니다.

명령줄 사용 (Command-Line Usage)

버전 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> — num개의 새 UUID를 생성합니다. (버전 3.14에서 추가)

예제 (Example)

uuid 모듈의 대표적인 사용 예시입니다.

>>> import uuid

>>> # 호스트 ID와 현재 시간에 기반한 UUID 만들기
>>> uuid.uuid1()
UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')

>>> # 네임스페이스 UUID와 이름의 MD5 해시로 UUID 만들기
>>> uuid.uuid3(uuid.NAMESPACE_DNS, 'python.org')
UUID('6fa459ea-ee8a-3ca4-894e-db77e160355e')

>>> # 무작위 UUID 만들기
>>> uuid.uuid4()
UUID('16fd2706-8baf-433b-82eb-8c7fada847da')

>>> # 네임스페이스 UUID와 이름의 SHA-1 해시로 UUID 만들기
>>> uuid.uuid5(uuid.NAMESPACE_DNS, 'python.org')
UUID('886313e1-3b8a-5372-9b90-0c9aee199e5d')

>>> # 16진수 문자열로 UUID 만들기 (괄호와 하이픈 무시)
>>> x = uuid.UUID('{00010203-0405-0607-0809-0a0b0c0d0e0f}')

>>> # UUID를 표준 형식의 16진수 문자열로 변환
>>> str(x)
'00010203-0405-0607-0809-0a0b0c0d0e0f'

>>> # UUID의 원시 16바이트 얻기
>>> x.bytes
b'\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f'

>>> # 16바이트 문자열로 UUID 만들기
>>> uuid.UUID(bytes=x.bytes)
UUID('00010203-0405-0607-0809-0a0b0c0d0e0f')

>>> # Nil UUID 얻기
>>> uuid.NIL
UUID('00000000-0000-0000-0000-000000000000')

>>> # Max UUID 얻기
>>> uuid.MAX
UUID('ffffffff-ffff-ffff-ffff-ffffffffffff')

>>> # UUIDv1과 같지만 DB 지역성 개선을 위해 필드 재배열
>>> uuid.uuid6()
UUID('1f0799c0-98b9-62db-92c6-a0d365b91053')

>>> # UUIDv7 생성(로컬) 시간을 밀리초 타임스탬프로 얻기
>>> u = uuid.uuid7()
>>> u.time
1743936859822

>>> # UUIDv7 생성(로컬) 시간을 datetime 객체로 얻기
>>> import datetime as dt
>>> dt.datetime.fromtimestamp(u.time / 1000)
datetime.datetime(...)

>>> # 커스텀 블록으로 UUID 만들기
>>> uuid.uuid8(0x12345678, 0x9abcdef0, 0x11223344)
UUID('00001234-5678-8ef0-8000-000011223344')

명령줄 예제 (Command-Line Example)

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