1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/python/mock-1.0.0/html/patch.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,648 @@
1.4 +
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +
1.8 +
1.9 +<html xmlns="http://www.w3.org/1999/xhtml">
1.10 + <head>
1.11 + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1.12 +
1.13 + <title>Patch Decorators — Mock 1.0.0 documentation</title>
1.14 +
1.15 + <link rel="stylesheet" href="_static/nature.css" type="text/css" />
1.16 + <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
1.17 +
1.18 + <script type="text/javascript">
1.19 + var DOCUMENTATION_OPTIONS = {
1.20 + URL_ROOT: '',
1.21 + VERSION: '1.0.0',
1.22 + COLLAPSE_INDEX: false,
1.23 + FILE_SUFFIX: '.html',
1.24 + HAS_SOURCE: true
1.25 + };
1.26 + </script>
1.27 + <script type="text/javascript" src="_static/jquery.js"></script>
1.28 + <script type="text/javascript" src="_static/underscore.js"></script>
1.29 + <script type="text/javascript" src="_static/doctools.js"></script>
1.30 + <link rel="top" title="Mock 1.0.0 documentation" href="index.html" />
1.31 + <link rel="next" title="Helpers" href="helpers.html" />
1.32 + <link rel="prev" title="The Mock Class" href="mock.html" />
1.33 + </head>
1.34 + <body>
1.35 + <div class="related">
1.36 + <h3>Navigation</h3>
1.37 + <ul>
1.38 + <li class="right" style="margin-right: 10px">
1.39 + <a href="genindex.html" title="General Index"
1.40 + accesskey="I">index</a></li>
1.41 + <li class="right" >
1.42 + <a href="helpers.html" title="Helpers"
1.43 + accesskey="N">next</a> |</li>
1.44 + <li class="right" >
1.45 + <a href="mock.html" title="The Mock Class"
1.46 + accesskey="P">previous</a> |</li>
1.47 + <li><a href="index.html">Mock 1.0.0 documentation</a> »</li>
1.48 + </ul>
1.49 + </div>
1.50 +
1.51 + <div class="document">
1.52 + <div class="documentwrapper">
1.53 + <div class="bodywrapper">
1.54 + <div class="body">
1.55 +
1.56 + <div class="section" id="patch-decorators">
1.57 +<h1>Patch Decorators<a class="headerlink" href="#patch-decorators" title="Permalink to this headline">¶</a></h1>
1.58 +<p>The patch decorators are used for patching objects only within the scope of
1.59 +the function they decorate. They automatically handle the unpatching for you,
1.60 +even if exceptions are raised. All of these functions can also be used in with
1.61 +statements or as class decorators.</p>
1.62 +<div class="section" id="patch">
1.63 +<h2>patch<a class="headerlink" href="#patch" title="Permalink to this headline">¶</a></h2>
1.64 +<div class="admonition note">
1.65 +<p class="first admonition-title">Note</p>
1.66 +<p class="last"><cite>patch</cite> is straightforward to use. The key is to do the patching in the
1.67 +right namespace. See the section <a class="reference internal" href="#id1">where to patch</a>.</p>
1.68 +</div>
1.69 +<dl class="function">
1.70 +<dt id="mock.patch">
1.71 +<tt class="descname">patch</tt><big>(</big><em>target</em>, <em>new=DEFAULT</em>, <em>spec=None</em>, <em>create=False</em>, <em>spec_set=None</em>, <em>autospec=None</em>, <em>new_callable=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch" title="Permalink to this definition">¶</a></dt>
1.72 +<dd><p><cite>patch</cite> acts as a function decorator, class decorator or a context
1.73 +manager. Inside the body of the function or with statement, the <cite>target</cite>
1.74 +is patched with a <cite>new</cite> object. When the function/with statement exits
1.75 +the patch is undone.</p>
1.76 +<p>If <cite>new</cite> is omitted, then the target is replaced with a
1.77 +<a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a>. If <cite>patch</cite> is used as a decorator and <cite>new</cite> is
1.78 +omitted, the created mock is passed in as an extra argument to the
1.79 +decorated function. If <cite>patch</cite> is used as a context manager the created
1.80 +mock is returned by the context manager.</p>
1.81 +<p><cite>target</cite> should be a string in the form <cite>‘package.module.ClassName’</cite>. The
1.82 +<cite>target</cite> is imported and the specified object replaced with the <cite>new</cite>
1.83 +object, so the <cite>target</cite> must be importable from the environment you are
1.84 +calling <cite>patch</cite> from. The target is imported when the decorated function
1.85 +is executed, not at decoration time.</p>
1.86 +<p>The <cite>spec</cite> and <cite>spec_set</cite> keyword arguments are passed to the <cite>MagicMock</cite>
1.87 +if patch is creating one for you.</p>
1.88 +<p>In addition you can pass <cite>spec=True</cite> or <cite>spec_set=True</cite>, which causes
1.89 +patch to pass in the object being mocked as the spec/spec_set object.</p>
1.90 +<p><cite>new_callable</cite> allows you to specify a different class, or callable object,
1.91 +that will be called to create the <cite>new</cite> object. By default <cite>MagicMock</cite> is
1.92 +used.</p>
1.93 +<p>A more powerful form of <cite>spec</cite> is <cite>autospec</cite>. If you set <cite>autospec=True</cite>
1.94 +then the mock with be created with a spec from the object being replaced.
1.95 +All attributes of the mock will also have the spec of the corresponding
1.96 +attribute of the object being replaced. Methods and functions being mocked
1.97 +will have their arguments checked and will raise a <cite>TypeError</cite> if they are
1.98 +called with the wrong signature. For mocks
1.99 +replacing a class, their return value (the ‘instance’) will have the same
1.100 +spec as the class. See the <a class="reference internal" href="helpers.html#mock.create_autospec" title="mock.create_autospec"><tt class="xref py py-func docutils literal"><span class="pre">create_autospec()</span></tt></a> function and
1.101 +<a class="reference internal" href="helpers.html#auto-speccing"><em>Autospeccing</em></a>.</p>
1.102 +<p>Instead of <cite>autospec=True</cite> you can pass <cite>autospec=some_object</cite> to use an
1.103 +arbitrary object as the spec instead of the one being replaced.</p>
1.104 +<p>By default <cite>patch</cite> will fail to replace attributes that don’t exist. If
1.105 +you pass in <cite>create=True</cite>, and the attribute doesn’t exist, patch will
1.106 +create the attribute for you when the patched function is called, and
1.107 +delete it again afterwards. This is useful for writing tests against
1.108 +attributes that your production code creates at runtime. It is off by by
1.109 +default because it can be dangerous. With it switched on you can write
1.110 +passing tests against APIs that don’t actually exist!</p>
1.111 +<p>Patch can be used as a <cite>TestCase</cite> class decorator. It works by
1.112 +decorating each test method in the class. This reduces the boilerplate
1.113 +code when your test methods share a common patchings set. <cite>patch</cite> finds
1.114 +tests by looking for method names that start with <cite>patch.TEST_PREFIX</cite>.
1.115 +By default this is <cite>test</cite>, which matches the way <cite>unittest</cite> finds tests.
1.116 +You can specify an alternative prefix by setting <cite>patch.TEST_PREFIX</cite>.</p>
1.117 +<p>Patch can be used as a context manager, with the with statement. Here the
1.118 +patching applies to the indented block after the with statement. If you
1.119 +use “as” then the patched object will be bound to the name after the
1.120 +“as”; very useful if <cite>patch</cite> is creating a mock object for you.</p>
1.121 +<p><cite>patch</cite> takes arbitrary keyword arguments. These will be passed to
1.122 +the <cite>Mock</cite> (or <cite>new_callable</cite>) on construction.</p>
1.123 +<p><cite>patch.dict(...)</cite>, <cite>patch.multiple(...)</cite> and <cite>patch.object(...)</cite> are
1.124 +available for alternate use-cases.</p>
1.125 +</dd></dl>
1.126 +
1.127 +<p><cite>patch</cite> as function decorator, creating the mock for you and passing it into
1.128 +the decorated function:</p>
1.129 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'__main__.SomeClass'</span><span class="p">)</span>
1.130 +<span class="gp">... </span><span class="k">def</span> <span class="nf">function</span><span class="p">(</span><span class="n">normal_argument</span><span class="p">,</span> <span class="n">mock_class</span><span class="p">):</span>
1.131 +<span class="gp">... </span> <span class="k">print</span> <span class="n">mock_class</span> <span class="ow">is</span> <span class="n">SomeClass</span>
1.132 +<span class="gp">...</span>
1.133 +<span class="gp">>>> </span><span class="n">function</span><span class="p">(</span><span class="bp">None</span><span class="p">)</span>
1.134 +<span class="go">True</span>
1.135 +</pre></div>
1.136 +</div>
1.137 +<p>Patching a class replaces the class with a <cite>MagicMock</cite> <em>instance</em>. If the
1.138 +class is instantiated in the code under test then it will be the
1.139 +<a class="reference internal" href="mock.html#mock.Mock.return_value" title="mock.Mock.return_value"><tt class="xref py py-attr docutils literal"><span class="pre">return_value</span></tt></a> of the mock that will be used.</p>
1.140 +<p>If the class is instantiated multiple times you could use
1.141 +<a class="reference internal" href="mock.html#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt></a> to return a new mock each time. Alternatively you
1.142 +can set the <cite>return_value</cite> to be anything you want.</p>
1.143 +<p>To configure return values on methods of <em>instances</em> on the patched class
1.144 +you must do this on the <cite>return_value</cite>. For example:</p>
1.145 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Class</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.146 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">method</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.147 +<span class="gp">... </span> <span class="k">pass</span>
1.148 +<span class="gp">...</span>
1.149 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.Class'</span><span class="p">)</span> <span class="k">as</span> <span class="n">MockClass</span><span class="p">:</span>
1.150 +<span class="gp">... </span> <span class="n">instance</span> <span class="o">=</span> <span class="n">MockClass</span><span class="o">.</span><span class="n">return_value</span>
1.151 +<span class="gp">... </span> <span class="n">instance</span><span class="o">.</span><span class="n">method</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">'foo'</span>
1.152 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">Class</span><span class="p">()</span> <span class="ow">is</span> <span class="n">instance</span>
1.153 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">Class</span><span class="p">()</span><span class="o">.</span><span class="n">method</span><span class="p">()</span> <span class="o">==</span> <span class="s">'foo'</span>
1.154 +<span class="gp">...</span>
1.155 +</pre></div>
1.156 +</div>
1.157 +<p>If you use <cite>spec</cite> or <cite>spec_set</cite> and <cite>patch</cite> is replacing a <em>class</em>, then the
1.158 +return value of the created mock will have the same spec.</p>
1.159 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">Original</span> <span class="o">=</span> <span class="n">Class</span>
1.160 +<span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.Class'</span><span class="p">,</span> <span class="n">spec</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
1.161 +<span class="gp">>>> </span><span class="n">MockClass</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.162 +<span class="gp">>>> </span><span class="n">instance</span> <span class="o">=</span> <span class="n">MockClass</span><span class="p">()</span>
1.163 +<span class="gp">>>> </span><span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">instance</span><span class="p">,</span> <span class="n">Original</span><span class="p">)</span>
1.164 +<span class="gp">>>> </span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
1.165 +</pre></div>
1.166 +</div>
1.167 +<p>The <cite>new_callable</cite> argument is useful where you want to use an alternative
1.168 +class to the default <a class="reference internal" href="magicmock.html#mock.MagicMock" title="mock.MagicMock"><tt class="xref py py-class docutils literal"><span class="pre">MagicMock</span></tt></a> for the created mock. For example, if
1.169 +you wanted a <a class="reference internal" href="mock.html#mock.NonCallableMock" title="mock.NonCallableMock"><tt class="xref py py-class docutils literal"><span class="pre">NonCallableMock</span></tt></a> to be used:</p>
1.170 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>
1.171 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing'</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">NonCallableMock</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_thing</span><span class="p">:</span>
1.172 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">thing</span> <span class="ow">is</span> <span class="n">mock_thing</span>
1.173 +<span class="gp">... </span> <span class="n">thing</span><span class="p">()</span>
1.174 +<span class="gp">...</span>
1.175 +<span class="gt">Traceback (most recent call last):</span>
1.176 + <span class="c">...</span>
1.177 +<span class="gr">TypeError</span>: <span class="n">'NonCallableMock' object is not callable</span>
1.178 +</pre></div>
1.179 +</div>
1.180 +<p>Another use case might be to replace an object with a <cite>StringIO</cite> instance:</p>
1.181 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">StringIO</span> <span class="kn">import</span> <span class="n">StringIO</span>
1.182 +<span class="gp">>>> </span><span class="k">def</span> <span class="nf">foo</span><span class="p">():</span>
1.183 +<span class="gp">... </span> <span class="k">print</span> <span class="s">'Something'</span>
1.184 +<span class="gp">...</span>
1.185 +<span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'sys.stdout'</span><span class="p">,</span> <span class="n">new_callable</span><span class="o">=</span><span class="n">StringIO</span><span class="p">)</span>
1.186 +<span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock_stdout</span><span class="p">):</span>
1.187 +<span class="gp">... </span> <span class="n">foo</span><span class="p">()</span>
1.188 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">mock_stdout</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span> <span class="o">==</span> <span class="s">'Something</span><span class="se">\n</span><span class="s">'</span>
1.189 +<span class="gp">...</span>
1.190 +<span class="gp">>>> </span><span class="n">test</span><span class="p">()</span>
1.191 +</pre></div>
1.192 +</div>
1.193 +<p>When <cite>patch</cite> is creating a mock for you, it is common that the first thing
1.194 +you need to do is to configure the mock. Some of that configuration can be done
1.195 +in the call to patch. Any arbitrary keywords you pass into the call will be
1.196 +used to set attributes on the created mock:</p>
1.197 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing'</span><span class="p">,</span> <span class="n">first</span><span class="o">=</span><span class="s">'one'</span><span class="p">,</span> <span class="n">second</span><span class="o">=</span><span class="s">'two'</span><span class="p">)</span>
1.198 +<span class="gp">>>> </span><span class="n">mock_thing</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.199 +<span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">first</span>
1.200 +<span class="go">'one'</span>
1.201 +<span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">second</span>
1.202 +<span class="go">'two'</span>
1.203 +</pre></div>
1.204 +</div>
1.205 +<p>As well as attributes on the created mock attributes, like the
1.206 +<a class="reference internal" href="mock.html#mock.Mock.return_value" title="mock.Mock.return_value"><tt class="xref py py-attr docutils literal"><span class="pre">return_value</span></tt></a> and <a class="reference internal" href="mock.html#mock.Mock.side_effect" title="mock.Mock.side_effect"><tt class="xref py py-attr docutils literal"><span class="pre">side_effect</span></tt></a>, of child mocks can
1.207 +also be configured. These aren’t syntactically valid to pass in directly as
1.208 +keyword arguments, but a dictionary with these as keys can still be expanded
1.209 +into a <cite>patch</cite> call using <cite>**</cite>:</p>
1.210 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="p">{</span><span class="s">'method.return_value'</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="s">'other.side_effect'</span><span class="p">:</span> <span class="ne">KeyError</span><span class="p">}</span>
1.211 +<span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'__main__.thing'</span><span class="p">,</span> <span class="o">**</span><span class="n">config</span><span class="p">)</span>
1.212 +<span class="gp">>>> </span><span class="n">mock_thing</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.213 +<span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">method</span><span class="p">()</span>
1.214 +<span class="go">3</span>
1.215 +<span class="gp">>>> </span><span class="n">mock_thing</span><span class="o">.</span><span class="n">other</span><span class="p">()</span>
1.216 +<span class="gt">Traceback (most recent call last):</span>
1.217 + <span class="c">...</span>
1.218 +<span class="gr">KeyError</span>
1.219 +</pre></div>
1.220 +</div>
1.221 +</div>
1.222 +<div class="section" id="patch-object">
1.223 +<h2>patch.object<a class="headerlink" href="#patch-object" title="Permalink to this headline">¶</a></h2>
1.224 +<dl class="function">
1.225 +<dt id="mock.patch.object">
1.226 +<tt class="descclassname">patch.</tt><tt class="descname">object</tt><big>(</big><em>target</em>, <em>attribute</em>, <em>new=DEFAULT</em>, <em>spec=None</em>, <em>create=False</em>, <em>spec_set=None</em>, <em>autospec=None</em>, <em>new_callable=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch.object" title="Permalink to this definition">¶</a></dt>
1.227 +<dd><p>patch the named member (<cite>attribute</cite>) on an object (<cite>target</cite>) with a mock
1.228 +object.</p>
1.229 +<p><cite>patch.object</cite> can be used as a decorator, class decorator or a context
1.230 +manager. Arguments <cite>new</cite>, <cite>spec</cite>, <cite>create</cite>, <cite>spec_set</cite>, <cite>autospec</cite> and
1.231 +<cite>new_callable</cite> have the same meaning as for <cite>patch</cite>. Like <cite>patch</cite>,
1.232 +<cite>patch.object</cite> takes arbitrary keyword arguments for configuring the mock
1.233 +object it creates.</p>
1.234 +<p>When used as a class decorator <cite>patch.object</cite> honours <cite>patch.TEST_PREFIX</cite>
1.235 +for choosing which methods to wrap.</p>
1.236 +</dd></dl>
1.237 +
1.238 +<p>You can either call <cite>patch.object</cite> with three arguments or two arguments. The
1.239 +three argument form takes the object to be patched, the attribute name and the
1.240 +object to replace the attribute with.</p>
1.241 +<p>When calling with the two argument form you omit the replacement object, and a
1.242 +mock is created for you and passed in as an extra argument to the decorated
1.243 +function:</p>
1.244 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch.object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s">'class_method'</span><span class="p">)</span>
1.245 +<span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock_method</span><span class="p">):</span>
1.246 +<span class="gp">... </span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">class_method</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
1.247 +<span class="gp">... </span> <span class="n">mock_method</span><span class="o">.</span><span class="n">assert_called_with</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
1.248 +<span class="gp">...</span>
1.249 +<span class="gp">>>> </span><span class="n">test</span><span class="p">()</span>
1.250 +</pre></div>
1.251 +</div>
1.252 +<p><cite>spec</cite>, <cite>create</cite> and the other arguments to <cite>patch.object</cite> have the same
1.253 +meaning as they do for <cite>patch</cite>.</p>
1.254 +</div>
1.255 +<div class="section" id="patch-dict">
1.256 +<h2>patch.dict<a class="headerlink" href="#patch-dict" title="Permalink to this headline">¶</a></h2>
1.257 +<dl class="function">
1.258 +<dt id="mock.patch.dict">
1.259 +<tt class="descclassname">patch.</tt><tt class="descname">dict</tt><big>(</big><em>in_dict</em>, <em>values=()</em>, <em>clear=False</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch.dict" title="Permalink to this definition">¶</a></dt>
1.260 +<dd><p>Patch a dictionary, or dictionary like object, and restore the dictionary
1.261 +to its original state after the test.</p>
1.262 +<p><cite>in_dict</cite> can be a dictionary or a mapping like container. If it is a
1.263 +mapping then it must at least support getting, setting and deleting items
1.264 +plus iterating over keys.</p>
1.265 +<p><cite>in_dict</cite> can also be a string specifying the name of the dictionary, which
1.266 +will then be fetched by importing it.</p>
1.267 +<p><cite>values</cite> can be a dictionary of values to set in the dictionary. <cite>values</cite>
1.268 +can also be an iterable of <cite>(key, value)</cite> pairs.</p>
1.269 +<p>If <cite>clear</cite> is True then the dictionary will be cleared before the new
1.270 +values are set.</p>
1.271 +<p><cite>patch.dict</cite> can also be called with arbitrary keyword arguments to set
1.272 +values in the dictionary.</p>
1.273 +<p><cite>patch.dict</cite> can be used as a context manager, decorator or class
1.274 +decorator. When used as a class decorator <cite>patch.dict</cite> honours
1.275 +<cite>patch.TEST_PREFIX</cite> for choosing which methods to wrap.</p>
1.276 +</dd></dl>
1.277 +
1.278 +<p><cite>patch.dict</cite> can be used to add members to a dictionary, or simply let a test
1.279 +change a dictionary, and ensure the dictionary is restored when the test
1.280 +ends.</p>
1.281 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">mock</span> <span class="kn">import</span> <span class="n">patch</span>
1.282 +<span class="gp">>>> </span><span class="n">foo</span> <span class="o">=</span> <span class="p">{}</span>
1.283 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="n">foo</span><span class="p">,</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}):</span>
1.284 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}</span>
1.285 +<span class="gp">...</span>
1.286 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">foo</span> <span class="o">==</span> <span class="p">{}</span>
1.287 +
1.288 +<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">os</span>
1.289 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="s">'os.environ'</span><span class="p">,</span> <span class="p">{</span><span class="s">'newkey'</span><span class="p">:</span> <span class="s">'newvalue'</span><span class="p">}):</span>
1.290 +<span class="gp">... </span> <span class="k">print</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s">'newkey'</span><span class="p">]</span>
1.291 +<span class="gp">...</span>
1.292 +<span class="go">newvalue</span>
1.293 +<span class="gp">>>> </span><span class="k">assert</span> <span class="s">'newkey'</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span>
1.294 +</pre></div>
1.295 +</div>
1.296 +<p>Keywords can be used in the <cite>patch.dict</cite> call to set values in the dictionary:</p>
1.297 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">mymodule</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
1.298 +<span class="gp">>>> </span><span class="n">mymodule</span><span class="o">.</span><span class="n">function</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="s">'fish'</span>
1.299 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="s">'sys.modules'</span><span class="p">,</span> <span class="n">mymodule</span><span class="o">=</span><span class="n">mymodule</span><span class="p">):</span>
1.300 +<span class="gp">... </span> <span class="kn">import</span> <span class="nn">mymodule</span>
1.301 +<span class="gp">... </span> <span class="n">mymodule</span><span class="o">.</span><span class="n">function</span><span class="p">(</span><span class="s">'some'</span><span class="p">,</span> <span class="s">'args'</span><span class="p">)</span>
1.302 +<span class="gp">...</span>
1.303 +<span class="go">'fish'</span>
1.304 +</pre></div>
1.305 +</div>
1.306 +<p><cite>patch.dict</cite> can be used with dictionary like objects that aren’t actually
1.307 +dictionaries. At the very minimum they must support item getting, setting,
1.308 +deleting and either iteration or membership test. This corresponds to the
1.309 +magic methods <cite>__getitem__</cite>, <cite>__setitem__</cite>, <cite>__delitem__</cite> and either
1.310 +<cite>__iter__</cite> or <cite>__contains__</cite>.</p>
1.311 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">Container</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.312 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.313 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span> <span class="o">=</span> <span class="p">{}</span>
1.314 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__getitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
1.315 +<span class="gp">... </span> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
1.316 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__setitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
1.317 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">[</span><span class="n">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
1.318 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__delitem__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">):</span>
1.319 +<span class="gp">... </span> <span class="k">del</span> <span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
1.320 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">__iter__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.321 +<span class="gp">... </span> <span class="k">return</span> <span class="nb">iter</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">values</span><span class="p">)</span>
1.322 +<span class="gp">...</span>
1.323 +<span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="n">Container</span><span class="p">()</span>
1.324 +<span class="gp">>>> </span><span class="n">thing</span><span class="p">[</span><span class="s">'one'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>
1.325 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">dict</span><span class="p">(</span><span class="n">thing</span><span class="p">,</span> <span class="n">one</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">two</span><span class="o">=</span><span class="mi">3</span><span class="p">):</span>
1.326 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s">'one'</span><span class="p">]</span> <span class="o">==</span> <span class="mi">2</span>
1.327 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s">'two'</span><span class="p">]</span> <span class="o">==</span> <span class="mi">3</span>
1.328 +<span class="gp">...</span>
1.329 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">thing</span><span class="p">[</span><span class="s">'one'</span><span class="p">]</span> <span class="o">==</span> <span class="mi">1</span>
1.330 +<span class="gp">>>> </span><span class="k">assert</span> <span class="nb">list</span><span class="p">(</span><span class="n">thing</span><span class="p">)</span> <span class="o">==</span> <span class="p">[</span><span class="s">'one'</span><span class="p">]</span>
1.331 +</pre></div>
1.332 +</div>
1.333 +</div>
1.334 +<div class="section" id="patch-multiple">
1.335 +<h2>patch.multiple<a class="headerlink" href="#patch-multiple" title="Permalink to this headline">¶</a></h2>
1.336 +<dl class="function">
1.337 +<dt id="mock.patch.multiple">
1.338 +<tt class="descclassname">patch.</tt><tt class="descname">multiple</tt><big>(</big><em>target</em>, <em>spec=None</em>, <em>create=False</em>, <em>spec_set=None</em>, <em>autospec=None</em>, <em>new_callable=None</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#mock.patch.multiple" title="Permalink to this definition">¶</a></dt>
1.339 +<dd><p>Perform multiple patches in a single call. It takes the object to be
1.340 +patched (either as an object or a string to fetch the object by importing)
1.341 +and keyword arguments for the patches:</p>
1.342 +<div class="highlight-python"><div class="highlight"><pre><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="n">settings</span><span class="p">,</span> <span class="n">FIRST_PATCH</span><span class="o">=</span><span class="s">'one'</span><span class="p">,</span> <span class="n">SECOND_PATCH</span><span class="o">=</span><span class="s">'two'</span><span class="p">):</span>
1.343 + <span class="o">...</span>
1.344 +</pre></div>
1.345 +</div>
1.346 +<p>Use <a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a> as the value if you want <cite>patch.multiple</cite> to create
1.347 +mocks for you. In this case the created mocks are passed into a decorated
1.348 +function by keyword, and a dictionary is returned when <cite>patch.multiple</cite> is
1.349 +used as a context manager.</p>
1.350 +<p><cite>patch.multiple</cite> can be used as a decorator, class decorator or a context
1.351 +manager. The arguments <cite>spec</cite>, <cite>spec_set</cite>, <cite>create</cite>, <cite>autospec</cite> and
1.352 +<cite>new_callable</cite> have the same meaning as for <cite>patch</cite>. These arguments will
1.353 +be applied to <em>all</em> patches done by <cite>patch.multiple</cite>.</p>
1.354 +<p>When used as a class decorator <cite>patch.multiple</cite> honours <cite>patch.TEST_PREFIX</cite>
1.355 +for choosing which methods to wrap.</p>
1.356 +</dd></dl>
1.357 +
1.358 +<p>If you want <cite>patch.multiple</cite> to create mocks for you, then you can use
1.359 +<a class="reference internal" href="sentinel.html#mock.DEFAULT" title="mock.DEFAULT"><tt class="xref py py-data docutils literal"><span class="pre">DEFAULT</span></tt></a> as the value. If you use <cite>patch.multiple</cite> as a decorator
1.360 +then the created mocks are passed into the decorated function by keyword.</p>
1.361 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">thing</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>
1.362 +<span class="gp">>>> </span><span class="n">other</span> <span class="o">=</span> <span class="nb">object</span><span class="p">()</span>
1.363 +
1.364 +<span class="gp">>>> </span><span class="nd">@patch.multiple</span><span class="p">(</span><span class="s">'__main__'</span><span class="p">,</span> <span class="n">thing</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">)</span>
1.365 +<span class="gp">... </span><span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">thing</span><span class="p">,</span> <span class="n">other</span><span class="p">):</span>
1.366 +<span class="gp">... </span> <span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">thing</span><span class="p">,</span> <span class="n">MagicMock</span><span class="p">)</span>
1.367 +<span class="gp">... </span> <span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">other</span><span class="p">,</span> <span class="n">MagicMock</span><span class="p">)</span>
1.368 +<span class="gp">...</span>
1.369 +<span class="gp">>>> </span><span class="n">test_function</span><span class="p">()</span>
1.370 +</pre></div>
1.371 +</div>
1.372 +<p><cite>patch.multiple</cite> can be nested with other <cite>patch</cite> decorators, but put arguments
1.373 +passed by keyword <em>after</em> any of the standard arguments created by <cite>patch</cite>:</p>
1.374 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'sys.exit'</span><span class="p">)</span>
1.375 +<span class="gp">... </span><span class="nd">@patch.multiple</span><span class="p">(</span><span class="s">'__main__'</span><span class="p">,</span> <span class="n">thing</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">)</span>
1.376 +<span class="gp">... </span><span class="k">def</span> <span class="nf">test_function</span><span class="p">(</span><span class="n">mock_exit</span><span class="p">,</span> <span class="n">other</span><span class="p">,</span> <span class="n">thing</span><span class="p">):</span>
1.377 +<span class="gp">... </span> <span class="k">assert</span> <span class="s">'other'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">other</span><span class="p">)</span>
1.378 +<span class="gp">... </span> <span class="k">assert</span> <span class="s">'thing'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">thing</span><span class="p">)</span>
1.379 +<span class="gp">... </span> <span class="k">assert</span> <span class="s">'exit'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">mock_exit</span><span class="p">)</span>
1.380 +<span class="gp">...</span>
1.381 +<span class="gp">>>> </span><span class="n">test_function</span><span class="p">()</span>
1.382 +</pre></div>
1.383 +</div>
1.384 +<p>If <cite>patch.multiple</cite> is used as a context manager, the value returned by the
1.385 +context manger is a dictionary where created mocks are keyed by name:</p>
1.386 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">multiple</span><span class="p">(</span><span class="s">'__main__'</span><span class="p">,</span> <span class="n">thing</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">,</span> <span class="n">other</span><span class="o">=</span><span class="n">DEFAULT</span><span class="p">)</span> <span class="k">as</span> <span class="n">values</span><span class="p">:</span>
1.387 +<span class="gp">... </span> <span class="k">assert</span> <span class="s">'other'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">values</span><span class="p">[</span><span class="s">'other'</span><span class="p">])</span>
1.388 +<span class="gp">... </span> <span class="k">assert</span> <span class="s">'thing'</span> <span class="ow">in</span> <span class="nb">repr</span><span class="p">(</span><span class="n">values</span><span class="p">[</span><span class="s">'thing'</span><span class="p">])</span>
1.389 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">values</span><span class="p">[</span><span class="s">'thing'</span><span class="p">]</span> <span class="ow">is</span> <span class="n">thing</span>
1.390 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">values</span><span class="p">[</span><span class="s">'other'</span><span class="p">]</span> <span class="ow">is</span> <span class="n">other</span>
1.391 +<span class="gp">...</span>
1.392 +</pre></div>
1.393 +</div>
1.394 +</div>
1.395 +<div class="section" id="patch-methods-start-and-stop">
1.396 +<span id="start-and-stop"></span><h2>patch methods: start and stop<a class="headerlink" href="#patch-methods-start-and-stop" title="Permalink to this headline">¶</a></h2>
1.397 +<p>All the patchers have <cite>start</cite> and <cite>stop</cite> methods. These make it simpler to do
1.398 +patching in <cite>setUp</cite> methods or where you want to do multiple patches without
1.399 +nesting decorators or with statements.</p>
1.400 +<p>To use them call <cite>patch</cite>, <cite>patch.object</cite> or <cite>patch.dict</cite> as normal and keep a
1.401 +reference to the returned <cite>patcher</cite> object. You can then call <cite>start</cite> to put
1.402 +the patch in place and <cite>stop</cite> to undo it.</p>
1.403 +<p>If you are using <cite>patch</cite> to create a mock for you then it will be returned by
1.404 +the call to <cite>patcher.start</cite>.</p>
1.405 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.ClassName'</span><span class="p">)</span>
1.406 +<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">package</span> <span class="kn">import</span> <span class="n">module</span>
1.407 +<span class="gp">>>> </span><span class="n">original</span> <span class="o">=</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span>
1.408 +<span class="gp">>>> </span><span class="n">new_mock</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.409 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">original</span>
1.410 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="n">new_mock</span>
1.411 +<span class="gp">>>> </span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
1.412 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="n">original</span>
1.413 +<span class="gp">>>> </span><span class="k">assert</span> <span class="n">module</span><span class="o">.</span><span class="n">ClassName</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">new_mock</span>
1.414 +</pre></div>
1.415 +</div>
1.416 +<p>A typical use case for this might be for doing multiple patches in the <cite>setUp</cite>
1.417 +method of a <cite>TestCase</cite>:</p>
1.418 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.419 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.420 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher1</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.Class1'</span><span class="p">)</span>
1.421 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher2</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.Class2'</span><span class="p">)</span>
1.422 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass1</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher1</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.423 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass2</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher2</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.424 +<span class="gp">...</span>
1.425 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.426 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher1</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
1.427 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">patcher2</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
1.428 +<span class="gp">...</span>
1.429 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_something</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.430 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">Class1</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass1</span>
1.431 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">Class2</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass2</span>
1.432 +<span class="gp">...</span>
1.433 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_something'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
1.434 +</pre></div>
1.435 +</div>
1.436 +<div class="admonition caution">
1.437 +<p class="first admonition-title">Caution</p>
1.438 +<p>If you use this technique you must ensure that the patching is “undone” by
1.439 +calling <cite>stop</cite>. This can be fiddlier than you might think, because if an
1.440 +exception is raised in the setUp then tearDown is not called. <a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> cleanup functions make this
1.441 +easier.</p>
1.442 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">MyTest</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
1.443 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.444 +<span class="gp">... </span> <span class="n">patcher</span> <span class="o">=</span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.Class'</span><span class="p">)</span>
1.445 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass</span> <span class="o">=</span> <span class="n">patcher</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>
1.446 +<span class="gp">... </span> <span class="bp">self</span><span class="o">.</span><span class="n">addCleanup</span><span class="p">(</span><span class="n">patcher</span><span class="o">.</span><span class="n">stop</span><span class="p">)</span>
1.447 +<span class="gp">...</span>
1.448 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">test_something</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.449 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">Class</span> <span class="ow">is</span> <span class="bp">self</span><span class="o">.</span><span class="n">MockClass</span>
1.450 +<span class="gp">...</span>
1.451 +<span class="gp">>>> </span><span class="n">MyTest</span><span class="p">(</span><span class="s">'test_something'</span><span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
1.452 +</pre></div>
1.453 +</div>
1.454 +<p class="last">As an added bonus you no longer need to keep a reference to the <cite>patcher</cite>
1.455 +object.</p>
1.456 +</div>
1.457 +<p>It is also possible to stop all patches which have been started by using
1.458 +<cite>patch.stopall</cite>.</p>
1.459 +<dl class="function">
1.460 +<dt id="mock.patch.stopall">
1.461 +<tt class="descclassname">patch.</tt><tt class="descname">stopall</tt><big>(</big><big>)</big><a class="headerlink" href="#mock.patch.stopall" title="Permalink to this definition">¶</a></dt>
1.462 +<dd><p>Stop all active patches. Only stops patches started with <cite>start</cite>.</p>
1.463 +</dd></dl>
1.464 +
1.465 +</div>
1.466 +<div class="section" id="test-prefix">
1.467 +<h2>TEST_PREFIX<a class="headerlink" href="#test-prefix" title="Permalink to this headline">¶</a></h2>
1.468 +<p>All of the patchers can be used as class decorators. When used in this way
1.469 +they wrap every test method on the class. The patchers recognise methods that
1.470 +start with <cite>test</cite> as being test methods. This is the same way that the
1.471 +<cite>unittest.TestLoader</cite> finds test methods by default.</p>
1.472 +<p>It is possible that you want to use a different prefix for your tests. You can
1.473 +inform the patchers of the different prefix by setting <cite>patch.TEST_PREFIX</cite>:</p>
1.474 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">patch</span><span class="o">.</span><span class="n">TEST_PREFIX</span> <span class="o">=</span> <span class="s">'foo'</span>
1.475 +<span class="gp">>>> </span><span class="n">value</span> <span class="o">=</span> <span class="mi">3</span>
1.476 +<span class="go">>>></span>
1.477 +<span class="gp">>>> </span><span class="nd">@patch</span><span class="p">(</span><span class="s">'__main__.value'</span><span class="p">,</span> <span class="s">'not three'</span><span class="p">)</span>
1.478 +<span class="gp">... </span><span class="k">class</span> <span class="nc">Thing</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
1.479 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">foo_one</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.480 +<span class="gp">... </span> <span class="k">print</span> <span class="n">value</span>
1.481 +<span class="gp">... </span> <span class="k">def</span> <span class="nf">foo_two</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
1.482 +<span class="gp">... </span> <span class="k">print</span> <span class="n">value</span>
1.483 +<span class="gp">...</span>
1.484 +<span class="go">>>></span>
1.485 +<span class="gp">>>> </span><span class="n">Thing</span><span class="p">()</span><span class="o">.</span><span class="n">foo_one</span><span class="p">()</span>
1.486 +<span class="go">not three</span>
1.487 +<span class="gp">>>> </span><span class="n">Thing</span><span class="p">()</span><span class="o">.</span><span class="n">foo_two</span><span class="p">()</span>
1.488 +<span class="go">not three</span>
1.489 +<span class="gp">>>> </span><span class="n">value</span>
1.490 +<span class="go">3</span>
1.491 +</pre></div>
1.492 +</div>
1.493 +</div>
1.494 +<div class="section" id="nesting-patch-decorators">
1.495 +<h2>Nesting Patch Decorators<a class="headerlink" href="#nesting-patch-decorators" title="Permalink to this headline">¶</a></h2>
1.496 +<p>If you want to perform multiple patches then you can simply stack up the
1.497 +decorators.</p>
1.498 +<p>You can stack up multiple patch decorators using this pattern:</p>
1.499 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="nd">@patch.object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s">'class_method'</span><span class="p">)</span>
1.500 +<span class="gp">... </span><span class="nd">@patch.object</span><span class="p">(</span><span class="n">SomeClass</span><span class="p">,</span> <span class="s">'static_method'</span><span class="p">)</span>
1.501 +<span class="gp">... </span><span class="k">def</span> <span class="nf">test</span><span class="p">(</span><span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span><span class="p">):</span>
1.502 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">static_method</span> <span class="ow">is</span> <span class="n">mock1</span>
1.503 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">class_method</span> <span class="ow">is</span> <span class="n">mock2</span>
1.504 +<span class="gp">... </span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">static_method</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
1.505 +<span class="gp">... </span> <span class="n">SomeClass</span><span class="o">.</span><span class="n">class_method</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span>
1.506 +<span class="gp">... </span> <span class="k">return</span> <span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span>
1.507 +<span class="gp">...</span>
1.508 +<span class="gp">>>> </span><span class="n">mock1</span><span class="p">,</span> <span class="n">mock2</span> <span class="o">=</span> <span class="n">test</span><span class="p">()</span>
1.509 +<span class="gp">>>> </span><span class="n">mock1</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span>
1.510 +<span class="gp">>>> </span><span class="n">mock2</span><span class="o">.</span><span class="n">assert_called_once_with</span><span class="p">(</span><span class="s">'bar'</span><span class="p">)</span>
1.511 +</pre></div>
1.512 +</div>
1.513 +<p>Note that the decorators are applied from the bottom upwards. This is the
1.514 +standard way that Python applies decorators. The order of the created mocks
1.515 +passed into your test function matches this order.</p>
1.516 +<p>Like all context-managers patches can be nested using contextlib’s nested
1.517 +function; <em>every</em> patching will appear in the tuple after “as”:</p>
1.518 +<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">contextlib</span> <span class="kn">import</span> <span class="n">nested</span>
1.519 +<span class="gp">>>> </span><span class="k">with</span> <span class="n">nested</span><span class="p">(</span>
1.520 +<span class="gp">... </span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.ClassName1'</span><span class="p">),</span>
1.521 +<span class="gp">... </span> <span class="n">patch</span><span class="p">(</span><span class="s">'package.module.ClassName2'</span><span class="p">)</span>
1.522 +<span class="gp">... </span> <span class="p">)</span> <span class="k">as</span> <span class="p">(</span><span class="n">MockClass1</span><span class="p">,</span> <span class="n">MockClass2</span><span class="p">):</span>
1.523 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">ClassName1</span> <span class="ow">is</span> <span class="n">MockClass1</span>
1.524 +<span class="gp">... </span> <span class="k">assert</span> <span class="n">package</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">ClassName2</span> <span class="ow">is</span> <span class="n">MockClass2</span>
1.525 +<span class="gp">...</span>
1.526 +</pre></div>
1.527 +</div>
1.528 +</div>
1.529 +<div class="section" id="where-to-patch">
1.530 +<span id="id1"></span><h2>Where to patch<a class="headerlink" href="#where-to-patch" title="Permalink to this headline">¶</a></h2>
1.531 +<p><cite>patch</cite> works by (temporarily) changing the object that a <em>name</em> points to with
1.532 +another one. There can be many names pointing to any individual object, so
1.533 +for patching to work you must ensure that you patch the name used by the system
1.534 +under test.</p>
1.535 +<p>The basic principle is that you patch where an object is <em>looked up</em>, which
1.536 +is not necessarily the same place as where it is defined. A couple of
1.537 +examples will help to clarify this.</p>
1.538 +<p>Imagine we have a project that we want to test with the following structure:</p>
1.539 +<div class="highlight-python"><pre>a.py
1.540 + -> Defines SomeClass
1.541 +
1.542 +b.py
1.543 + -> from a import SomeClass
1.544 + -> some_function instantiates SomeClass</pre>
1.545 +</div>
1.546 +<p>Now we want to test <cite>some_function</cite> but we want to mock out <cite>SomeClass</cite> using
1.547 +<cite>patch</cite>. The problem is that when we import module b, which we will have to
1.548 +do then it imports <cite>SomeClass</cite> from module a. If we use <cite>patch</cite> to mock out
1.549 +<cite>a.SomeClass</cite> then it will have no effect on our test; module b already has a
1.550 +reference to the <em>real</em> <cite>SomeClass</cite> and it looks like our patching had no
1.551 +effect.</p>
1.552 +<p>The key is to patch out <cite>SomeClass</cite> where it is used (or where it is looked up
1.553 +). In this case <cite>some_function</cite> will actually look up <cite>SomeClass</cite> in module b,
1.554 +where we have imported it. The patching should look like:</p>
1.555 +<blockquote>
1.556 +<div><cite>@patch(‘b.SomeClass’)</cite></div></blockquote>
1.557 +<p>However, consider the alternative scenario where instead of <cite>from a import
1.558 +SomeClass</cite> module b does <cite>import a</cite> and <cite>some_function</cite> uses <cite>a.SomeClass</cite>. Both
1.559 +of these import forms are common. In this case the class we want to patch is
1.560 +being looked up on the a module and so we have to patch <cite>a.SomeClass</cite> instead:</p>
1.561 +<blockquote>
1.562 +<div><cite>@patch(‘a.SomeClass’)</cite></div></blockquote>
1.563 +</div>
1.564 +<div class="section" id="patching-descriptors-and-proxy-objects">
1.565 +<h2>Patching Descriptors and Proxy Objects<a class="headerlink" href="#patching-descriptors-and-proxy-objects" title="Permalink to this headline">¶</a></h2>
1.566 +<p>Since version 0.6.0 both <a class="reference internal" href="#patch">patch</a> and <a class="reference internal" href="#patch-object">patch.object</a> have been able to correctly
1.567 +patch and restore descriptors: class methods, static methods and properties.
1.568 +You should patch these on the <em>class</em> rather than an instance.</p>
1.569 +<p>Since version 0.7.0 <a class="reference internal" href="#patch">patch</a> and <a class="reference internal" href="#patch-object">patch.object</a> work correctly with some objects
1.570 +that proxy attribute access, like the <a class="reference external" href="http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198">django setttings object</a>.</p>
1.571 +<div class="admonition note">
1.572 +<p class="first admonition-title">Note</p>
1.573 +<p class="last">In django <cite>import settings</cite> and <cite>from django.conf import settings</cite>
1.574 +return different objects. If you are using libraries / apps that do both you
1.575 +may have to patch both. Grrr...</p>
1.576 +</div>
1.577 +</div>
1.578 +</div>
1.579 +
1.580 +
1.581 + </div>
1.582 + </div>
1.583 + </div>
1.584 + <div class="sphinxsidebar">
1.585 + <div class="sphinxsidebarwrapper">
1.586 + <h3><a href="index.html">Table Of Contents</a></h3>
1.587 + <ul>
1.588 +<li><a class="reference internal" href="#">Patch Decorators</a><ul>
1.589 +<li><a class="reference internal" href="#patch">patch</a></li>
1.590 +<li><a class="reference internal" href="#patch-object">patch.object</a></li>
1.591 +<li><a class="reference internal" href="#patch-dict">patch.dict</a></li>
1.592 +<li><a class="reference internal" href="#patch-multiple">patch.multiple</a></li>
1.593 +<li><a class="reference internal" href="#patch-methods-start-and-stop">patch methods: start and stop</a></li>
1.594 +<li><a class="reference internal" href="#test-prefix">TEST_PREFIX</a></li>
1.595 +<li><a class="reference internal" href="#nesting-patch-decorators">Nesting Patch Decorators</a></li>
1.596 +<li><a class="reference internal" href="#where-to-patch">Where to patch</a></li>
1.597 +<li><a class="reference internal" href="#patching-descriptors-and-proxy-objects">Patching Descriptors and Proxy Objects</a></li>
1.598 +</ul>
1.599 +</li>
1.600 +</ul>
1.601 +
1.602 + <h4>Previous topic</h4>
1.603 + <p class="topless"><a href="mock.html"
1.604 + title="previous chapter">The Mock Class</a></p>
1.605 + <h4>Next topic</h4>
1.606 + <p class="topless"><a href="helpers.html"
1.607 + title="next chapter">Helpers</a></p>
1.608 + <h3>This Page</h3>
1.609 + <ul class="this-page-menu">
1.610 + <li><a href="_sources/patch.txt"
1.611 + rel="nofollow">Show Source</a></li>
1.612 + </ul>
1.613 +<div id="searchbox" style="display: none">
1.614 + <h3>Quick search</h3>
1.615 + <form class="search" action="search.html" method="get">
1.616 + <input type="text" name="q" />
1.617 + <input type="submit" value="Go" />
1.618 + <input type="hidden" name="check_keywords" value="yes" />
1.619 + <input type="hidden" name="area" value="default" />
1.620 + </form>
1.621 + <p class="searchtip" style="font-size: 90%">
1.622 + Enter search terms or a module, class or function name.
1.623 + </p>
1.624 +</div>
1.625 +<script type="text/javascript">$('#searchbox').show(0);</script>
1.626 + </div>
1.627 + </div>
1.628 + <div class="clearer"></div>
1.629 + </div>
1.630 + <div class="related">
1.631 + <h3>Navigation</h3>
1.632 + <ul>
1.633 + <li class="right" style="margin-right: 10px">
1.634 + <a href="genindex.html" title="General Index"
1.635 + >index</a></li>
1.636 + <li class="right" >
1.637 + <a href="helpers.html" title="Helpers"
1.638 + >next</a> |</li>
1.639 + <li class="right" >
1.640 + <a href="mock.html" title="The Mock Class"
1.641 + >previous</a> |</li>
1.642 + <li><a href="index.html">Mock 1.0.0 documentation</a> »</li>
1.643 + </ul>
1.644 + </div>
1.645 + <div class="footer">
1.646 + © Copyright 2007-2012, Michael Foord & the mock team.
1.647 + Last updated on Oct 07, 2012.
1.648 + Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
1.649 + </div>
1.650 + </body>
1.651 +</html>
1.652 \ No newline at end of file
