dbm — Gränssnitt till Unix ”databaser”

Källkod: Lib/dbm/__init__.py

dbm är ett generiskt gränssnitt till varianter av DBM-databasen:

Om ingen av dessa moduler är installerade kommer den långsamma men enkla implementationen i modulen dbm.dumb att användas. Det finns ett tredjepartsgränssnitt till Oracle Berkeley DB.

exception dbm.error

En tupel som innehåller de undantag som kan utlösas av var och en av de moduler som stöds, med ett unikt undantag som också heter dbm.error som första objekt — det senare används när dbm.error utlöses.

dbm.whichdb(filename)

Denna funktion försöker gissa vilken av de många enkla databasmoduler som finns tillgängliga — dbm.sqlite3, dbm.gnu, dbm.ndbm eller dbm.dumb — som skall användas för att öppna en given fil.

Returnerar ett av följande värden:

  • None om filen inte kan öppnas eftersom den är oläslig eller inte finns

  • den tomma strängen ('') om filens format inte kan gissas

  • en sträng som innehåller namnet på den modul som krävs, t.ex. 'dbm.ndbm' eller 'dbm.gnu'

Ändrad i version 3.11: filename accepterar en path-like object.

dbm.open(file, flag='r', mode=0o666)

Öppna en databas och returnera motsvarande databasobjekt.

Parametrar:

  • file (path-like object) – Databasfilen som skall öppnas. Om databasfilen redan finns, används funktionen whichdb() för att bestämma dess typ och lämplig modul används; om den inte finns, används den första undermodulen som listas ovan och som kan importeras.

  • flag (str) –

    • 'r' (standard): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

Ändrad i version 3.11: file accepterar en path-like object.

Objektet som returneras av open() har samma grundläggande funktionalitet som en dict; nycklar och deras motsvarande värden kan lagras, hämtas och raderas, och operatorn in och metoden keys() finns tillgängliga, liksom metoderna get() och setdefault().

Nycklar och värden lagras alltid som bytes. Detta innebär att när strängar används konverteras de implicit till standardkodningen innan de lagras.

Dessa objekt kan också användas i en with-sats, som automatiskt stänger dem när de är klara.

Ändrad i version 3.2: metoderna get() och setdefault() är nu tillgängliga för alla dbm-backends.

Ändrad i version 3.4: Lagt till inbyggt stöd för kontexthanteringsprotokollet till de objekt som returneras av open().

Ändrad i version 3.8: Om du tar bort en nyckel från en skrivskyddad databas uppstår ett undantag som är specifikt för databasmodulen i stället för KeyError.

I följande exempel registreras några värdnamn och en motsvarande titel, och sedan skrivs innehållet i databasen ut:

import dbm

# Open database, creating it if necessary.
with dbm.open('cache', 'c') as db:

    # Record some values
    db[b'hello'] = b'there'
    db['www.python.org'] = 'Python Website'
    db['www.cnn.com'] = 'Cable News Network'

    # Note that the keys are considered bytes now.
    assert db[b'www.python.org'] == b'Python Website'
    # Notice how the value is now in bytes.
    assert db['www.cnn.com'] == b'Cable News Network'

    # Often-used methods of the dict interface work too.
    print(db.get('python.org', b'not present'))

    # Storing a non-string key or value will raise an exception (most
    # likely a TypeError).
    db['www.yahoo.com'] = 4

# db is automatically closed when leaving the with statement.

Se även

Modul shelve

Persistensmodul som lagrar data som inte är strängdata.

De enskilda undermodulerna beskrivs i följande avsnitt.

dbm.sqlite3 — SQLite-backend för dbm

Tillagd i version 3.13.

Källkod: Lib/dbm/sqlite3.py

Den här modulen använder standardbiblioteket sqlite3 för att tillhandahålla en SQLite-backend för modulen dbm. Filerna som skapas av dbm.sqlite3 kan därmed öppnas av sqlite3 eller någon annan SQLite-webbläsare, inklusive SQLite CLI.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

