uuid — UUID-objekt enligt RFC 9562¶
Källkod: Lib/uuid.py
Denna modul tillhandahåller oföränderliga UUID-objekt (klassen UUID) och funktioner för att generera UUIDs som motsvarar en specifik UUID-version enligt specifikationen i RFC 9562 (som ersätter RFC 4122), till exempel uuid1() för UUID version 1, uuid3() för UUID version 3, och så vidare. Observera att UUID version 2 avsiktligt utelämnas eftersom den ligger utanför RFC:s tillämpningsområde.
Om allt du vill ha är ett unikt ID bör du förmodligen anropa uuid1() eller uuid4(). Observera att uuid1() kan äventyra integriteten eftersom det skapar ett UUID som innehåller datorns nätverksadress. uuid4() skapar ett slumpmässigt UUID.
Beroende på stöd från den underliggande plattformen kan uuid1() returnera ett ”säkert” UUID eller inte. Ett säkert UUID är ett UUID som genereras med hjälp av synkroniseringsmetoder som säkerställer att inga två processer kan få samma UUID. Alla instanser av UUID har ett is_safe-attribut som förmedlar all information om UUID:s säkerhet med hjälp av denna uppräkning:
- class uuid.SafeUUID¶
Tillagd i version 3.7.
- unknown¶
Plattformen tillhandahåller inte information om huruvida UUID genererades på ett säkert sätt eller inte.
- class uuid.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)¶
Skapa ett UUID från antingen en sträng med 32 hexadecimala siffror, en sträng med 16 byte i big-endian-ordning som argument bytes, en sträng med 16 byte i little-endian-ordning som argument bytes_le, en tupel med sex heltal (32-bitars time_low, 16-bitars time_mid, 16-bitars time_hi_version, 8-bitars clock_seq_hi_variant, 8-bitars clock_seq_low, 48-bitars node) som argument fields, eller ett enda 128-bitars heltal som argument int. När en sträng med hexadecimala siffror anges är hakparenteser, bindestreck och ett URN-prefix valfria. Till exempel ger alla dessa uttryck samma 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(fält=(0x12345678, 0x1234, 0x5678, 0x12, 0x34, 0x567812345678)) UUID(int=0x12345678123456781234567812345678)
Exakt en av hex, bytes, bytes_le, fields eller int måste anges. Argumentet version är valfritt; om det anges kommer det resulterande UUID att ha sin variant och sitt versionsnummer enligt RFC 9562, vilket åsidosätter bitar i de angivna hex, bytes, bytes_le, fields eller int.
Jämförelse av UUID-objekt görs genom att jämföra deras
UUID.int-attribut. Jämförelse med ett icke-UUID-objekt ger upphov till ettTypeError.str(uuid)returnerar en sträng i formen12345678-1234-5678-1234-567812345678där de 32 hexadecimala siffrorna representerar UUID.
UUID-instanser har dessa skrivskyddade attribut:
- UUID.bytes¶
UUID som en 16-byte-sträng (som innehåller de sex heltalsfälten i big-endian byteordning).
- UUID.bytes_le¶
UUID som en 16-byte-sträng (med time_low, time_mid och time_hi_version i little-endian byte-ordning).
- UUID.fields¶
En tupel av UUID:s sex heltalsfält, som också finns tillgängliga som sex individuella attribut och två härledda attribut:
Fält |
Betydelse |
|
De första 32 bitarna av UUID. Endast relevant för version 1. |
|
De kommande 16 bitarna av UUID. Endast relevant för version 1. |
|
De kommande 16 bitarna av UUID. Endast relevant för version 1. |
|
De kommande 8 bitarna av UUID. Endast relevant för version 1 och 6. |
|
De kommande 8 bitarna av UUID. Endast relevant för version 1 och 6. |
|
De sista 48 bitarna av UUID. Endast relevant för version 1. |
|
60-bitars tidsstämpel i 100-nanosekundersintervall sedan gregoriansk epok (1582-10-15 00:00:00) för version 1 och 6, eller 48-bitars tidsstämpel i millisekunder sedan Unix epok (1970-01-01 00:00:00) för version 7. |
|
14-bitars sekvensnummer. Endast relevant för version 1 och 6. |
- UUID.hex¶
UUID som en 32 tecken lång hexadecimal sträng med gemener.
- UUID.int¶
UUID som ett 128-bitars heltal.
- UUID.variant¶
UUID-varianten, som bestämmer den interna layouten för UUID. Detta kommer att vara en av konstanterna
RESERVED_NCS,RFC_4122,RESERVED_MICROSOFT, ellerRESERVED_FUTURE.
- UUID.version¶
UUID:s versionsnummer (1 till 8, endast meningsfullt när varianten är
RFC_4122).Ändrad i version 3.14: Lagt till UUID version 6, 7 och 8.
- UUID.is_safe¶
En uppräkning av
SafeUUIDsom anger om plattformen genererade UUID:n på ett multiprocessing-säkert sätt.Tillagd i version 3.7.
Modulen uuid definierar följande funktioner:
- uuid.getnode()¶
Hämta hårdvaruadressen som ett 48-bitars positivt heltal. Första gången detta körs kan det hända att ett separat program startas, vilket kan vara ganska långsamt. Om alla försök att få fram maskinvaruadressen misslyckas väljer vi ett slumpmässigt 48-bitarsnummer med multicastbiten (den minst signifikanta biten i den första oktetten) satt till 1 enligt rekommendationen i RFC 4122. med ”hårdvaruadress” avses MAC-adressen för ett nätverksgränssnitt. På en maskin med flera nätverksgränssnitt kommer universellt administrerade MAC-adresser (dvs. där den näst minst signifikanta biten i den första oktetten är unset) att föredras framför lokalt administrerade MAC-adresser, men utan några andra ordningsgarantier.
Ändrad i version 3.7: Universellt administrerade MAC-adresser är att föredra framför lokalt administrerade MAC-adresser, eftersom de förra garanterat är globalt unika, medan de senare inte är det.
- uuid.uuid1(node=None, clock_seq=None)¶
Generera ett UUID från ett värd-ID, sekvensnummer och aktuell tid enligt RFC 9562, §5.1.
När node inte är specificerat används
getnode()för att få hårdvaruadressen som ett 48-bitars positivt heltal. När ett sekvensnummer clock_seq inte specificeras genereras ett pseudoslumpmässigt 14-bitars positivt heltal.Om node eller clock_seq överskrider sitt förväntade bitantal sparas endast de minst signifikanta bitarna.
- uuid.uuid3(namespace, name)¶
Generera ett UUID baserat på MD5-hashningen av en namnrymdsidentifierare (som är ett UUID) och ett namn (som är ett
bytes-objekt eller en sträng som kommer att kodas med UTF-8) enligt RFC 9562, §5.3.
- uuid.uuid4()¶
Generera ett slumpmässigt UUID med en kryptografiskt säker metod enligt RFC 9562, §5.4.
- uuid.uuid5(namespace, name)¶
Generera ett UUID baserat på SHA-1-hashningen av en namnrymdsidentifierare (som är ett UUID) och ett namn (som är ett
bytes-objekt eller en sträng som kommer att kodas med UTF-8) enligt RFC 9562, §5.5.
- uuid.uuid6(node=None, clock_seq=None)¶
Generera ett UUID från ett sekvensnummer och den aktuella tiden enligt RFC 9562, §5.6.
Detta är ett alternativ till
uuid1()för att förbättra databaslokaliseringen.När node inte är specificerat används
getnode()för att få hårdvaruadressen som ett 48-bitars positivt heltal. När ett sekvensnummer clock_seq inte specificeras genereras ett pseudoslumpmässigt 14-bitars positivt heltal.Om node eller clock_seq överskrider sitt förväntade bitantal sparas endast de minst signifikanta bitarna.
Tillagd i version 3.14.
- uuid.uuid7()¶
Generera en tidsbaserad UUID enligt RFC 9562, §5.7.
För portabilitet på plattformar som saknar precision under en millisekund bäddar UUID:er som produceras av den här funktionen in en 48-bitars tidsstämpel och använder en 42-bitars räknare för att garantera monotonicitet inom en millisekund.
Tillagd i version 3.14.
- uuid.uuid8(a=None, b=None, c=None)¶
Generera ett pseudoslumpmässigt UUID enligt RFC 9562, §5.8.
När parametrarna a, b och c specificeras förväntas de vara positiva heltal på 48, 12 respektive 62 bitar. Om de överstiger det förväntade bitantalet behålls endast de minst signifikanta bitarna; ospecificerade argument ersätts med ett pseudoslumpmässigt heltal av lämplig storlek.
Som standard genereras a, b och c inte av en kryptografiskt säker pseudoslumptalsgenerator (CSPRNG). Använd
uuid4()när ett UUID behöver användas i ett säkerhetskänsligt sammanhang.Tillagd i version 3.14.
Modulen uuid definierar följande namnrymdsidentifierare för användning med uuid3() eller uuid5().
- uuid.NAMESPACE_DNS¶
När denna namnrymd anges är strängen name ett fullständigt kvalificerat domännamn.
- uuid.NAMESPACE_URL¶
När detta namnrymd anges är name-strängen en URL.
- uuid.NAMESPACE_OID¶
När denna namnrymd anges är name-strängen en ISO OID.
- uuid.NAMESPACE_X500¶
När denna namnrymd anges är name-strängen en X.500 DN i DER- eller textutmatningsformat.
Modulen uuid definierar följande konstanter för de möjliga värdena för attributet variant:
- uuid.RESERVED_NCS¶
Reserverad för NCS-kompatibilitet.
- uuid.RFC_4122¶
Anger den UUID-layout som anges i RFC 4122. Denna konstant behålls för bakåtkompatibilitet även om RFC 4122 har ersatts av RFC 9562.
- uuid.RESERVED_MICROSOFT¶
Reserverad för Microsoft-kompatibilitet.
- uuid.RESERVED_FUTURE¶
Reserverad för framtida definition.
Modulen uuid definierar de speciella Nil- och Max-värdena för UUID:
- uuid.NIL¶
En speciell form av UUID som är specificerad att ha alla 128 bitar nollställda enligt RFC 9562, §5.9.
Tillagd i version 3.14.
- uuid.MAX¶
En speciell form av UUID som är specificerad så att alla 128 bitar är satta till ett enligt RFC 9562, §5.10.
Tillagd i version 3.14.
Se även
Användning av kommandoraden¶
Tillagd i version 3.12.
Modulen uuid kan exekveras som ett skript från kommandoraden.
python -m uuid [-h] [-u {uuid1,uuid3,uuid4,uuid5,uuid6,uuid7,uuid8}] [-n NAMESPACE] [-N NAME]
Följande alternativ accepteras:
- -h, --help¶
Visa hjälpmeddelandet och avsluta.
- -u <uuid>¶
- --uuid <uuid>¶
Ange det funktionsnamn som ska användas för att generera uuid. Som standard används
uuid4().Ändrad i version 3.14: Tillåt generering av UUID version 6, 7 och 8.
- -n <namespace>¶
- --namespace <namespace>¶
Namnrymden är ett
UUIDeller@nsdärnsär ett välkänt fördefinierat UUID som adresseras av namnrymdens namn. Till exempel@dns,@url,@oidoch@x500. Krävs endast för funktionernauuid3()/uuid5().
Exempel¶
Här följer några exempel på typisk användning av modulen 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')
Exempel på kommandoraden¶
Här följer några exempel på typisk användning av kommandoradsgränssnittet uuid:
# generera ett slumpmässigt UUID - som standard används uuid4()
$ python -m uuid
# generera ett UUID med hjälp av uuid1()
$ python -m uuid -u uuid1
# generera ett UUID med hjälp av uuid5
$ python -m uuid -u uuid5 -n @url -N exempel.com
# generera 42 slumpmässiga UUID
$ python -m uuid -C 42