Mercurial > pymonkey
view docs/rendered/pymonkey.html @ 167:b745c9d8eef9
Added docs for pending exception methods.
| author | Atul Varma <varmaa@toolness.com> |
|---|---|
| date | Sun, 30 Aug 2009 20:13:41 -0700 |
| parents | 3fadba042201 |
| children | 68d9e1ed19f8 |
line wrap: on
line source
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>pymonkey — Access SpiderMonkey from Python — Pymonkey v0.0.1 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '0.0.1', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="Pymonkey v0.0.1 documentation" href="index.html" /> <link rel="prev" title="Pymonkey Documentation" href="index.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="modindex.html" title="Global Module Index" accesskey="M">modules</a> |</li> <li class="right" > <a href="index.html" title="Pymonkey Documentation" accesskey="P">previous</a> |</li> <li><a href="index.html">Pymonkey v0.0.1 documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="module-pymonkey"> <h1><tt class="xref docutils literal"><span class="pre">pymonkey</span></tt> — Access SpiderMonkey from Python<a class="headerlink" href="#module-pymonkey" title="Permalink to this headline">¶</a></h1> <p>This module offers a low-level interface to the <a class="reference" href="https://developer.mozilla.org/en/SpiderMonkey">Mozilla SpiderMonkey</a> JavaScript engine.</p> <dl class="exception"> <dt id="pymonkey.error"> <em class="property"> exception </em><tt class="descclassname">pymonkey.</tt><tt class="descname">error</tt><a class="headerlink" href="#pymonkey.error" title="Permalink to this definition">¶</a></dt> <dd>This is the type of any SpiderMonkey-related errors thrown by this module.</dd></dl> <dl class="data"> <dt id="pymonkey.undefined"> <tt class="descclassname">pymonkey.</tt><tt class="descname">undefined</tt><a class="headerlink" href="#pymonkey.undefined" title="Permalink to this definition">¶</a></dt> <dd><p>This is the singleton that represents the JavaScript value <tt class="docutils literal"><span class="pre">undefined</span></tt>, as Python has no equivalent representation (JavaScript’s <tt class="docutils literal"><span class="pre">null</span></tt> is mapped to Python’s <tt class="xref docutils literal"><span class="pre">None</span></tt> object). For instance:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">evaluate_script</span><span class="p">(</span><span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">(),</span> <span class="s">''</span><span class="p">,</span> <span class="s">'<string>'</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span> <span class="go">pymonkey.undefined</span> </pre></div> </div> <p>This object also has a “falsy” value:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">if</span> <span class="ow">not</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">undefined</span><span class="p">:</span> <span class="gp">... </span> <span class="k">print</span> <span class="s">"See, it's falsy!"</span> <span class="go">See, it's falsy!</span> </pre></div> </div> </dd></dl> <dl class="class"> <dt id="pymonkey.Object"> <em class="property"> class </em><tt class="descclassname">pymonkey.</tt><tt class="descname">Object</tt><a class="headerlink" href="#pymonkey.Object" title="Permalink to this definition">¶</a></dt> <dd><p>This is the type of JavaScript objects. Such objects can only be created via Pymonkey calls like <a title="pymonkey.Context.new_object" class="reference" href="#pymonkey.Context.new_object"><tt class="xref docutils literal"><span class="pre">Context.new_object()</span></tt></a> or through the execution of JS code, but this type object can be used with Python’s built-in <tt class="xref docutils literal"><span class="pre">isinstance()</span></tt> to verify that an object is a JS object, like so:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Object</span><span class="p">)</span> <span class="go">True</span> </pre></div> </div> <p>Note that <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a> and all its subclasses are identity-preserving when passed between Python and JavaScript code. For instance:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj1</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj2</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">evaluate_script</span><span class="p">(</span><span class="n">obj1</span><span class="p">,</span> <span class="s">'this'</span><span class="p">,</span> <span class="s">'<string>'</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">obj1</span> <span class="ow">is</span> <span class="n">obj2</span> <span class="go">True</span> </pre></div> </div> <dl class="method"> <dt id="pymonkey.Object.get_runtime"> <tt class="descname">get_runtime</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Object.get_runtime" title="Permalink to this definition">¶</a></dt> <dd>Returns the <a title="pymonkey.Runtime" class="reference" href="#pymonkey.Runtime"><tt class="xref docutils literal"><span class="pre">Runtime</span></tt></a> that the object belongs to.</dd></dl> </dd></dl> <dl class="class"> <dt id="pymonkey.Function"> <em class="property"> class </em><tt class="descclassname">pymonkey.</tt><tt class="descname">Function</tt><a class="headerlink" href="#pymonkey.Function" title="Permalink to this definition">¶</a></dt> <dd><p>This is the type of JavaScript functions, which is a subtype of <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>.</p> <dl class="data"> <dt id="pymonkey.Function.filename"> <tt class="descname">filename</tt><a class="headerlink" href="#pymonkey.Function.filename" title="Permalink to this definition">¶</a></dt> <dd>Name of the file that contains the function’s original JS source code. If the function isn’t a JS function, this value is <tt class="xref docutils literal"><span class="pre">None</span></tt>.</dd></dl> <dl class="data"> <dt id="pymonkey.Function.base_lineno"> <tt class="descname">base_lineno</tt><a class="headerlink" href="#pymonkey.Function.base_lineno" title="Permalink to this definition">¶</a></dt> <dd>The line number at which the function’s JS source code begins.</dd></dl> <dl class="data"> <dt id="pymonkey.Function.line_extent"> <tt class="descname">line_extent</tt><a class="headerlink" href="#pymonkey.Function.line_extent" title="Permalink to this definition">¶</a></dt> <dd>The number of lines comprising the function’s JS source code.</dd></dl> <dl class="data"> <dt id="pymonkey.Function.is_python"> <tt class="descname">is_python</tt><a class="headerlink" href="#pymonkey.Function.is_python" title="Permalink to this definition">¶</a></dt> <dd>Whether or not the function is actually implemented in Python. If it is, you can use <a title="pymonkey.Context.get_object_private" class="reference" href="#pymonkey.Context.get_object_private"><tt class="xref docutils literal"><span class="pre">Context.get_object_private()</span></tt></a> to retrieve this Python function.</dd></dl> </dd></dl> <dl class="class"> <dt id="pymonkey.Script"> <em class="property"> class </em><tt class="descclassname">pymonkey.</tt><tt class="descname">Script</tt><a class="headerlink" href="#pymonkey.Script" title="Permalink to this definition">¶</a></dt> <dd><p>This is the type of compiled JavaScript scripts; it’s actually a subtype of <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>, though when exposed to JS code it doesn’t provide access to any special data or functionality.</p> <p>Script instances have a read-only buffer interface that exposes their bytecode. This can be accessed by passing an instance to Python’s built-in <tt class="docutils literal"><span class="pre">buffer()</span></tt> function.</p> <dl class="data"> <dt id="pymonkey.Script.filename"> <tt class="descname">filename</tt><a class="headerlink" href="#pymonkey.Script.filename" title="Permalink to this definition">¶</a></dt> <dd>The filename of the script’s original source code.</dd></dl> <dl class="data"> <dt id="pymonkey.Script.base_lineno"> <tt class="descname">base_lineno</tt><a class="headerlink" href="#pymonkey.Script.base_lineno" title="Permalink to this definition">¶</a></dt> <dd>The line number at which the script’s original source code begins.</dd></dl> <dl class="data"> <dt id="pymonkey.Script.line_extent"> <tt class="descname">line_extent</tt><a class="headerlink" href="#pymonkey.Script.line_extent" title="Permalink to this definition">¶</a></dt> <dd>The number of lines comprising the original source code.</dd></dl> </dd></dl> <dl class="class"> <dt id="pymonkey.Context"> <em class="property"> class </em><tt class="descclassname">pymonkey.</tt><tt class="descname">Context</tt><a class="headerlink" href="#pymonkey.Context" title="Permalink to this definition">¶</a></dt> <dd><p>This is the type of JavaScript context objects. Contexts can only be created via a call to <a title="pymonkey.Runtime.new_context" class="reference" href="#pymonkey.Runtime.new_context"><tt class="xref docutils literal"><span class="pre">Runtime.new_context()</span></tt></a>, but this type object can be used with Python’s built-in <tt class="xref docutils literal"><span class="pre">isinstance()</span></tt> to verify that an object is a context, like so:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="nb">isinstance</span><span class="p">(</span><span class="n">cx</span><span class="p">,</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Context</span><span class="p">)</span> <span class="go">True</span> </pre></div> </div> <p>JS contexts are weak-referencable.</p> <dl class="method"> <dt id="pymonkey.Context.get_runtime"> <tt class="descname">get_runtime</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Context.get_runtime" title="Permalink to this definition">¶</a></dt> <dd>Returns the <a title="pymonkey.Runtime" class="reference" href="#pymonkey.Runtime"><tt class="xref docutils literal"><span class="pre">Runtime</span></tt></a> that the context belongs to.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.get_stack"> <tt class="descname">get_stack</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Context.get_stack" title="Permalink to this definition">¶</a></dt> <dd><p>Returns a dictionary containing information about the context’s current stack.</p> <p>The dictionary contains the following string keys:</p> <table border="1" class="docutils"> <colgroup> <col width="45%" /> <col width="55%" /> </colgroup> <thead valign="bottom"> <tr><th class="head">key</th> <th class="head">value</th> </tr> </thead> <tbody valign="top"> <tr><td><tt class="xref docutils literal"><span class="pre">script</span></tt></td> <td><a title="pymonkey.Script" class="reference" href="#pymonkey.Script"><tt class="xref docutils literal"><span class="pre">Script</span></tt></a> of the frame. This may be <tt class="xref docutils literal"><span class="pre">None</span></tt> if the frame isn’t a scripted frame, or if it’s not possible to expose the script to Python for some reason.</td> </tr> <tr><td><tt class="xref docutils literal"><span class="pre">lineno</span></tt></td> <td>Line number of the frame, if the frame is scripted.</td> </tr> <tr><td><tt class="xref docutils literal"><span class="pre">pc</span></tt></td> <td>Program counter of the frame; this is an index into the bytecode of the frame’s script, if the frame is scripted.</td> </tr> <tr><td><tt class="xref docutils literal"><span class="pre">function</span></tt></td> <td>The <a title="pymonkey.Function" class="reference" href="#pymonkey.Function"><tt class="xref docutils literal"><span class="pre">Function</span></tt></a> in which the frame is executing, if any.</td> </tr> <tr><td><tt class="xref docutils literal"><span class="pre">caller</span></tt></td> <td>Dictionary containing information about the stack frame of the caller of this frame. If this frame has no caller, this value is <tt class="xref docutils literal"><span class="pre">None</span></tt>.</td> </tr> </tbody> </table> <p>If the context isn’t currently executing any code (i.e., the stack is empty), this method returns <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.new_object"> <tt class="descname">new_object</tt><big>(</big><span class="optional">[</span><em>private_obj</em><span class="optional">]</span><big>)</big><a class="headerlink" href="#pymonkey.Context.new_object" title="Permalink to this definition">¶</a></dt> <dd>Creates a new <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a> instance and returns it. <tt class="docutils literal"><span class="pre">private_obj</span></tt> is any Python object that is privately stored within the new JS object; it can be retrieved using <a title="pymonkey.Context.get_object_private" class="reference" href="#pymonkey.Context.get_object_private"><tt class="xref docutils literal"><span class="pre">get_object_private()</span></tt></a>.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.new_function"> <tt class="descname">new_function</tt><big>(</big><em>func</em>, <em>name</em><big>)</big><a class="headerlink" href="#pymonkey.Context.new_function" title="Permalink to this definition">¶</a></dt> <dd><p>Creates a new <a title="pymonkey.Function" class="reference" href="#pymonkey.Function"><tt class="xref docutils literal"><span class="pre">Function</span></tt></a> instance that wraps the given Python callable. In JS-land, the function will have the given name.</p> <p>When the function is executed from JavaScript, <cite>func</cite> will be passed three positional arguments.</p> <p>The first argument is a <a title="pymonkey.Context" class="reference" href="#pymonkey.Context"><tt class="xref docutils literal"><span class="pre">Context</span></tt></a> that represents the JS context which is calling the function.</p> <p>The second argument is an <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a> that represents the value of <tt class="docutils literal"><span class="pre">this</span></tt> for the duration of the call.</p> <p>The third argument is a tuple containing the arguments passed to the function.</p> <p>For instance:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">add</span><span class="p">(</span><span class="n">cx</span><span class="p">,</span> <span class="n">this</span><span class="p">,</span> <span class="n">args</span><span class="p">):</span> <span class="gp">... </span> <span class="k">return</span> <span class="n">args</span><span class="p">[</span><span class="mf">0</span><span class="p">]</span> <span class="o">+</span> <span class="n">args</span><span class="p">[</span><span class="mf">1</span><span class="p">]</span> <span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">define_property</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'add'</span><span class="p">,</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_function</span><span class="p">(</span><span class="n">add</span><span class="p">,</span> <span class="s">'add'</span><span class="p">))</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">evaluate_script</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'add(1, 1);'</span><span class="p">,</span> <span class="s">'<string>'</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span> <span class="go">2</span> </pre></div> </div> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.define_property"> <tt class="descname">define_property</tt><big>(</big><em>object</em>, <em>name</em>, <em>value</em><big>)</big><a class="headerlink" href="#pymonkey.Context.define_property" title="Permalink to this definition">¶</a></dt> <dd>Creates a new property on <cite>object</cite>, bypassing any JavaScript setters.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.has_property"> <tt class="descname">has_property</tt><big>(</big><em>object</em>, <em>name</em><big>)</big><a class="headerlink" href="#pymonkey.Context.has_property" title="Permalink to this definition">¶</a></dt> <dd>Returns whether or not <cite>object</cite> has the specified property.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.get_property"> <tt class="descname">get_property</tt><big>(</big><em>object</em>, <em>name</em><big>)</big><a class="headerlink" href="#pymonkey.Context.get_property" title="Permalink to this definition">¶</a></dt> <dd><p>Finds the specified property on <cite>object</cite> and returns its value, possibly invoking a JavaScript getter.</p> <p>Example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">define_property</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'beets'</span><span class="p">,</span> <span class="s">'i like beets.'</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">get_property</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'beets'</span><span class="p">)</span> <span class="go">u'i like beets.'</span> </pre></div> </div> <p>Note also that calling this function on undefined properties yields <a title="pymonkey.undefined" class="reference" href="#pymonkey.undefined"><tt class="xref docutils literal"><span class="pre">undefined</span></tt></a>:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">get_property</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'carrots'</span><span class="p">)</span> <span class="go">pymonkey.undefined</span> </pre></div> </div> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.get_object_private"> <tt class="descname">get_object_private</tt><big>(</big><em>object</em><big>)</big><a class="headerlink" href="#pymonkey.Context.get_object_private" title="Permalink to this definition">¶</a></dt> <dd><p>Returns the <tt class="docutils literal"><span class="pre">private_obj</span></tt> passed to <a title="pymonkey.Context.new_object" class="reference" href="#pymonkey.Context.new_object"><tt class="xref docutils literal"><span class="pre">new_object()</span></tt></a> when <cite>object</cite> was first created. If it doesn’t exist, <tt class="xref docutils literal"><span class="pre">None</span></tt> is returned.</p> <p>If <cite>object</cite> was created with <a title="pymonkey.Context.new_function" class="reference" href="#pymonkey.Context.new_function"><tt class="xref docutils literal"><span class="pre">new_function()</span></tt></a>, then this method returns the Python callable wrapped by <cite>object</cite>.</p> <p>This functionality is useful if you want to securely represent Python objects in JS-land.</p> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.clear_object_private"> <tt class="descname">clear_object_private</tt><big>(</big><em>object</em><big>)</big><a class="headerlink" href="#pymonkey.Context.clear_object_private" title="Permalink to this definition">¶</a></dt> <dd><p>Clears the <tt class="docutils literal"><span class="pre">private_obj</span></tt> passed to <a title="pymonkey.Context.new_object" class="reference" href="#pymonkey.Context.new_object"><tt class="xref docutils literal"><span class="pre">new_object()</span></tt></a> when <cite>object</cite> was first created. If it doesn’t exist, this function returns nothing.</p> <p>If <cite>object</cite> was created with <a title="pymonkey.Context.new_function" class="reference" href="#pymonkey.Context.new_function"><tt class="xref docutils literal"><span class="pre">new_function()</span></tt></a>, then this method effectively “unbinds” the Python callable wrapped by <cite>object</cite>. If <cite>object</cite> is later called, an exception will be raised.</p> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.evaluate_script"> <tt class="descname">evaluate_script</tt><big>(</big><em>globalobj</em>, <em>code</em>, <em>filename</em>, <em>lineno</em><big>)</big><a class="headerlink" href="#pymonkey.Context.evaluate_script" title="Permalink to this definition">¶</a></dt> <dd><p>Evaluates the text <cite>code</cite> using <cite>globalobj</cite> as the global object/scope.</p> <p>It’s assumed that <cite>code</cite> is coming from the file named by <cite>filename</cite>; the first line of <cite>code</cite> is assumed to be line number <cite>lineno</cite> of <cite>filename</cite>. This metadata is very useful for debugging stack traces, exceptions, and so forth.</p> <p>For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">init_standard_classes</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">evaluate_script</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'5 * Math'</span><span class="p">,</span> <span class="s">'<string>'</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span> <span class="go">nan</span> </pre></div> </div> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.compile_script"> <tt class="descname">compile_script</tt><big>(</big><em>code</em>, <em>filename</em>, <em>lineno</em><big>)</big><a class="headerlink" href="#pymonkey.Context.compile_script" title="Permalink to this definition">¶</a></dt> <dd><p>Compiles the given string of code and returns a <a title="pymonkey.Script" class="reference" href="#pymonkey.Script"><tt class="xref docutils literal"><span class="pre">Script</span></tt></a> instance that can be executed via <a title="pymonkey.Context.execute_script" class="reference" href="#pymonkey.Context.execute_script"><tt class="xref docutils literal"><span class="pre">execute_script()</span></tt></a>.</p> <p><cite>filename</cite> and <cite>lineno</cite> are used just as in <a title="pymonkey.Context.evaluate_script" class="reference" href="#pymonkey.Context.evaluate_script"><tt class="xref docutils literal"><span class="pre">evaluate_script()</span></tt></a>.</p> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.execute_script"> <tt class="descname">execute_script</tt><big>(</big><em>globalobj</em>, <em>script</em><big>)</big><a class="headerlink" href="#pymonkey.Context.execute_script" title="Permalink to this definition">¶</a></dt> <dd><p>Executes the code in the given <a title="pymonkey.Script" class="reference" href="#pymonkey.Script"><tt class="xref docutils literal"><span class="pre">Script</span></tt></a> object, using <cite>globalobj</cite> as the global object/scope, and returns the result.</p> <p>For example:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">init_standard_classes</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">script</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">compile_script</span><span class="p">(</span><span class="s">'5 * Math'</span><span class="p">,</span> <span class="s">'<string>'</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">execute_script</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="n">script</span><span class="p">)</span> <span class="go">nan</span> </pre></div> </div> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.call_function"> <tt class="descname">call_function</tt><big>(</big><em>thisobj</em>, <em>func</em>, <em>args</em><big>)</big><a class="headerlink" href="#pymonkey.Context.call_function" title="Permalink to this definition">¶</a></dt> <dd><p>Calls a JavaScript function.</p> <p><cite>thisobj</cite> is an <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a> that will be used as the value of <tt class="docutils literal"><span class="pre">this</span></tt> when the function executes, <cite>func</cite> is the <a title="pymonkey.Function" class="reference" href="#pymonkey.Function"><tt class="xref docutils literal"><span class="pre">Function</span></tt></a> to execute, and <cite>args</cite> is a tuple of arguments to pass to the function.</p> <p>For instance:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">obj</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">init_standard_classes</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">Math</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">get_property</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s">'Math'</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">floor</span> <span class="o">=</span> <span class="n">cx</span><span class="o">.</span><span class="n">get_property</span><span class="p">(</span><span class="n">Math</span><span class="p">,</span> <span class="s">'floor'</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">call_function</span><span class="p">(</span><span class="n">Math</span><span class="p">,</span> <span class="n">floor</span><span class="p">,</span> <span class="p">(</span><span class="mf">5.3</span><span class="p">,))</span> <span class="go">5</span> </pre></div> </div> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.init_standard_classes"> <tt class="descname">init_standard_classes</tt><big>(</big><em>object</em><big>)</big><a class="headerlink" href="#pymonkey.Context.init_standard_classes" title="Permalink to this definition">¶</a></dt> <dd>Defines the standard JavaScript classes on the given <a title="pymonkey.Object" class="reference" href="#pymonkey.Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>, such as <tt class="docutils literal"><span class="pre">Array</span></tt>, <tt class="docutils literal"><span class="pre">eval</span></tt>, <tt class="docutils literal"><span class="pre">undefined</span></tt>, and so forth. For more information, see the documentation to <a class="reference" href="https://developer.mozilla.org/en/SpiderMonkey/JSAPI_Reference/JS_InitStandardClasses">JS_InitStandardClasses()</a>, which this method wraps.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.gc"> <tt class="descname">gc</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Context.gc" title="Permalink to this definition">¶</a></dt> <dd>Performs garbage collection on the context’s JavaScript runtime.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.is_exception_pending"> <tt class="descname">is_exception_pending</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Context.is_exception_pending" title="Permalink to this definition">¶</a></dt> <dd>Returns whether an exception is currently being propagated in the context.</dd></dl> <dl class="method"> <dt id="pymonkey.Context.get_pending_exception"> <tt class="descname">get_pending_exception</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Context.get_pending_exception" title="Permalink to this definition">¶</a></dt> <dd><p>Returns the current exception being propagated in the context. If no exception is being propagated, this method returns <tt class="xref docutils literal"><span class="pre">None</span></tt>.</p> <p>If you need to disambiguate between whether <tt class="xref docutils literal"><span class="pre">None</span></tt> is the pending exception or there is no pending exception, use <a title="pymonkey.Context.is_exception_pending" class="reference" href="#pymonkey.Context.is_exception_pending"><tt class="xref docutils literal"><span class="pre">is_exception_pending()</span></tt></a>.</p> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.set_operation_callback"> <tt class="descname">set_operation_callback</tt><big>(</big><em>func</em><big>)</big><a class="headerlink" href="#pymonkey.Context.set_operation_callback" title="Permalink to this definition">¶</a></dt> <dd><p>Sets the operation callback for the context to the given Python callable. The callback can be triggered via <a title="pymonkey.Context.trigger_operation_callback" class="reference" href="#pymonkey.Context.trigger_operation_callback"><tt class="xref docutils literal"><span class="pre">trigger_operation_callback()</span></tt></a>.</p> <p><cite>func</cite> takes one argument: the context that triggered it.</p> </dd></dl> <dl class="method"> <dt id="pymonkey.Context.trigger_operation_callback"> <tt class="descname">trigger_operation_callback</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Context.trigger_operation_callback" title="Permalink to this definition">¶</a></dt> <dd><p>Triggers the context’s operation callback. If no callback has yet been set, this function does nothing.</p> <p>This function is one of the few thread-safe functions available to a JS runtime, and together with <a title="pymonkey.Context.set_operation_callback" class="reference" href="#pymonkey.Context.set_operation_callback"><tt class="xref docutils literal"><span class="pre">set_operation_callback()</span></tt></a> can be used to abort the execution of long-running code.</p> <p>For instance, we first create an operation callback to stop long-running code by throwing an exception:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">import</span> <span class="nn">time</span><span class="o">,</span> <span class="nn">threading</span> <span class="gp">>>> </span><span class="n">cx</span> <span class="o">=</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">Runtime</span><span class="p">()</span><span class="o">.</span><span class="n">new_context</span><span class="p">()</span> <span class="gp">>>> </span><span class="k">def</span> <span class="nf">stop_running_code</span><span class="p">(</span><span class="n">cx</span><span class="p">):</span> <span class="gp">... </span> <span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s">'JS took too long to execute.'</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">cx</span><span class="o">.</span><span class="n">set_operation_callback</span><span class="p">(</span><span class="n">stop_running_code</span><span class="p">)</span> </pre></div> </div> <p>Then we create a watchdog thread to trigger the operation callback once a long amount of time has passed:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">def</span> <span class="nf">watchdog_thread</span><span class="p">():</span> <span class="gp">... </span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mf">0.1</span><span class="p">)</span> <span class="c"># An eternity to a computer!</span> <span class="gp">... </span> <span class="n">cx</span><span class="o">.</span><span class="n">trigger_operation_callback</span><span class="p">()</span> <span class="gp">>>> </span><span class="n">thread</span> <span class="o">=</span> <span class="n">threading</span><span class="o">.</span><span class="n">Thread</span><span class="p">(</span><span class="n">target</span><span class="o">=</span><span class="n">watchdog_thread</span><span class="p">)</span> <span class="gp">>>> </span><span class="n">thread</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> </pre></div> </div> <p>Now, when we execute code that takes too long to run, it gets aborted:</p> <div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="k">try</span><span class="p">:</span> <span class="gp">... </span> <span class="n">cx</span><span class="o">.</span><span class="n">evaluate_script</span><span class="p">(</span><span class="n">cx</span><span class="o">.</span><span class="n">new_object</span><span class="p">(),</span> <span class="s">'while (1) {}'</span><span class="p">,</span> <span class="gp">... </span> <span class="s">'<string>'</span><span class="p">,</span> <span class="mf">1</span><span class="p">)</span> <span class="gp">... </span><span class="k">except</span> <span class="n">pymonkey</span><span class="o">.</span><span class="n">error</span><span class="p">,</span> <span class="n">e</span><span class="p">:</span> <span class="gp">... </span> <span class="k">print</span> <span class="n">cx</span><span class="o">.</span><span class="n">get_object_private</span><span class="p">(</span><span class="n">e</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="mf">0</span><span class="p">])</span> <span class="go">JS took too long to execute.</span> </pre></div> </div> </dd></dl> </dd></dl> <dl class="class"> <dt id="pymonkey.Runtime"> <em class="property"> class </em><tt class="descclassname">pymonkey.</tt><tt class="descname">Runtime</tt><a class="headerlink" href="#pymonkey.Runtime" title="Permalink to this definition">¶</a></dt> <dd><p>Creates a new JavaScript runtime. JS objects created by the runtime may only interact with other JS objects of the same runtime.</p> <p>With few exceptions, objects belonging to a runtime can currently only be used in the same thread that the runtime was created in. This may be changed in the future, since SpiderMonkey itself has support for thread safety.</p> <p>JS runtimes are weak-referencable.</p> <dl class="method"> <dt id="pymonkey.Runtime.new_context"> <tt class="descname">new_context</tt><big>(</big><big>)</big><a class="headerlink" href="#pymonkey.Runtime.new_context" title="Permalink to this definition">¶</a></dt> <dd>Creates a new Context object and returns it. Contexts are best conceptualized as threads of execution in a JS runtme; each one has a program counter, a current exception state, and so forth. JS objects may be freely accessed and changed by contexts that are associated with the same JS runtime as the objects.</dd></dl> </dd></dl> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h4>Previous topic</h4> <p class="topless"><a href="index.html" title="previous chapter">Pymonkey Documentation</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/pymonkey.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="modindex.html" title="Global Module Index" >modules</a> |</li> <li class="right" > <a href="index.html" title="Pymonkey Documentation" >previous</a> |</li> <li><a href="index.html">Pymonkey v0.0.1 documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2009, Atul Varma. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.2. </div> </body> </html>