We are currently solving the following issue within our repository. Here is the issue text:
--- BEGIN ISSUE ---
pyro.poutine module is absent from sphinx docs
For example, there is no documentation for `pyro.poutine.block()`

--- END ISSUE ---

Below are some code segments, each from a relevant file. One or more of these files may contain bugs.
--- BEGIN FILES ---
Path: `pyro/poutine/__init__.py`
Content:
```
1 from __future__ import absolute_import, division, print_function
2 
3 import functools
4 from six.moves import xrange
5 
6 from pyro.poutine import util
7 
8 from .block_messenger import BlockMessenger
9 from .condition_messenger import ConditionMessenger
10 from .enumerate_messenger import EnumerateMessenger  # noqa: F401
11 from .escape_messenger import EscapeMessenger
12 from .indep_messenger import IndepMessenger  # noqa: F401
13 from .infer_config_messenger import InferConfigMessenger
14 from .lift_messenger import LiftMessenger
15 from .messenger import _PYRO_STACK, Messenger  # noqa: F401
16 from .replay_messenger import ReplayMessenger
17 from .scale_messenger import ScaleMessenger
18 from .trace import Trace  # noqa: F401
19 from .trace_messenger import TraceMessenger
20 
21 ############################################
22 # Begin primitive operations
23 ############################################
24 
25 
26 def trace(fn=None, graph_type=None, param_only=None):
27     """
28     :param fn: a stochastic function (callable containing pyro primitive calls)
29     :param graph_type: string that specifies the kind of graph to construct
30     :param param_only: if true, only records params and not samples
31     :returns: stochastic function wrapped in a TraceHandler
32     :rtype: pyro.poutine.TraceHandler
33 
34     Alias for TraceHandler constructor.
35 
36     Given a callable that contains Pyro primitive calls, return a TraceHandler callable
37     that records the inputs and outputs to those primitive calls
38     and their dependencies.
39 
40     Adds trace data structure site constructors to primitive stacks
41     """
42     msngr = TraceMessenger(graph_type=graph_type, param_only=param_only)
43     return msngr(fn) if fn is not None else msngr
44 
45 
46 def replay(fn=None, trace=None, sites=None):
47     """
48     :param fn: a stochastic function (callable containing pyro primitive calls)
49     :param trace: a Trace data structure to replay against
50     :param sites: list or dict of names of sample sites in fn to replay against,
51     defaulting to all sites
52     :returns: stochastic function wrapped in a ReplayHandler
53     :rtype: pyro.poutine.ReplayHandler
54 
55     Alias for ReplayHandler constructor.
56 
57     Given a callable that contains Pyro primitive calls,
58     return a callable that runs the original, reusing the values at sites in trace
59     at those sites in the new trace
60     """
61     msngr = ReplayMessenger(trace=trace, sites=sites)
62     return msngr(fn) if fn is not None else msngr
63 
64 
65 def lift(fn=None, prior=None):
66     """
67     :param fn: function whose parameters will be lifted to random values
68     :param prior: prior function in the form of a Distribution or a dict of stochastic fns
69     :returns: stochastic function wrapped in LiftHandler
70 
71     Given a stochastic function with param calls and a prior distribution,
72     create a stochastic function where all param calls are replaced by sampling from prior.
73     Prior should be a callable or a dict of names to callables.
74     """
75     msngr = LiftMessenger(prior=prior)
76     return msngr(fn) if fn is not None else msngr
77 
78 
79 def block(fn=None, hide=None, expose=None, hide_types=None, expose_types=None):
80     """
81     :param fn: a stochastic function (callable containing pyro primitive calls)
82     :param hide: list of site names to hide
83     :param expose: list of site names to be exposed while all others hidden
84     :param hide_types: list of site types to be hidden
85     :param expose_types: list of site types to be exposed while all others hidden
86     :returns: stochastic function wrapped in a BlockHandler
87     :rtype: pyro.poutine.BlockHandler
88 
89     Alias for BlockHandler constructor.
90 
91     Given a callable that contains Pyro primitive calls,
92     selectively hide some of those calls from poutines higher up the stack
93     """
94     msngr = BlockMessenger(hide=hide, expose=expose,
95                            hide_types=hide_types, expose_types=expose_types)
96     return msngr(fn) if fn is not None else msngr
97 
98 
99 def escape(fn=None, escape_fn=None):
100     """
101     :param fn: a stochastic function (callable containing pyro primitive calls)
102     :param escape_fn: function that takes a partial trace and a site
103     and returns a boolean value to decide whether to exit at that site
104     :returns: stochastic function wrapped in EscapeHandler
105 
106     Alias for EscapeHandler constructor.
107 
108     Given a callable that contains Pyro primitive calls,
109     evaluate escape_fn on each site, and if the result is True,
110     raise a NonlocalExit exception that stops execution
111     and returns the offending site.
112     """
113     msngr = EscapeMessenger(escape_fn)
114     return msngr(fn) if fn is not None else msngr
115 
116 
117 def condition(fn=None, data=None):
118     """
119     :param fn: a stochastic function (callable containing pyro primitive calls)
120     :param data: a dict or a Trace
121     :returns: stochastic function wrapped in a ConditionHandler
122     :rtype: pyro.poutine.ConditionHandler
123 
124     Alias for ConditionHandler constructor.
125 
126     Given a stochastic function with some sample statements
127     and a dictionary of observations at names,
128     change the sample statements at those names into observes
129     with those values
130     """
131     msngr = ConditionMessenger(data=data)
132     return msngr(fn) if fn is not None else msngr
133 
134 
135 def infer_config(fn=None, config_fn=None):
136     """
137     :param fn: a stochastic function (callable containing pyro primitive calls)
138     :param config_fn: a callable taking a site and returning an infer dict
139 
140     Alias for :class:`~pyro.poutine.infer_config_messenger.InferConfigHandler` constructor.
141 
142     Given a callable that contains Pyro primitive calls
143     and a callable taking a trace site and returning a dictionary,
144     updates the value of the infer kwarg at a sample site to config_fn(site)
145     """
146     msngr = InferConfigMessenger(config_fn)
147     return msngr(fn) if fn is not None else msngr
148 
149 
150 def scale(fn=None, scale=None):
151     """
152     :param scale: a positive scaling factor
153     :rtype: pyro.poutine.ScaleMessenger
154 
155     Alias for ScaleMessenger constructor.
156 
157     Given a stochastic function with some sample statements and a positive
158     scale factor, scale the score of all sample and observe sites in the
159     function.
160     """
161     msngr = ScaleMessenger(scale=scale)
162     # XXX temporary compatibility fix
163     return msngr(fn) if callable(fn) else msngr
164 
165 
166 def indep(fn=None, name=None, size=None, dim=None):
167     """
168     Alias for IndepMessenger constructor.
169 
170     This messenger keeps track of stack of independence information declared by
171     nested ``irange`` and ``iarange`` contexts. This information is stored in
172     a ``cond_indep_stack`` at each sample/observe site for consumption by
173     ``TraceMessenger``.
174     """
175     msngr = IndepMessenger(name=name, size=size, dim=dim)
176     return msngr(fn) if fn is not None else msngr
177 
178 
179 def enum(fn=None, first_available_dim=None):
180     """
181     :param int first_available_dim: The first tensor dimension (counting
182         from the right) that is available for parallel enumeration. This
183         dimension and all dimensions left may be used internally by Pyro.
184 
185     Alias for EnumerateMessenger constructor.
186 
187     Enumerates in parallel over discrete sample sites marked
188     ``infer={"enumerate": "parallel"}``.
189     """
190     msngr = EnumerateMessenger(first_available_dim=first_available_dim)
191     return msngr(fn) if fn is not None else msngr
192 
193 
194 #########################################
195 # Begin composite operations
196 #########################################
197 
198 def do(fn=None, data=None):
199     """
200     :param fn: a stochastic function (callable containing pyro primitive calls)
201     :param data: a dict or a Trace
202     :returns: stochastic function wrapped in a BlockHandler and ConditionHandler
203     :rtype: pyro.poutine.BlockHandler
204 
205     Given a stochastic function with some sample statements
206     and a dictionary of values at names,
207     set the return values of those sites equal to the values
208     and hide them from the rest of the stack
209     as if they were hard-coded to those values
210     by using BlockHandler
211     """
212     def wrapper(wrapped):
213         return block(condition(wrapped, data=data), hide=list(data.keys()))
214     return wrapper(fn) if fn is not None else wrapper
215 
216 
217 def queue(fn=None, queue=None, max_tries=None,
218           extend_fn=None, escape_fn=None, num_samples=None):
219     """
220     :param fn: a stochastic function (callable containing pyro primitive calls)
221     :param queue: a queue data structure like multiprocessing.Queue to hold partial traces
222     :param max_tries: maximum number of attempts to compute a single complete trace
223     :param extend_fn: function (possibly stochastic) that takes a partial trace and a site
224     and returns a list of extended traces
225     :param escape_fn: function (possibly stochastic) that takes a partial trace and a site
226     and returns a boolean value to decide whether to exit
227     :param num_samples: optional number of extended traces for extend_fn to return
228     :returns: stochastic function wrapped in poutine logic
229 
230     Given a stochastic function and a queue,
231     return a return value from a complete trace in the queue
232     """
233 
234     if max_tries is None:
235         max_tries = int(1e6)
236 
237     if extend_fn is None:
238         extend_fn = util.enum_extend
239 
240     if escape_fn is None:
241         escape_fn = util.discrete_escape
242 
243     if num_samples is None:
244         num_samples = -1
245 
246     def wrapper(wrapped):
247         def _fn(*args, **kwargs):
248 
249             for i in xrange(max_tries):
250                 assert not queue.empty(), \
251                     "trying to get() from an empty queue will deadlock"
252 
253                 next_trace = queue.get()
254                 try:
255                     ftr = trace(escape(replay(wrapped, trace=next_trace),
256                                        escape_fn=functools.partial(escape_fn,
257                                                                    next_trace)))
258                     return ftr(*args, **kwargs)
259                 except util.NonlocalExit as site_container:
260                     site_container.reset_stack()
261                     for tr in extend_fn(ftr.trace.copy(), site_container.site,
262                                         num_samples=num_samples):
263                         queue.put(tr)
264 
265             raise ValueError("max tries ({}) exceeded".format(str(max_tries)))
266         return _fn
267 
268     return wrapper(fn) if fn is not None else wrapper
269
```
--- END FILES ---

