947 lines
66 KiB
HTML
947 lines
66 KiB
HTML
|
|
|||
|
|
<!DOCTYPE html>
|
|||
|
|
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<title>winreg — Windows registry access — Python 3.7.4 documentation</title>
|
|||
|
|
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
|||
|
|
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/jquery.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/underscore.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/doctools.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/language_data.js"></script>
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
|||
|
|
|
|||
|
|
<link rel="search" type="application/opensearchdescription+xml"
|
|||
|
|
title="Search within Python 3.7.4 documentation"
|
|||
|
|
href="../_static/opensearch.xml"/>
|
|||
|
|
<link rel="author" title="About these documents" href="../about.html" />
|
|||
|
|
<link rel="index" title="Index" href="../genindex.html" />
|
|||
|
|
<link rel="search" title="Search" href="../search.html" />
|
|||
|
|
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
|||
|
|
<link rel="next" title="winsound — Sound-playing interface for Windows" href="winsound.html" />
|
|||
|
|
<link rel="prev" title="msvcrt — Useful routines from the MS VC++ runtime" href="msvcrt.html" />
|
|||
|
|
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
|||
|
|
<link rel="canonical" href="https://docs.python.org/3/library/winreg.html" />
|
|||
|
|
|
|||
|
|
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
|||
|
|
<script type="text/javascript" src="../_static/switchers.js"></script>
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
<style>
|
|||
|
|
@media only screen {
|
|||
|
|
table.full-width-table {
|
|||
|
|
width: 100%;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</head><body>
|
|||
|
|
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
accesskey="I">index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="winsound.html" title="winsound — Sound-playing interface for Windows"
|
|||
|
|
accesskey="N">next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="msvcrt.html" title="msvcrt — Useful routines from the MS VC++ runtime"
|
|||
|
|
accesskey="P">previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="windows.html" accesskey="U">MS Windows Specific Services</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
<div class="document">
|
|||
|
|
<div class="documentwrapper">
|
|||
|
|
<div class="bodywrapper">
|
|||
|
|
<div class="body" role="main">
|
|||
|
|
|
|||
|
|
<div class="section" id="module-winreg">
|
|||
|
|
<span id="winreg-windows-registry-access"></span><h1><a class="reference internal" href="#module-winreg" title="winreg: Routines and objects for manipulating the Windows registry. (Windows)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">winreg</span></code></a> — Windows registry access<a class="headerlink" href="#module-winreg" title="Permalink to this headline">¶</a></h1>
|
|||
|
|
<hr class="docutils" />
|
|||
|
|
<p>These functions expose the Windows registry API to Python. Instead of using an
|
|||
|
|
integer as the registry handle, a <a class="reference internal" href="#handle-object"><span class="std std-ref">handle object</span></a> is used
|
|||
|
|
to ensure that the handles are closed correctly, even if the programmer neglects
|
|||
|
|
to explicitly close them.</p>
|
|||
|
|
<div class="versionchanged" id="exception-changed">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>Several functions in this module used to raise a
|
|||
|
|
<a class="reference internal" href="exceptions.html#WindowsError" title="WindowsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">WindowsError</span></code></a>, which is now an alias of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="functions">
|
|||
|
|
<span id="id1"></span><h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>This module offers the following functions:</p>
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.CloseKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">CloseKey</code><span class="sig-paren">(</span><em>hkey</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.CloseKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Closes a previously opened registry key. The <em>hkey</em> argument specifies a
|
|||
|
|
previously opened key.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>If <em>hkey</em> is not closed using this method (or via <a class="reference internal" href="#winreg.PyHKEY.Close" title="winreg.PyHKEY.Close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">hkey.Close()</span></code></a>), it is closed when the <em>hkey</em> object is destroyed by
|
|||
|
|
Python.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.ConnectRegistry">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">ConnectRegistry</code><span class="sig-paren">(</span><em>computer_name</em>, <em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.ConnectRegistry" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Establishes a connection to a predefined registry handle on another computer,
|
|||
|
|
and returns a <a class="reference internal" href="#handle-object"><span class="std std-ref">handle object</span></a>.</p>
|
|||
|
|
<p><em>computer_name</em> is the name of the remote computer, of the form
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">r"\\computername"</span></code>. If <code class="docutils literal notranslate"><span class="pre">None</span></code>, the local computer is used.</p>
|
|||
|
|
<p><em>key</em> is the predefined handle to connect to.</p>
|
|||
|
|
<p>The return value is the handle of the opened key. If the function fails, an
|
|||
|
|
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is raised.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.CreateKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">CreateKey</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.CreateKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Creates or opens the specified key, returning a
|
|||
|
|
<a class="reference internal" href="#handle-object"><span class="std std-ref">handle object</span></a>.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that names the key this method opens or creates.</p>
|
|||
|
|
<p>If <em>key</em> is one of the predefined keys, <em>sub_key</em> may be <code class="docutils literal notranslate"><span class="pre">None</span></code>. In that
|
|||
|
|
case, the handle returned is the same key handle passed in to the function.</p>
|
|||
|
|
<p>If the key already exists, this function opens the existing key.</p>
|
|||
|
|
<p>The return value is the handle of the opened key. If the function fails, an
|
|||
|
|
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is raised.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.CreateKeyEx">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">CreateKeyEx</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em>, <em>reserved=0</em>, <em>access=KEY_WRITE</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.CreateKeyEx" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Creates or opens the specified key, returning a
|
|||
|
|
<a class="reference internal" href="#handle-object"><span class="std std-ref">handle object</span></a>.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that names the key this method opens or creates.</p>
|
|||
|
|
<p><em>reserved</em> is a reserved integer, and must be zero. The default is zero.</p>
|
|||
|
|
<p><em>access</em> is an integer that specifies an access mask that describes the desired
|
|||
|
|
security access for the key. Default is <a class="reference internal" href="#winreg.KEY_WRITE" title="winreg.KEY_WRITE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_WRITE</span></code></a>. See
|
|||
|
|
<a class="reference internal" href="#access-rights"><span class="std std-ref">Access Rights</span></a> for other allowed values.</p>
|
|||
|
|
<p>If <em>key</em> is one of the predefined keys, <em>sub_key</em> may be <code class="docutils literal notranslate"><span class="pre">None</span></code>. In that
|
|||
|
|
case, the handle returned is the same key handle passed in to the function.</p>
|
|||
|
|
<p>If the key already exists, this function opens the existing key.</p>
|
|||
|
|
<p>The return value is the handle of the opened key. If the function fails, an
|
|||
|
|
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is raised.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.DeleteKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">DeleteKey</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.DeleteKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Deletes the specified key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that must be a subkey of the key identified by the <em>key</em>
|
|||
|
|
parameter. This value must not be <code class="docutils literal notranslate"><span class="pre">None</span></code>, and the key may not have subkeys.</p>
|
|||
|
|
<p><em>This method can not delete keys with subkeys.</em></p>
|
|||
|
|
<p>If the method succeeds, the entire key, including all of its values, is removed.
|
|||
|
|
If the method fails, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is raised.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.DeleteKeyEx">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">DeleteKeyEx</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em>, <em>access=KEY_WOW64_64KEY</em>, <em>reserved=0</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.DeleteKeyEx" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Deletes the specified key.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>The <a class="reference internal" href="#winreg.DeleteKeyEx" title="winreg.DeleteKeyEx"><code class="xref py py-func docutils literal notranslate"><span class="pre">DeleteKeyEx()</span></code></a> function is implemented with the RegDeleteKeyEx
|
|||
|
|
Windows API function, which is specific to 64-bit versions of Windows.
|
|||
|
|
See the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx">RegDeleteKeyEx documentation</a>.</p>
|
|||
|
|
</div>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that must be a subkey of the key identified by the
|
|||
|
|
<em>key</em> parameter. This value must not be <code class="docutils literal notranslate"><span class="pre">None</span></code>, and the key may not have
|
|||
|
|
subkeys.</p>
|
|||
|
|
<p><em>reserved</em> is a reserved integer, and must be zero. The default is zero.</p>
|
|||
|
|
<p><em>access</em> is an integer that specifies an access mask that describes the desired
|
|||
|
|
security access for the key. Default is <a class="reference internal" href="#winreg.KEY_WOW64_64KEY" title="winreg.KEY_WOW64_64KEY"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_WOW64_64KEY</span></code></a>. See
|
|||
|
|
<a class="reference internal" href="#access-rights"><span class="std std-ref">Access Rights</span></a> for other allowed values.</p>
|
|||
|
|
<p><em>This method can not delete keys with subkeys.</em></p>
|
|||
|
|
<p>If the method succeeds, the entire key, including all of its values, is
|
|||
|
|
removed. If the method fails, an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is raised.</p>
|
|||
|
|
<p>On unsupported Windows versions, <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplementedError</span></code></a> is raised.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.DeleteValue">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">DeleteValue</code><span class="sig-paren">(</span><em>key</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.DeleteValue" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Removes a named value from a registry key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>value</em> is a string that identifies the value to remove.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.EnumKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">EnumKey</code><span class="sig-paren">(</span><em>key</em>, <em>index</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.EnumKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Enumerates subkeys of an open registry key, returning a string.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>index</em> is an integer that identifies the index of the key to retrieve.</p>
|
|||
|
|
<p>The function retrieves the name of one subkey each time it is called. It is
|
|||
|
|
typically called repeatedly until an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is
|
|||
|
|
raised, indicating, no more values are available.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.EnumValue">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">EnumValue</code><span class="sig-paren">(</span><em>key</em>, <em>index</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.EnumValue" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Enumerates values of an open registry key, returning a tuple.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>index</em> is an integer that identifies the index of the value to retrieve.</p>
|
|||
|
|
<p>The function retrieves the name of one subkey each time it is called. It is
|
|||
|
|
typically called repeatedly, until an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> exception is
|
|||
|
|
raised, indicating no more values.</p>
|
|||
|
|
<p>The result is a tuple of 3 items:</p>
|
|||
|
|
<table class="docutils align-center">
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 14%" />
|
|||
|
|
<col style="width: 86%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="row-odd"><th class="head"><p>Index</p></th>
|
|||
|
|
<th class="head"><p>Meaning</p></th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>
|
|||
|
|
<td><p>A string that identifies the value name</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
|
|||
|
|
<td><p>An object that holds the value data, and
|
|||
|
|
whose type depends on the underlying
|
|||
|
|
registry type</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
|
|||
|
|
<td><p>An integer that identifies the type of the
|
|||
|
|
value data (see table in docs for
|
|||
|
|
<a class="reference internal" href="#winreg.SetValueEx" title="winreg.SetValueEx"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SetValueEx()</span></code></a>)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<span class="target" id="index-0"></span><dl class="function">
|
|||
|
|
<dt id="winreg.ExpandEnvironmentStrings">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">ExpandEnvironmentStrings</code><span class="sig-paren">(</span><em>str</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.ExpandEnvironmentStrings" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Expands environment variable placeholders <code class="docutils literal notranslate"><span class="pre">%NAME%</span></code> in strings like
|
|||
|
|
<a class="reference internal" href="#winreg.REG_EXPAND_SZ" title="winreg.REG_EXPAND_SZ"><code class="xref py py-const docutils literal notranslate"><span class="pre">REG_EXPAND_SZ</span></code></a>:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ExpandEnvironmentStrings</span><span class="p">(</span><span class="s1">'%windir%'</span><span class="p">)</span>
|
|||
|
|
<span class="go">'C:\\Windows'</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.FlushKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">FlushKey</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.FlushKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Writes all the attributes of a key to the registry.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p>It is not necessary to call <a class="reference internal" href="#winreg.FlushKey" title="winreg.FlushKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">FlushKey()</span></code></a> to change a key. Registry changes are
|
|||
|
|
flushed to disk by the registry using its lazy flusher. Registry changes are
|
|||
|
|
also flushed to disk at system shutdown. Unlike <a class="reference internal" href="#winreg.CloseKey" title="winreg.CloseKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">CloseKey()</span></code></a>, the
|
|||
|
|
<a class="reference internal" href="#winreg.FlushKey" title="winreg.FlushKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">FlushKey()</span></code></a> method returns only when all the data has been written to the
|
|||
|
|
registry. An application should only call <a class="reference internal" href="#winreg.FlushKey" title="winreg.FlushKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">FlushKey()</span></code></a> if it requires
|
|||
|
|
absolute certainty that registry changes are on disk.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="admonition-title">Note</p>
|
|||
|
|
<p>If you don’t know whether a <a class="reference internal" href="#winreg.FlushKey" title="winreg.FlushKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">FlushKey()</span></code></a> call is required, it probably
|
|||
|
|
isn’t.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.LoadKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">LoadKey</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em>, <em>file_name</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.LoadKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Creates a subkey under the specified key and stores registration information
|
|||
|
|
from a specified file into that subkey.</p>
|
|||
|
|
<p><em>key</em> is a handle returned by <a class="reference internal" href="#winreg.ConnectRegistry" title="winreg.ConnectRegistry"><code class="xref py py-func docutils literal notranslate"><span class="pre">ConnectRegistry()</span></code></a> or one of the constants
|
|||
|
|
<a class="reference internal" href="#winreg.HKEY_USERS" title="winreg.HKEY_USERS"><code class="xref py py-const docutils literal notranslate"><span class="pre">HKEY_USERS</span></code></a> or <a class="reference internal" href="#winreg.HKEY_LOCAL_MACHINE" title="winreg.HKEY_LOCAL_MACHINE"><code class="xref py py-const docutils literal notranslate"><span class="pre">HKEY_LOCAL_MACHINE</span></code></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that identifies the subkey to load.</p>
|
|||
|
|
<p><em>file_name</em> is the name of the file to load registry data from. This file must
|
|||
|
|
have been created with the <a class="reference internal" href="#winreg.SaveKey" title="winreg.SaveKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">SaveKey()</span></code></a> function. Under the file allocation
|
|||
|
|
table (FAT) file system, the filename may not have an extension.</p>
|
|||
|
|
<p>A call to <a class="reference internal" href="#winreg.LoadKey" title="winreg.LoadKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">LoadKey()</span></code></a> fails if the calling process does not have the
|
|||
|
|
<code class="xref py py-const docutils literal notranslate"><span class="pre">SE_RESTORE_PRIVILEGE</span></code> privilege. Note that privileges are different
|
|||
|
|
from permissions – see the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx">RegLoadKey documentation</a> for
|
|||
|
|
more details.</p>
|
|||
|
|
<p>If <em>key</em> is a handle returned by <a class="reference internal" href="#winreg.ConnectRegistry" title="winreg.ConnectRegistry"><code class="xref py py-func docutils literal notranslate"><span class="pre">ConnectRegistry()</span></code></a>, then the path
|
|||
|
|
specified in <em>file_name</em> is relative to the remote computer.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.OpenKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">OpenKey</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em>, <em>reserved=0</em>, <em>access=KEY_READ</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.OpenKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dt id="winreg.OpenKeyEx">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">OpenKeyEx</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em>, <em>reserved=0</em>, <em>access=KEY_READ</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.OpenKeyEx" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Opens the specified key, returning a <a class="reference internal" href="#handle-object"><span class="std std-ref">handle object</span></a>.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that identifies the sub_key to open.</p>
|
|||
|
|
<p><em>reserved</em> is a reserved integer, and must be zero. The default is zero.</p>
|
|||
|
|
<p><em>access</em> is an integer that specifies an access mask that describes the desired
|
|||
|
|
security access for the key. Default is <a class="reference internal" href="#winreg.KEY_READ" title="winreg.KEY_READ"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_READ</span></code></a>. See <a class="reference internal" href="#access-rights"><span class="std std-ref">Access
|
|||
|
|
Rights</span></a> for other allowed values.</p>
|
|||
|
|
<p>The result is a new handle to the specified key.</p>
|
|||
|
|
<p>If the function fails, <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised.</p>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.2: </span>Allow the use of named arguments.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="versionchanged">
|
|||
|
|
<p><span class="versionmodified changed">Changed in version 3.3: </span>See <a class="reference internal" href="#exception-changed"><span class="std std-ref">above</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.QueryInfoKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">QueryInfoKey</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.QueryInfoKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Returns information about a key, as a tuple.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p>The result is a tuple of 3 items:</p>
|
|||
|
|
<table class="docutils align-center">
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 13%" />
|
|||
|
|
<col style="width: 87%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="row-odd"><th class="head"><p>Index</p></th>
|
|||
|
|
<th class="head"><p>Meaning</p></th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>
|
|||
|
|
<td><p>An integer giving the number of sub keys
|
|||
|
|
this key has.</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
|
|||
|
|
<td><p>An integer giving the number of values this
|
|||
|
|
key has.</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">2</span></code></p></td>
|
|||
|
|
<td><p>An integer giving when the key was last
|
|||
|
|
modified (if available) as 100’s of
|
|||
|
|
nanoseconds since Jan 1, 1601.</p></td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.QueryValue">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">QueryValue</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.QueryValue" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Retrieves the unnamed value for a key, as a string.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that holds the name of the subkey with which the value is
|
|||
|
|
associated. If this parameter is <code class="docutils literal notranslate"><span class="pre">None</span></code> or empty, the function retrieves the
|
|||
|
|
value set by the <a class="reference internal" href="#winreg.SetValue" title="winreg.SetValue"><code class="xref py py-func docutils literal notranslate"><span class="pre">SetValue()</span></code></a> method for the key identified by <em>key</em>.</p>
|
|||
|
|
<p>Values in the registry have name, type, and data components. This method
|
|||
|
|
retrieves the data for a key’s first value that has a NULL name. But the
|
|||
|
|
underlying API call doesn’t return the type, so always use
|
|||
|
|
<a class="reference internal" href="#winreg.QueryValueEx" title="winreg.QueryValueEx"><code class="xref py py-func docutils literal notranslate"><span class="pre">QueryValueEx()</span></code></a> if possible.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.QueryValueEx">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">QueryValueEx</code><span class="sig-paren">(</span><em>key</em>, <em>value_name</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.QueryValueEx" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Retrieves the type and data for a specified value name associated with
|
|||
|
|
an open registry key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>value_name</em> is a string indicating the value to query.</p>
|
|||
|
|
<p>The result is a tuple of 2 items:</p>
|
|||
|
|
<table class="docutils align-center">
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 15%" />
|
|||
|
|
<col style="width: 85%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="row-odd"><th class="head"><p>Index</p></th>
|
|||
|
|
<th class="head"><p>Meaning</p></th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>
|
|||
|
|
<td><p>The value of the registry item.</p></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
|
|||
|
|
<td><p>An integer giving the registry type for
|
|||
|
|
this value (see table in docs for
|
|||
|
|
<a class="reference internal" href="#winreg.SetValueEx" title="winreg.SetValueEx"><code class="xref py py-meth docutils literal notranslate"><span class="pre">SetValueEx()</span></code></a>)</p></td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.SaveKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">SaveKey</code><span class="sig-paren">(</span><em>key</em>, <em>file_name</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.SaveKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Saves the specified key, and all its subkeys to the specified file.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>file_name</em> is the name of the file to save registry data to. This file
|
|||
|
|
cannot already exist. If this filename includes an extension, it cannot be
|
|||
|
|
used on file allocation table (FAT) file systems by the <a class="reference internal" href="#winreg.LoadKey" title="winreg.LoadKey"><code class="xref py py-meth docutils literal notranslate"><span class="pre">LoadKey()</span></code></a>
|
|||
|
|
method.</p>
|
|||
|
|
<p>If <em>key</em> represents a key on a remote computer, the path described by
|
|||
|
|
<em>file_name</em> is relative to the remote computer. The caller of this method must
|
|||
|
|
possess the <code class="xref py py-const docutils literal notranslate"><span class="pre">SeBackupPrivilege</span></code> security privilege. Note that
|
|||
|
|
privileges are different than permissions – see the
|
|||
|
|
<a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx">Conflicts Between User Rights and Permissions documentation</a>
|
|||
|
|
for more details.</p>
|
|||
|
|
<p>This function passes NULL for <em>security_attributes</em> to the API.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.SetValue">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">SetValue</code><span class="sig-paren">(</span><em>key</em>, <em>sub_key</em>, <em>type</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.SetValue" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Associates a value with a specified key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>sub_key</em> is a string that names the subkey with which the value is associated.</p>
|
|||
|
|
<p><em>type</em> is an integer that specifies the type of the data. Currently this must be
|
|||
|
|
<a class="reference internal" href="#winreg.REG_SZ" title="winreg.REG_SZ"><code class="xref py py-const docutils literal notranslate"><span class="pre">REG_SZ</span></code></a>, meaning only strings are supported. Use the <a class="reference internal" href="#winreg.SetValueEx" title="winreg.SetValueEx"><code class="xref py py-func docutils literal notranslate"><span class="pre">SetValueEx()</span></code></a>
|
|||
|
|
function for support for other data types.</p>
|
|||
|
|
<p><em>value</em> is a string that specifies the new value.</p>
|
|||
|
|
<p>If the key specified by the <em>sub_key</em> parameter does not exist, the SetValue
|
|||
|
|
function creates it.</p>
|
|||
|
|
<p>Value lengths are limited by available memory. Long values (more than 2048
|
|||
|
|
bytes) should be stored as files with the filenames stored in the configuration
|
|||
|
|
registry. This helps the registry perform efficiently.</p>
|
|||
|
|
<p>The key identified by the <em>key</em> parameter must have been opened with
|
|||
|
|
<a class="reference internal" href="#winreg.KEY_SET_VALUE" title="winreg.KEY_SET_VALUE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_SET_VALUE</span></code></a> access.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.SetValueEx">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">SetValueEx</code><span class="sig-paren">(</span><em>key</em>, <em>value_name</em>, <em>reserved</em>, <em>type</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.SetValueEx" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Stores data in the value field of an open registry key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p><em>value_name</em> is a string that names the subkey with which the value is
|
|||
|
|
associated.</p>
|
|||
|
|
<p><em>reserved</em> can be anything – zero is always passed to the API.</p>
|
|||
|
|
<p><em>type</em> is an integer that specifies the type of the data. See
|
|||
|
|
<a class="reference internal" href="#value-types"><span class="std std-ref">Value Types</span></a> for the available types.</p>
|
|||
|
|
<p><em>value</em> is a string that specifies the new value.</p>
|
|||
|
|
<p>This method can also set additional value and type information for the specified
|
|||
|
|
key. The key identified by the key parameter must have been opened with
|
|||
|
|
<a class="reference internal" href="#winreg.KEY_SET_VALUE" title="winreg.KEY_SET_VALUE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_SET_VALUE</span></code></a> access.</p>
|
|||
|
|
<p>To open the key, use the <a class="reference internal" href="#winreg.CreateKey" title="winreg.CreateKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">CreateKey()</span></code></a> or <a class="reference internal" href="#winreg.OpenKey" title="winreg.OpenKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">OpenKey()</span></code></a> methods.</p>
|
|||
|
|
<p>Value lengths are limited by available memory. Long values (more than 2048
|
|||
|
|
bytes) should be stored as files with the filenames stored in the configuration
|
|||
|
|
registry. This helps the registry perform efficiently.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.DisableReflectionKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">DisableReflectionKey</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.DisableReflectionKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Disables registry reflection for 32-bit processes running on a 64-bit
|
|||
|
|
operating system.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined <a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p>Will generally raise <a class="reference internal" href="constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> if executed on a 32-bit operating
|
|||
|
|
system.</p>
|
|||
|
|
<p>If the key is not on the reflection list, the function succeeds but has no
|
|||
|
|
effect. Disabling reflection for a key does not affect reflection of any
|
|||
|
|
subkeys.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.EnableReflectionKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">EnableReflectionKey</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.EnableReflectionKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Restores registry reflection for the specified disabled key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined <a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p>Will generally raise <a class="reference internal" href="constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> if executed on a 32-bit operating
|
|||
|
|
system.</p>
|
|||
|
|
<p>Restoring reflection for a key does not affect reflection of any subkeys.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="function">
|
|||
|
|
<dt id="winreg.QueryReflectionKey">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">QueryReflectionKey</code><span class="sig-paren">(</span><em>key</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.QueryReflectionKey" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Determines the reflection state for the specified key.</p>
|
|||
|
|
<p><em>key</em> is an already open key, or one of the predefined
|
|||
|
|
<a class="reference internal" href="#hkey-constants"><span class="std std-ref">HKEY_* constants</span></a>.</p>
|
|||
|
|
<p>Returns <code class="docutils literal notranslate"><span class="pre">True</span></code> if reflection is disabled.</p>
|
|||
|
|
<p>Will generally raise <a class="reference internal" href="constants.html#NotImplemented" title="NotImplemented"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NotImplemented</span></code></a> if executed on a 32-bit
|
|||
|
|
operating system.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="constants">
|
|||
|
|
<span id="id2"></span><h2>Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>The following constants are defined for use in many <code class="xref py py-mod docutils literal notranslate"><span class="pre">_winreg</span></code> functions.</p>
|
|||
|
|
<div class="section" id="hkey-constants">
|
|||
|
|
<span id="id3"></span><h3>HKEY_* Constants<a class="headerlink" href="#hkey-constants" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_CLASSES_ROOT">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_CLASSES_ROOT</code><a class="headerlink" href="#winreg.HKEY_CLASSES_ROOT" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Registry entries subordinate to this key define types (or classes) of
|
|||
|
|
documents and the properties associated with those types. Shell and
|
|||
|
|
COM applications use the information stored under this key.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_CURRENT_USER">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_CURRENT_USER</code><a class="headerlink" href="#winreg.HKEY_CURRENT_USER" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Registry entries subordinate to this key define the preferences of
|
|||
|
|
the current user. These preferences include the settings of
|
|||
|
|
environment variables, data about program groups, colors, printers,
|
|||
|
|
network connections, and application preferences.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_LOCAL_MACHINE">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_LOCAL_MACHINE</code><a class="headerlink" href="#winreg.HKEY_LOCAL_MACHINE" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Registry entries subordinate to this key define the physical state
|
|||
|
|
of the computer, including data about the bus type, system memory,
|
|||
|
|
and installed hardware and software.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_USERS">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_USERS</code><a class="headerlink" href="#winreg.HKEY_USERS" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Registry entries subordinate to this key define the default user
|
|||
|
|
configuration for new users on the local computer and the user
|
|||
|
|
configuration for the current user.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_PERFORMANCE_DATA">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_PERFORMANCE_DATA</code><a class="headerlink" href="#winreg.HKEY_PERFORMANCE_DATA" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Registry entries subordinate to this key allow you to access
|
|||
|
|
performance data. The data is not actually stored in the registry;
|
|||
|
|
the registry functions cause the system to collect the data from
|
|||
|
|
its source.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_CURRENT_CONFIG">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_CURRENT_CONFIG</code><a class="headerlink" href="#winreg.HKEY_CURRENT_CONFIG" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Contains information about the current hardware profile of the
|
|||
|
|
local computer system.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.HKEY_DYN_DATA">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">HKEY_DYN_DATA</code><a class="headerlink" href="#winreg.HKEY_DYN_DATA" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>This key is not used in versions of Windows after 98.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="access-rights">
|
|||
|
|
<span id="id4"></span><h3>Access Rights<a class="headerlink" href="#access-rights" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>For more information, see <a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx">Registry Key Security and Access</a>.</p>
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_ALL_ACCESS">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_ALL_ACCESS</code><a class="headerlink" href="#winreg.KEY_ALL_ACCESS" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Combines the STANDARD_RIGHTS_REQUIRED, <a class="reference internal" href="#winreg.KEY_QUERY_VALUE" title="winreg.KEY_QUERY_VALUE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_QUERY_VALUE</span></code></a>,
|
|||
|
|
<a class="reference internal" href="#winreg.KEY_SET_VALUE" title="winreg.KEY_SET_VALUE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_SET_VALUE</span></code></a>, <a class="reference internal" href="#winreg.KEY_CREATE_SUB_KEY" title="winreg.KEY_CREATE_SUB_KEY"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_CREATE_SUB_KEY</span></code></a>,
|
|||
|
|
<a class="reference internal" href="#winreg.KEY_ENUMERATE_SUB_KEYS" title="winreg.KEY_ENUMERATE_SUB_KEYS"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_ENUMERATE_SUB_KEYS</span></code></a>, <a class="reference internal" href="#winreg.KEY_NOTIFY" title="winreg.KEY_NOTIFY"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_NOTIFY</span></code></a>,
|
|||
|
|
and <a class="reference internal" href="#winreg.KEY_CREATE_LINK" title="winreg.KEY_CREATE_LINK"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_CREATE_LINK</span></code></a> access rights.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_WRITE">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_WRITE</code><a class="headerlink" href="#winreg.KEY_WRITE" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Combines the STANDARD_RIGHTS_WRITE, <a class="reference internal" href="#winreg.KEY_SET_VALUE" title="winreg.KEY_SET_VALUE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_SET_VALUE</span></code></a>, and
|
|||
|
|
<a class="reference internal" href="#winreg.KEY_CREATE_SUB_KEY" title="winreg.KEY_CREATE_SUB_KEY"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_CREATE_SUB_KEY</span></code></a> access rights.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_READ">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_READ</code><a class="headerlink" href="#winreg.KEY_READ" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Combines the STANDARD_RIGHTS_READ, <a class="reference internal" href="#winreg.KEY_QUERY_VALUE" title="winreg.KEY_QUERY_VALUE"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_QUERY_VALUE</span></code></a>,
|
|||
|
|
<a class="reference internal" href="#winreg.KEY_ENUMERATE_SUB_KEYS" title="winreg.KEY_ENUMERATE_SUB_KEYS"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_ENUMERATE_SUB_KEYS</span></code></a>, and <a class="reference internal" href="#winreg.KEY_NOTIFY" title="winreg.KEY_NOTIFY"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_NOTIFY</span></code></a> values.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_EXECUTE">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_EXECUTE</code><a class="headerlink" href="#winreg.KEY_EXECUTE" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Equivalent to <a class="reference internal" href="#winreg.KEY_READ" title="winreg.KEY_READ"><code class="xref py py-const docutils literal notranslate"><span class="pre">KEY_READ</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_QUERY_VALUE">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_QUERY_VALUE</code><a class="headerlink" href="#winreg.KEY_QUERY_VALUE" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Required to query the values of a registry key.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_SET_VALUE">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_SET_VALUE</code><a class="headerlink" href="#winreg.KEY_SET_VALUE" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Required to create, delete, or set a registry value.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_CREATE_SUB_KEY">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_CREATE_SUB_KEY</code><a class="headerlink" href="#winreg.KEY_CREATE_SUB_KEY" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Required to create a subkey of a registry key.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_ENUMERATE_SUB_KEYS">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_ENUMERATE_SUB_KEYS</code><a class="headerlink" href="#winreg.KEY_ENUMERATE_SUB_KEYS" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Required to enumerate the subkeys of a registry key.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_NOTIFY">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_NOTIFY</code><a class="headerlink" href="#winreg.KEY_NOTIFY" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Required to request change notifications for a registry key or for
|
|||
|
|
subkeys of a registry key.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_CREATE_LINK">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_CREATE_LINK</code><a class="headerlink" href="#winreg.KEY_CREATE_LINK" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Reserved for system use.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<div class="section" id="bit-specific">
|
|||
|
|
<span id="bit-access-rights"></span><h4>64-bit Specific<a class="headerlink" href="#bit-specific" title="Permalink to this headline">¶</a></h4>
|
|||
|
|
<p>For more information, see <a class="reference external" href="https://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx">Accessing an Alternate Registry View</a>.</p>
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_WOW64_64KEY">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_WOW64_64KEY</code><a class="headerlink" href="#winreg.KEY_WOW64_64KEY" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Indicates that an application on 64-bit Windows should operate on
|
|||
|
|
the 64-bit registry view.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.KEY_WOW64_32KEY">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">KEY_WOW64_32KEY</code><a class="headerlink" href="#winreg.KEY_WOW64_32KEY" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Indicates that an application on 64-bit Windows should operate on
|
|||
|
|
the 32-bit registry view.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="value-types">
|
|||
|
|
<span id="id5"></span><h3>Value Types<a class="headerlink" href="#value-types" title="Permalink to this headline">¶</a></h3>
|
|||
|
|
<p>For more information, see <a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx">Registry Value Types</a>.</p>
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_BINARY">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_BINARY</code><a class="headerlink" href="#winreg.REG_BINARY" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Binary data in any form.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_DWORD">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_DWORD</code><a class="headerlink" href="#winreg.REG_DWORD" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>32-bit number.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_DWORD_LITTLE_ENDIAN">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_DWORD_LITTLE_ENDIAN</code><a class="headerlink" href="#winreg.REG_DWORD_LITTLE_ENDIAN" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A 32-bit number in little-endian format. Equivalent to <a class="reference internal" href="#winreg.REG_DWORD" title="winreg.REG_DWORD"><code class="xref py py-const docutils literal notranslate"><span class="pre">REG_DWORD</span></code></a>.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_DWORD_BIG_ENDIAN">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_DWORD_BIG_ENDIAN</code><a class="headerlink" href="#winreg.REG_DWORD_BIG_ENDIAN" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A 32-bit number in big-endian format.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_EXPAND_SZ">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_EXPAND_SZ</code><a class="headerlink" href="#winreg.REG_EXPAND_SZ" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Null-terminated string containing references to environment
|
|||
|
|
variables (<code class="docutils literal notranslate"><span class="pre">%PATH%</span></code>).</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_LINK">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_LINK</code><a class="headerlink" href="#winreg.REG_LINK" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A Unicode symbolic link.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_MULTI_SZ">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_MULTI_SZ</code><a class="headerlink" href="#winreg.REG_MULTI_SZ" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A sequence of null-terminated strings, terminated by two null characters.
|
|||
|
|
(Python handles this termination automatically.)</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_NONE">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_NONE</code><a class="headerlink" href="#winreg.REG_NONE" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>No defined value type.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_QWORD">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_QWORD</code><a class="headerlink" href="#winreg.REG_QWORD" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A 64-bit number.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_QWORD_LITTLE_ENDIAN">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_QWORD_LITTLE_ENDIAN</code><a class="headerlink" href="#winreg.REG_QWORD_LITTLE_ENDIAN" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A 64-bit number in little-endian format. Equivalent to <a class="reference internal" href="#winreg.REG_QWORD" title="winreg.REG_QWORD"><code class="xref py py-const docutils literal notranslate"><span class="pre">REG_QWORD</span></code></a>.</p>
|
|||
|
|
<div class="versionadded">
|
|||
|
|
<p><span class="versionmodified added">New in version 3.6.</span></p>
|
|||
|
|
</div>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_RESOURCE_LIST">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_RESOURCE_LIST</code><a class="headerlink" href="#winreg.REG_RESOURCE_LIST" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A device-driver resource list.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_FULL_RESOURCE_DESCRIPTOR">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_FULL_RESOURCE_DESCRIPTOR</code><a class="headerlink" href="#winreg.REG_FULL_RESOURCE_DESCRIPTOR" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A hardware setting.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_RESOURCE_REQUIREMENTS_LIST">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_RESOURCE_REQUIREMENTS_LIST</code><a class="headerlink" href="#winreg.REG_RESOURCE_REQUIREMENTS_LIST" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A hardware resource list.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="data">
|
|||
|
|
<dt id="winreg.REG_SZ">
|
|||
|
|
<code class="descclassname">winreg.</code><code class="descname">REG_SZ</code><a class="headerlink" href="#winreg.REG_SZ" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>A null-terminated string.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="registry-handle-objects">
|
|||
|
|
<span id="handle-object"></span><h2>Registry Handle Objects<a class="headerlink" href="#registry-handle-objects" title="Permalink to this headline">¶</a></h2>
|
|||
|
|
<p>This object wraps a Windows HKEY object, automatically closing it when the
|
|||
|
|
object is destroyed. To guarantee cleanup, you can call either the
|
|||
|
|
<a class="reference internal" href="#winreg.PyHKEY.Close" title="winreg.PyHKEY.Close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Close()</span></code></a> method on the object, or the <a class="reference internal" href="#winreg.CloseKey" title="winreg.CloseKey"><code class="xref py py-func docutils literal notranslate"><span class="pre">CloseKey()</span></code></a> function.</p>
|
|||
|
|
<p>All registry functions in this module return one of these objects.</p>
|
|||
|
|
<p>All registry functions in this module which accept a handle object also accept
|
|||
|
|
an integer, however, use of the handle object is encouraged.</p>
|
|||
|
|
<p>Handle objects provide semantics for <a class="reference internal" href="../reference/datamodel.html#object.__bool__" title="object.__bool__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__bool__()</span></code></a> – thus</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">handle</span><span class="p">:</span>
|
|||
|
|
<span class="nb">print</span><span class="p">(</span><span class="s2">"Yes"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>will print <code class="docutils literal notranslate"><span class="pre">Yes</span></code> if the handle is currently valid (has not been closed or
|
|||
|
|
detached).</p>
|
|||
|
|
<p>The object also support comparison semantics, so handle objects will compare
|
|||
|
|
true if they both reference the same underlying Windows handle value.</p>
|
|||
|
|
<p>Handle objects can be converted to an integer (e.g., using the built-in
|
|||
|
|
<a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-func docutils literal notranslate"><span class="pre">int()</span></code></a> function), in which case the underlying Windows handle value is
|
|||
|
|
returned. You can also use the <a class="reference internal" href="#winreg.PyHKEY.Detach" title="winreg.PyHKEY.Detach"><code class="xref py py-meth docutils literal notranslate"><span class="pre">Detach()</span></code></a> method to return the
|
|||
|
|
integer handle, and also disconnect the Windows handle from the handle object.</p>
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="winreg.PyHKEY.Close">
|
|||
|
|
<code class="descclassname">PyHKEY.</code><code class="descname">Close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#winreg.PyHKEY.Close" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Closes the underlying Windows handle.</p>
|
|||
|
|
<p>If the handle is already closed, no error is raised.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="winreg.PyHKEY.Detach">
|
|||
|
|
<code class="descclassname">PyHKEY.</code><code class="descname">Detach</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#winreg.PyHKEY.Detach" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>Detaches the Windows handle from the handle object.</p>
|
|||
|
|
<p>The result is an integer that holds the value of the handle before it is
|
|||
|
|
detached. If the handle is already detached or closed, this will return
|
|||
|
|
zero.</p>
|
|||
|
|
<p>After calling this function, the handle is effectively invalidated, but the
|
|||
|
|
handle is not closed. You would call this function when you need the
|
|||
|
|
underlying Win32 handle to exist beyond the lifetime of the handle object.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
<dl class="method">
|
|||
|
|
<dt id="winreg.PyHKEY.__enter__">
|
|||
|
|
<code class="descclassname">PyHKEY.</code><code class="descname">__enter__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#winreg.PyHKEY.__enter__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dt id="winreg.PyHKEY.__exit__">
|
|||
|
|
<code class="descclassname">PyHKEY.</code><code class="descname">__exit__</code><span class="sig-paren">(</span><em>*exc_info</em><span class="sig-paren">)</span><a class="headerlink" href="#winreg.PyHKEY.__exit__" title="Permalink to this definition">¶</a></dt>
|
|||
|
|
<dd><p>The HKEY object implements <a class="reference internal" href="../reference/datamodel.html#object.__enter__" title="object.__enter__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__enter__()</span></code></a> and
|
|||
|
|
<a class="reference internal" href="../reference/datamodel.html#object.__exit__" title="object.__exit__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__exit__()</span></code></a> and thus supports the context protocol for 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> statement:</p>
|
|||
|
|
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">OpenKey</span><span class="p">(</span><span class="n">HKEY_LOCAL_MACHINE</span><span class="p">,</span> <span class="s2">"foo"</span><span class="p">)</span> <span class="k">as</span> <span class="n">key</span><span class="p">:</span>
|
|||
|
|
<span class="o">...</span> <span class="c1"># work with key</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>will automatically close <em>key</em> when control leaves 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> block.</p>
|
|||
|
|
</dd></dl>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
|||
|
|
<div class="sphinxsidebarwrapper">
|
|||
|
|
<h3><a href="../contents.html">Table of Contents</a></h3>
|
|||
|
|
<ul>
|
|||
|
|
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">winreg</span></code> — Windows registry access</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#functions">Functions</a></li>
|
|||
|
|
<li><a class="reference internal" href="#constants">Constants</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#hkey-constants">HKEY_* Constants</a></li>
|
|||
|
|
<li><a class="reference internal" href="#access-rights">Access Rights</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#bit-specific">64-bit Specific</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#value-types">Value Types</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
<li><a class="reference internal" href="#registry-handle-objects">Registry Handle Objects</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
<h4>Previous topic</h4>
|
|||
|
|
<p class="topless"><a href="msvcrt.html"
|
|||
|
|
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">msvcrt</span></code> — Useful routines from the MS VC++ runtime</a></p>
|
|||
|
|
<h4>Next topic</h4>
|
|||
|
|
<p class="topless"><a href="winsound.html"
|
|||
|
|
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">winsound</span></code> — Sound-playing interface for Windows</a></p>
|
|||
|
|
<div role="note" aria-label="source link">
|
|||
|
|
<h3>This Page</h3>
|
|||
|
|
<ul class="this-page-menu">
|
|||
|
|
<li><a href="../bugs.html">Report a Bug</a></li>
|
|||
|
|
<li>
|
|||
|
|
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/winreg.rst"
|
|||
|
|
rel="nofollow">Show Source
|
|||
|
|
</a>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="clearer"></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="related" role="navigation" aria-label="related navigation">
|
|||
|
|
<h3>Navigation</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li class="right" style="margin-right: 10px">
|
|||
|
|
<a href="../genindex.html" title="General Index"
|
|||
|
|
>index</a></li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="../py-modindex.html" title="Python Module Index"
|
|||
|
|
>modules</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="winsound.html" title="winsound — Sound-playing interface for Windows"
|
|||
|
|
>next</a> |</li>
|
|||
|
|
<li class="right" >
|
|||
|
|
<a href="msvcrt.html" title="msvcrt — Useful routines from the MS VC++ runtime"
|
|||
|
|
>previous</a> |</li>
|
|||
|
|
<li><img src="../_static/py.png" alt=""
|
|||
|
|
style="vertical-align: middle; margin-top: -1px"/></li>
|
|||
|
|
<li><a href="https://www.python.org/">Python</a> »</li>
|
|||
|
|
<li>
|
|||
|
|
<span class="language_switcher_placeholder">en</span>
|
|||
|
|
<span class="version_switcher_placeholder">3.7.4</span>
|
|||
|
|
<a href="../index.html">Documentation </a> »
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
|||
|
|
<li class="nav-item nav-item-2"><a href="windows.html" >MS Windows Specific Services</a> »</li>
|
|||
|
|
<li class="right">
|
|||
|
|
|
|||
|
|
|
|||
|
|
<div class="inline-search" style="display: none" role="search">
|
|||
|
|
<form class="inline-search" action="../search.html" method="get">
|
|||
|
|
<input placeholder="Quick search" type="text" name="q" />
|
|||
|
|
<input type="submit" value="Go" />
|
|||
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|||
|
|
<input type="hidden" name="area" value="default" />
|
|||
|
|
</form>
|
|||
|
|
</div>
|
|||
|
|
<script type="text/javascript">$('.inline-search').show(0);</script>
|
|||
|
|
|
|
|||
|
|
</li>
|
|||
|
|
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
<div class="footer">
|
|||
|
|
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
|||
|
|
<br />
|
|||
|
|
The Python Software Foundation is a non-profit corporation.
|
|||
|
|
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
|||
|
|
<br />
|
|||
|
|
Last updated on Jul 13, 2019.
|
|||
|
|
<a href="../bugs.html">Found a bug</a>?
|
|||
|
|
<br />
|
|||
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
|||
|
|
</div>
|
|||
|
|
|
|||
|
|
</body>
|
|||
|
|
</html>
|