dbm.sqlite3.open(filename, /, flag='r', mode=0o666)

Öppnar en SQLite-databas. Det returnerade objektet beter sig som en mapping, implementerar en close()-metod och stöder en ”stängande” kontexthanterare via nyckelordet with.

Parametrar:

  • filename (path-like object) – Sökvägen till den databas som ska öppnas.

  • flag (str) –

    • 'r' (standard): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode – Filens Unix-filåtkomstläge (standard: oktal 0o666), används endast när databasen måste skapas.

dbm.gnu — GNU databashanterare

Källkod: Lib/dbm/gnu.py

Modulen dbm.gnu tillhandahåller ett gränssnitt till biblioteket GDBM, liknande modulen dbm.ndbm, men med ytterligare funktionalitet som kraschtolerans.

Anteckning

De filformat som skapas av dbm.gnu och dbm.ndbm är inkompatibla och kan inte användas omväxlande.

Tillgänglighet: not Android, not iOS, not WASI.

Denna modul stöds inte på mobile platforms eller WebAssembly platforms.

exception dbm.gnu.error

Uppstår vid dbm.gnu-specifika fel, t.ex. I/O-fel. KeyError uppstår vid allmänna mappningsfel, t.ex. om en felaktig nyckel anges.

dbm.gnu.open(filename, flag='r', mode=0o666, /)

Öppna en GDBM-databas och returnera ett gdbm-objekt.

Parametrar:

  • filename (path-like object) – Den databasfil som ska öppnas.

  • flag (str) –

    • 'r' (standard): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

    Följande tilläggstecken kan läggas till för att styra hur databasen öppnas:

    • 'f': Öppna databasen i snabbläge. Skrivningar till databasen kommer inte att synkroniseras.

    • 's': Synkroniserat läge. Ändringar i databasen kommer omedelbart att skrivas till filen.

    • 'u': Lås inte databasen.

    Alla flaggor är inte giltiga för alla versioner av GDBM. Se medlemmen open_flags för en lista över flaggtecken som stöds.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

Höjer:

error – Om ett ogiltigt flag-argument skickas.

Ändrad i version 3.11: filename accepterar en path-like object.

dbm.gnu.open_flags

En sträng med tecken som parametern flag i open() stöder.

gdbm-objekt beter sig på liknande sätt som mappings, men metoderna items() och values() stöds inte. Följande metoder tillhandahålls också:

gdbm.firstkey()

Det är möjligt att loopa över varje nyckel i databasen med hjälp av denna metod och metoden nextkey(). Traversieringen ordnas efter GDBM:s interna hashvärden och sorteras inte efter nyckelvärdena. Den här metoden returnerar startnyckeln.

gdbm.nextkey(key)

Returnerar den nyckel som följer efter nyckel i traverseringen. Följande kod skriver ut alla nycklar i databasen db, utan att behöva skapa en lista i minnet som innehåller dem alla:

k = db.första nyckel()
medan k inte är None:
    print(k)
    k = db.nästa tangent(k)
gdbm.reorganize()

Om du har gjort många raderingar och vill krympa det utrymme som GDBM-filen använder, omorganiserar den här rutinen databasen. gdbm-objekt förkortar inte längden på en databasfil utom genom att använda den här omorganisationen; annars behålls det raderade filutrymmet och återanvänds när nya (nyckel, värde)-par läggs till.

gdbm.sync()

När databasen har öppnats i snabbläge tvingar den här metoden alla oskrivna data att skrivas till disken.

gdbm.close()

Stäng GDBM-databasen.

gdbm.clear()

Ta bort alla objekt från GDBM-databasen.

Tillagd i version 3.13.

dbm.ndbm — Ny databashanterare

Källkod: Lib/dbm/ndbm.py

Modulen dbm.ndbm tillhandahåller ett gränssnitt till biblioteket NDBM. Denna modul kan användas med det ”klassiska” NDBM-gränssnittet eller GDBM kompatibilitetsgränssnitt.

Anteckning