Please first localize the bug based on the issue statement, and then generate a patch according to the `git diff` format fenced by three backticks.

Here is an example:

```diff
diff --git a/examples/server_async.py b/examples/server_async.py
--- a/examples/server_async.py
+++ b/examples/server_async.py
@@ -313,4 +313,4 @@
 
 
 if __name__ == "__main__":
-    asyncio.run(run_async_server("."), debug=True)
+    asyncio.run(run_async_server(), debug=True)
diff --git a/examples/server_sync.py b/examples/server_sync.py
--- a/examples/server_sync.py
+++ b/examples/server_sync.py
@@ -313,5 +313,5 @@
 
 
 if __name__ == "__main__":
-    server = run_sync_server(".")
+    server = run_sync_server()
     server.shutdown()

```

diff --git a/pyro/poutine/__init__.py b/pyro/poutine/__init__.py
--- a/pyro/poutine/__init__.py
+++ b/pyro/poutine/__init__.py
@@ -48,7 +48,7 @@
     :param fn: a stochastic function (callable containing pyro primitive calls)
     :param trace: a Trace data structure to replay against
     :param sites: list or dict of names of sample sites in fn to replay against,
-    defaulting to all sites
+        defaulting to all sites
     :returns: stochastic function wrapped in a ReplayHandler
     :rtype: pyro.poutine.ReplayHandler
 
