parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="dbm — Interfaces to Unix “databases”" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/dbm.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/dbm/__init__.py dbm is a generic interface to variants of the DBM database: dbm.sqlite3, dbm.gnu, dbm.ndbm. If none of these modules are installed, the slow-but-simple implementati..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_dbm_4f65734e.png" />15<meta property="og:image:alt" content="Source code: Lib/dbm/__init__.py dbm is a generic interface to variants of the DBM database: dbm.sqlite3, dbm.gnu, dbm.ndbm. If none of these modules are installed, the slow-but-simple implementati..." />16<meta name="description" content="Source code: Lib/dbm/__init__.py dbm is a generic interface to variants of the DBM database: dbm.sqlite3, dbm.gnu, dbm.ndbm. If none of these modules are installed, the slow-but-simple implementati..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>dbm — Interfaces to Unix “databases” — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="sqlite3 — DB-API 2.0 interface for SQLite databases" href="sqlite3.html" />43 <link rel="prev" title="marshal — Internal Python object serialization" href="marshal.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/dbm.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> — Interfaces to Unix “databases”</a><ul>108<li><a class="reference internal" href="#module-dbm.sqlite3"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code> — SQLite backend for dbm</a></li>109<li><a class="reference internal" href="#module-dbm.gnu"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code> — GNU database manager</a></li>110<li><a class="reference internal" href="#module-dbm.ndbm"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code> — New Database Manager</a></li>111<li><a class="reference internal" href="#module-dbm.dumb"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> — Portable DBM implementation</a></li>112</ul>113</li>114</ul>115 116 </div>117 <div>118 <h4>Previous topic</h4>119 <p class="topless"><a href="marshal.html"120 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">marshal</span></code> — Internal Python object serialization</a></p>121 </div>122 <div>123 <h4>Next topic</h4>124 <p class="topless"><a href="sqlite3.html"125 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlite3</span></code> — DB-API 2.0 interface for SQLite databases</a></p>126 </div>127 <script>128 document.addEventListener('DOMContentLoaded', () => {129 const title = document.querySelector('meta[property="og:title"]').content;130 const elements = document.querySelectorAll('.improvepage');131 const pageurl = window.location.href.split('?')[0];132 elements.forEach(element => {133 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));134 url.searchParams.set('pagetitle', title);135 url.searchParams.set('pageurl', pageurl);136 url.searchParams.set('pagesource', "library/dbm.rst");137 element.href = url.toString();138 });139 });140 </script>141 <div role="note" aria-label="source link">142 <h3>This page</h3>143 <ul class="this-page-menu">144 <li><a href="../bugs.html">Report a bug</a></li>145 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>146 <li>147 <a href="https://github.com/python/cpython/blob/main/Doc/library/dbm.rst?plain=1"148 rel="nofollow">Show source149 </a>150 </li>151 152 </ul>153 </div>154 </nav>155 </div>156</div>157 158 159 <div class="related" role="navigation" aria-label="Related">160 <h3>Navigation</h3>161 <ul>162 <li class="right" style="margin-right: 10px">163 <a href="../genindex.html" title="General Index"164 accesskey="I">index</a></li>165 <li class="right" >166 <a href="../py-modindex.html" title="Python Module Index"167 >modules</a> |</li>168 <li class="right" >169 <a href="sqlite3.html" title="sqlite3 — DB-API 2.0 interface for SQLite databases"170 accesskey="N">next</a> |</li>171 <li class="right" >172 <a href="marshal.html" title="marshal — Internal Python object serialization"173 accesskey="P">previous</a> |</li>174 175 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>176 <li><a href="https://www.python.org/">Python</a> »</li>177 <li class="switchers">178 <div class="language_switcher_placeholder"></div>179 <div class="version_switcher_placeholder"></div>180 </li>181 <li>182 183 </li>184 <li id="cpython-language-and-version">185 <a href="../index.html">3.15.0a6 Documentation</a> »186 </li>187 188 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>189 <li class="nav-item nav-item-2"><a href="persistence.html" accesskey="U">Data Persistence</a> »</li>190 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> — Interfaces to Unix “databases”</a></li>191 <li class="right">192 193 194 <div class="inline-search" role="search">195 <form class="inline-search" action="../search.html" method="get">196 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">197 <input type="submit" value="Go">198 </form>199 </div>200 |201 </li>202 <li class="right">203<label class="theme-selector-label">204 Theme205 <select class="theme-selector" oninput="activateTheme(this.value)">206 <option value="auto" selected>Auto</option>207 <option value="light">Light</option>208 <option value="dark">Dark</option>209 </select>210</label> |</li>211 212 </ul>213 </div> 214 215 <div class="document">216 <div class="documentwrapper">217 <div class="bodywrapper">218 <div class="body" role="main">219 220 <section id="module-dbm">221<span id="dbm-interfaces-to-unix-databases"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> — Interfaces to Unix “databases”<a class="headerlink" href="#module-dbm" title="Link to this heading">¶</a></h1>222<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/dbm/__init__.py">Lib/dbm/__init__.py</a></p>223<hr class="docutils" />224<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> is a generic interface to variants of the DBM database:</p>225<ul class="simple">226<li><p><a class="reference internal" href="#module-dbm.sqlite3" title="dbm.sqlite3: SQLite backend for dbm"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code></a></p></li>227<li><p><a class="reference internal" href="#module-dbm.gnu" title="dbm.gnu: GNU database manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code></a></p></li>228<li><p><a class="reference internal" href="#module-dbm.ndbm" title="dbm.ndbm: The New Database Manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code></a></p></li>229</ul>230<p>If none of these modules are installed, the231slow-but-simple implementation in module <a class="reference internal" href="#module-dbm.dumb" title="dbm.dumb: Portable implementation of the simple DBM interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code></a> will be used. There232is a <a class="reference external" href="https://www.jcea.es/programacion/pybsddb.htm">third party interface</a> to233the Oracle Berkeley DB.</p>234<div class="admonition note">235<p class="admonition-title">Note</p>236<p>None of the underlying modules will automatically shrink the disk space used by237the database file. However, <a class="reference internal" href="#module-dbm.sqlite3" title="dbm.sqlite3: SQLite backend for dbm"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code></a>, <a class="reference internal" href="#module-dbm.gnu" title="dbm.gnu: GNU database manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code></a> and <a class="reference internal" href="#module-dbm.dumb" title="dbm.dumb: Portable implementation of the simple DBM interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code></a>238provide a <code class="xref py py-meth docutils literal notranslate"><span class="pre">reorganize()</span></code> method that can be used for this purpose.</p>239</div>240<dl class="py exception">241<dt class="sig sig-object py" id="dbm.error">242<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dbm.</span></span><span class="sig-name descname"><span class="pre">error</span></span><a class="headerlink" href="#dbm.error" title="Link to this definition">¶</a></dt>243<dd><p>A tuple containing the exceptions that can be raised by each of the supported244modules, with a unique exception also named <a class="reference internal" href="#dbm.error" title="dbm.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">dbm.error</span></code></a> as the first245item — the latter is used when <code class="xref py py-exc docutils literal notranslate"><span class="pre">dbm.error</span></code> is raised.</p>246</dd></dl>247 248<dl class="py function">249<dt class="sig sig-object py" id="dbm.whichdb">250<span class="sig-prename descclassname"><span class="pre">dbm.</span></span><span class="sig-name descname"><span class="pre">whichdb</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.whichdb" title="Link to this definition">¶</a></dt>251<dd><p>This function attempts to guess which of the several simple database modules252available — <a class="reference internal" href="#module-dbm.sqlite3" title="dbm.sqlite3: SQLite backend for dbm"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code></a>, <a class="reference internal" href="#module-dbm.gnu" title="dbm.gnu: GNU database manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code></a>, <a class="reference internal" href="#module-dbm.ndbm" title="dbm.ndbm: The New Database Manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code></a>,253or <a class="reference internal" href="#module-dbm.dumb" title="dbm.dumb: Portable implementation of the simple DBM interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code></a> — should be used to open a given file.</p>254<p>Return one of the following values:</p>255<ul class="simple">256<li><p><code class="docutils literal notranslate"><span class="pre">None</span></code> if the file can’t be opened because it’s unreadable or doesn’t exist</p></li>257<li><p>the empty string (<code class="docutils literal notranslate"><span class="pre">''</span></code>) if the file’s format can’t be guessed</p></li>258<li><p>a string containing the required module name, such as <code class="docutils literal notranslate"><span class="pre">'dbm.ndbm'</span></code> or <code class="docutils literal notranslate"><span class="pre">'dbm.gnu'</span></code></p></li>259</ul>260<div class="versionchanged">261<p><span class="versionmodified changed">Changed in version 3.11: </span><em>filename</em> accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>262</div>263</dd></dl>264 265<dl class="py function">266<dt class="sig sig-object py" id="dbm.open">267<span class="sig-prename descclassname"><span class="pre">dbm.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0o666</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.open" title="Link to this definition">¶</a></dt>268<dd><p>Open a database and return the corresponding database object.</p>269<dl class="field-list simple">270<dt class="field-odd">Parameters<span class="colon">:</span></dt>271<dd class="field-odd"><ul class="simple">272<li><p><strong>file</strong> (<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>) – <p>The database file to open.</p>273<p>If the database file already exists, the <a class="reference internal" href="#dbm.whichdb" title="dbm.whichdb"><code class="xref py py-func docutils literal notranslate"><span class="pre">whichdb()</span></code></a> function is used to274determine its type and the appropriate module is used; if it does not exist,275the first submodule listed above that can be imported is used.</p>276</p></li>277<li><p><strong>flag</strong> (<a class="reference internal" href="stdtypes.html#str" title="str"><em>str</em></a>) – <ul>278<li><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code> (default): Open existing database for reading only.</p></li>279<li><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code>: Open existing database for reading and writing.</p></li>280<li><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code>: Open database for reading and writing, creating it if it doesn’t exist.</p></li>281<li><p><code class="docutils literal notranslate"><span class="pre">'n'</span></code>: Always create a new, empty database, open for reading and writing.</p></li>282</ul>283</p></li>284<li><p><strong>mode</strong> (<a class="reference internal" href="functions.html#int" title="int"><em>int</em></a>) – The Unix file access mode of the file (default: octal <code class="docutils literal notranslate"><span class="pre">0o666</span></code>),285used only when the database has to be created.</p></li>286</ul>287</dd>288</dl>289<div class="versionchanged">290<p><span class="versionmodified changed">Changed in version 3.11: </span><em>file</em> accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>291</div>292</dd></dl>293 294<p>The object returned by <a class="reference internal" href="#dbm.open" title="dbm.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> supports the basic295functionality of mutable <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mappings</span></a>;296keys and their corresponding values can be stored, retrieved, and297deleted, and iteration, the <a class="reference internal" href="../reference/expressions.html#in"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">in</span></code></a> operator and methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code>,298<code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code> are available.299The <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code> method returns a list instead of a view object.300The <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> method requires two arguments.</p>301<p>Key and values are always stored as <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>. This means that when302strings are used they are implicitly converted to the default encoding before303being stored.</p>304<p>These objects also support being used in a <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement, which305will automatically close them when done.</p>306<div class="versionchanged">307<p><span class="versionmodified changed">Changed in version 3.2: </span><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> methods are now available for all308<code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> backends.</p>309</div>310<div class="versionchanged">311<p><span class="versionmodified changed">Changed in version 3.4: </span>Added native support for the context management protocol to the objects312returned by <a class="reference internal" href="#dbm.open" title="dbm.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>.</p>313</div>314<div class="versionchanged">315<p><span class="versionmodified changed">Changed in version 3.8: </span>Deleting a key from a read-only database raises a database module specific exception316instead of <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>.</p>317</div>318<div class="versionchanged">319<p><span class="versionmodified changed">Changed in version 3.13: </span><code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code> methods are now available for all <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> backends.</p>320</div>321<p>The following example records some hostnames and a corresponding title, and322then prints out the contents of the database:</p>323<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">dbm</span>324 325<span class="c1"># Open database, creating it if necessary.</span>326<span class="k">with</span> <span class="n">dbm</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="s1">'cache'</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">)</span> <span class="k">as</span> <span class="n">db</span><span class="p">:</span>327 328 <span class="c1"># Record some values</span>329 <span class="n">db</span><span class="p">[</span><span class="sa">b</span><span class="s1">'hello'</span><span class="p">]</span> <span class="o">=</span> <span class="sa">b</span><span class="s1">'there'</span>330 <span class="n">db</span><span class="p">[</span><span class="s1">'www.python.org'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'Python Website'</span>331 <span class="n">db</span><span class="p">[</span><span class="s1">'www.cnn.com'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'Cable News Network'</span>332 333 <span class="c1"># Note that the keys are considered bytes now.</span>334 <span class="k">assert</span> <span class="n">db</span><span class="p">[</span><span class="sa">b</span><span class="s1">'www.python.org'</span><span class="p">]</span> <span class="o">==</span> <span class="sa">b</span><span class="s1">'Python Website'</span>335 <span class="c1"># Notice how the value is now in bytes.</span>336 <span class="k">assert</span> <span class="n">db</span><span class="p">[</span><span class="s1">'www.cnn.com'</span><span class="p">]</span> <span class="o">==</span> <span class="sa">b</span><span class="s1">'Cable News Network'</span>337 338 <span class="c1"># Often-used methods of the dict interface work too.</span>339 <span class="nb">print</span><span class="p">(</span><span class="n">db</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'python.org'</span><span class="p">,</span> <span class="sa">b</span><span class="s1">'not present'</span><span class="p">))</span>340 341 <span class="c1"># Storing a non-string key or value will raise an exception (most</span>342 <span class="c1"># likely a TypeError).</span>343 <span class="n">db</span><span class="p">[</span><span class="s1">'www.yahoo.com'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">4</span>344 345<span class="c1"># db is automatically closed when leaving the with statement.</span>346</pre></div>347</div>348<div class="admonition seealso">349<p class="admonition-title">See also</p>350<dl class="simple">351<dt>Module <a class="reference internal" href="shelve.html#module-shelve" title="shelve: Python object persistence."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shelve</span></code></a></dt><dd><p>Persistence module which stores non-string data.</p>352</dd>353</dl>354</div>355<p>The individual submodules are described in the following sections.</p>356<section id="module-dbm.sqlite3">357<span id="dbm-sqlite3-sqlite-backend-for-dbm"></span><h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code> — SQLite backend for dbm<a class="headerlink" href="#module-dbm.sqlite3" title="Link to this heading">¶</a></h2>358<div class="versionadded">359<p><span class="versionmodified added">Added in version 3.13.</span></p>360</div>361<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/dbm/sqlite3.py">Lib/dbm/sqlite3.py</a></p>362<hr class="docutils" />363<p>This module uses the standard library <a class="reference internal" href="sqlite3.html#module-sqlite3" title="sqlite3: A DB-API 2.0 implementation using SQLite 3.x."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlite3</span></code></a> module to provide an364SQLite backend for the <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> module.365The files created by <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code> can thus be opened by <code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlite3</span></code>,366or any other SQLite browser, including the SQLite CLI.</p>367<div class="availability docutils container">368<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not WASI.</p>369<p>This module does not work or is not available on WebAssembly. See370<a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p>371</div>372<dl class="py function">373<dt class="sig sig-object py" id="dbm.sqlite3.open">374<span class="sig-prename descclassname"><span class="pre">dbm.sqlite3.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0o666</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.sqlite3.open" title="Link to this definition">¶</a></dt>375<dd><p>Open an SQLite database.</p>376<dl class="field-list simple">377<dt class="field-odd">Parameters<span class="colon">:</span></dt>378<dd class="field-odd"><ul class="simple">379<li><p><strong>filename</strong> (<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>) – The path to the database to be opened.</p></li>380<li><p><strong>flag</strong> (<a class="reference internal" href="stdtypes.html#str" title="str"><em>str</em></a>) – <ul>381<li><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code> (default): Open existing database for reading only.</p></li>382<li><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code>: Open existing database for reading and writing.</p></li>383<li><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code>: Open database for reading and writing, creating it if it doesn’t exist.</p></li>384<li><p><code class="docutils literal notranslate"><span class="pre">'n'</span></code>: Always create a new, empty database, open for reading and writing.</p></li>385</ul>386</p></li>387<li><p><strong>mode</strong> – The Unix file access mode of the file (default: octal <code class="docutils literal notranslate"><span class="pre">0o666</span></code>),388used only when the database has to be created.</p></li>389</ul>390</dd>391</dl>392<p>The returned database object behaves similar to a mutable <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a>,393but the <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code> method returns a list, and394the <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> method requires two arguments.395It also supports a “closing” context manager via the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> keyword.</p>396<p>The following methods are also provided:</p>397<dl class="py method">398<dt class="sig sig-object py" id="dbm.sqlite3.sqlite3.close">399<span class="sig-prename descclassname"><span class="pre">sqlite3.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.sqlite3.sqlite3.close" title="Link to this definition">¶</a></dt>400<dd><p>Close the SQLite database.</p>401</dd></dl>402 403<dl class="py method">404<dt class="sig sig-object py" id="dbm.sqlite3.sqlite3.reorganize">405<span class="sig-prename descclassname"><span class="pre">sqlite3.</span></span><span class="sig-name descname"><span class="pre">reorganize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.sqlite3.sqlite3.reorganize" title="Link to this definition">¶</a></dt>406<dd><p>If you have carried out a lot of deletions and would like to shrink the space407used on disk, this method will reorganize the database; otherwise, deleted file408space will be kept and reused as new (key, value) pairs are added.</p>409<div class="admonition note">410<p class="admonition-title">Note</p>411<p>While reorganizing, as much as two times the size of the original database is required412in free disk space. However, be aware that this factor changes for each <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> submodule.</p>413</div>414<div class="versionadded">415<p><span class="versionmodified added">Added in version 3.15.</span></p>416</div>417</dd></dl>418 419</dd></dl>420 421</section>422<section id="module-dbm.gnu">423<span id="dbm-gnu-gnu-database-manager"></span><h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code> — GNU database manager<a class="headerlink" href="#module-dbm.gnu" title="Link to this heading">¶</a></h2>424<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/dbm/gnu.py">Lib/dbm/gnu.py</a></p>425<hr class="docutils" />426<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code> module provides an interface to the <abbr title="GNU dbm">GDBM</abbr>427library, similar to the <a class="reference internal" href="#module-dbm.ndbm" title="dbm.ndbm: The New Database Manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code></a> module, but with additional428functionality like crash tolerance.</p>429<div class="admonition note">430<p class="admonition-title">Note</p>431<p>The file formats created by <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code> and <a class="reference internal" href="#module-dbm.ndbm" title="dbm.ndbm: The New Database Manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code></a> are incompatible432and can not be used interchangeably.</p>433</div>434<div class="availability docutils container">435<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not Android, not iOS, not WASI.</p>436<p>This module is not supported on <a class="reference internal" href="intro.html#mobile-availability"><span class="std std-ref">mobile platforms</span></a>437or <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a>.</p>438</div>439<div class="availability docutils container">440<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>441</div>442<dl class="py exception">443<dt class="sig sig-object py" id="dbm.gnu.error">444<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dbm.gnu.</span></span><span class="sig-name descname"><span class="pre">error</span></span><a class="headerlink" href="#dbm.gnu.error" title="Link to this definition">¶</a></dt>445<dd><p>Raised on <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code>-specific errors, such as I/O errors. <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is446raised for general mapping errors like specifying an incorrect key.</p>447</dd></dl>448 449<dl class="py data">450<dt class="sig sig-object py" id="dbm.gnu.open_flags">451<span class="sig-prename descclassname"><span class="pre">dbm.gnu.</span></span><span class="sig-name descname"><span class="pre">open_flags</span></span><a class="headerlink" href="#dbm.gnu.open_flags" title="Link to this definition">¶</a></dt>452<dd><p>A string of characters the <em>flag</em> parameter of <a class="reference internal" href="#dbm.gnu.open" title="dbm.gnu.open"><code class="xref py py-meth docutils literal notranslate"><span class="pre">open()</span></code></a> supports.</p>453</dd></dl>454 455<dl class="py function">456<dt class="sig sig-object py" id="dbm.gnu.open">457<span class="sig-prename descclassname"><span class="pre">dbm.gnu.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0o666</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.gnu.open" title="Link to this definition">¶</a></dt>458<dd><p>Open a GDBM database and return a <code class="xref py py-class docutils literal notranslate"><span class="pre">gdbm</span></code> object.</p>459<dl class="field-list simple">460<dt class="field-odd">Parameters<span class="colon">:</span></dt>461<dd class="field-odd"><ul class="simple">462<li><p><strong>filename</strong> (<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>) – The database file to open.</p></li>463<li><p><strong>flag</strong> (<a class="reference internal" href="stdtypes.html#str" title="str"><em>str</em></a>) – <ul>464<li><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code> (default): Open existing database for reading only.</p></li>465<li><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code>: Open existing database for reading and writing.</p></li>466<li><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code>: Open database for reading and writing, creating it if it doesn’t exist.</p></li>467<li><p><code class="docutils literal notranslate"><span class="pre">'n'</span></code>: Always create a new, empty database, open for reading and writing.</p></li>468</ul>469<p>The following additional characters may be appended470to control how the database is opened:</p>471<ul>472<li><p><code class="docutils literal notranslate"><span class="pre">'f'</span></code>: Open the database in fast mode.473Writes to the database will not be synchronized.</p></li>474<li><p><code class="docutils literal notranslate"><span class="pre">'s'</span></code>: Synchronized mode.475Changes to the database will be written immediately to the file.</p></li>476<li><p><code class="docutils literal notranslate"><span class="pre">'u'</span></code>: Do not lock database.</p></li>477</ul>478<p>Not all flags are valid for all versions of GDBM.479See the <a class="reference internal" href="#dbm.gnu.open_flags" title="dbm.gnu.open_flags"><code class="xref py py-data docutils literal notranslate"><span class="pre">open_flags</span></code></a> member for a list of supported flag characters.</p>480</p></li>481<li><p><strong>mode</strong> (<a class="reference internal" href="functions.html#int" title="int"><em>int</em></a>) – The Unix file access mode of the file (default: octal <code class="docutils literal notranslate"><span class="pre">0o666</span></code>),482used only when the database has to be created.</p></li>483</ul>484</dd>485<dt class="field-even">Raises<span class="colon">:</span></dt>486<dd class="field-even"><p><a class="reference internal" href="#dbm.gnu.error" title="dbm.gnu.error"><strong>error</strong></a> – If an invalid <em>flag</em> argument is passed.</p>487</dd>488</dl>489<div class="versionchanged">490<p><span class="versionmodified changed">Changed in version 3.11: </span><em>filename</em> accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>491</div>492<p><code class="xref py py-class docutils literal notranslate"><span class="pre">gdbm</span></code> objects behave similar to mutable <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mappings</span></a>,493but methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">items()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">values()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">pop()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">popitem()</span></code>,494and <code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code> are not supported,495the <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code> method returns a list, and496the <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> method requires two arguments.497It also supports a “closing” context manager via the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> keyword.</p>498<div class="versionchanged">499<p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> methods.</p>500</div>501<div class="versionchanged">502<p><span class="versionmodified changed">Changed in version 3.13: </span>Added the <code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code> method.</p>503</div>504<p>The following methods are also provided:</p>505<dl class="py method">506<dt class="sig sig-object py" id="dbm.gnu.gdbm.close">507<span class="sig-prename descclassname"><span class="pre">gdbm.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.gnu.gdbm.close" title="Link to this definition">¶</a></dt>508<dd><p>Close the GDBM database.</p>509</dd></dl>510 511<dl class="py method">512<dt class="sig sig-object py" id="dbm.gnu.gdbm.firstkey">513<span class="sig-prename descclassname"><span class="pre">gdbm.</span></span><span class="sig-name descname"><span class="pre">firstkey</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.gnu.gdbm.firstkey" title="Link to this definition">¶</a></dt>514<dd><p>It’s possible to loop over every key in the database using this method and the515<a class="reference internal" href="#dbm.gnu.gdbm.nextkey" title="dbm.gnu.gdbm.nextkey"><code class="xref py py-meth docutils literal notranslate"><span class="pre">nextkey()</span></code></a> method. The traversal is ordered by GDBM’s internal516hash values, and won’t be sorted by the key values. This method returns517the starting key.</p>518</dd></dl>519 520<dl class="py method">521<dt class="sig sig-object py" id="dbm.gnu.gdbm.nextkey">522<span class="sig-prename descclassname"><span class="pre">gdbm.</span></span><span class="sig-name descname"><span class="pre">nextkey</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.gnu.gdbm.nextkey" title="Link to this definition">¶</a></dt>523<dd><p>Returns the key that follows <em>key</em> in the traversal. The following code prints524every key in the database <code class="docutils literal notranslate"><span class="pre">db</span></code>, without having to create a list in memory that525contains them all:</p>526<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">k</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">firstkey</span><span class="p">()</span>527<span class="k">while</span> <span class="n">k</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>528 <span class="nb">print</span><span class="p">(</span><span class="n">k</span><span class="p">)</span>529 <span class="n">k</span> <span class="o">=</span> <span class="n">db</span><span class="o">.</span><span class="n">nextkey</span><span class="p">(</span><span class="n">k</span><span class="p">)</span>530</pre></div>531</div>532</dd></dl>533 534<dl class="py method">535<dt class="sig sig-object py" id="dbm.gnu.gdbm.reorganize">536<span class="sig-prename descclassname"><span class="pre">gdbm.</span></span><span class="sig-name descname"><span class="pre">reorganize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.gnu.gdbm.reorganize" title="Link to this definition">¶</a></dt>537<dd><p>If you have carried out a lot of deletions and would like to shrink the space538used by the GDBM file, this routine will reorganize the database. <code class="xref py py-class docutils literal notranslate"><span class="pre">gdbm</span></code>539objects will not shorten the length of a database file except by using this540reorganization; otherwise, deleted file space will be kept and reused as new541(key, value) pairs are added.</p>542<div class="admonition note">543<p class="admonition-title">Note</p>544<p>While reorganizing, as much as one time the size of the original database is required545in free disk space. However, be aware that this factor changes for each <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> submodule.</p>546</div>547</dd></dl>548 549<dl class="py method">550<dt class="sig sig-object py" id="dbm.gnu.gdbm.sync">551<span class="sig-prename descclassname"><span class="pre">gdbm.</span></span><span class="sig-name descname"><span class="pre">sync</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.gnu.gdbm.sync" title="Link to this definition">¶</a></dt>552<dd><p>When the database has been opened in fast mode, this method forces any553unwritten data to be written to the disk.</p>554</dd></dl>555 556</dd></dl>557 558</section>559<section id="module-dbm.ndbm">560<span id="dbm-ndbm-new-database-manager"></span><h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code> — New Database Manager<a class="headerlink" href="#module-dbm.ndbm" title="Link to this heading">¶</a></h2>561<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/dbm/ndbm.py">Lib/dbm/ndbm.py</a></p>562<hr class="docutils" />563<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code> module provides an interface to the564<abbr title="New Database Manager">NDBM</abbr> library.565This module can be used with the “classic” NDBM interface or the566<abbr title="GNU dbm">GDBM</abbr> compatibility interface.</p>567<div class="admonition note">568<p class="admonition-title">Note</p>569<p>The file formats created by <a class="reference internal" href="#module-dbm.gnu" title="dbm.gnu: GNU database manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code></a> and <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code> are incompatible570and can not be used interchangeably.</p>571</div>572<div class="admonition warning">573<p class="admonition-title">Warning</p>574<p>The NDBM library shipped as part of macOS has an undocumented limitation on the575size of values, which can result in corrupted database files576when storing values larger than this limit. Reading such corrupted files can577result in a hard crash (segmentation fault).</p>578</div>579<div class="availability docutils container">580<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not Android, not iOS, not WASI.</p>581<p>This module is not supported on <a class="reference internal" href="intro.html#mobile-availability"><span class="std std-ref">mobile platforms</span></a>582or <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a>.</p>583</div>584<div class="availability docutils container">585<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: Unix.</p>586</div>587<dl class="py exception">588<dt class="sig sig-object py" id="dbm.ndbm.error">589<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dbm.ndbm.</span></span><span class="sig-name descname"><span class="pre">error</span></span><a class="headerlink" href="#dbm.ndbm.error" title="Link to this definition">¶</a></dt>590<dd><p>Raised on <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code>-specific errors, such as I/O errors. <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is raised591for general mapping errors like specifying an incorrect key.</p>592</dd></dl>593 594<dl class="py data">595<dt class="sig sig-object py" id="dbm.ndbm.library">596<span class="sig-prename descclassname"><span class="pre">dbm.ndbm.</span></span><span class="sig-name descname"><span class="pre">library</span></span><a class="headerlink" href="#dbm.ndbm.library" title="Link to this definition">¶</a></dt>597<dd><p>Name of the NDBM implementation library used.</p>598</dd></dl>599 600<dl class="py function">601<dt class="sig sig-object py" id="dbm.ndbm.open">602<span class="sig-prename descclassname"><span class="pre">dbm.ndbm.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0o666</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.ndbm.open" title="Link to this definition">¶</a></dt>603<dd><p>Open an NDBM database and return an <code class="xref py py-class docutils literal notranslate"><span class="pre">ndbm</span></code> object.</p>604<dl class="field-list simple">605<dt class="field-odd">Parameters<span class="colon">:</span></dt>606<dd class="field-odd"><ul class="simple">607<li><p><strong>filename</strong> (<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>) – The basename of the database file608(without the <code class="file docutils literal notranslate"><span class="pre">.dir</span></code> or <code class="file docutils literal notranslate"><span class="pre">.pag</span></code> extensions).</p></li>609<li><p><strong>flag</strong> (<a class="reference internal" href="stdtypes.html#str" title="str"><em>str</em></a>) – <ul>610<li><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code> (default): Open existing database for reading only.</p></li>611<li><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code>: Open existing database for reading and writing.</p></li>612<li><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code>: Open database for reading and writing, creating it if it doesn’t exist.</p></li>613<li><p><code class="docutils literal notranslate"><span class="pre">'n'</span></code>: Always create a new, empty database, open for reading and writing.</p></li>614</ul>615</p></li>616<li><p><strong>mode</strong> (<a class="reference internal" href="functions.html#int" title="int"><em>int</em></a>) – The Unix file access mode of the file (default: octal <code class="docutils literal notranslate"><span class="pre">0o666</span></code>),617used only when the database has to be created.</p></li>618</ul>619</dd>620</dl>621<div class="versionchanged">622<p><span class="versionmodified changed">Changed in version 3.11: </span>Accepts <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a> for filename.</p>623</div>624<p><code class="xref py py-class docutils literal notranslate"><span class="pre">ndbm</span></code> objects behave similar to mutable <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mappings</span></a>,625but methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">items()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">values()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">pop()</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">popitem()</span></code>,626and <code class="xref py py-meth docutils literal notranslate"><span class="pre">update()</span></code> are not supported,627the <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code> method returns a list, and628the <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> method requires two arguments.629It also supports a “closing” context manager via the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> keyword.</p>630<div class="versionchanged">631<p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> methods.</p>632</div>633<div class="versionchanged">634<p><span class="versionmodified changed">Changed in version 3.13: </span>Added the <code class="xref py py-meth docutils literal notranslate"><span class="pre">clear()</span></code> method.</p>635</div>636<p>The following method is also provided:</p>637<dl class="py method">638<dt class="sig sig-object py" id="dbm.ndbm.ndbm.close">639<span class="sig-prename descclassname"><span class="pre">ndbm.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.ndbm.ndbm.close" title="Link to this definition">¶</a></dt>640<dd><p>Close the NDBM database.</p>641</dd></dl>642 643</dd></dl>644 645</section>646<section id="module-dbm.dumb">647<span id="dbm-dumb-portable-dbm-implementation"></span><h2><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> — Portable DBM implementation<a class="headerlink" href="#module-dbm.dumb" title="Link to this heading">¶</a></h2>648<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/dbm/dumb.py">Lib/dbm/dumb.py</a></p>649<div class="admonition note" id="index-0">650<p class="admonition-title">Note</p>651<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> module is intended as a last resort fallback for the652<code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> module when a more robust module is not available. The <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code>653module is not written for speed and is not nearly as heavily used as the other654database modules.</p>655</div>656<hr class="docutils" />657<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> module provides a persistent <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>-like658interface which is written entirely in Python.659Unlike other <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> backends, such as <a class="reference internal" href="#module-dbm.gnu" title="dbm.gnu: GNU database manager"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code></a>, no660external library is required.</p>661<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> module defines the following:</p>662<dl class="py exception">663<dt class="sig sig-object py" id="dbm.dumb.error">664<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dbm.dumb.</span></span><span class="sig-name descname"><span class="pre">error</span></span><a class="headerlink" href="#dbm.dumb.error" title="Link to this definition">¶</a></dt>665<dd><p>Raised on <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code>-specific errors, such as I/O errors. <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a> is666raised for general mapping errors like specifying an incorrect key.</p>667</dd></dl>668 669<dl class="py function">670<dt class="sig sig-object py" id="dbm.dumb.open">671<span class="sig-prename descclassname"><span class="pre">dbm.dumb.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">flag</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'c'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0o666</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dbm.dumb.open" title="Link to this definition">¶</a></dt>672<dd><p>Open a <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> database.</p>673<dl class="field-list simple">674<dt class="field-odd">Parameters<span class="colon">:</span></dt>675<dd class="field-odd"><ul class="simple">676<li><p><strong>filename</strong> – <p>The basename of the database file (without extensions).677A new database creates the following files:</p>678<ul>679<li><p><code class="file docutils literal notranslate"><em><span class="pre">filename</span></em><span class="pre">.dat</span></code></p></li>680<li><p><code class="file docutils literal notranslate"><em><span class="pre">filename</span></em><span class="pre">.dir</span></code></p></li>681</ul>682</p></li>683<li><p><strong>flag</strong> (<a class="reference internal" href="stdtypes.html#str" title="str"><em>str</em></a>) – <ul>684<li><p><code class="docutils literal notranslate"><span class="pre">'r'</span></code>: Open existing database for reading only.</p></li>685<li><p><code class="docutils literal notranslate"><span class="pre">'w'</span></code>: Open existing database for reading and writing.</p></li>686<li><p><code class="docutils literal notranslate"><span class="pre">'c'</span></code> (default): Open database for reading and writing, creating it if it doesn’t exist.</p></li>687<li><p><code class="docutils literal notranslate"><span class="pre">'n'</span></code>: Always create a new, empty database, open for reading and writing.</p></li>688</ul>689</p></li>690<li><p><strong>mode</strong> (<a class="reference internal" href="functions.html#int" title="int"><em>int</em></a>) – The Unix file access mode of the file (default: octal <code class="docutils literal notranslate"><span class="pre">0o666</span></code>),691used only when the database has to be created.</p></li>692</ul>693</dd>694</dl>695<div class="admonition warning">696<p class="admonition-title">Warning</p>697<p>It is possible to crash the Python interpreter when loading a database698with a sufficiently large/complex entry due to stack depth limitations in699Python’s AST compiler.</p>700</div>701<div class="admonition warning">702<p class="admonition-title">Warning</p>703<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> does not support concurrent read/write access. (Multiple704simultaneous read accesses are safe.) When a program has the database open705for writing, no other program should have it open for reading or writing.</p>706</div>707<div class="versionchanged">708<p><span class="versionmodified changed">Changed in version 3.5: </span><a class="reference internal" href="#dbm.dumb.open" title="dbm.dumb.open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> always creates a new database when <em>flag</em> is <code class="docutils literal notranslate"><span class="pre">'n'</span></code>.</p>709</div>710<div class="versionchanged">711<p><span class="versionmodified changed">Changed in version 3.8: </span>A database opened read-only if <em>flag</em> is <code class="docutils literal notranslate"><span class="pre">'r'</span></code>.712A database is not created if it does not exist if <em>flag</em> is <code class="docutils literal notranslate"><span class="pre">'r'</span></code> or <code class="docutils literal notranslate"><span class="pre">'w'</span></code>.</p>713</div>714<div class="versionchanged">715<p><span class="versionmodified changed">Changed in version 3.11: </span><em>filename</em> accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>716</div>717<p>The returned database object behaves similar to a mutable <a class="reference internal" href="../glossary.html#term-mapping"><span class="xref std std-term">mapping</span></a>,718but the <code class="xref py py-meth docutils literal notranslate"><span class="pre">keys()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">items()</span></code> methods return lists, and719the <code class="xref py py-meth docutils literal notranslate"><span class="pre">setdefault()</span></code> method requires two arguments.720It also supports a “closing” context manager via the <a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> keyword.</p>721<p>The following methods are also provided:</p>722<dl class="py method">723<dt class="sig sig-object py" id="dbm.dumb.dumbdbm.close">724<span class="sig-prename descclassname"><span class="pre">dumbdbm.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.dumb.dumbdbm.close" title="Link to this definition">¶</a></dt>725<dd><p>Close the database.</p>726</dd></dl>727 728<dl class="py method">729<dt class="sig sig-object py" id="dbm.dumb.dumbdbm.reorganize">730<span class="sig-prename descclassname"><span class="pre">dumbdbm.</span></span><span class="sig-name descname"><span class="pre">reorganize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.dumb.dumbdbm.reorganize" title="Link to this definition">¶</a></dt>731<dd><p>If you have carried out a lot of deletions and would like to shrink the space732used on disk, this method will reorganize the database; otherwise, deleted file733space will not be reused.</p>734<div class="admonition note">735<p class="admonition-title">Note</p>736<p>While reorganizing, no additional free disk space is required. However, be aware737that this factor changes for each <code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> submodule.</p>738</div>739<div class="versionadded">740<p><span class="versionmodified added">Added in version 3.15.</span></p>741</div>742</dd></dl>743 744<dl class="py method">745<dt class="sig sig-object py" id="dbm.dumb.dumbdbm.sync">746<span class="sig-prename descclassname"><span class="pre">dumbdbm.</span></span><span class="sig-name descname"><span class="pre">sync</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#dbm.dumb.dumbdbm.sync" title="Link to this definition">¶</a></dt>747<dd><p>Synchronize the on-disk directory and data files. This method is called748by the <a class="reference internal" href="shelve.html#shelve.Shelf.sync" title="shelve.Shelf.sync"><code class="xref py py-meth docutils literal notranslate"><span class="pre">shelve.Shelf.sync()</span></code></a> method.</p>749</dd></dl>750 751</dd></dl>752 753</section>754</section>755 756 757 <div class="clearer"></div>758 </div>759 </div>760 </div>761 <div class="sphinxsidebar" role="navigation" aria-label="Main">762 <div class="sphinxsidebarwrapper">763 <div>764 <h3><a href="../contents.html">Table of Contents</a></h3>765 <ul>766<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> — Interfaces to Unix “databases”</a><ul>767<li><a class="reference internal" href="#module-dbm.sqlite3"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.sqlite3</span></code> — SQLite backend for dbm</a></li>768<li><a class="reference internal" href="#module-dbm.gnu"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.gnu</span></code> — GNU database manager</a></li>769<li><a class="reference internal" href="#module-dbm.ndbm"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.ndbm</span></code> — New Database Manager</a></li>770<li><a class="reference internal" href="#module-dbm.dumb"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm.dumb</span></code> — Portable DBM implementation</a></li>771</ul>772</li>773</ul>774 775 </div>776 <div>777 <h4>Previous topic</h4>778 <p class="topless"><a href="marshal.html"779 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">marshal</span></code> — Internal Python object serialization</a></p>780 </div>781 <div>782 <h4>Next topic</h4>783 <p class="topless"><a href="sqlite3.html"784 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sqlite3</span></code> — DB-API 2.0 interface for SQLite databases</a></p>785 </div>786 <script>787 document.addEventListener('DOMContentLoaded', () => {788 const title = document.querySelector('meta[property="og:title"]').content;789 const elements = document.querySelectorAll('.improvepage');790 const pageurl = window.location.href.split('?')[0];791 elements.forEach(element => {792 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));793 url.searchParams.set('pagetitle', title);794 url.searchParams.set('pageurl', pageurl);795 url.searchParams.set('pagesource', "library/dbm.rst");796 element.href = url.toString();797 });798 });799 </script>800 <div role="note" aria-label="source link">801 <h3>This page</h3>802 <ul class="this-page-menu">803 <li><a href="../bugs.html">Report a bug</a></li>804 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>805 <li>806 <a href="https://github.com/python/cpython/blob/main/Doc/library/dbm.rst?plain=1"807 rel="nofollow">Show source808 </a>809 </li>810 811 </ul>812 </div>813 </div>814<div id="sidebarbutton" title="Collapse sidebar">815<span>«</span>816</div>817 818 </div>819 <div class="clearer"></div>820 </div> 821 <div class="related" role="navigation" aria-label="Related">822 <h3>Navigation</h3>823 <ul>824 <li class="right" style="margin-right: 10px">825 <a href="../genindex.html" title="General Index"826 >index</a></li>827 <li class="right" >828 <a href="../py-modindex.html" title="Python Module Index"829 >modules</a> |</li>830 <li class="right" >831 <a href="sqlite3.html" title="sqlite3 — DB-API 2.0 interface for SQLite databases"832 >next</a> |</li>833 <li class="right" >834 <a href="marshal.html" title="marshal — Internal Python object serialization"835 >previous</a> |</li>836 837 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>838 <li><a href="https://www.python.org/">Python</a> »</li>839 <li class="switchers">840 <div class="language_switcher_placeholder"></div>841 <div class="version_switcher_placeholder"></div>842 </li>843 <li>844 845 </li>846 <li id="cpython-language-and-version">847 <a href="../index.html">3.15.0a6 Documentation</a> »848 </li>849 850 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>851 <li class="nav-item nav-item-2"><a href="persistence.html" >Data Persistence</a> »</li>852 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">dbm</span></code> — Interfaces to Unix “databases”</a></li>853 <li class="right">854 855 856 <div class="inline-search" role="search">857 <form class="inline-search" action="../search.html" method="get">858 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">859 <input type="submit" value="Go">860 </form>861 </div>862 |863 </li>864 <li class="right">865<label class="theme-selector-label">866 Theme867 <select class="theme-selector" oninput="activateTheme(this.value)">868 <option value="auto" selected>Auto</option>869 <option value="light">Light</option>870 <option value="dark">Dark</option>871 </select>872</label> |</li>873 874 </ul>875 </div> 876 <div class="footer">877 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.878 <br>879 This page is licensed under the Python Software Foundation License Version 2.880 <br>881 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.882 <br>883 884 See <a href="/license.html">History and License</a> for more information.<br>885 886 887 <br>888 889 The Python Software Foundation is a non-profit corporation.890<a href="https://www.python.org/psf/donations/">Please donate.</a>891<br>892 <br>893 Last updated on Mar 10, 2026 (08:58 UTC).894 895 <a href="/bugs.html">Found a bug</a>?896 897 <br>898 899 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.900 </div>901 902 </body>903</html>