De filformat som skapas av dbm.gnu och dbm.ndbm är inkompatibla och kan inte användas omväxlande.

Varning

NDBM-biblioteket som levereras som en del av macOS har en odokumenterad begränsning av storleken på värden, vilket kan resultera i skadade databasfiler när värden som är större än denna gräns lagras. Läsning av sådana skadade filer kan resultera i en hårdkrasch (segmenteringsfel).

Tillgänglighet: not Android, not iOS, not WASI.

Denna modul stöds inte på mobile platforms eller WebAssembly platforms.

exception dbm.ndbm.error

Uppstår vid dbm.ndbm-specifika fel, t.ex. I/O-fel. KeyError uppstår vid allmänna mappningsfel, t.ex. om en felaktig nyckel anges.

dbm.ndbm.library

Namn på det implementeringsbibliotek för NDBM som används.

dbm.ndbm.open(filename, flag='r', mode=0o666, /)

Öppna en NDBM-databas och returnera ett ndbm-objekt.

Parametrar:

  • filename (path-like object) – Grundnamnet på databasfilen (utan tilläggen .dir eller .pag).

  • flag (str) –

    • 'r' (standard): Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c': Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

ndbm-objekt beter sig på liknande sätt som mappings, men metoderna items() och values() stöds inte. Följande metoder tillhandahålls också:

Ändrad i version 3.11: Accepterar path-like object för filnamn.

ndbm.close()

Stäng NDBM-databasen.

ndbm.clear()

Ta bort alla objekt från NDBM-databasen.

Tillagd i version 3.13.

dbm.dumb — Portabel DBM-implementering

Källkod: Lib/dbm/dumb.py

Anteckning

Modulen dbm.dumb är avsedd som en sista utväg för modulen dbm när en mer robust modul inte är tillgänglig. Modulen dbm.dumb är inte skriven för snabbhet och används inte alls lika flitigt som de andra databasmodulerna.

Modulen dbm.dumb tillhandahåller ett beständigt dict-liknande gränssnitt som är helt skrivet i Python. Till skillnad från andra dbm-backends, såsom dbm.gnu, krävs inget externt bibliotek.

Modulen dbm.dumb definierar följande:

exception dbm.dumb.error

Uppstår vid dbm.dumb-specifika fel, t.ex. I/O-fel. KeyError uppstår vid allmänna mappningsfel som t.ex. att ange en felaktig nyckel.

dbm.dumb.open(filename, flag='c', mode=0o666)

Öppnar en dbm.dumb-databas. Det returnerade databasobjektet beter sig på liknande sätt som en mapping, förutom att det tillhandahåller metoderna sync() och close().

Parametrar:

  • filename – Grundnamnet på databasfilen (utan tillägg). En ny databas skapar följande filer: - filename.dat - filename.dir - filename.dir

  • flag (str) –

    • 'r': Open existing database for reading only.

    • 'w': Open existing database for reading and writing.

    • 'c' (standard): Open database for reading and writing, creating it if it doesn’t exist.

    • 'n': Always create a new, empty database, open for reading and writing.

  • mode (int) – The Unix file access mode of the file (default: octal 0o666), used only when the database has to be created.

Varning

Det är möjligt att krascha Python-tolken när man laddar en databas med en tillräckligt stor/komplex post på grund av begränsningar i stackdjupet i Pythons AST-kompilator.

Ändrad i version 3.5: open() skapar alltid en ny databas när flag är 'n'.

Ändrad i version 3.8: En databas öppnas skrivskyddad om flag är 'r'. En databas skapas inte om den inte redan finns om flag är 'r' eller 'w'.

Ändrad i version 3.11: filename accepterar en path-like object.

Förutom de metoder som tillhandahålls av collections.abc.MutableMapping-klassen, tillhandahålls följande metoder:

dumbdbm.sync()

Synkroniserar katalogen och datafilerna på disken. Denna metod anropas av metoden shelve.Shelf.sync().

dumbdbm.close()

Stäng databasen.