@@ -99,8 +99,8 @@
 def escape(fn=None, escape_fn=None):
     """
     :param fn: a stochastic function (callable containing pyro primitive calls)
-    :param escape_fn: function that takes a partial trace and a site
-    and returns a boolean value to decide whether to exit at that site
+    :param escape_fn: function that takes a partial trace and a site,
+        and returns a boolean value to decide whether to exit at that site
     :returns: stochastic function wrapped in EscapeHandler
 
     Alias for EscapeHandler constructor.
@@ -220,10 +220,10 @@
     :param fn: a stochastic function (callable containing pyro primitive calls)
     :param queue: a queue data structure like multiprocessing.Queue to hold partial traces
     :param max_tries: maximum number of attempts to compute a single complete trace
-    :param extend_fn: function (possibly stochastic) that takes a partial trace and a site
-    and returns a list of extended traces
-    :param escape_fn: function (possibly stochastic) that takes a partial trace and a site
-    and returns a boolean value to decide whether to exit
+    :param extend_fn: function (possibly stochastic) that takes a partial trace and a site,
+        and returns a list of extended traces
+    :param escape_fn: function (possibly stochastic) that takes a partial trace and a site,
+        and returns a boolean value to decide whether to exit
     :param num_samples: optional number of extended traces for extend_fn to return
     :returns: stochastic function wrapped in poutine logic

{"golden_diff": "diff --git a/pyro/poutine/__init__.py b/pyro/poutine/__init__.py\n--- a/pyro/poutine/__init__.py\n+++ b/pyro/poutine/__init__.py\n@@ -48,7 +48,7 @@\n     :param fn: a stochastic function (callable containing pyro primitive calls)\n     :param trace: a Trace data structure to replay against\n     :param sites: list or dict of names of sample sites in fn to replay against,\n-    defaulting to all sites\n+        defaulting to all sites\n     :returns: stochastic function wrapped in a ReplayHandler\n     :rtype: pyro.poutine.ReplayHandler\n \n@@ -99,8 +99,8 @@\n def escape(fn=None, escape_fn=None):\n     \"\"\"\n     :param fn: a stochastic function (callable containing pyro primitive calls)\n-    :param escape_fn: function that takes a partial trace and a site\n-    and returns a boolean value to decide whether to exit at that site\n+    :param escape_fn: function that takes a partial trace and a site,\n+        and returns a boolean value to decide whether to exit at that site\n     :returns: stochastic function wrapped in EscapeHandler\n \n     Alias for EscapeHandler constructor.\n@@ -220,10 +220,10 @@\n     :param fn: a stochastic function (callable containing pyro primitive calls)\n     :param queue: a queue data structure like multiprocessing.Queue to hold partial traces\n     :param max_tries: maximum number of attempts to compute a single complete trace\n-    :param extend_fn: function (possibly stochastic) that takes a partial trace and a site\n-    and returns a list of extended traces\n-    :param escape_fn: function (possibly stochastic) that takes a partial trace and a site\n-    and returns a boolean value to decide whether to exit\n+    :param extend_fn: function (possibly stochastic) that takes a partial trace and a site,\n+        and returns a list of extended traces\n+    :param escape_fn: function (possibly stochastic) that takes a partial trace and a site,\n+        and returns a boolean value to decide whether to exit\n     :param num_samples: optional number of extended traces for extend_fn to return\n     :returns: stochastic function wrapped in poutine logic\n", "issue": "pyro.poutine module is absent from sphinx docs\nFor example, there is no documentation for `pyro.poutine.block()`\n", "before_files": [{"content": "from __future__ import absolute_import, division, print_function\n\nimport functools\nfrom six.moves import xrange\n\nfrom pyro.poutine import util\n\nfrom .block_messenger import BlockMessenger\nfrom .condition_messenger import ConditionMessenger\nfrom .enumerate_messenger import EnumerateMessenger  # noqa: F401\nfrom .escape_messenger import EscapeMessenger\nfrom .indep_messenger import IndepMessenger  # noqa: F401\nfrom .infer_config_messenger import InferConfigMessenger\nfrom .lift_messenger import LiftMessenger\nfrom .messenger import _PYRO_STACK, Messenger  # noqa: F401\nfrom .replay_messenger import ReplayMessenger\nfrom .scale_messenger import ScaleMessenger\nfrom .trace import Trace  # noqa: F401\nfrom .trace_messenger import TraceMessenger\n\n############################################\n# Begin primitive operations\n############################################\n\n\ndef trace(fn=None, graph_type=None, param_only=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param graph_type: string that specifies the kind of graph to construct\n    :param param_only: if true, only records params and not samples\n    :returns: stochastic function wrapped in a TraceHandler\n    :rtype: pyro.poutine.TraceHandler\n\n    Alias for TraceHandler constructor.\n\n    Given a callable that contains Pyro primitive calls, return a TraceHandler callable\n    that records the inputs and outputs to those primitive calls\n    and their dependencies.\n\n    Adds trace data structure site constructors to primitive stacks\n    \"\"\"\n    msngr = TraceMessenger(graph_type=graph_type, param_only=param_only)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef replay(fn=None, trace=None, sites=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param trace: a Trace data structure to replay against\n    :param sites: list or dict of names of sample sites in fn to replay against,\n    defaulting to all sites\n    :returns: stochastic function wrapped in a ReplayHandler\n    :rtype: pyro.poutine.ReplayHandler\n\n    Alias for ReplayHandler constructor.\n\n    Given a callable that contains Pyro primitive calls,\n    return a callable that runs the original, reusing the values at sites in trace\n    at those sites in the new trace\n    \"\"\"\n    msngr = ReplayMessenger(trace=trace, sites=sites)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef lift(fn=None, prior=None):\n    \"\"\"\n    :param fn: function whose parameters will be lifted to random values\n    :param prior: prior function in the form of a Distribution or a dict of stochastic fns\n    :returns: stochastic function wrapped in LiftHandler\n\n    Given a stochastic function with param calls and a prior distribution,\n    create a stochastic function where all param calls are replaced by sampling from prior.\n    Prior should be a callable or a dict of names to callables.\n    \"\"\"\n    msngr = LiftMessenger(prior=prior)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef block(fn=None, hide=None, expose=None, hide_types=None, expose_types=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param hide: list of site names to hide\n    :param expose: list of site names to be exposed while all others hidden\n    :param hide_types: list of site types to be hidden\n    :param expose_types: list of site types to be exposed while all others hidden\n    :returns: stochastic function wrapped in a BlockHandler\n    :rtype: pyro.poutine.BlockHandler\n\n    Alias for BlockHandler constructor.\n\n    Given a callable that contains Pyro primitive calls,\n    selectively hide some of those calls from poutines higher up the stack\n    \"\"\"\n    msngr = BlockMessenger(hide=hide, expose=expose,\n                           hide_types=hide_types, expose_types=expose_types)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef escape(fn=None, escape_fn=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param escape_fn: function that takes a partial trace and a site\n    and returns a boolean value to decide whether to exit at that site\n    :returns: stochastic function wrapped in EscapeHandler\n\n    Alias for EscapeHandler constructor.\n\n    Given a callable that contains Pyro primitive calls,\n    evaluate escape_fn on each site, and if the result is True,\n    raise a NonlocalExit exception that stops execution\n    and returns the offending site.\n    \"\"\"\n    msngr = EscapeMessenger(escape_fn)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef condition(fn=None, data=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param data: a dict or a Trace\n    :returns: stochastic function wrapped in a ConditionHandler\n    :rtype: pyro.poutine.ConditionHandler\n\n    Alias for ConditionHandler constructor.\n\n    Given a stochastic function with some sample statements\n    and a dictionary of observations at names,\n    change the sample statements at those names into observes\n    with those values\n    \"\"\"\n    msngr = ConditionMessenger(data=data)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef infer_config(fn=None, config_fn=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param config_fn: a callable taking a site and returning an infer dict\n\n    Alias for :class:`~pyro.poutine.infer_config_messenger.InferConfigHandler` constructor.\n\n    Given a callable that contains Pyro primitive calls\n    and a callable taking a trace site and returning a dictionary,\n    updates the value of the infer kwarg at a sample site to config_fn(site)\n    \"\"\"\n    msngr = InferConfigMessenger(config_fn)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef scale(fn=None, scale=None):\n    \"\"\"\n    :param scale: a positive scaling factor\n    :rtype: pyro.poutine.ScaleMessenger\n\n    Alias for ScaleMessenger constructor.\n\n    Given a stochastic function with some sample statements and a positive\n    scale factor, scale the score of all sample and observe sites in the\n    function.\n    \"\"\"\n    msngr = ScaleMessenger(scale=scale)\n    # XXX temporary compatibility fix\n    return msngr(fn) if callable(fn) else msngr\n\n\ndef indep(fn=None, name=None, size=None, dim=None):\n    \"\"\"\n    Alias for IndepMessenger constructor.\n\n    This messenger keeps track of stack of independence information declared by\n    nested ``irange`` and ``iarange`` contexts. This information is stored in\n    a ``cond_indep_stack`` at each sample/observe site for consumption by\n    ``TraceMessenger``.\n    \"\"\"\n    msngr = IndepMessenger(name=name, size=size, dim=dim)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef enum(fn=None, first_available_dim=None):\n    \"\"\"\n    :param int first_available_dim: The first tensor dimension (counting\n        from the right) that is available for parallel enumeration. This\n        dimension and all dimensions left may be used internally by Pyro.\n\n    Alias for EnumerateMessenger constructor.\n\n    Enumerates in parallel over discrete sample sites marked\n    ``infer={\"enumerate\": \"parallel\"}``.\n    \"\"\"\n    msngr = EnumerateMessenger(first_available_dim=first_available_dim)\n    return msngr(fn) if fn is not None else msngr\n\n\n#########################################\n# Begin composite operations\n#########################################\n\ndef do(fn=None, data=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param data: a dict or a Trace\n    :returns: stochastic function wrapped in a BlockHandler and ConditionHandler\n    :rtype: pyro.poutine.BlockHandler\n\n    Given a stochastic function with some sample statements\n    and a dictionary of values at names,\n    set the return values of those sites equal to the values\n    and hide them from the rest of the stack\n    as if they were hard-coded to those values\n    by using BlockHandler\n    \"\"\"\n    def wrapper(wrapped):\n        return block(condition(wrapped, data=data), hide=list(data.keys()))\n    return wrapper(fn) if fn is not None else wrapper\n\n\ndef queue(fn=None, queue=None, max_tries=None,\n          extend_fn=None, escape_fn=None, num_samples=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param queue: a queue data structure like multiprocessing.Queue to hold partial traces\n    :param max_tries: maximum number of attempts to compute a single complete trace\n    :param extend_fn: function (possibly stochastic) that takes a partial trace and a site\n    and returns a list of extended traces\n    :param escape_fn: function (possibly stochastic) that takes a partial trace and a site\n    and returns a boolean value to decide whether to exit\n    :param num_samples: optional number of extended traces for extend_fn to return\n    :returns: stochastic function wrapped in poutine logic\n\n    Given a stochastic function and a queue,\n    return a return value from a complete trace in the queue\n    \"\"\"\n\n    if max_tries is None:\n        max_tries = int(1e6)\n\n    if extend_fn is None:\n        extend_fn = util.enum_extend\n\n    if escape_fn is None:\n        escape_fn = util.discrete_escape\n\n    if num_samples is None:\n        num_samples = -1\n\n    def wrapper(wrapped):\n        def _fn(*args, **kwargs):\n\n            for i in xrange(max_tries):\n                assert not queue.empty(), \\\n                    \"trying to get() from an empty queue will deadlock\"\n\n                next_trace = queue.get()\n                try:\n                    ftr = trace(escape(replay(wrapped, trace=next_trace),\n                                       escape_fn=functools.partial(escape_fn,\n                                                                   next_trace)))\n                    return ftr(*args, **kwargs)\n                except util.NonlocalExit as site_container:\n                    site_container.reset_stack()\n                    for tr in extend_fn(ftr.trace.copy(), site_container.site,\n                                        num_samples=num_samples):\n                        queue.put(tr)\n\n            raise ValueError(\"max tries ({}) exceeded\".format(str(max_tries)))\n        return _fn\n\n    return wrapper(fn) if fn is not None else wrapper\n", "path": "pyro/poutine/__init__.py"}], "after_files": [{"content": "from __future__ import absolute_import, division, print_function\n\nimport functools\nfrom six.moves import xrange\n\nfrom pyro.poutine import util\n\nfrom .block_messenger import BlockMessenger\nfrom .condition_messenger import ConditionMessenger\nfrom .enumerate_messenger import EnumerateMessenger  # noqa: F401\nfrom .escape_messenger import EscapeMessenger\nfrom .indep_messenger import IndepMessenger  # noqa: F401\nfrom .infer_config_messenger import InferConfigMessenger\nfrom .lift_messenger import LiftMessenger\nfrom .messenger import _PYRO_STACK, Messenger  # noqa: F401\nfrom .replay_messenger import ReplayMessenger\nfrom .scale_messenger import ScaleMessenger\nfrom .trace import Trace  # noqa: F401\nfrom .trace_messenger import TraceMessenger\n\n############################################\n# Begin primitive operations\n############################################\n\n\ndef trace(fn=None, graph_type=None, param_only=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param graph_type: string that specifies the kind of graph to construct\n    :param param_only: if true, only records params and not samples\n    :returns: stochastic function wrapped in a TraceHandler\n    :rtype: pyro.poutine.TraceHandler\n\n    Alias for TraceHandler constructor.\n\n    Given a callable that contains Pyro primitive calls, return a TraceHandler callable\n    that records the inputs and outputs to those primitive calls\n    and their dependencies.\n\n    Adds trace data structure site constructors to primitive stacks\n    \"\"\"\n    msngr = TraceMessenger(graph_type=graph_type, param_only=param_only)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef replay(fn=None, trace=None, sites=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param trace: a Trace data structure to replay against\n    :param sites: list or dict of names of sample sites in fn to replay against,\n        defaulting to all sites\n    :returns: stochastic function wrapped in a ReplayHandler\n    :rtype: pyro.poutine.ReplayHandler\n\n    Alias for ReplayHandler constructor.\n\n    Given a callable that contains Pyro primitive calls,\n    return a callable that runs the original, reusing the values at sites in trace\n    at those sites in the new trace\n    \"\"\"\n    msngr = ReplayMessenger(trace=trace, sites=sites)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef lift(fn=None, prior=None):\n    \"\"\"\n    :param fn: function whose parameters will be lifted to random values\n    :param prior: prior function in the form of a Distribution or a dict of stochastic fns\n    :returns: stochastic function wrapped in LiftHandler\n\n    Given a stochastic function with param calls and a prior distribution,\n    create a stochastic function where all param calls are replaced by sampling from prior.\n    Prior should be a callable or a dict of names to callables.\n    \"\"\"\n    msngr = LiftMessenger(prior=prior)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef block(fn=None, hide=None, expose=None, hide_types=None, expose_types=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param hide: list of site names to hide\n    :param expose: list of site names to be exposed while all others hidden\n    :param hide_types: list of site types to be hidden\n    :param expose_types: list of site types to be exposed while all others hidden\n    :returns: stochastic function wrapped in a BlockHandler\n    :rtype: pyro.poutine.BlockHandler\n\n    Alias for BlockHandler constructor.\n\n    Given a callable that contains Pyro primitive calls,\n    selectively hide some of those calls from poutines higher up the stack\n    \"\"\"\n    msngr = BlockMessenger(hide=hide, expose=expose,\n                           hide_types=hide_types, expose_types=expose_types)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef escape(fn=None, escape_fn=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param escape_fn: function that takes a partial trace and a site,\n        and returns a boolean value to decide whether to exit at that site\n    :returns: stochastic function wrapped in EscapeHandler\n\n    Alias for EscapeHandler constructor.\n\n    Given a callable that contains Pyro primitive calls,\n    evaluate escape_fn on each site, and if the result is True,\n    raise a NonlocalExit exception that stops execution\n    and returns the offending site.\n    \"\"\"\n    msngr = EscapeMessenger(escape_fn)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef condition(fn=None, data=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param data: a dict or a Trace\n    :returns: stochastic function wrapped in a ConditionHandler\n    :rtype: pyro.poutine.ConditionHandler\n\n    Alias for ConditionHandler constructor.\n\n    Given a stochastic function with some sample statements\n    and a dictionary of observations at names,\n    change the sample statements at those names into observes\n    with those values\n    \"\"\"\n    msngr = ConditionMessenger(data=data)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef infer_config(fn=None, config_fn=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param config_fn: a callable taking a site and returning an infer dict\n\n    Alias for :class:`~pyro.poutine.infer_config_messenger.InferConfigHandler` constructor.\n\n    Given a callable that contains Pyro primitive calls\n    and a callable taking a trace site and returning a dictionary,\n    updates the value of the infer kwarg at a sample site to config_fn(site)\n    \"\"\"\n    msngr = InferConfigMessenger(config_fn)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef scale(fn=None, scale=None):\n    \"\"\"\n    :param scale: a positive scaling factor\n    :rtype: pyro.poutine.ScaleMessenger\n\n    Alias for ScaleMessenger constructor.\n\n    Given a stochastic function with some sample statements and a positive\n    scale factor, scale the score of all sample and observe sites in the\n    function.\n    \"\"\"\n    msngr = ScaleMessenger(scale=scale)\n    # XXX temporary compatibility fix\n    return msngr(fn) if callable(fn) else msngr\n\n\ndef indep(fn=None, name=None, size=None, dim=None):\n    \"\"\"\n    Alias for IndepMessenger constructor.\n\n    This messenger keeps track of stack of independence information declared by\n    nested ``irange`` and ``iarange`` contexts. This information is stored in\n    a ``cond_indep_stack`` at each sample/observe site for consumption by\n    ``TraceMessenger``.\n    \"\"\"\n    msngr = IndepMessenger(name=name, size=size, dim=dim)\n    return msngr(fn) if fn is not None else msngr\n\n\ndef enum(fn=None, first_available_dim=None):\n    \"\"\"\n    :param int first_available_dim: The first tensor dimension (counting\n        from the right) that is available for parallel enumeration. This\n        dimension and all dimensions left may be used internally by Pyro.\n\n    Alias for EnumerateMessenger constructor.\n\n    Enumerates in parallel over discrete sample sites marked\n    ``infer={\"enumerate\": \"parallel\"}``.\n    \"\"\"\n    msngr = EnumerateMessenger(first_available_dim=first_available_dim)\n    return msngr(fn) if fn is not None else msngr\n\n\n#########################################\n# Begin composite operations\n#########################################\n\ndef do(fn=None, data=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param data: a dict or a Trace\n    :returns: stochastic function wrapped in a BlockHandler and ConditionHandler\n    :rtype: pyro.poutine.BlockHandler\n\n    Given a stochastic function with some sample statements\n    and a dictionary of values at names,\n    set the return values of those sites equal to the values\n    and hide them from the rest of the stack\n    as if they were hard-coded to those values\n    by using BlockHandler\n    \"\"\"\n    def wrapper(wrapped):\n        return block(condition(wrapped, data=data), hide=list(data.keys()))\n    return wrapper(fn) if fn is not None else wrapper\n\n\ndef queue(fn=None, queue=None, max_tries=None,\n          extend_fn=None, escape_fn=None, num_samples=None):\n    \"\"\"\n    :param fn: a stochastic function (callable containing pyro primitive calls)\n    :param queue: a queue data structure like multiprocessing.Queue to hold partial traces\n    :param max_tries: maximum number of attempts to compute a single complete trace\n    :param extend_fn: function (possibly stochastic) that takes a partial trace and a site,\n        and returns a list of extended traces\n    :param escape_fn: function (possibly stochastic) that takes a partial trace and a site,\n        and returns a boolean value to decide whether to exit\n    :param num_samples: optional number of extended traces for extend_fn to return\n    :returns: stochastic function wrapped in poutine logic\n\n    Given a stochastic function and a queue,\n    return a return value from a complete trace in the queue\n    \"\"\"\n\n    if max_tries is None:\n        max_tries = int(1e6)\n\n    if extend_fn is None:\n        extend_fn = util.enum_extend\n\n    if escape_fn is None:\n        escape_fn = util.discrete_escape\n\n    if num_samples is None:\n        num_samples = -1\n\n    def wrapper(wrapped):\n        def _fn(*args, **kwargs):\n\n            for i in xrange(max_tries):\n                assert not queue.empty(), \\\n                    \"trying to get() from an empty queue will deadlock\"\n\n                next_trace = queue.get()\n                try:\n                    ftr = trace(escape(replay(wrapped, trace=next_trace),\n                                       escape_fn=functools.partial(escape_fn,\n                                                                   next_trace)))\n                    return ftr(*args, **kwargs)\n                except util.NonlocalExit as site_container:\n                    site_container.reset_stack()\n                    for tr in extend_fn(ftr.trace.copy(), site_container.site,\n                                        num_samples=num_samples):\n                        queue.put(tr)\n\n            raise ValueError(\"max tries ({}) exceeded\".format(str(max_tries)))\n        return _fn\n\n    return wrapper(fn) if fn is not None else wrapper\n", "path": "pyro/poutine/__init__.py"}]}