# HG changeset patch # User Atul Varma # Date 1251799644 25200 # Node ID dd32a92f6b4f7bee1e20f805d8b2fc643d98ee84 # Parent 2b98d4643c447804979aa07789f9e70a5913de0c Initial attempt at renaming pymonkey to pydermonkey. diff -r 2b98d4643c44 -r dd32a92f6b4f README --- a/README Sun Aug 30 20:56:43 2009 -0700 +++ b/README Tue Sep 01 03:07:24 2009 -0700 @@ -1,8 +1,8 @@ -Pymonkey README +Pydermonkey README --------------- -Pymonkey is a Python C extension module to expose the Mozilla +Pydermonkey is a Python C extension module to expose the Mozilla SpiderMonkey engine to Python. -Please run "python setup.py docs" to open the full Pymonkey +Please run "python setup.py docs" to open the full Pydermonkey documentation in your web browser. diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/_sources/index.txt --- a/docs/rendered/_sources/index.txt Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/rendered/_sources/index.txt Tue Sep 01 03:07:24 2009 -0700 @@ -1,20 +1,20 @@ -.. Pymonkey documentation master file, created by +.. Pydermonkey documentation master file, created by sphinx-quickstart on Mon Jul 6 17:20:31 2009. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. ====================== -Pymonkey Documentation +Pydermonkey Documentation ====================== -Pymonkey is a Python C extension module to expose the `Mozilla +Pydermonkey is a Python C extension module to expose the `Mozilla SpiderMonkey `_ engine to Python. .. toctree:: :maxdepth: 2 - pymonkey + pydermonkey Rationale and Goals: @@ -34,17 +34,17 @@ `_ are currently paving the way in this field. There's Java-based solutions like Rhino out there, but nothing really mature is available for the Python - world. Ideally, Pymonkey should enable a Python programmer to create + world. Ideally, Pydermonkey should enable a Python programmer to create a custom sandboxed environment for executing JS code without needing to write any C. -* Pymonkey should have awesome Sphinx documentation with doctests and +* Pydermonkey should have awesome Sphinx documentation with doctests and all the trappings of a model Python package. Not only should it be easy for Python programmers to learn how to use the module, but it should also be easy for them to learn more about how SpiderMonkey works by reading the documentation and playing around with the code. -* Pymonkey needs to have outstanding developer ergonomics. Full +* Pydermonkey needs to have outstanding developer ergonomics. Full cross-language stack tracebacks should be available, for instance, and developers should be able to easily debug. Access to memory profiling facilities in JS-land is a must. @@ -69,7 +69,7 @@ Building, Testing, and Installing ================================= -From the root of your pymonkey repository, run:: +From the root of your pydermonkey repository, run:: python setup.py build test @@ -86,7 +86,7 @@ ========== There's a number of challenges that need to be resolved before -pymonkey can be really usable. Here's some of them. +pydermonkey can be really usable. Here's some of them. **Garbage Collection** @@ -100,7 +100,7 @@ `_. For the time being, however, such cycles can be manually broken via -:meth:`pymonkey.Context.clear_object_private()` on valid objects and functions. +:meth:`pydermonkey.Context.clear_object_private()` on valid objects and functions. Indices and Tables ================== diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/_sources/pydermonkey.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/rendered/_sources/pydermonkey.txt Tue Sep 01 03:07:24 2009 -0700 @@ -0,0 +1,446 @@ +:mod:`pydermonkey` --- Access SpiderMonkey from Python +=================================================== + +.. module:: pydermonkey + :synopsis: Access SpiderMonkey from Python + +.. testsetup:: * + + import pydermonkey + +This module offers a low-level interface to the `Mozilla SpiderMonkey +`_ JavaScript engine. + +.. exception:: error + + This is the type of any SpiderMonkey-related errors thrown by this + module. + + If the error is a wrapped JavaScript exception, the first argument + will be the thrown JS exception, and the second argument will be + the JS exception converted to a string. Otherwise, the error + will only contain a descriptive string argument. + + For example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> cx.evaluate_script(cx.new_object(), 'throw 1', '', 1) + Traceback (most recent call last): + ... + error: (1, u'1') + +.. data:: undefined + + This is the singleton that represents the JavaScript value + ``undefined``, as Python has no equivalent representation + (JavaScript's ``null`` is mapped to Python's ``None`` object). + For instance: + + >>> cx = pydermonkey.Runtime().new_context() + >>> cx.evaluate_script(cx.new_object(), '', '', 1) + pydermonkey.undefined + + This object also has a "falsy" value: + + >>> if not pydermonkey.undefined: + ... print "See, it's falsy!" + See, it's falsy! + +.. class:: Object + + This is the type of JavaScript objects. Such objects can only be + created via Pydermonkey calls like :meth:`Context.new_object()` or + through the execution of JS code, but this type object can be used + with Python's built-in :func:`isinstance()` to verify that an + object is a JS object, like so: + + >>> obj = pydermonkey.Runtime().new_context().new_object() + >>> isinstance(obj, pydermonkey.Object) + True + + Note that :class:`Object` and all its subclasses are + identity-preserving when passed between Python and + JavaScript code. For instance: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj1 = cx.new_object() + >>> obj2 = cx.evaluate_script(obj1, 'this', '', 1) + >>> obj1 is obj2 + True + + .. method:: get_runtime() + + Returns the :class:`Runtime` that the object belongs to. + +.. class:: Function + + This is the type of JavaScript functions, which is a subtype of + :class:`Object`. + + .. data:: filename + + Name of the file that contains the function's original JS source + code. If the function isn't a JS function, this value is + ``None``. + + .. data:: base_lineno + + The line number at which the function's JS source code begins. + + .. data:: line_extent + + The number of lines comprising the function's JS source code. + + .. data:: is_python + + Whether or not the function is actually implemented in Python. + If it is, you can use :meth:`Context.get_object_private()` to + retrieve this Python function. + +.. class:: Script + + This is the type of compiled JavaScript scripts; it's actually a + subtype of :class:`Object`, though when exposed to JS code it + doesn't provide access to any special data or functionality. + + 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 ``buffer()`` function. + + .. data:: filename + + The filename of the script's original source code. + + .. data:: base_lineno + + The line number at which the script's original source code + begins. + + .. data:: line_extent + + The number of lines comprising the original source code. + +.. class:: Context + + This is the type of JavaScript context objects. Contexts can only + be created via a call to :meth:`Runtime.new_context()`, but this + type object can be used with Python's built-in :func:`isinstance()` + to verify that an object is a context, like so: + + >>> cx = pydermonkey.Runtime().new_context() + >>> isinstance(cx, pydermonkey.Context) + True + + JS contexts are weak-referencable. + + .. method:: get_runtime() + + Returns the :class:`Runtime` that the context belongs to. + + .. method:: get_stack() + + Returns a dictionary containing information about the context's + current stack. + + The dictionary contains the following string keys: + + +------------------------------+-------------------------------------+ + | key | value | + +==============================+=====================================+ + | :const:`script` | :class:`Script` of the frame. | + | | This may be ``None`` if the frame | + | | isn't a scripted frame, or if it's | + | | not possible to expose the script | + | | to Python for some reason. | + +------------------------------+-------------------------------------+ + | :const:`lineno` | Line number of the frame, if the | + | | frame is scripted. | + +------------------------------+-------------------------------------+ + | :const:`pc` | Program counter of the frame; this | + | | is an index into the bytecode of | + | | the frame's script, if the frame | + | | is scripted. | + +------------------------------+-------------------------------------+ + | :const:`function` | The :class:`Function` in which the | + | | frame is executing, if any. | + +------------------------------+-------------------------------------+ + | :const:`caller` | Dictionary containing information | + | | about the stack frame of the | + | | caller of this frame. If this frame | + | | has no caller, this value is | + | | ``None``. | + +------------------------------+-------------------------------------+ + + If the context isn't currently executing any code (i.e., the stack + is empty), this method returns ``None``. + + .. method:: new_object([private_obj]) + + Creates a new :class:`Object` instance and returns + it. ``private_obj`` is any Python object that is privately + stored within the new JS object; it can be retrieved using + :meth:`get_object_private()`. + + .. method:: new_function(func, name) + + Creates a new :class:`Function` instance that wraps the + given Python callable. In JS-land, the function will + have the given name. + + When the function is executed from JavaScript, `func` + will be passed three positional arguments. + + The first argument is a :class:`Context` that represents the + JS context which is calling the function. + + The second argument is an :class:`Object` that represents the + value of ``this`` for the duration of the call. + + The third argument is a tuple containing the arguments + passed to the function. + + For instance: + + >>> def add(cx, this, args): + ... return args[0] + args[1] + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.define_property(obj, 'add', cx.new_function(add, 'add')) + >>> cx.evaluate_script(obj, 'add(1, 1);', '', 1) + 2 + + .. method:: define_property(object, name, value) + + Creates a new property on `object`, bypassing any JavaScript setters. + + .. method:: has_property(object, name) + + Returns whether or not `object` has the specified property. + + .. method:: get_property(object, name) + + Finds the specified property on `object` and returns its value, + possibly invoking a JavaScript getter. + + Example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.define_property(obj, 'beets', 'i like beets.') + >>> cx.get_property(obj, 'beets') + u'i like beets.' + + Note also that calling this function on undefined properties + yields :data:`undefined`: + + >>> cx.get_property(obj, 'carrots') + pydermonkey.undefined + + .. method:: get_object_private(object) + + Returns the ``private_obj`` passed to :meth:`new_object()` + when `object` was first created. If it doesn't exist, ``None`` + is returned. + + If `object` was created with :meth:`new_function()`, then this + method returns the Python callable wrapped by `object`. + + This functionality is useful if you want to securely represent + Python objects in JS-land. + + .. method:: clear_object_private(object) + + Clears the ``private_obj`` passed to :meth:`new_object()` + when `object` was first created. If it doesn't exist, this + function returns nothing. + + If `object` was created with :meth:`new_function()`, then this + method effectively "unbinds" the Python callable wrapped by + `object`. If `object` is later called, an exception will be + raised. + + .. method:: evaluate_script(globalobj, code, filename, lineno) + + Evaluates the text `code` using `globalobj` as the global + object/scope. + + It's assumed that `code` is coming from the file named by `filename`; + the first line of `code` is assumed to be line number `lineno` of + `filename`. This metadata is very useful for debugging stack traces, + exceptions, and so forth. + + For example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.init_standard_classes(obj) + >>> cx.evaluate_script(obj, '5 * Math', '', 1) + nan + + .. method:: compile_script(code, filename, lineno) + + Compiles the given string of code and returns a :class:`Script` + instance that can be executed via :meth:`execute_script()`. + + `filename` and `lineno` are used just as in + :meth:`evaluate_script()`. + + .. method:: execute_script(globalobj, script) + + Executes the code in the given :class:`Script` object, using + `globalobj` as the global object/scope, and returns the result. + + For example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.init_standard_classes(obj) + >>> script = cx.compile_script('5 * Math', '', 1) + >>> cx.execute_script(obj, script) + nan + + .. method:: call_function(thisobj, func, args) + + Calls a JavaScript function. + + `thisobj` is an :class:`Object` that will be used as the value + of ``this`` when the function executes, `func` is the + :class:`Function` to execute, and `args` is a tuple of arguments + to pass to the function. + + For instance: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.init_standard_classes(obj) + >>> Math = cx.get_property(obj, 'Math') + >>> floor = cx.get_property(Math, 'floor') + >>> cx.call_function(Math, floor, (5.3,)) + 5 + + .. method:: init_standard_classes(object) + + Defines the standard JavaScript classes on the given + :class:`Object`, such as ``Array``, ``eval``, ``undefined``, and + so forth. For more information, see the documentation to + `JS_InitStandardClasses() + `_, + which this method wraps. + + .. method:: gc() + + Performs garbage collection on the context's JavaScript runtime. + + .. method:: is_exception_pending() + + Returns whether an exception is currently being propagated in + the context. + + .. method:: get_pending_exception() + + Returns the current exception being propagated in the context. If + no exception is being propagated, this method returns ``None``. + + If you need to disambiguate between whether ``None`` is the + pending exception or there is no pending exception, use + :meth:`is_exception_pending()`. + + .. method:: set_throw_hook(func) + + Sets the throw hook for the context to the given Python callable. + The hook is triggered whenever an exception is thrown in the + context. + + `func` takes one argument: the context that triggered it. + + For example, here's a throw hook that prints information about + an exception as it's being propagated through the stack: + + >>> def throwhook(cx): + ... stack = cx.get_stack() + ... if stack['function']: + ... where = stack['function'].name + ... else: + ... where = stack['script'].filename + ... exc = cx.get_pending_exception() + ... print "%s being thrown in %s" % (exc, where) + + Here's the hook in action: + + >>> cx = pydermonkey.Runtime().new_context() + >>> cx.set_throw_hook(throwhook) + >>> obj = cx.new_object() + >>> code = "(function foo() { throw 'oops' })()" + >>> try: + ... cx.evaluate_script(obj, code, '', 1) + ... except pydermonkey.error, e: + ... print "caught %s" % e.args[0] + oops being thrown in foo + oops being thrown in + caught oops + + .. method:: set_operation_callback(func) + + Sets the operation callback for the context to the given Python + callable. The callback can be triggered via + :meth:`trigger_operation_callback()`. + + `func` takes one argument: the context that triggered it. + + .. method:: trigger_operation_callback() + + Triggers the context's operation callback. If no callback has + yet been set, this function does nothing. + + This function is one of the few thread-safe functions available + to a JS runtime, and together with + :meth:`set_operation_callback()` can be used to abort the + execution of long-running code. + + For instance, we first create an operation callback to stop + long-running code by throwing an exception: + + >>> import time, threading + >>> cx = pydermonkey.Runtime().new_context() + >>> def stop_running_code(cx): + ... raise Exception('JS took too long to execute.') + >>> cx.set_operation_callback(stop_running_code) + + Then we create a watchdog thread to trigger the operation + callback once a long amount of time has passed: + + >>> def watchdog_thread(): + ... time.sleep(0.1) # An eternity to a computer! + ... cx.trigger_operation_callback() + >>> thread = threading.Thread(target=watchdog_thread) + >>> thread.start() + + Now, when we execute code that takes too long to run, it gets + aborted: + + >>> try: + ... cx.evaluate_script(cx.new_object(), 'while (1) {}', + ... '', 1) + ... except pydermonkey.error, e: + ... print cx.get_object_private(e.args[0]) + JS took too long to execute. + +.. class:: Runtime() + + Creates a new JavaScript runtime. JS objects created by the runtime + may only interact with other JS objects of the same runtime. + + 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. + + JS runtimes are weak-referencable. + + .. method:: new_context() + + 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. diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/_sources/pymonkey.txt --- a/docs/rendered/_sources/pymonkey.txt Sun Aug 30 20:56:43 2009 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,446 +0,0 @@ -:mod:`pymonkey` --- Access SpiderMonkey from Python -=================================================== - -.. module:: pymonkey - :synopsis: Access SpiderMonkey from Python - -.. testsetup:: * - - import pymonkey - -This module offers a low-level interface to the `Mozilla SpiderMonkey -`_ JavaScript engine. - -.. exception:: error - - This is the type of any SpiderMonkey-related errors thrown by this - module. - - If the error is a wrapped JavaScript exception, the first argument - will be the thrown JS exception, and the second argument will be - the JS exception converted to a string. Otherwise, the error - will only contain a descriptive string argument. - - For example: - - >>> cx = pymonkey.Runtime().new_context() - >>> cx.evaluate_script(cx.new_object(), 'throw 1', '', 1) - Traceback (most recent call last): - ... - error: (1, u'1') - -.. data:: undefined - - This is the singleton that represents the JavaScript value - ``undefined``, as Python has no equivalent representation - (JavaScript's ``null`` is mapped to Python's ``None`` object). - For instance: - - >>> cx = pymonkey.Runtime().new_context() - >>> cx.evaluate_script(cx.new_object(), '', '', 1) - pymonkey.undefined - - This object also has a "falsy" value: - - >>> if not pymonkey.undefined: - ... print "See, it's falsy!" - See, it's falsy! - -.. class:: Object - - This is the type of JavaScript objects. Such objects can only be - created via Pymonkey calls like :meth:`Context.new_object()` or - through the execution of JS code, but this type object can be used - with Python's built-in :func:`isinstance()` to verify that an - object is a JS object, like so: - - >>> obj = pymonkey.Runtime().new_context().new_object() - >>> isinstance(obj, pymonkey.Object) - True - - Note that :class:`Object` and all its subclasses are - identity-preserving when passed between Python and - JavaScript code. For instance: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj1 = cx.new_object() - >>> obj2 = cx.evaluate_script(obj1, 'this', '', 1) - >>> obj1 is obj2 - True - - .. method:: get_runtime() - - Returns the :class:`Runtime` that the object belongs to. - -.. class:: Function - - This is the type of JavaScript functions, which is a subtype of - :class:`Object`. - - .. data:: filename - - Name of the file that contains the function's original JS source - code. If the function isn't a JS function, this value is - ``None``. - - .. data:: base_lineno - - The line number at which the function's JS source code begins. - - .. data:: line_extent - - The number of lines comprising the function's JS source code. - - .. data:: is_python - - Whether or not the function is actually implemented in Python. - If it is, you can use :meth:`Context.get_object_private()` to - retrieve this Python function. - -.. class:: Script - - This is the type of compiled JavaScript scripts; it's actually a - subtype of :class:`Object`, though when exposed to JS code it - doesn't provide access to any special data or functionality. - - 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 ``buffer()`` function. - - .. data:: filename - - The filename of the script's original source code. - - .. data:: base_lineno - - The line number at which the script's original source code - begins. - - .. data:: line_extent - - The number of lines comprising the original source code. - -.. class:: Context - - This is the type of JavaScript context objects. Contexts can only - be created via a call to :meth:`Runtime.new_context()`, but this - type object can be used with Python's built-in :func:`isinstance()` - to verify that an object is a context, like so: - - >>> cx = pymonkey.Runtime().new_context() - >>> isinstance(cx, pymonkey.Context) - True - - JS contexts are weak-referencable. - - .. method:: get_runtime() - - Returns the :class:`Runtime` that the context belongs to. - - .. method:: get_stack() - - Returns a dictionary containing information about the context's - current stack. - - The dictionary contains the following string keys: - - +------------------------------+-------------------------------------+ - | key | value | - +==============================+=====================================+ - | :const:`script` | :class:`Script` of the frame. | - | | This may be ``None`` if the frame | - | | isn't a scripted frame, or if it's | - | | not possible to expose the script | - | | to Python for some reason. | - +------------------------------+-------------------------------------+ - | :const:`lineno` | Line number of the frame, if the | - | | frame is scripted. | - +------------------------------+-------------------------------------+ - | :const:`pc` | Program counter of the frame; this | - | | is an index into the bytecode of | - | | the frame's script, if the frame | - | | is scripted. | - +------------------------------+-------------------------------------+ - | :const:`function` | The :class:`Function` in which the | - | | frame is executing, if any. | - +------------------------------+-------------------------------------+ - | :const:`caller` | Dictionary containing information | - | | about the stack frame of the | - | | caller of this frame. If this frame | - | | has no caller, this value is | - | | ``None``. | - +------------------------------+-------------------------------------+ - - If the context isn't currently executing any code (i.e., the stack - is empty), this method returns ``None``. - - .. method:: new_object([private_obj]) - - Creates a new :class:`Object` instance and returns - it. ``private_obj`` is any Python object that is privately - stored within the new JS object; it can be retrieved using - :meth:`get_object_private()`. - - .. method:: new_function(func, name) - - Creates a new :class:`Function` instance that wraps the - given Python callable. In JS-land, the function will - have the given name. - - When the function is executed from JavaScript, `func` - will be passed three positional arguments. - - The first argument is a :class:`Context` that represents the - JS context which is calling the function. - - The second argument is an :class:`Object` that represents the - value of ``this`` for the duration of the call. - - The third argument is a tuple containing the arguments - passed to the function. - - For instance: - - >>> def add(cx, this, args): - ... return args[0] + args[1] - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.define_property(obj, 'add', cx.new_function(add, 'add')) - >>> cx.evaluate_script(obj, 'add(1, 1);', '', 1) - 2 - - .. method:: define_property(object, name, value) - - Creates a new property on `object`, bypassing any JavaScript setters. - - .. method:: has_property(object, name) - - Returns whether or not `object` has the specified property. - - .. method:: get_property(object, name) - - Finds the specified property on `object` and returns its value, - possibly invoking a JavaScript getter. - - Example: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.define_property(obj, 'beets', 'i like beets.') - >>> cx.get_property(obj, 'beets') - u'i like beets.' - - Note also that calling this function on undefined properties - yields :data:`undefined`: - - >>> cx.get_property(obj, 'carrots') - pymonkey.undefined - - .. method:: get_object_private(object) - - Returns the ``private_obj`` passed to :meth:`new_object()` - when `object` was first created. If it doesn't exist, ``None`` - is returned. - - If `object` was created with :meth:`new_function()`, then this - method returns the Python callable wrapped by `object`. - - This functionality is useful if you want to securely represent - Python objects in JS-land. - - .. method:: clear_object_private(object) - - Clears the ``private_obj`` passed to :meth:`new_object()` - when `object` was first created. If it doesn't exist, this - function returns nothing. - - If `object` was created with :meth:`new_function()`, then this - method effectively "unbinds" the Python callable wrapped by - `object`. If `object` is later called, an exception will be - raised. - - .. method:: evaluate_script(globalobj, code, filename, lineno) - - Evaluates the text `code` using `globalobj` as the global - object/scope. - - It's assumed that `code` is coming from the file named by `filename`; - the first line of `code` is assumed to be line number `lineno` of - `filename`. This metadata is very useful for debugging stack traces, - exceptions, and so forth. - - For example: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.init_standard_classes(obj) - >>> cx.evaluate_script(obj, '5 * Math', '', 1) - nan - - .. method:: compile_script(code, filename, lineno) - - Compiles the given string of code and returns a :class:`Script` - instance that can be executed via :meth:`execute_script()`. - - `filename` and `lineno` are used just as in - :meth:`evaluate_script()`. - - .. method:: execute_script(globalobj, script) - - Executes the code in the given :class:`Script` object, using - `globalobj` as the global object/scope, and returns the result. - - For example: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.init_standard_classes(obj) - >>> script = cx.compile_script('5 * Math', '', 1) - >>> cx.execute_script(obj, script) - nan - - .. method:: call_function(thisobj, func, args) - - Calls a JavaScript function. - - `thisobj` is an :class:`Object` that will be used as the value - of ``this`` when the function executes, `func` is the - :class:`Function` to execute, and `args` is a tuple of arguments - to pass to the function. - - For instance: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.init_standard_classes(obj) - >>> Math = cx.get_property(obj, 'Math') - >>> floor = cx.get_property(Math, 'floor') - >>> cx.call_function(Math, floor, (5.3,)) - 5 - - .. method:: init_standard_classes(object) - - Defines the standard JavaScript classes on the given - :class:`Object`, such as ``Array``, ``eval``, ``undefined``, and - so forth. For more information, see the documentation to - `JS_InitStandardClasses() - `_, - which this method wraps. - - .. method:: gc() - - Performs garbage collection on the context's JavaScript runtime. - - .. method:: is_exception_pending() - - Returns whether an exception is currently being propagated in - the context. - - .. method:: get_pending_exception() - - Returns the current exception being propagated in the context. If - no exception is being propagated, this method returns ``None``. - - If you need to disambiguate between whether ``None`` is the - pending exception or there is no pending exception, use - :meth:`is_exception_pending()`. - - .. method:: set_throw_hook(func) - - Sets the throw hook for the context to the given Python callable. - The hook is triggered whenever an exception is thrown in the - context. - - `func` takes one argument: the context that triggered it. - - For example, here's a throw hook that prints information about - an exception as it's being propagated through the stack: - - >>> def throwhook(cx): - ... stack = cx.get_stack() - ... if stack['function']: - ... where = stack['function'].name - ... else: - ... where = stack['script'].filename - ... exc = cx.get_pending_exception() - ... print "%s being thrown in %s" % (exc, where) - - Here's the hook in action: - - >>> cx = pymonkey.Runtime().new_context() - >>> cx.set_throw_hook(throwhook) - >>> obj = cx.new_object() - >>> code = "(function foo() { throw 'oops' })()" - >>> try: - ... cx.evaluate_script(obj, code, '', 1) - ... except pymonkey.error, e: - ... print "caught %s" % e.args[0] - oops being thrown in foo - oops being thrown in - caught oops - - .. method:: set_operation_callback(func) - - Sets the operation callback for the context to the given Python - callable. The callback can be triggered via - :meth:`trigger_operation_callback()`. - - `func` takes one argument: the context that triggered it. - - .. method:: trigger_operation_callback() - - Triggers the context's operation callback. If no callback has - yet been set, this function does nothing. - - This function is one of the few thread-safe functions available - to a JS runtime, and together with - :meth:`set_operation_callback()` can be used to abort the - execution of long-running code. - - For instance, we first create an operation callback to stop - long-running code by throwing an exception: - - >>> import time, threading - >>> cx = pymonkey.Runtime().new_context() - >>> def stop_running_code(cx): - ... raise Exception('JS took too long to execute.') - >>> cx.set_operation_callback(stop_running_code) - - Then we create a watchdog thread to trigger the operation - callback once a long amount of time has passed: - - >>> def watchdog_thread(): - ... time.sleep(0.1) # An eternity to a computer! - ... cx.trigger_operation_callback() - >>> thread = threading.Thread(target=watchdog_thread) - >>> thread.start() - - Now, when we execute code that takes too long to run, it gets - aborted: - - >>> try: - ... cx.evaluate_script(cx.new_object(), 'while (1) {}', - ... '', 1) - ... except pymonkey.error, e: - ... print cx.get_object_private(e.args[0]) - JS took too long to execute. - -.. class:: Runtime() - - Creates a new JavaScript runtime. JS objects created by the runtime - may only interact with other JS objects of the same runtime. - - 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. - - JS runtimes are weak-referencable. - - .. method:: new_context() - - 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. diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/genindex.html --- a/docs/rendered/genindex.html Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/rendered/genindex.html Tue Sep 01 03:07:24 2009 -0700 @@ -5,7 +5,7 @@ - Index — Pymonkey v0.0.1 documentation + Index — Pydermonkey v0.0.1 documentation - +
@@ -31,7 +31,7 @@
  • modules |
    • -
  • Pymonkey v0.0.1 documentation »
    • +
  • Pydermonkey v0.0.1 documentation »
    • @@ -52,123 +52,123 @@
    -
    call_function() (pymonkey.Context method)
    -
    clear_object_private() (pymonkey.Context method)
    -
    compile_script() (pymonkey.Context method)
    -
    Context (class in pymonkey)
    +
    call_function() (pydermonkey.Context method)
    +
    clear_object_private() (pydermonkey.Context method)
    +
    compile_script() (pydermonkey.Context method)
    +
    Context (class in pydermonkey)

    D

    -
    define_property() (pymonkey.Context method)
    +
    define_property() (pydermonkey.Context method)

    E

    -
    error
    -
    evaluate_script() (pymonkey.Context method)
    -
    execute_script() (pymonkey.Context method)
    +
    error
    +
    evaluate_script() (pydermonkey.Context method)
    +
    execute_script() (pydermonkey.Context method)

    F

    -
    Function (class in pymonkey)
    -
    Function.base_lineno (in module pymonkey)
    -
    Function.filename (in module pymonkey)
    -
    Function.is_python (in module pymonkey)
    -
    Function.line_extent (in module pymonkey)
    +
    Function (class in pydermonkey)
    +
    Function.base_lineno (in module pydermonkey)
    +
    Function.filename (in module pydermonkey)
    +
    Function.is_python (in module pydermonkey)
    +
    Function.line_extent (in module pydermonkey)

    G

    -
    gc() (pymonkey.Context method)
    -
    get_object_private() (pymonkey.Context method)
    -
    get_pending_exception() (pymonkey.Context method)
    -
    get_property() (pymonkey.Context method)
    -
    get_runtime() (pymonkey.Context method)
    +
    gc() (pydermonkey.Context method)
    +
    get_object_private() (pydermonkey.Context method)
    +
    get_pending_exception() (pydermonkey.Context method)
    +
    get_property() (pydermonkey.Context method)
    +
    get_runtime() (pydermonkey.Context method)
    -
    (pymonkey.Object method)
    +
    (pydermonkey.Object method)
    -
    get_stack() (pymonkey.Context method)
    +
    get_stack() (pydermonkey.Context method)

    H

    -
    has_property() (pymonkey.Context method)
    +
    has_property() (pydermonkey.Context method)

    I

    -
    init_standard_classes() (pymonkey.Context method)
    -
    is_exception_pending() (pymonkey.Context method)
    +
    init_standard_classes() (pydermonkey.Context method)
    +
    is_exception_pending() (pydermonkey.Context method)

    N

    -
    new_context() (pymonkey.Runtime method)
    -
    new_function() (pymonkey.Context method)
    -
    new_object() (pymonkey.Context method)
    +
    new_context() (pydermonkey.Runtime method)
    +
    new_function() (pydermonkey.Context method)
    +
    new_object() (pydermonkey.Context method)

    O

    -
    Object (class in pymonkey)
    +
    Object (class in pydermonkey)

    P

    -
    pymonkey (module)
    +
    pydermonkey (module)

    R

    -
    Runtime (class in pymonkey)
    +
    Runtime (class in pydermonkey)

    S

    -
    Script (class in pymonkey)
    -
    Script.base_lineno (in module pymonkey)
    -
    Script.filename (in module pymonkey)
    -
    Script.line_extent (in module pymonkey)
    -
    set_operation_callback() (pymonkey.Context method)
    -
    set_throw_hook() (pymonkey.Context method)
    +
    Script (class in pydermonkey)
    +
    Script.base_lineno (in module pydermonkey)
    +
    Script.filename (in module pydermonkey)
    +
    Script.line_extent (in module pydermonkey)
    +
    set_operation_callback() (pydermonkey.Context method)
    +
    set_throw_hook() (pydermonkey.Context method)

    T

    -
    trigger_operation_callback() (pymonkey.Context method)
    +
    trigger_operation_callback() (pydermonkey.Context method)

    U

    -
    undefined (in module pymonkey)
    +
    undefined (in module pydermonkey)
    @@ -207,7 +207,7 @@
  • modules |
    • -
  • Pymonkey v0.0.1 documentation »
    • +
  • Pydermonkey v0.0.1 documentation »
    • diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/index.html --- a/docs/rendered/index.html Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/rendered/index.html Tue Sep 01 03:07:24 2009 -0700 @@ -5,7 +5,7 @@ - Pymonkey Documentation — Pymonkey v0.0.1 documentation + Pydermonkey Documentation — Pydermonkey v0.0.1 documentation - - + +
    @@ -33,9 +33,9 @@ modules |
  • - next |
    • -
  • Pymonkey v0.0.1 documentation »
    • +
  • Pydermonkey v0.0.1 documentation »
    • @@ -44,13 +44,13 @@
    -
    -

    Pymonkey Documentation

    -

    Pymonkey is a Python C extension module to expose the Mozilla +

    +

    Pydermonkey Documentation

    +

    Pydermonkey is a Python C extension module to expose the Mozilla SpiderMonkey engine to Python.

    Rationale and Goals:

      @@ -69,17 +69,17 @@ would be very useful. Standards-based solutions like ServerJS are currently paving the way in this field. There’s Java-based solutions like Rhino out there, but nothing really mature is available for the Python -world. Ideally, Pymonkey should enable a Python programmer to create +world. Ideally, Pydermonkey should enable a Python programmer to create a custom sandboxed environment for executing JS code without needing to write any C.

      -

    • Pymonkey should have awesome Sphinx documentation with doctests and +

    • Pydermonkey should have awesome Sphinx documentation with doctests and all the trappings of a model Python package. Not only should it be easy for Python programmers to learn how to use the module, but it should also be easy for them to learn more about how SpiderMonkey works by reading the documentation and playing around with the code.

      • -

    • Pymonkey needs to have outstanding developer ergonomics. Full +

    • Pydermonkey needs to have outstanding developer ergonomics. Full cross-language stack tracebacks should be available, for instance, and developers should be able to easily debug. Access to memory profiling facilities in JS-land is a must.

      @@ -103,7 +103,7 @@

    Building, Testing, and Installing

    -

    From the root of your pymonkey repository, run:

    +

    From the root of your pydermonkey repository, run:

    python setup.py build test

    This will fetch and compile SpiderMonkey, build the C extension, and @@ -116,7 +116,7 @@

    Challenges

    There’s a number of challenges that need to be resolved before -pymonkey can be really usable. Here’s some of them.

    +pydermonkey can be really usable. Here’s some of them.

    Garbage Collection

    Python’s garbage collection uses reference counting, whereas SpiderMonkey’s is mark-and-sweep. It’s possible for there to be @@ -126,7 +126,7 @@ reference counting too–so detecting such cycles will probably involve creating something akin to XPCOM’s cycle collector.

    For the time being, however, such cycles can be manually broken via -pymonkey.Context.clear_object_private() on valid objects and functions.

    +pydermonkey.Context.clear_object_private() on valid objects and functions.

    Indices and Tables

    @@ -146,7 +146,7 @@

    Table Of Contents

    diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/modindex.html --- a/docs/rendered/modindex.html Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/rendered/modindex.html Tue Sep 01 03:07:24 2009 -0700 @@ -5,7 +5,7 @@ - Global Module Index — Pymonkey v0.0.1 documentation + Global Module Index — Pydermonkey v0.0.1 documentation - + + + + + + + +
    +

    Navigation

    + +
    + +
    +
    +
    +
    + +
    +

    pydermonkey — Access SpiderMonkey from Python

    +

    This module offers a low-level interface to the Mozilla SpiderMonkey JavaScript engine.

    +
    +
    + +exception pydermonkey.error
    +

    This is the type of any SpiderMonkey-related errors thrown by this +module.

    +

    If the error is a wrapped JavaScript exception, the first argument +will be the thrown JS exception, and the second argument will be +the JS exception converted to a string. Otherwise, the error +will only contain a descriptive string argument.

    +

    For example:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> cx.evaluate_script(cx.new_object(), 'throw 1', '<string>', 1)
+...
+error: (1, u'1')
+
    +
    +
    + +
    +
    +pydermonkey.undefined
    +

    This is the singleton that represents the JavaScript value +undefined, as Python has no equivalent representation +(JavaScript’s null is mapped to Python’s None object). +For instance:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> cx.evaluate_script(cx.new_object(), '', '<string>', 1)
+pydermonkey.undefined
+
    +
    +

    This object also has a “falsy” value:

    +
    >>> if not pydermonkey.undefined:
+...   print "See, it's falsy!"
+See, it's falsy!
+
    +
    +
    + +
    +
    + +class pydermonkey.Object
    +

    This is the type of JavaScript objects. Such objects can only be +created via Pydermonkey calls like Context.new_object() or +through the execution of JS code, but this type object can be used +with Python’s built-in isinstance() to verify that an +object is a JS object, like so:

    +
    >>> obj = pydermonkey.Runtime().new_context().new_object()
+>>> isinstance(obj, pydermonkey.Object)
+True
+
    +
    +

    Note that Object and all its subclasses are +identity-preserving when passed between Python and +JavaScript code. For instance:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> obj1 = cx.new_object()
+>>> obj2 = cx.evaluate_script(obj1, 'this', '<string>', 1)
+>>> obj1 is obj2
+True
+
    +
    +
    +
    +get_runtime()
    +
    Returns the Runtime that the object belongs to.
    + +
    + +
    +
    + +class pydermonkey.Function
    +

    This is the type of JavaScript functions, which is a subtype of +Object.

    +
    +
    +filename
    +
    Name of the file that contains the function’s original JS source +code. If the function isn’t a JS function, this value is +None.
    + +
    +
    +base_lineno
    +
    The line number at which the function’s JS source code begins.
    + +
    +
    +line_extent
    +
    The number of lines comprising the function’s JS source code.
    + +
    +
    +is_python
    +
    Whether or not the function is actually implemented in Python. +If it is, you can use Context.get_object_private() to +retrieve this Python function.
    + +
    + +
    +
    + +class pydermonkey.Script
    +

    This is the type of compiled JavaScript scripts; it’s actually a +subtype of Object, though when exposed to JS code it +doesn’t provide access to any special data or functionality.

    +

    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 buffer() function.

    +
    +
    +filename
    +
    The filename of the script’s original source code.
    + +
    +
    +base_lineno
    +
    The line number at which the script’s original source code +begins.
    + +
    +
    +line_extent
    +
    The number of lines comprising the original source code.
    + +
    + +
    +
    + +class pydermonkey.Context
    +

    This is the type of JavaScript context objects. Contexts can only +be created via a call to Runtime.new_context(), but this +type object can be used with Python’s built-in isinstance() +to verify that an object is a context, like so:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> isinstance(cx, pydermonkey.Context)
+True
+
    +
    +

    JS contexts are weak-referencable.

    +
    +
    +get_runtime()
    +
    Returns the Runtime that the context belongs to.
    + +
    +
    +get_stack()
    +

    Returns a dictionary containing information about the context’s +current stack.

    +

    The dictionary contains the following string keys:

    + ++++ + + + + + + + + + + + + + + + + + + + + + + +
    keyvalue
    scriptScript of the frame. +This may be None if the frame +isn’t a scripted frame, or if it’s +not possible to expose the script +to Python for some reason.
    linenoLine number of the frame, if the +frame is scripted.
    pcProgram counter of the frame; this +is an index into the bytecode of +the frame’s script, if the frame +is scripted.
    functionThe Function in which the +frame is executing, if any.
    callerDictionary containing information +about the stack frame of the +caller of this frame. If this frame +has no caller, this value is +None.
    +

    If the context isn’t currently executing any code (i.e., the stack +is empty), this method returns None.

    +
    + +
    +
    +new_object([private_obj])
    +
    Creates a new Object instance and returns +it. private_obj is any Python object that is privately +stored within the new JS object; it can be retrieved using +get_object_private().
    + +
    +
    +new_function(func, name)
    +

    Creates a new Function instance that wraps the +given Python callable. In JS-land, the function will +have the given name.

    +

    When the function is executed from JavaScript, func +will be passed three positional arguments.

    +

    The first argument is a Context that represents the +JS context which is calling the function.

    +

    The second argument is an Object that represents the +value of this for the duration of the call.

    +

    The third argument is a tuple containing the arguments +passed to the function.

    +

    For instance:

    +
    >>> def add(cx, this, args):
+...   return args[0] + args[1]
+>>> cx = pydermonkey.Runtime().new_context()
+>>> obj = cx.new_object()
+>>> cx.define_property(obj, 'add', cx.new_function(add, 'add'))
+>>> cx.evaluate_script(obj, 'add(1, 1);', '<string>', 1)
+2
+
    +
    +
    + +
    +
    +define_property(object, name, value)
    +
    Creates a new property on object, bypassing any JavaScript setters.
    + +
    +
    +has_property(object, name)
    +
    Returns whether or not object has the specified property.
    + +
    +
    +get_property(object, name)
    +

    Finds the specified property on object and returns its value, +possibly invoking a JavaScript getter.

    +

    Example:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> obj = cx.new_object()
+>>> cx.define_property(obj, 'beets', 'i like beets.')
+>>> cx.get_property(obj, 'beets')
+u'i like beets.'
+
    +
    +

    Note also that calling this function on undefined properties +yields undefined:

    +
    >>> cx.get_property(obj, 'carrots')
+pydermonkey.undefined
+
    +
    +
    + +
    +
    +get_object_private(object)
    +

    Returns the private_obj passed to new_object() +when object was first created. If it doesn’t exist, None +is returned.

    +

    If object was created with new_function(), then this +method returns the Python callable wrapped by object.

    +

    This functionality is useful if you want to securely represent +Python objects in JS-land.

    +
    + +
    +
    +clear_object_private(object)
    +

    Clears the private_obj passed to new_object() +when object was first created. If it doesn’t exist, this +function returns nothing.

    +

    If object was created with new_function(), then this +method effectively “unbinds” the Python callable wrapped by +object. If object is later called, an exception will be +raised.

    +
    + +
    +
    +evaluate_script(globalobj, code, filename, lineno)
    +

    Evaluates the text code using globalobj as the global +object/scope.

    +

    It’s assumed that code is coming from the file named by filename; +the first line of code is assumed to be line number lineno of +filename. This metadata is very useful for debugging stack traces, +exceptions, and so forth.

    +

    For example:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> obj = cx.new_object()
+>>> cx.init_standard_classes(obj)
+>>> cx.evaluate_script(obj, '5 * Math', '<string>', 1)
+nan
+
    +
    +
    + +
    +
    +compile_script(code, filename, lineno)
    +

    Compiles the given string of code and returns a Script +instance that can be executed via execute_script().

    +

    filename and lineno are used just as in +evaluate_script().

    +
    + +
    +
    +execute_script(globalobj, script)
    +

    Executes the code in the given Script object, using +globalobj as the global object/scope, and returns the result.

    +

    For example:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> obj = cx.new_object()
+>>> cx.init_standard_classes(obj)
+>>> script = cx.compile_script('5 * Math', '<string>', 1)
+>>> cx.execute_script(obj, script)
+nan
+
    +
    +
    + +
    +
    +call_function(thisobj, func, args)
    +

    Calls a JavaScript function.

    +

    thisobj is an Object that will be used as the value +of this when the function executes, func is the +Function to execute, and args is a tuple of arguments +to pass to the function.

    +

    For instance:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> obj = cx.new_object()
+>>> cx.init_standard_classes(obj)
+>>> Math = cx.get_property(obj, 'Math')
+>>> floor = cx.get_property(Math, 'floor')
+>>> cx.call_function(Math, floor, (5.3,))
+5
+
    +
    +
    + +
    +
    +init_standard_classes(object)
    +
    Defines the standard JavaScript classes on the given +Object, such as Array, eval, undefined, and +so forth. For more information, see the documentation to +JS_InitStandardClasses(), +which this method wraps.
    + +
    +
    +gc()
    +
    Performs garbage collection on the context’s JavaScript runtime.
    + +
    +
    +is_exception_pending()
    +
    Returns whether an exception is currently being propagated in +the context.
    + +
    +
    +get_pending_exception()
    +

    Returns the current exception being propagated in the context. If +no exception is being propagated, this method returns None.

    +

    If you need to disambiguate between whether None is the +pending exception or there is no pending exception, use +is_exception_pending().

    +
    + +
    +
    +set_throw_hook(func)
    +

    Sets the throw hook for the context to the given Python callable. +The hook is triggered whenever an exception is thrown in the +context.

    +

    func takes one argument: the context that triggered it.

    +

    For example, here’s a throw hook that prints information about +an exception as it’s being propagated through the stack:

    +
    >>> def throwhook(cx):
+...   stack = cx.get_stack()
+...   if stack['function']:
+...     where = stack['function'].name
+...   else:
+...     where = stack['script'].filename
+...   exc = cx.get_pending_exception()
+...   print "%s being thrown in %s" % (exc, where)
+
    +
    +

    Here’s the hook in action:

    +
    >>> cx = pydermonkey.Runtime().new_context()
+>>> cx.set_throw_hook(throwhook)
+>>> obj = cx.new_object()
+>>> code = "(function foo() { throw 'oops' })()"
+>>> try:
+...   cx.evaluate_script(obj, code, '<string>', 1)
+... except pydermonkey.error, e:
+...   print "caught %s" % e.args[0]
+oops being thrown in foo
+oops being thrown in <string>
+caught oops
+
    +
    +
    + +
    +
    +set_operation_callback(func)
    +

    Sets the operation callback for the context to the given Python +callable. The callback can be triggered via +trigger_operation_callback().

    +

    func takes one argument: the context that triggered it.

    +
    + +
    +
    +trigger_operation_callback()
    +

    Triggers the context’s operation callback. If no callback has +yet been set, this function does nothing.

    +

    This function is one of the few thread-safe functions available +to a JS runtime, and together with +set_operation_callback() can be used to abort the +execution of long-running code.

    +

    For instance, we first create an operation callback to stop +long-running code by throwing an exception:

    +
    >>> import time, threading
+>>> cx = pydermonkey.Runtime().new_context()
+>>> def stop_running_code(cx):
+...   raise Exception('JS took too long to execute.')
+>>> cx.set_operation_callback(stop_running_code)
+
    +
    +

    Then we create a watchdog thread to trigger the operation +callback once a long amount of time has passed:

    +
    >>> def watchdog_thread():
+...   time.sleep(0.1)                 # An eternity to a computer!
+...   cx.trigger_operation_callback()
+>>> thread = threading.Thread(target=watchdog_thread)
+>>> thread.start()
+
    +
    +

    Now, when we execute code that takes too long to run, it gets +aborted:

    +
    >>> try:
+...   cx.evaluate_script(cx.new_object(), 'while (1) {}',
+...                      '<string>', 1)
+... except pydermonkey.error, e:
+...   print cx.get_object_private(e.args[0])
+JS took too long to execute.
+
    +
    +
    + +
    + +
    +
    + +class pydermonkey.Runtime
    +

    Creates a new JavaScript runtime. JS objects created by the runtime +may only interact with other JS objects of the same runtime.

    +

    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.

    +

    JS runtimes are weak-referencable.

    +
    +
    +new_context()
    +
    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.
    + +
    + +
    + + +
    +
    +
    +
    +
    +

    Previous topic

    +

    Pydermonkey Documentation

    +

    This Page

    + + + +
    +
    +
    +
    +
    +

    Navigation

    + +
    +
    + © Copyright 2009, Atul Varma. + Created using Sphinx 0.6.2. +
    + + \ No newline at end of file diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/pymonkey.html --- a/docs/rendered/pymonkey.html Sun Aug 30 20:56:43 2009 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,593 +0,0 @@ - - - - - - - pymonkey — Access SpiderMonkey from Python — Pymonkey v0.0.1 documentation - - - - - - - - - -
    -

    Navigation

    - -
    - -
    -
    -
    -
    - -
    -

    pymonkey — Access SpiderMonkey from Python

    -

    This module offers a low-level interface to the Mozilla SpiderMonkey JavaScript engine.

    -
    -
    - -exception pymonkey.error
    -

    This is the type of any SpiderMonkey-related errors thrown by this -module.

    -

    If the error is a wrapped JavaScript exception, the first argument -will be the thrown JS exception, and the second argument will be -the JS exception converted to a string. Otherwise, the error -will only contain a descriptive string argument.

    -

    For example:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> cx.evaluate_script(cx.new_object(), 'throw 1', '<string>', 1)
-...
-error: (1, u'1')
-
    -
    -
    - -
    -
    -pymonkey.undefined
    -

    This is the singleton that represents the JavaScript value -undefined, as Python has no equivalent representation -(JavaScript’s null is mapped to Python’s None object). -For instance:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> cx.evaluate_script(cx.new_object(), '', '<string>', 1)
-pymonkey.undefined
-
    -
    -

    This object also has a “falsy” value:

    -
    >>> if not pymonkey.undefined:
-...   print "See, it's falsy!"
-See, it's falsy!
-
    -
    -
    - -
    -
    - -class pymonkey.Object
    -

    This is the type of JavaScript objects. Such objects can only be -created via Pymonkey calls like Context.new_object() or -through the execution of JS code, but this type object can be used -with Python’s built-in isinstance() to verify that an -object is a JS object, like so:

    -
    >>> obj = pymonkey.Runtime().new_context().new_object()
->>> isinstance(obj, pymonkey.Object)
-True
-
    -
    -

    Note that Object and all its subclasses are -identity-preserving when passed between Python and -JavaScript code. For instance:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> obj1 = cx.new_object()
->>> obj2 = cx.evaluate_script(obj1, 'this', '<string>', 1)
->>> obj1 is obj2
-True
-
    -
    -
    -
    -get_runtime()
    -
    Returns the Runtime that the object belongs to.
    - -
    - -
    -
    - -class pymonkey.Function
    -

    This is the type of JavaScript functions, which is a subtype of -Object.

    -
    -
    -filename
    -
    Name of the file that contains the function’s original JS source -code. If the function isn’t a JS function, this value is -None.
    - -
    -
    -base_lineno
    -
    The line number at which the function’s JS source code begins.
    - -
    -
    -line_extent
    -
    The number of lines comprising the function’s JS source code.
    - -
    -
    -is_python
    -
    Whether or not the function is actually implemented in Python. -If it is, you can use Context.get_object_private() to -retrieve this Python function.
    - -
    - -
    -
    - -class pymonkey.Script
    -

    This is the type of compiled JavaScript scripts; it’s actually a -subtype of Object, though when exposed to JS code it -doesn’t provide access to any special data or functionality.

    -

    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 buffer() function.

    -
    -
    -filename
    -
    The filename of the script’s original source code.
    - -
    -
    -base_lineno
    -
    The line number at which the script’s original source code -begins.
    - -
    -
    -line_extent
    -
    The number of lines comprising the original source code.
    - -
    - -
    -
    - -class pymonkey.Context
    -

    This is the type of JavaScript context objects. Contexts can only -be created via a call to Runtime.new_context(), but this -type object can be used with Python’s built-in isinstance() -to verify that an object is a context, like so:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> isinstance(cx, pymonkey.Context)
-True
-
    -
    -

    JS contexts are weak-referencable.

    -
    -
    -get_runtime()
    -
    Returns the Runtime that the context belongs to.
    - -
    -
    -get_stack()
    -

    Returns a dictionary containing information about the context’s -current stack.

    -

    The dictionary contains the following string keys:

    - ---- - - - - - - - - - - - - - - - - - - - - - - -
    keyvalue
    scriptScript of the frame. -This may be None if the frame -isn’t a scripted frame, or if it’s -not possible to expose the script -to Python for some reason.
    linenoLine number of the frame, if the -frame is scripted.
    pcProgram counter of the frame; this -is an index into the bytecode of -the frame’s script, if the frame -is scripted.
    functionThe Function in which the -frame is executing, if any.
    callerDictionary containing information -about the stack frame of the -caller of this frame. If this frame -has no caller, this value is -None.
    -

    If the context isn’t currently executing any code (i.e., the stack -is empty), this method returns None.

    -
    - -
    -
    -new_object([private_obj])
    -
    Creates a new Object instance and returns -it. private_obj is any Python object that is privately -stored within the new JS object; it can be retrieved using -get_object_private().
    - -
    -
    -new_function(func, name)
    -

    Creates a new Function instance that wraps the -given Python callable. In JS-land, the function will -have the given name.

    -

    When the function is executed from JavaScript, func -will be passed three positional arguments.

    -

    The first argument is a Context that represents the -JS context which is calling the function.

    -

    The second argument is an Object that represents the -value of this for the duration of the call.

    -

    The third argument is a tuple containing the arguments -passed to the function.

    -

    For instance:

    -
    >>> def add(cx, this, args):
-...   return args[0] + args[1]
->>> cx = pymonkey.Runtime().new_context()
->>> obj = cx.new_object()
->>> cx.define_property(obj, 'add', cx.new_function(add, 'add'))
->>> cx.evaluate_script(obj, 'add(1, 1);', '<string>', 1)
-2
-
    -
    -
    - -
    -
    -define_property(object, name, value)
    -
    Creates a new property on object, bypassing any JavaScript setters.
    - -
    -
    -has_property(object, name)
    -
    Returns whether or not object has the specified property.
    - -
    -
    -get_property(object, name)
    -

    Finds the specified property on object and returns its value, -possibly invoking a JavaScript getter.

    -

    Example:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> obj = cx.new_object()
->>> cx.define_property(obj, 'beets', 'i like beets.')
->>> cx.get_property(obj, 'beets')
-u'i like beets.'
-
    -
    -

    Note also that calling this function on undefined properties -yields undefined:

    -
    >>> cx.get_property(obj, 'carrots')
-pymonkey.undefined
-
    -
    -
    - -
    -
    -get_object_private(object)
    -

    Returns the private_obj passed to new_object() -when object was first created. If it doesn’t exist, None -is returned.

    -

    If object was created with new_function(), then this -method returns the Python callable wrapped by object.

    -

    This functionality is useful if you want to securely represent -Python objects in JS-land.

    -
    - -
    -
    -clear_object_private(object)
    -

    Clears the private_obj passed to new_object() -when object was first created. If it doesn’t exist, this -function returns nothing.

    -

    If object was created with new_function(), then this -method effectively “unbinds” the Python callable wrapped by -object. If object is later called, an exception will be -raised.

    -
    - -
    -
    -evaluate_script(globalobj, code, filename, lineno)
    -

    Evaluates the text code using globalobj as the global -object/scope.

    -

    It’s assumed that code is coming from the file named by filename; -the first line of code is assumed to be line number lineno of -filename. This metadata is very useful for debugging stack traces, -exceptions, and so forth.

    -

    For example:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> obj = cx.new_object()
->>> cx.init_standard_classes(obj)
->>> cx.evaluate_script(obj, '5 * Math', '<string>', 1)
-nan
-
    -
    -
    - -
    -
    -compile_script(code, filename, lineno)
    -

    Compiles the given string of code and returns a Script -instance that can be executed via execute_script().

    -

    filename and lineno are used just as in -evaluate_script().

    -
    - -
    -
    -execute_script(globalobj, script)
    -

    Executes the code in the given Script object, using -globalobj as the global object/scope, and returns the result.

    -

    For example:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> obj = cx.new_object()
->>> cx.init_standard_classes(obj)
->>> script = cx.compile_script('5 * Math', '<string>', 1)
->>> cx.execute_script(obj, script)
-nan
-
    -
    -
    - -
    -
    -call_function(thisobj, func, args)
    -

    Calls a JavaScript function.

    -

    thisobj is an Object that will be used as the value -of this when the function executes, func is the -Function to execute, and args is a tuple of arguments -to pass to the function.

    -

    For instance:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> obj = cx.new_object()
->>> cx.init_standard_classes(obj)
->>> Math = cx.get_property(obj, 'Math')
->>> floor = cx.get_property(Math, 'floor')
->>> cx.call_function(Math, floor, (5.3,))
-5
-
    -
    -
    - -
    -
    -init_standard_classes(object)
    -
    Defines the standard JavaScript classes on the given -Object, such as Array, eval, undefined, and -so forth. For more information, see the documentation to -JS_InitStandardClasses(), -which this method wraps.
    - -
    -
    -gc()
    -
    Performs garbage collection on the context’s JavaScript runtime.
    - -
    -
    -is_exception_pending()
    -
    Returns whether an exception is currently being propagated in -the context.
    - -
    -
    -get_pending_exception()
    -

    Returns the current exception being propagated in the context. If -no exception is being propagated, this method returns None.

    -

    If you need to disambiguate between whether None is the -pending exception or there is no pending exception, use -is_exception_pending().

    -
    - -
    -
    -set_throw_hook(func)
    -

    Sets the throw hook for the context to the given Python callable. -The hook is triggered whenever an exception is thrown in the -context.

    -

    func takes one argument: the context that triggered it.

    -

    For example, here’s a throw hook that prints information about -an exception as it’s being propagated through the stack:

    -
    >>> def throwhook(cx):
-...   stack = cx.get_stack()
-...   if stack['function']:
-...     where = stack['function'].name
-...   else:
-...     where = stack['script'].filename
-...   exc = cx.get_pending_exception()
-...   print "%s being thrown in %s" % (exc, where)
-
    -
    -

    Here’s the hook in action:

    -
    >>> cx = pymonkey.Runtime().new_context()
->>> cx.set_throw_hook(throwhook)
->>> obj = cx.new_object()
->>> code = "(function foo() { throw 'oops' })()"
->>> try:
-...   cx.evaluate_script(obj, code, '<string>', 1)
-... except pymonkey.error, e:
-...   print "caught %s" % e.args[0]
-oops being thrown in foo
-oops being thrown in <string>
-caught oops
-
    -
    -
    - -
    -
    -set_operation_callback(func)
    -

    Sets the operation callback for the context to the given Python -callable. The callback can be triggered via -trigger_operation_callback().

    -

    func takes one argument: the context that triggered it.

    -
    - -
    -
    -trigger_operation_callback()
    -

    Triggers the context’s operation callback. If no callback has -yet been set, this function does nothing.

    -

    This function is one of the few thread-safe functions available -to a JS runtime, and together with -set_operation_callback() can be used to abort the -execution of long-running code.

    -

    For instance, we first create an operation callback to stop -long-running code by throwing an exception:

    -
    >>> import time, threading
->>> cx = pymonkey.Runtime().new_context()
->>> def stop_running_code(cx):
-...   raise Exception('JS took too long to execute.')
->>> cx.set_operation_callback(stop_running_code)
-
    -
    -

    Then we create a watchdog thread to trigger the operation -callback once a long amount of time has passed:

    -
    >>> def watchdog_thread():
-...   time.sleep(0.1)                 # An eternity to a computer!
-...   cx.trigger_operation_callback()
->>> thread = threading.Thread(target=watchdog_thread)
->>> thread.start()
-
    -
    -

    Now, when we execute code that takes too long to run, it gets -aborted:

    -
    >>> try:
-...   cx.evaluate_script(cx.new_object(), 'while (1) {}',
-...                      '<string>', 1)
-... except pymonkey.error, e:
-...   print cx.get_object_private(e.args[0])
-JS took too long to execute.
-
    -
    -
    - -
    - -
    -
    - -class pymonkey.Runtime
    -

    Creates a new JavaScript runtime. JS objects created by the runtime -may only interact with other JS objects of the same runtime.

    -

    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.

    -

    JS runtimes are weak-referencable.

    -
    -
    -new_context()
    -
    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.
    - -
    - -
    - - -
    -
    -
    -
    -
    -

    Previous topic

    -

    Pymonkey Documentation

    -

    This Page

    - - - -
    -
    -
    -
    -
    -

    Navigation

    - -
    -
    - © Copyright 2009, Atul Varma. - Created using Sphinx 0.6.2. -
    - - \ No newline at end of file diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/search.html --- a/docs/rendered/search.html Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/rendered/search.html Tue Sep 01 03:07:24 2009 -0700 @@ -5,7 +5,7 @@ - Search — Pymonkey v0.0.1 documentation + Search — Pydermonkey v0.0.1 documentation - +
    @@ -32,7 +32,7 @@
  • modules |
    • -
  • Pymonkey v0.0.1 documentation »
    • +
  • Pydermonkey v0.0.1 documentation »
    • @@ -83,7 +83,7 @@
  • modules |
    • -
  • Pymonkey v0.0.1 documentation »
    • +
  • Pydermonkey v0.0.1 documentation »
    • diff -r 2b98d4643c44 -r dd32a92f6b4f docs/rendered/searchindex.js --- a/docs/rendered/searchindex.js Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/rendered/searchindex.js Tue Sep 01 03:07:24 2009 -0700 @@ -1,1 +1,1 @@ -Search.setIndex({desctypes:{"0":"method","1":"data","2":"class","3":"exception"},terms:{spidermonkei:[0,1],represent:1,all:[0,1],code:[0,1],untrust:0,lack:0,concept:0,sleep:1,follow:1,privat:1,depend:0,readabl:0,program:1,isinst:1,sourc:1,string:1,veri:[0,1],join:[],vast:0,level:1,"try":[0,1],eas:0,second:1,pass:1,casual:0,even:[],index:[0,1],what:[],conceptu:1,evaluate_script:1,abl:0,"while":1,access:[0,1],"new":1,objdir:[],method:1,metadata:1,involv:0,full:0,subtyp:1,never:0,new_object:1,here:[0,1],objcec:[],path:[],sinc:1,valu:1,convert:1,amount:1,has_properti:1,doctest:0,action:1,chang:1,tremend:0,via:[0,1],modul:[0,1],filenam:1,api:0,instal:0,test_pymonkei:[],from:[0,1],would:0,memori:0,init_standard_class:1,line_ext:1,few:1,disambigu:1,scope:1,type:1,more:[0,1],thisobj:1,mozilla:[0,1],ctype:0,oop:1,known:0,central:[],must:0,none:1,retriev:1,setup:0,work:0,compile_script:1,abort:1,can:[0,1],learn:0,akin:0,root:0,fetch:0,def:1,give:0,process:0,challeng:0,sudo:0,indic:0,carrot:1,want:[0,1],alwai:0,goal:0,secur:[0,1],write:0,how:0,verifi:1,map:1,product:0,referenc:1,clone:[],usabl:0,befor:0,mai:1,data:1,third:[0,1],counter:1,callback:1,sandbox:0,environ:0,enter:[],callabl:1,oper:1,becaus:0,intermediari:0,through:1,dynam:0,bytecod:1,platform:0,window:0,pend:1,is_python:1,bypass:1,easier:0,them:0,within:1,"return":1,thei:[],python:[0,1],safe:1,now:1,xpcom:0,name:1,anyth:0,get_runtim:1,easili:0,trigger_operation_callback:1,trap:0,compris:1,each:1,debug:[0,1],side:0,mean:0,compil:[0,1],realli:0,ensur:0,"static":[],collector:0,special:1,out:0,safeti:1,path_to_objdir:[],profil:0,lineno:1,rational:0,print:1,forth:1,math:1,model:0,situat:0,free:[],standard:[0,1],reason:1,base:0,dictionari:1,thrown:1,etern:1,thread:1,traceback:[0,1],isn:1,caught:1,first:1,origin:1,singleton:1,obviou:0,pyrex:0,feel:[],onc:1,arrai:1,number:[0,1],get_properti:1,hook:1,instruct:[],facil:0,given:1,script:1,associ:1,interact:1,stack:[0,1],too:[0,1],"final":0,store:1,relationship:0,beet:1,tool:[],huh:[],took:1,specifi:1,getter:1,than:0,wide:0,kind:[],target:1,whenev:1,provid:[0,1],posit:1,browser:0,pre:1,comput:1,falsi:1,arg:1,argument:1,packag:0,have:[0,1],tabl:0,need:[0,1],"null":1,engin:[0,1],built:1,equival:1,inform:1,latter:[],client:0,note:[0,1],also:[0,1],ideal:0,without:0,build:0,which:[0,1],noth:[0,1],begin:1,trace:1,though:1,buffer:1,object:[0,1],most:1,plai:0,"class":1,don:0,exc:1,clear:1,later:1,doe:1,runtim:1,awesom:0,text:1,particularli:0,find:1,setter:1,define_properti:1,current:[0,1],onli:[0,1],just:1,solut:0,should:0,busi:0,obj1:1,obj2:1,contribut:0,get:1,get_pending_except:1,stop:1,pave:0,increas:0,requir:0,enabl:0,yield:1,contain:1,where:[0,1],set:1,new_context:1,frame:1,see:1,result:1,stop_running_cod:1,disadvantag:0,best:1,page:0,detect:0,someth:0,state:1,won:0,outstand:0,between:[0,1],atul:0,"import":1,call_funct:1,watchdog_thread:1,kei:1,javascript:[0,1],weak:1,cycl:0,preprocessor:0,complementari:0,come:1,last:1,easi:0,extens:0,howev:0,blargh:[],instanc:[0,1],context:[0,1],logic:0,freeli:1,com:[],private_obj:1,unclear:[],simpli:[],sweep:0,header:0,assum:1,duplic:0,quit:0,java:0,creat:[0,1],three:1,been:1,mark:0,trigger:1,clear_object_priv:[0,1],search:0,ani:[0,1],togeth:1,func:1,base_lineno:1,ident:1,straight:0,properti:1,durat:1,defin:[0,1],invok:1,error:1,propag:1,advantag:0,unintuit:[],readm:[],contributor:0,blah:[],itself:1,is_exception_pend:1,develop:0,perform:1,parti:0,make:0,belong:1,cross:0,same:1,preserv:1,complex:0,document:[0,1],http:[],wherea:0,effect:1,hand:0,fairli:0,moment:[],rais:1,get_stack:1,implement:1,pymonkei:[0,1],recent:1,off:[],macro:0,exampl:1,thi:[0,1],undefin:1,programm:0,everyth:0,know:[],new_funct:1,execut:[0,1],less:0,when:1,obtain:[],yet:1,languag:0,web:0,expos:[0,1],except:1,add:1,valid:0,get_object_priv:1,els:1,take:1,around:0,read:[0,1],swig:0,envis:0,capi:0,world:0,bit:0,like:[0,1],vibrant:0,manual:0,resolv:0,server:0,collect:[0,1],set_throw_hook:1,either:[],docutil:1,manag:[],right:[],some:[0,1],back:[],global:1,mirror:[],librari:0,subclass:1,rhino:0,foo:1,refer:0,run:[0,1],garbag:[0,1],broken:0,set_operation_callback:1,repositori:0,throwhook:1,"throw":1,about:[0,1],actual:[0,1],unfortun:[],js_initstandardclass:1,due:0,empti:1,serverj:0,wrap:1,watchdog:1,your:0,execute_script:1,span:1,wai:0,ergonom:0,support:1,"long":1,custom:0,avail:[0,1],start:1,interfac:1,low:1,lot:0,suit:0,call:1,"function":[0,1],properli:0,offer:1,tupl:1,globalobj:1,line:1,"true":1,count:0,made:0,possibl:[0,1],whether:1,caller:1,otherwis:1,similar:0,featur:0,evalu:1,runtm:1,doesn:[0,1],repres:1,exist:[0,1],file:[0,1],check:[],probabl:0,floor:1,boop:[],todo:[],nan:1,field:0,other:[0,1],role:[],futur:1,test:0,you:[0,1],boof:[],matur:0,relat:1,liter:1,eval:1,unbind:1,land:[0,1],sphinx:0,directori:[],descript:1,obj:1,time:[0,1]},titles:["Pymonkey Documentation","pymonkey — Access SpiderMonkey from Python"],modules:{pymonkey:1},descrefs:{"pymonkey.Runtime":{new_context:[1,0]},"pymonkey.Script":{base_lineno:[1,1],line_extent:[1,1],filename:[1,1]},"pymonkey.Context":{get_object_private:[1,0],get_property:[1,0],new_object:[1,0],has_property:[1,0],call_function:[1,0],trigger_operation_callback:[1,0],evaluate_script:[1,0],clear_object_private:[1,0],new_function:[1,0],init_standard_classes:[1,0],define_property:[1,0],compile_script:[1,0],set_operation_callback:[1,0],set_throw_hook:[1,0],gc:[1,0],get_runtime:[1,0],get_stack:[1,0],get_pending_exception:[1,0],is_exception_pending:[1,0],execute_script:[1,0]},pymonkey:{Function:[1,2],undefined:[1,1],Script:[1,2],Object:[1,2],Context:[1,2],error:[1,3],Runtime:[1,2]},"pymonkey.Function":{base_lineno:[1,1],is_python:[1,1],line_extent:[1,1],filename:[1,1]},"pymonkey.Object":{get_runtime:[1,0]}},filenames:["index","pymonkey"]}) \ No newline at end of file +Search.setIndex({desctypes:{"0":"method","1":"data","2":"class","3":"exception"},terms:{spidermonkei:[0,1],represent:1,all:[0,1],code:[0,1],untrust:0,lack:0,concept:0,sleep:1,follow:1,privat:1,depend:0,readabl:0,program:1,isinst:1,sourc:1,string:1,veri:[0,1],join:[],vast:0,level:1,"try":[0,1],eas:0,second:1,pass:1,casual:0,even:[],index:[0,1],what:[],conceptu:1,evaluate_script:1,abl:0,"while":1,access:[0,1],"new":1,objdir:[],method:1,metadata:1,involv:0,full:0,subtyp:1,never:0,new_object:1,here:[0,1],objcec:[],path:[],sinc:1,valu:1,convert:1,amount:1,has_properti:1,doctest:0,action:1,chang:1,tremend:0,via:[0,1],modul:[0,1],filenam:1,api:0,instal:0,test_pymonkei:[],from:[0,1],would:0,memori:0,init_standard_class:1,line_ext:1,few:1,disambigu:1,scope:1,type:1,more:[0,1],thisobj:1,mozilla:[0,1],ctype:0,oop:1,known:0,central:[],must:0,none:1,retriev:1,setup:0,work:0,compile_script:1,abort:1,can:[0,1],learn:0,akin:0,root:0,fetch:0,def:1,give:0,process:0,challeng:0,sudo:0,indic:0,carrot:1,want:[0,1],alwai:0,goal:0,secur:[0,1],write:0,how:0,verifi:1,map:1,product:0,referenc:1,clone:[],usabl:0,befor:0,mai:1,data:1,third:[0,1],counter:1,callback:1,sandbox:0,environ:0,enter:[],callabl:1,oper:1,becaus:0,intermediari:0,through:1,dynam:0,bytecod:1,platform:0,window:0,pend:1,is_python:1,bypass:1,easier:0,them:0,within:1,"return":1,thei:[],python:[0,1],safe:1,now:1,xpcom:0,name:1,anyth:0,get_runtim:1,easili:0,trigger_operation_callback:1,trap:0,compris:1,each:1,debug:[0,1],side:0,mean:0,compil:[0,1],realli:0,ensur:0,"static":[],collector:0,special:1,out:0,safeti:1,path_to_objdir:[],profil:0,lineno:1,rational:0,print:1,forth:1,math:1,model:0,situat:0,free:[],standard:[0,1],reason:1,base:0,dictionari:1,thrown:1,etern:1,thread:1,traceback:[0,1],isn:1,caught:1,first:1,origin:1,singleton:1,obviou:0,pyrex:0,feel:[],onc:1,arrai:1,number:[0,1],get_properti:1,hook:1,instruct:[],facil:0,given:1,script:1,associ:1,interact:1,stack:[0,1],too:[0,1],"final":0,store:1,relationship:0,beet:1,tool:[],huh:[],took:1,specifi:1,getter:1,than:0,wide:0,kind:[],target:1,whenev:1,provid:[0,1],posit:1,browser:0,pre:1,comput:1,falsi:1,arg:1,argument:1,packag:0,have:[0,1],tabl:0,need:[0,1],"null":1,engin:[0,1],built:1,equival:1,inform:1,latter:[],client:0,note:[0,1],also:[0,1],ideal:0,without:0,build:0,which:[0,1],noth:[0,1],begin:1,trace:1,though:1,buffer:1,object:[0,1],most:1,plai:0,"class":1,don:0,exc:1,clear:1,later:1,doe:1,runtim:1,awesom:0,text:1,particularli:0,find:1,setter:1,define_properti:1,current:[0,1],onli:[0,1],just:1,solut:0,should:0,busi:0,obj1:1,obj2:1,contribut:0,get:1,get_pending_except:1,stop:1,pave:0,increas:0,requir:0,enabl:0,yield:1,contain:1,where:[0,1],set:1,new_context:1,frame:1,see:1,result:1,stop_running_cod:1,disadvantag:0,best:1,page:0,detect:0,someth:0,state:1,won:0,outstand:0,between:[0,1],atul:0,"import":1,call_funct:1,watchdog_thread:1,kei:1,javascript:[0,1],weak:1,cycl:0,preprocessor:0,complementari:0,come:1,last:1,easi:0,extens:0,howev:0,blargh:[],instanc:[0,1],context:[0,1],logic:0,freeli:1,com:[],private_obj:1,unclear:[],simpli:[],sweep:0,header:0,assum:1,duplic:0,quit:0,java:0,creat:[0,1],three:1,been:1,mark:0,trigger:1,clear_object_priv:[0,1],search:0,ani:[0,1],togeth:1,func:1,base_lineno:1,ident:1,straight:0,properti:1,durat:1,defin:[0,1],invok:1,error:1,propag:1,advantag:0,unintuit:[],readm:[],contributor:0,blah:[],itself:1,is_exception_pend:1,develop:0,perform:1,parti:0,make:0,belong:1,cross:0,same:1,preserv:1,complex:0,document:[0,1],http:[],wherea:0,effect:1,hand:0,fairli:0,moment:[],rais:1,get_stack:1,implement:1,pymonkei:[0,1],recent:1,off:[],macro:0,exampl:1,thi:[0,1],undefin:1,programm:0,everyth:0,know:[],new_funct:1,execut:[0,1],less:0,when:1,obtain:[],yet:1,languag:0,web:0,expos:[0,1],except:1,add:1,valid:0,get_object_priv:1,els:1,take:1,around:0,read:[0,1],swig:0,envis:0,capi:0,world:0,bit:0,like:[0,1],vibrant:0,manual:0,resolv:0,server:0,collect:[0,1],set_throw_hook:1,either:[],docutil:1,manag:[],right:[],some:[0,1],back:[],global:1,mirror:[],librari:0,subclass:1,rhino:0,foo:1,refer:0,run:[0,1],garbag:[0,1],broken:0,set_operation_callback:1,repositori:0,throwhook:1,"throw":1,about:[0,1],actual:[0,1],unfortun:[],js_initstandardclass:1,due:0,empti:1,serverj:0,wrap:1,watchdog:1,your:0,execute_script:1,span:1,wai:0,ergonom:0,support:1,"long":1,custom:0,avail:[0,1],start:1,interfac:1,low:1,lot:0,suit:0,call:1,"function":[0,1],properli:0,offer:1,tupl:1,globalobj:1,line:1,"true":1,count:0,made:0,possibl:[0,1],whether:1,caller:1,otherwis:1,similar:0,featur:0,evalu:1,runtm:1,doesn:[0,1],repres:1,exist:[0,1],file:[0,1],check:[],probabl:0,floor:1,boop:[],todo:[],nan:1,field:0,other:[0,1],role:[],futur:1,test:0,you:[0,1],boof:[],matur:0,relat:1,liter:1,eval:1,unbind:1,land:[0,1],sphinx:0,directori:[],descript:1,obj:1,time:[0,1]},titles:["Pydermonkey Documentation","pydermonkey — Access SpiderMonkey from Python"],modules:{pydermonkey:1},descrefs:{"pydermonkey.Runtime":{new_context:[1,0]},"pydermonkey.Script":{base_lineno:[1,1],line_extent:[1,1],filename:[1,1]},"pydermonkey.Context":{get_object_private:[1,0],get_property:[1,0],new_object:[1,0],has_property:[1,0],call_function:[1,0],trigger_operation_callback:[1,0],evaluate_script:[1,0],clear_object_private:[1,0],new_function:[1,0],init_standard_classes:[1,0],define_property:[1,0],compile_script:[1,0],set_operation_callback:[1,0],set_throw_hook:[1,0],gc:[1,0],get_runtime:[1,0],get_stack:[1,0],get_pending_exception:[1,0],is_exception_pending:[1,0],execute_script:[1,0]},pydermonkey:{Function:[1,2],undefined:[1,1],Script:[1,2],Object:[1,2],Context:[1,2],error:[1,3],Runtime:[1,2]},"pydermonkey.Function":{base_lineno:[1,1],is_python:[1,1],line_extent:[1,1],filename:[1,1]},"pydermonkey.Object":{get_runtime:[1,0]}},filenames:["index","pydermonkey"]}) \ No newline at end of file diff -r 2b98d4643c44 -r dd32a92f6b4f docs/src/conf.py --- a/docs/src/conf.py Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/src/conf.py Tue Sep 01 03:07:24 2009 -0700 @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# Pymonkey documentation build configuration file, created by +# Pydermonkey documentation build configuration file, created by # sphinx-quickstart on Mon Jul 6 17:20:31 2009. # # This file is execfile()d with the current directory set to its containing dir. @@ -37,7 +37,7 @@ master_doc = 'index' # General information about the project. -project = u'Pymonkey' +project = u'Pydermonkey' copyright = u'2009, Atul Varma' # The version info for the project you're documenting, acts as replacement for @@ -158,7 +158,7 @@ #html_file_suffix = '' # Output file base name for HTML help builder. -htmlhelp_basename = 'Pymonkeydoc' +htmlhelp_basename = 'Pydermonkeydoc' # -- Options for LaTeX output -------------------------------------------------- @@ -172,7 +172,7 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'Pymonkey.tex', u'Pymonkey Documentation', + ('index', 'Pydermonkey.tex', u'Pydermonkey Documentation', u'Atul Varma', 'manual'), ] diff -r 2b98d4643c44 -r dd32a92f6b4f docs/src/index.txt --- a/docs/src/index.txt Sun Aug 30 20:56:43 2009 -0700 +++ b/docs/src/index.txt Tue Sep 01 03:07:24 2009 -0700 @@ -1,20 +1,20 @@ -.. Pymonkey documentation master file, created by +.. Pydermonkey documentation master file, created by sphinx-quickstart on Mon Jul 6 17:20:31 2009. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. ====================== -Pymonkey Documentation +Pydermonkey Documentation ====================== -Pymonkey is a Python C extension module to expose the `Mozilla +Pydermonkey is a Python C extension module to expose the `Mozilla SpiderMonkey `_ engine to Python. .. toctree:: :maxdepth: 2 - pymonkey + pydermonkey Rationale and Goals: @@ -34,17 +34,17 @@ `_ are currently paving the way in this field. There's Java-based solutions like Rhino out there, but nothing really mature is available for the Python - world. Ideally, Pymonkey should enable a Python programmer to create + world. Ideally, Pydermonkey should enable a Python programmer to create a custom sandboxed environment for executing JS code without needing to write any C. -* Pymonkey should have awesome Sphinx documentation with doctests and +* Pydermonkey should have awesome Sphinx documentation with doctests and all the trappings of a model Python package. Not only should it be easy for Python programmers to learn how to use the module, but it should also be easy for them to learn more about how SpiderMonkey works by reading the documentation and playing around with the code. -* Pymonkey needs to have outstanding developer ergonomics. Full +* Pydermonkey needs to have outstanding developer ergonomics. Full cross-language stack tracebacks should be available, for instance, and developers should be able to easily debug. Access to memory profiling facilities in JS-land is a must. @@ -69,7 +69,7 @@ Building, Testing, and Installing ================================= -From the root of your pymonkey repository, run:: +From the root of your pydermonkey repository, run:: python setup.py build test @@ -86,7 +86,7 @@ ========== There's a number of challenges that need to be resolved before -pymonkey can be really usable. Here's some of them. +pydermonkey can be really usable. Here's some of them. **Garbage Collection** @@ -100,7 +100,7 @@ `_. For the time being, however, such cycles can be manually broken via -:meth:`pymonkey.Context.clear_object_private()` on valid objects and functions. +:meth:`pydermonkey.Context.clear_object_private()` on valid objects and functions. Indices and Tables ================== diff -r 2b98d4643c44 -r dd32a92f6b4f docs/src/pydermonkey.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/src/pydermonkey.txt Tue Sep 01 03:07:24 2009 -0700 @@ -0,0 +1,446 @@ +:mod:`pydermonkey` --- Access SpiderMonkey from Python +=================================================== + +.. module:: pydermonkey + :synopsis: Access SpiderMonkey from Python + +.. testsetup:: * + + import pydermonkey + +This module offers a low-level interface to the `Mozilla SpiderMonkey +`_ JavaScript engine. + +.. exception:: error + + This is the type of any SpiderMonkey-related errors thrown by this + module. + + If the error is a wrapped JavaScript exception, the first argument + will be the thrown JS exception, and the second argument will be + the JS exception converted to a string. Otherwise, the error + will only contain a descriptive string argument. + + For example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> cx.evaluate_script(cx.new_object(), 'throw 1', '', 1) + Traceback (most recent call last): + ... + error: (1, u'1') + +.. data:: undefined + + This is the singleton that represents the JavaScript value + ``undefined``, as Python has no equivalent representation + (JavaScript's ``null`` is mapped to Python's ``None`` object). + For instance: + + >>> cx = pydermonkey.Runtime().new_context() + >>> cx.evaluate_script(cx.new_object(), '', '', 1) + pydermonkey.undefined + + This object also has a "falsy" value: + + >>> if not pydermonkey.undefined: + ... print "See, it's falsy!" + See, it's falsy! + +.. class:: Object + + This is the type of JavaScript objects. Such objects can only be + created via Pydermonkey calls like :meth:`Context.new_object()` or + through the execution of JS code, but this type object can be used + with Python's built-in :func:`isinstance()` to verify that an + object is a JS object, like so: + + >>> obj = pydermonkey.Runtime().new_context().new_object() + >>> isinstance(obj, pydermonkey.Object) + True + + Note that :class:`Object` and all its subclasses are + identity-preserving when passed between Python and + JavaScript code. For instance: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj1 = cx.new_object() + >>> obj2 = cx.evaluate_script(obj1, 'this', '', 1) + >>> obj1 is obj2 + True + + .. method:: get_runtime() + + Returns the :class:`Runtime` that the object belongs to. + +.. class:: Function + + This is the type of JavaScript functions, which is a subtype of + :class:`Object`. + + .. data:: filename + + Name of the file that contains the function's original JS source + code. If the function isn't a JS function, this value is + ``None``. + + .. data:: base_lineno + + The line number at which the function's JS source code begins. + + .. data:: line_extent + + The number of lines comprising the function's JS source code. + + .. data:: is_python + + Whether or not the function is actually implemented in Python. + If it is, you can use :meth:`Context.get_object_private()` to + retrieve this Python function. + +.. class:: Script + + This is the type of compiled JavaScript scripts; it's actually a + subtype of :class:`Object`, though when exposed to JS code it + doesn't provide access to any special data or functionality. + + 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 ``buffer()`` function. + + .. data:: filename + + The filename of the script's original source code. + + .. data:: base_lineno + + The line number at which the script's original source code + begins. + + .. data:: line_extent + + The number of lines comprising the original source code. + +.. class:: Context + + This is the type of JavaScript context objects. Contexts can only + be created via a call to :meth:`Runtime.new_context()`, but this + type object can be used with Python's built-in :func:`isinstance()` + to verify that an object is a context, like so: + + >>> cx = pydermonkey.Runtime().new_context() + >>> isinstance(cx, pydermonkey.Context) + True + + JS contexts are weak-referencable. + + .. method:: get_runtime() + + Returns the :class:`Runtime` that the context belongs to. + + .. method:: get_stack() + + Returns a dictionary containing information about the context's + current stack. + + The dictionary contains the following string keys: + + +------------------------------+-------------------------------------+ + | key | value | + +==============================+=====================================+ + | :const:`script` | :class:`Script` of the frame. | + | | This may be ``None`` if the frame | + | | isn't a scripted frame, or if it's | + | | not possible to expose the script | + | | to Python for some reason. | + +------------------------------+-------------------------------------+ + | :const:`lineno` | Line number of the frame, if the | + | | frame is scripted. | + +------------------------------+-------------------------------------+ + | :const:`pc` | Program counter of the frame; this | + | | is an index into the bytecode of | + | | the frame's script, if the frame | + | | is scripted. | + +------------------------------+-------------------------------------+ + | :const:`function` | The :class:`Function` in which the | + | | frame is executing, if any. | + +------------------------------+-------------------------------------+ + | :const:`caller` | Dictionary containing information | + | | about the stack frame of the | + | | caller of this frame. If this frame | + | | has no caller, this value is | + | | ``None``. | + +------------------------------+-------------------------------------+ + + If the context isn't currently executing any code (i.e., the stack + is empty), this method returns ``None``. + + .. method:: new_object([private_obj]) + + Creates a new :class:`Object` instance and returns + it. ``private_obj`` is any Python object that is privately + stored within the new JS object; it can be retrieved using + :meth:`get_object_private()`. + + .. method:: new_function(func, name) + + Creates a new :class:`Function` instance that wraps the + given Python callable. In JS-land, the function will + have the given name. + + When the function is executed from JavaScript, `func` + will be passed three positional arguments. + + The first argument is a :class:`Context` that represents the + JS context which is calling the function. + + The second argument is an :class:`Object` that represents the + value of ``this`` for the duration of the call. + + The third argument is a tuple containing the arguments + passed to the function. + + For instance: + + >>> def add(cx, this, args): + ... return args[0] + args[1] + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.define_property(obj, 'add', cx.new_function(add, 'add')) + >>> cx.evaluate_script(obj, 'add(1, 1);', '', 1) + 2 + + .. method:: define_property(object, name, value) + + Creates a new property on `object`, bypassing any JavaScript setters. + + .. method:: has_property(object, name) + + Returns whether or not `object` has the specified property. + + .. method:: get_property(object, name) + + Finds the specified property on `object` and returns its value, + possibly invoking a JavaScript getter. + + Example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.define_property(obj, 'beets', 'i like beets.') + >>> cx.get_property(obj, 'beets') + u'i like beets.' + + Note also that calling this function on undefined properties + yields :data:`undefined`: + + >>> cx.get_property(obj, 'carrots') + pydermonkey.undefined + + .. method:: get_object_private(object) + + Returns the ``private_obj`` passed to :meth:`new_object()` + when `object` was first created. If it doesn't exist, ``None`` + is returned. + + If `object` was created with :meth:`new_function()`, then this + method returns the Python callable wrapped by `object`. + + This functionality is useful if you want to securely represent + Python objects in JS-land. + + .. method:: clear_object_private(object) + + Clears the ``private_obj`` passed to :meth:`new_object()` + when `object` was first created. If it doesn't exist, this + function returns nothing. + + If `object` was created with :meth:`new_function()`, then this + method effectively "unbinds" the Python callable wrapped by + `object`. If `object` is later called, an exception will be + raised. + + .. method:: evaluate_script(globalobj, code, filename, lineno) + + Evaluates the text `code` using `globalobj` as the global + object/scope. + + It's assumed that `code` is coming from the file named by `filename`; + the first line of `code` is assumed to be line number `lineno` of + `filename`. This metadata is very useful for debugging stack traces, + exceptions, and so forth. + + For example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.init_standard_classes(obj) + >>> cx.evaluate_script(obj, '5 * Math', '', 1) + nan + + .. method:: compile_script(code, filename, lineno) + + Compiles the given string of code and returns a :class:`Script` + instance that can be executed via :meth:`execute_script()`. + + `filename` and `lineno` are used just as in + :meth:`evaluate_script()`. + + .. method:: execute_script(globalobj, script) + + Executes the code in the given :class:`Script` object, using + `globalobj` as the global object/scope, and returns the result. + + For example: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.init_standard_classes(obj) + >>> script = cx.compile_script('5 * Math', '', 1) + >>> cx.execute_script(obj, script) + nan + + .. method:: call_function(thisobj, func, args) + + Calls a JavaScript function. + + `thisobj` is an :class:`Object` that will be used as the value + of ``this`` when the function executes, `func` is the + :class:`Function` to execute, and `args` is a tuple of arguments + to pass to the function. + + For instance: + + >>> cx = pydermonkey.Runtime().new_context() + >>> obj = cx.new_object() + >>> cx.init_standard_classes(obj) + >>> Math = cx.get_property(obj, 'Math') + >>> floor = cx.get_property(Math, 'floor') + >>> cx.call_function(Math, floor, (5.3,)) + 5 + + .. method:: init_standard_classes(object) + + Defines the standard JavaScript classes on the given + :class:`Object`, such as ``Array``, ``eval``, ``undefined``, and + so forth. For more information, see the documentation to + `JS_InitStandardClasses() + `_, + which this method wraps. + + .. method:: gc() + + Performs garbage collection on the context's JavaScript runtime. + + .. method:: is_exception_pending() + + Returns whether an exception is currently being propagated in + the context. + + .. method:: get_pending_exception() + + Returns the current exception being propagated in the context. If + no exception is being propagated, this method returns ``None``. + + If you need to disambiguate between whether ``None`` is the + pending exception or there is no pending exception, use + :meth:`is_exception_pending()`. + + .. method:: set_throw_hook(func) + + Sets the throw hook for the context to the given Python callable. + The hook is triggered whenever an exception is thrown in the + context. + + `func` takes one argument: the context that triggered it. + + For example, here's a throw hook that prints information about + an exception as it's being propagated through the stack: + + >>> def throwhook(cx): + ... stack = cx.get_stack() + ... if stack['function']: + ... where = stack['function'].name + ... else: + ... where = stack['script'].filename + ... exc = cx.get_pending_exception() + ... print "%s being thrown in %s" % (exc, where) + + Here's the hook in action: + + >>> cx = pydermonkey.Runtime().new_context() + >>> cx.set_throw_hook(throwhook) + >>> obj = cx.new_object() + >>> code = "(function foo() { throw 'oops' })()" + >>> try: + ... cx.evaluate_script(obj, code, '', 1) + ... except pydermonkey.error, e: + ... print "caught %s" % e.args[0] + oops being thrown in foo + oops being thrown in + caught oops + + .. method:: set_operation_callback(func) + + Sets the operation callback for the context to the given Python + callable. The callback can be triggered via + :meth:`trigger_operation_callback()`. + + `func` takes one argument: the context that triggered it. + + .. method:: trigger_operation_callback() + + Triggers the context's operation callback. If no callback has + yet been set, this function does nothing. + + This function is one of the few thread-safe functions available + to a JS runtime, and together with + :meth:`set_operation_callback()` can be used to abort the + execution of long-running code. + + For instance, we first create an operation callback to stop + long-running code by throwing an exception: + + >>> import time, threading + >>> cx = pydermonkey.Runtime().new_context() + >>> def stop_running_code(cx): + ... raise Exception('JS took too long to execute.') + >>> cx.set_operation_callback(stop_running_code) + + Then we create a watchdog thread to trigger the operation + callback once a long amount of time has passed: + + >>> def watchdog_thread(): + ... time.sleep(0.1) # An eternity to a computer! + ... cx.trigger_operation_callback() + >>> thread = threading.Thread(target=watchdog_thread) + >>> thread.start() + + Now, when we execute code that takes too long to run, it gets + aborted: + + >>> try: + ... cx.evaluate_script(cx.new_object(), 'while (1) {}', + ... '', 1) + ... except pydermonkey.error, e: + ... print cx.get_object_private(e.args[0]) + JS took too long to execute. + +.. class:: Runtime() + + Creates a new JavaScript runtime. JS objects created by the runtime + may only interact with other JS objects of the same runtime. + + 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. + + JS runtimes are weak-referencable. + + .. method:: new_context() + + 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. diff -r 2b98d4643c44 -r dd32a92f6b4f docs/src/pymonkey.txt --- a/docs/src/pymonkey.txt Sun Aug 30 20:56:43 2009 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,446 +0,0 @@ -:mod:`pymonkey` --- Access SpiderMonkey from Python -=================================================== - -.. module:: pymonkey - :synopsis: Access SpiderMonkey from Python - -.. testsetup:: * - - import pymonkey - -This module offers a low-level interface to the `Mozilla SpiderMonkey -`_ JavaScript engine. - -.. exception:: error - - This is the type of any SpiderMonkey-related errors thrown by this - module. - - If the error is a wrapped JavaScript exception, the first argument - will be the thrown JS exception, and the second argument will be - the JS exception converted to a string. Otherwise, the error - will only contain a descriptive string argument. - - For example: - - >>> cx = pymonkey.Runtime().new_context() - >>> cx.evaluate_script(cx.new_object(), 'throw 1', '', 1) - Traceback (most recent call last): - ... - error: (1, u'1') - -.. data:: undefined - - This is the singleton that represents the JavaScript value - ``undefined``, as Python has no equivalent representation - (JavaScript's ``null`` is mapped to Python's ``None`` object). - For instance: - - >>> cx = pymonkey.Runtime().new_context() - >>> cx.evaluate_script(cx.new_object(), '', '', 1) - pymonkey.undefined - - This object also has a "falsy" value: - - >>> if not pymonkey.undefined: - ... print "See, it's falsy!" - See, it's falsy! - -.. class:: Object - - This is the type of JavaScript objects. Such objects can only be - created via Pymonkey calls like :meth:`Context.new_object()` or - through the execution of JS code, but this type object can be used - with Python's built-in :func:`isinstance()` to verify that an - object is a JS object, like so: - - >>> obj = pymonkey.Runtime().new_context().new_object() - >>> isinstance(obj, pymonkey.Object) - True - - Note that :class:`Object` and all its subclasses are - identity-preserving when passed between Python and - JavaScript code. For instance: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj1 = cx.new_object() - >>> obj2 = cx.evaluate_script(obj1, 'this', '', 1) - >>> obj1 is obj2 - True - - .. method:: get_runtime() - - Returns the :class:`Runtime` that the object belongs to. - -.. class:: Function - - This is the type of JavaScript functions, which is a subtype of - :class:`Object`. - - .. data:: filename - - Name of the file that contains the function's original JS source - code. If the function isn't a JS function, this value is - ``None``. - - .. data:: base_lineno - - The line number at which the function's JS source code begins. - - .. data:: line_extent - - The number of lines comprising the function's JS source code. - - .. data:: is_python - - Whether or not the function is actually implemented in Python. - If it is, you can use :meth:`Context.get_object_private()` to - retrieve this Python function. - -.. class:: Script - - This is the type of compiled JavaScript scripts; it's actually a - subtype of :class:`Object`, though when exposed to JS code it - doesn't provide access to any special data or functionality. - - 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 ``buffer()`` function. - - .. data:: filename - - The filename of the script's original source code. - - .. data:: base_lineno - - The line number at which the script's original source code - begins. - - .. data:: line_extent - - The number of lines comprising the original source code. - -.. class:: Context - - This is the type of JavaScript context objects. Contexts can only - be created via a call to :meth:`Runtime.new_context()`, but this - type object can be used with Python's built-in :func:`isinstance()` - to verify that an object is a context, like so: - - >>> cx = pymonkey.Runtime().new_context() - >>> isinstance(cx, pymonkey.Context) - True - - JS contexts are weak-referencable. - - .. method:: get_runtime() - - Returns the :class:`Runtime` that the context belongs to. - - .. method:: get_stack() - - Returns a dictionary containing information about the context's - current stack. - - The dictionary contains the following string keys: - - +------------------------------+-------------------------------------+ - | key | value | - +==============================+=====================================+ - | :const:`script` | :class:`Script` of the frame. | - | | This may be ``None`` if the frame | - | | isn't a scripted frame, or if it's | - | | not possible to expose the script | - | | to Python for some reason. | - +------------------------------+-------------------------------------+ - | :const:`lineno` | Line number of the frame, if the | - | | frame is scripted. | - +------------------------------+-------------------------------------+ - | :const:`pc` | Program counter of the frame; this | - | | is an index into the bytecode of | - | | the frame's script, if the frame | - | | is scripted. | - +------------------------------+-------------------------------------+ - | :const:`function` | The :class:`Function` in which the | - | | frame is executing, if any. | - +------------------------------+-------------------------------------+ - | :const:`caller` | Dictionary containing information | - | | about the stack frame of the | - | | caller of this frame. If this frame | - | | has no caller, this value is | - | | ``None``. | - +------------------------------+-------------------------------------+ - - If the context isn't currently executing any code (i.e., the stack - is empty), this method returns ``None``. - - .. method:: new_object([private_obj]) - - Creates a new :class:`Object` instance and returns - it. ``private_obj`` is any Python object that is privately - stored within the new JS object; it can be retrieved using - :meth:`get_object_private()`. - - .. method:: new_function(func, name) - - Creates a new :class:`Function` instance that wraps the - given Python callable. In JS-land, the function will - have the given name. - - When the function is executed from JavaScript, `func` - will be passed three positional arguments. - - The first argument is a :class:`Context` that represents the - JS context which is calling the function. - - The second argument is an :class:`Object` that represents the - value of ``this`` for the duration of the call. - - The third argument is a tuple containing the arguments - passed to the function. - - For instance: - - >>> def add(cx, this, args): - ... return args[0] + args[1] - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.define_property(obj, 'add', cx.new_function(add, 'add')) - >>> cx.evaluate_script(obj, 'add(1, 1);', '', 1) - 2 - - .. method:: define_property(object, name, value) - - Creates a new property on `object`, bypassing any JavaScript setters. - - .. method:: has_property(object, name) - - Returns whether or not `object` has the specified property. - - .. method:: get_property(object, name) - - Finds the specified property on `object` and returns its value, - possibly invoking a JavaScript getter. - - Example: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.define_property(obj, 'beets', 'i like beets.') - >>> cx.get_property(obj, 'beets') - u'i like beets.' - - Note also that calling this function on undefined properties - yields :data:`undefined`: - - >>> cx.get_property(obj, 'carrots') - pymonkey.undefined - - .. method:: get_object_private(object) - - Returns the ``private_obj`` passed to :meth:`new_object()` - when `object` was first created. If it doesn't exist, ``None`` - is returned. - - If `object` was created with :meth:`new_function()`, then this - method returns the Python callable wrapped by `object`. - - This functionality is useful if you want to securely represent - Python objects in JS-land. - - .. method:: clear_object_private(object) - - Clears the ``private_obj`` passed to :meth:`new_object()` - when `object` was first created. If it doesn't exist, this - function returns nothing. - - If `object` was created with :meth:`new_function()`, then this - method effectively "unbinds" the Python callable wrapped by - `object`. If `object` is later called, an exception will be - raised. - - .. method:: evaluate_script(globalobj, code, filename, lineno) - - Evaluates the text `code` using `globalobj` as the global - object/scope. - - It's assumed that `code` is coming from the file named by `filename`; - the first line of `code` is assumed to be line number `lineno` of - `filename`. This metadata is very useful for debugging stack traces, - exceptions, and so forth. - - For example: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.init_standard_classes(obj) - >>> cx.evaluate_script(obj, '5 * Math', '', 1) - nan - - .. method:: compile_script(code, filename, lineno) - - Compiles the given string of code and returns a :class:`Script` - instance that can be executed via :meth:`execute_script()`. - - `filename` and `lineno` are used just as in - :meth:`evaluate_script()`. - - .. method:: execute_script(globalobj, script) - - Executes the code in the given :class:`Script` object, using - `globalobj` as the global object/scope, and returns the result. - - For example: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.init_standard_classes(obj) - >>> script = cx.compile_script('5 * Math', '', 1) - >>> cx.execute_script(obj, script) - nan - - .. method:: call_function(thisobj, func, args) - - Calls a JavaScript function. - - `thisobj` is an :class:`Object` that will be used as the value - of ``this`` when the function executes, `func` is the - :class:`Function` to execute, and `args` is a tuple of arguments - to pass to the function. - - For instance: - - >>> cx = pymonkey.Runtime().new_context() - >>> obj = cx.new_object() - >>> cx.init_standard_classes(obj) - >>> Math = cx.get_property(obj, 'Math') - >>> floor = cx.get_property(Math, 'floor') - >>> cx.call_function(Math, floor, (5.3,)) - 5 - - .. method:: init_standard_classes(object) - - Defines the standard JavaScript classes on the given - :class:`Object`, such as ``Array``, ``eval``, ``undefined``, and - so forth. For more information, see the documentation to - `JS_InitStandardClasses() - `_, - which this method wraps. - - .. method:: gc() - - Performs garbage collection on the context's JavaScript runtime. - - .. method:: is_exception_pending() - - Returns whether an exception is currently being propagated in - the context. - - .. method:: get_pending_exception() - - Returns the current exception being propagated in the context. If - no exception is being propagated, this method returns ``None``. - - If you need to disambiguate between whether ``None`` is the - pending exception or there is no pending exception, use - :meth:`is_exception_pending()`. - - .. method:: set_throw_hook(func) - - Sets the throw hook for the context to the given Python callable. - The hook is triggered whenever an exception is thrown in the - context. - - `func` takes one argument: the context that triggered it. - - For example, here's a throw hook that prints information about - an exception as it's being propagated through the stack: - - >>> def throwhook(cx): - ... stack = cx.get_stack() - ... if stack['function']: - ... where = stack['function'].name - ... else: - ... where = stack['script'].filename - ... exc = cx.get_pending_exception() - ... print "%s being thrown in %s" % (exc, where) - - Here's the hook in action: - - >>> cx = pymonkey.Runtime().new_context() - >>> cx.set_throw_hook(throwhook) - >>> obj = cx.new_object() - >>> code = "(function foo() { throw 'oops' })()" - >>> try: - ... cx.evaluate_script(obj, code, '', 1) - ... except pymonkey.error, e: - ... print "caught %s" % e.args[0] - oops being thrown in foo - oops being thrown in - caught oops - - .. method:: set_operation_callback(func) - - Sets the operation callback for the context to the given Python - callable. The callback can be triggered via - :meth:`trigger_operation_callback()`. - - `func` takes one argument: the context that triggered it. - - .. method:: trigger_operation_callback() - - Triggers the context's operation callback. If no callback has - yet been set, this function does nothing. - - This function is one of the few thread-safe functions available - to a JS runtime, and together with - :meth:`set_operation_callback()` can be used to abort the - execution of long-running code. - - For instance, we first create an operation callback to stop - long-running code by throwing an exception: - - >>> import time, threading - >>> cx = pymonkey.Runtime().new_context() - >>> def stop_running_code(cx): - ... raise Exception('JS took too long to execute.') - >>> cx.set_operation_callback(stop_running_code) - - Then we create a watchdog thread to trigger the operation - callback once a long amount of time has passed: - - >>> def watchdog_thread(): - ... time.sleep(0.1) # An eternity to a computer! - ... cx.trigger_operation_callback() - >>> thread = threading.Thread(target=watchdog_thread) - >>> thread.start() - - Now, when we execute code that takes too long to run, it gets - aborted: - - >>> try: - ... cx.evaluate_script(cx.new_object(), 'while (1) {}', - ... '', 1) - ... except pymonkey.error, e: - ... print cx.get_object_private(e.args[0]) - JS took too long to execute. - -.. class:: Runtime() - - Creates a new JavaScript runtime. JS objects created by the runtime - may only interact with other JS objects of the same runtime. - - 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. - - JS runtimes are weak-referencable. - - .. method:: new_context() - - 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. diff -r 2b98d4643c44 -r dd32a92f6b4f setup.py --- a/setup.py Sun Aug 30 20:56:43 2009 -0700 +++ b/setup.py Tue Sep 01 03:07:24 2009 -0700 @@ -37,7 +37,7 @@ from paver.easy import * from paver.setuputils import setup -SOURCE_FILES = ['pymonkey.cpp', +SOURCE_FILES = ['pydermonkey.cpp', 'utils.cpp', 'object.cpp', 'function.cpp', @@ -62,7 +62,7 @@ DOCTEST_OUTPUT_DIR = os.path.join(BUILD_DIR, 'doctest_output') setup_options = dict( - name='pymonkey', + name='pydermonkey', version='0.0.1', description='Access SpiderMonkey from Python', author='Atul Varma', @@ -92,7 +92,7 @@ ext_options['libraries'] = ['js_static'] setup_options['ext_modules'] = [ - distutils.core.Extension('pymonkey', + distutils.core.Extension('pydermonkey', [os.path.join("src", filename) for filename in SOURCE_FILES], **ext_options) @@ -102,7 +102,7 @@ @task def docs(options): - """Open the Pymonkey documentation in your web browser.""" + """Open the Pydermonkey documentation in your web browser.""" url = os.path.abspath(os.path.join("docs", "rendered", "index.html")) url = urllib.pathname2url(url) @@ -164,13 +164,13 @@ @task @needs('build_spidermonkey', 'setuptools.command.build') def build(options): - """Builds the pymonkey extension.""" + """Builds the pydermonkey extension.""" pass @task def build_docs(options): - """Build the Pymonkey documentation (requires Sphinx).""" + """Build the Pydermonkey documentation (requires Sphinx).""" retval = subprocess.call(["sphinx-build", "-b", "html", @@ -206,7 +206,7 @@ @task def test(options): - """Test the Pymonkey Python C extension.""" + """Test the Pydermonkey Python C extension.""" print "Running test suite." @@ -219,7 +219,7 @@ new_env[env_var] = os.path.pathsep.join(paths) # We have to add our build directory to the python path so that - # our tests can find the pymonkey module. + # our tests can find the pydermonkey module. append_path('PYTHONPATH', get_lib_dir()) if sys.platform == 'win32': @@ -229,7 +229,7 @@ result = subprocess.call( [sys.executable, - os.path.join("tests", "test_pymonkey.py")], + os.path.join("tests", "test_pydermonkey.py")], env = new_env ) diff -r 2b98d4643c44 -r dd32a92f6b4f src/context.cpp --- a/src/context.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/context.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 @@ -43,7 +43,7 @@ #include "jsdbgapi.h" #include "jsscript.h" -// This is the default throw hook for pymonkey-owned JS contexts, +// This is the default throw hook for pydermonkey-owned JS contexts, // when they've defined one in Python. static JSTrapStatus PYM_throwHook(JSContext *cx, JSScript *script, jsbytecode *pc, jsval *rval, @@ -70,7 +70,7 @@ return JSTRAP_CONTINUE; } -// This is the default JSOperationCallback for pymonkey-owned JS contexts, +// This is the default JSOperationCallback for pydermonkey-owned JS contexts, // when they've defined one in Python. static JSBool PYM_operationCallback(JSContext *cx) @@ -96,7 +96,7 @@ return JS_TRUE; } -// This is the default JSErrorReporter for pymonkey-owned JS contexts. +// This is the default JSErrorReporter for pydermonkey-owned JS contexts. static void PYM_reportError(JSContext *cx, const char *message, JSErrorReport *report) { @@ -804,7 +804,7 @@ PyTypeObject PYM_JSContextType = { PyObject_HEAD_INIT(NULL) 0, /*ob_size*/ - "pymonkey.Context", /*tp_name*/ + "pydermonkey.Context", /*tp_name*/ sizeof(PYM_JSContextObject), /*tp_basicsize*/ 0, /*tp_itemsize*/ /*tp_dealloc*/ diff -r 2b98d4643c44 -r dd32a92f6b4f src/context.h --- a/src/context.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/context.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/function.cpp --- a/src/function.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/function.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 @@ -152,7 +152,7 @@ PyTypeObject PYM_JSFunctionType = { PyObject_HEAD_INIT(NULL) 0, /*ob_size*/ - "pymonkey.Function", /*tp_name*/ + "pydermonkey.Function", /*tp_name*/ sizeof(PYM_JSFunction), /*tp_basicsize*/ 0, /*tp_itemsize*/ /*tp_dealloc*/ diff -r 2b98d4643c44 -r dd32a92f6b4f src/function.h --- a/src/function.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/function.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/object.cpp --- a/src/object.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/object.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 @@ -69,7 +69,7 @@ { JSClass *klass = JS_GET_CLASS(cx, obj); if (klass != &PYM_JS_ObjectClass) { - JS_ReportError(cx, "Object is not an instance of PymonkeyObject"); + JS_ReportError(cx, "Object is not an instance of PydermonkeyObject"); return JS_FALSE; } @@ -93,7 +93,7 @@ // garbage collected by the JS interpreter, it releases its reference on // the Python object. JSClass PYM_JS_ObjectClass = { - "PymonkeyObject", JSCLASS_GLOBAL_FLAGS | JSCLASS_HAS_PRIVATE, + "PydermonkeyObject", JSCLASS_GLOBAL_FLAGS | JSCLASS_HAS_PRIVATE, JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_PropertyStub, JS_EnumerateStub, JS_ResolveStub, JS_ConvertStub, PYM_JS_finalizeObject, JSCLASS_NO_OPTIONAL_MEMBERS @@ -137,7 +137,7 @@ PyTypeObject PYM_JSObjectType = { PyObject_HEAD_INIT(NULL) 0, /*ob_size*/ - "pymonkey.Object", /*tp_name*/ + "pydermonkey.Object", /*tp_name*/ sizeof(PYM_JSObject), /*tp_basicsize*/ 0, /*tp_itemsize*/ /*tp_dealloc*/ @@ -246,6 +246,6 @@ object->obj = obj; JS_AddNamedRootRT(object->runtime->rt, &object->obj, - "Pymonkey-Generated Object"); + "Pydermonkey-Generated Object"); return object; } diff -r 2b98d4643c44 -r dd32a92f6b4f src/object.h --- a/src/object.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/object.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/pydermonkey.cpp --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/pydermonkey.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -0,0 +1,112 @@ +/* ***** BEGIN LICENSE BLOCK ***** + * Version: MPL 1.1/GPL 2.0/LGPL 2.1 + * + * The contents of this file are subject to the Mozilla Public License Version + * 1.1 (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS IS" basis, + * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License + * for the specific language governing rights and limitations under the + * License. + * + * The Original Code is Pydermonkey. + * + * The Initial Developer of the Original Code is Mozilla. + * Portions created by the Initial Developer are Copyright (C) 2007 + * the Initial Developer. All Rights Reserved. + * + * Contributor(s): + * Atul Varma + * + * Alternatively, the contents of this file may be used under the terms of + * either the GNU General Public License Version 2 or later (the "GPL"), or + * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), + * in which case the provisions of the GPL or the LGPL are applicable instead + * of those above. If you wish to allow use of your version of this file only + * under the terms of either the GPL or the LGPL, and not to allow others to + * use your version of this file under the terms of the MPL, indicate your + * decision by deleting the provisions above and replace them with the notice + * and other provisions required by the GPL or the LGPL. If you do not delete + * the provisions above, a recipient may use your version of this file under + * the terms of any one of the MPL, the GPL or the LGPL. + * + * ***** END LICENSE BLOCK ***** */ + +#include "undefined.h" +#include "runtime.h" +#include "context.h" +#include "object.h" +#include "function.h" +#include "script.h" +#include "utils.h" + +static PyObject * +PYM_getDebugInfo(PyObject *self, PyObject *args) +{ + PyObject *info = Py_BuildValue("{sI}", + "runtime_count", PYM_getJSRuntimeCount()); + return info; +} + +static PyMethodDef PYM_methods[] = { + {"get_debug_info", PYM_getDebugInfo, METH_VARARGS, + "Get debugging information about the module."}, + {NULL, NULL, 0, NULL} +}; + +PyMODINIT_FUNC +initpydermonkey(void) +{ + PyObject *module; + + module = Py_InitModule("pydermonkey", PYM_methods); + if (module == NULL) + return; + + if (PyType_Ready(&PYM_undefinedType) < 0) + return; + + PYM_undefined = PyObject_New(PYM_undefinedObject, &PYM_undefinedType); + if (PYM_undefined == NULL) + return; + Py_INCREF(PYM_undefined); + PyModule_AddObject(module, "undefined", (PyObject *) PYM_undefined); + + PYM_error = PyErr_NewException("pydermonkey.error", NULL, NULL); + Py_INCREF(PYM_error); + PyModule_AddObject(module, "error", PYM_error); + + if (!PyType_Ready(&PYM_JSRuntimeType) < 0) + return; + + Py_INCREF(&PYM_JSRuntimeType); + PyModule_AddObject(module, "Runtime", (PyObject *) &PYM_JSRuntimeType); + + if (!PyType_Ready(&PYM_JSContextType) < 0) + return; + + Py_INCREF(&PYM_JSContextType); + PyModule_AddObject(module, "Context", (PyObject *) &PYM_JSContextType); + + if (!PyType_Ready(&PYM_JSObjectType) < 0) + return; + + Py_INCREF(&PYM_JSObjectType); + PyModule_AddObject(module, "Object", (PyObject *) &PYM_JSObjectType); + + PYM_JSFunctionType.tp_base = &PYM_JSObjectType; + if (!PyType_Ready(&PYM_JSFunctionType) < 0) + return; + + Py_INCREF(&PYM_JSFunctionType); + PyModule_AddObject(module, "Function", (PyObject *) &PYM_JSFunctionType); + + PYM_JSScriptType.tp_base = &PYM_JSObjectType; + if (!PyType_Ready(&PYM_JSScriptType) < 0) + return; + + Py_INCREF(&PYM_JSScriptType); + PyModule_AddObject(module, "Script", (PyObject *) &PYM_JSScriptType); +} diff -r 2b98d4643c44 -r dd32a92f6b4f src/pymonkey.cpp --- a/src/pymonkey.cpp Sun Aug 30 20:56:43 2009 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,112 +0,0 @@ -/* ***** BEGIN LICENSE BLOCK ***** - * Version: MPL 1.1/GPL 2.0/LGPL 2.1 - * - * The contents of this file are subject to the Mozilla Public License Version - * 1.1 (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at - * http://www.mozilla.org/MPL/ - * - * Software distributed under the License is distributed on an "AS IS" basis, - * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License - * for the specific language governing rights and limitations under the - * License. - * - * The Original Code is Pymonkey. - * - * The Initial Developer of the Original Code is Mozilla. - * Portions created by the Initial Developer are Copyright (C) 2007 - * the Initial Developer. All Rights Reserved. - * - * Contributor(s): - * Atul Varma - * - * Alternatively, the contents of this file may be used under the terms of - * either the GNU General Public License Version 2 or later (the "GPL"), or - * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), - * in which case the provisions of the GPL or the LGPL are applicable instead - * of those above. If you wish to allow use of your version of this file only - * under the terms of either the GPL or the LGPL, and not to allow others to - * use your version of this file under the terms of the MPL, indicate your - * decision by deleting the provisions above and replace them with the notice - * and other provisions required by the GPL or the LGPL. If you do not delete - * the provisions above, a recipient may use your version of this file under - * the terms of any one of the MPL, the GPL or the LGPL. - * - * ***** END LICENSE BLOCK ***** */ - -#include "undefined.h" -#include "runtime.h" -#include "context.h" -#include "object.h" -#include "function.h" -#include "script.h" -#include "utils.h" - -static PyObject * -PYM_getDebugInfo(PyObject *self, PyObject *args) -{ - PyObject *info = Py_BuildValue("{sI}", - "runtime_count", PYM_getJSRuntimeCount()); - return info; -} - -static PyMethodDef PYM_methods[] = { - {"get_debug_info", PYM_getDebugInfo, METH_VARARGS, - "Get debugging information about the module."}, - {NULL, NULL, 0, NULL} -}; - -PyMODINIT_FUNC -initpymonkey(void) -{ - PyObject *module; - - module = Py_InitModule("pymonkey", PYM_methods); - if (module == NULL) - return; - - if (PyType_Ready(&PYM_undefinedType) < 0) - return; - - PYM_undefined = PyObject_New(PYM_undefinedObject, &PYM_undefinedType); - if (PYM_undefined == NULL) - return; - Py_INCREF(PYM_undefined); - PyModule_AddObject(module, "undefined", (PyObject *) PYM_undefined); - - PYM_error = PyErr_NewException("pymonkey.error", NULL, NULL); - Py_INCREF(PYM_error); - PyModule_AddObject(module, "error", PYM_error); - - if (!PyType_Ready(&PYM_JSRuntimeType) < 0) - return; - - Py_INCREF(&PYM_JSRuntimeType); - PyModule_AddObject(module, "Runtime", (PyObject *) &PYM_JSRuntimeType); - - if (!PyType_Ready(&PYM_JSContextType) < 0) - return; - - Py_INCREF(&PYM_JSContextType); - PyModule_AddObject(module, "Context", (PyObject *) &PYM_JSContextType); - - if (!PyType_Ready(&PYM_JSObjectType) < 0) - return; - - Py_INCREF(&PYM_JSObjectType); - PyModule_AddObject(module, "Object", (PyObject *) &PYM_JSObjectType); - - PYM_JSFunctionType.tp_base = &PYM_JSObjectType; - if (!PyType_Ready(&PYM_JSFunctionType) < 0) - return; - - Py_INCREF(&PYM_JSFunctionType); - PyModule_AddObject(module, "Function", (PyObject *) &PYM_JSFunctionType); - - PYM_JSScriptType.tp_base = &PYM_JSObjectType; - if (!PyType_Ready(&PYM_JSScriptType) < 0) - return; - - Py_INCREF(&PYM_JSScriptType); - PyModule_AddObject(module, "Script", (PyObject *) &PYM_JSScriptType); -} diff -r 2b98d4643c44 -r dd32a92f6b4f src/runtime.cpp --- a/src/runtime.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/runtime.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 @@ -151,7 +151,7 @@ PyTypeObject PYM_JSRuntimeType = { PyObject_HEAD_INIT(NULL) 0, /*ob_size*/ - "pymonkey.Runtime", /*tp_name*/ + "pydermonkey.Runtime", /*tp_name*/ sizeof(PYM_JSRuntimeObject), /*tp_basicsize*/ 0, /*tp_itemsize*/ /*tp_dealloc*/ diff -r 2b98d4643c44 -r dd32a92f6b4f src/runtime.h --- a/src/runtime.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/runtime.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/script.cpp --- a/src/script.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/script.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 @@ -90,7 +90,7 @@ PyTypeObject PYM_JSScriptType = { PyObject_HEAD_INIT(NULL) 0, /*ob_size*/ - "pymonkey.Script", /*tp_name*/ + "pydermonkey.Script", /*tp_name*/ sizeof(PYM_JSScript), /*tp_basicsize*/ 0, /*tp_itemsize*/ /*tp_dealloc*/ diff -r 2b98d4643c44 -r dd32a92f6b4f src/script.h --- a/src/script.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/script.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/undefined.cpp --- a/src/undefined.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/undefined.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 @@ -47,13 +47,13 @@ }; static PyObject *PYM_undefinedRepr(PyObject *o) { - return PyString_FromString("pymonkey.undefined"); + return PyString_FromString("pydermonkey.undefined"); } PyTypeObject PYM_undefinedType = { PyObject_HEAD_INIT(NULL) 0, /*ob_size*/ - "pymonkey.undefined", /*tp_name*/ + "pydermonkey.undefined", /*tp_name*/ sizeof(PYM_undefinedObject), /*tp_basicsize*/ 0, /*tp_itemsize*/ 0, /*tp_dealloc*/ diff -r 2b98d4643c44 -r dd32a92f6b4f src/undefined.h --- a/src/undefined.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/undefined.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/utils.cpp --- a/src/utils.cpp Sun Aug 30 20:56:43 2009 -0700 +++ b/src/utils.cpp Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f src/utils.h --- a/src/utils.h Sun Aug 30 20:56:43 2009 -0700 +++ b/src/utils.h Tue Sep 01 03:07:24 2009 -0700 @@ -11,7 +11,7 @@ * for the specific language governing rights and limitations under the * License. * - * The Original Code is Pymonkey. + * The Original Code is Pydermonkey. * * The Initial Developer of the Original Code is Mozilla. * Portions created by the Initial Developer are Copyright (C) 2007 diff -r 2b98d4643c44 -r dd32a92f6b4f tests/test_pydermonkey.py --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tests/test_pydermonkey.py Tue Sep 01 03:07:24 2009 -0700 @@ -0,0 +1,830 @@ +import gc +import sys +import unittest +import weakref +import time +import threading + +import pydermonkey + +class PydermonkeyTests(unittest.TestCase): + def setUp(self): + self._teardowns = [] + + def tearDown(self): + self.last_exception = None + while self._teardowns: + obj = self._teardowns.pop() + runtime = obj.get_runtime() + runtime.new_context().clear_object_private(obj) + del runtime + del obj + self.assertEqual(pydermonkey.get_debug_info()['runtime_count'], 0) + + def _clearOnTeardown(self, obj): + self._teardowns.append(obj) + + def _evaljs(self, code): + rt = pydermonkey.Runtime() + cx = rt.new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + return cx.evaluate_script(obj, code, '', 1) + + def _execjs(self, code): + rt = pydermonkey.Runtime() + cx = rt.new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + script = cx.compile_script(code, '', 1) + return cx.execute_script(obj, script) + + def _evalJsWrappedPyFunc(self, func, code): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.new_function(func, func.__name__) + self._clearOnTeardown(jsfunc) + cx.define_property(obj, func.__name__, jsfunc) + return cx.evaluate_script(obj, code, '', 1) + + def assertRaises(self, exctype, func, *args): + was_raised = False + try: + func(*args) + except exctype, e: + self.last_exception = e + was_raised = True + self.assertTrue(was_raised) + + def testSyntaxErrorsAreRaised(self): + for run in [self._evaljs, self._execjs]: + self.assertRaises(pydermonkey.error, run, '5f') + self.assertEqual( + self.last_exception.args[1], + u'SyntaxError: missing ; before statement' + ) + + def testGetStackOnEmptyStackReturnsNone(self): + cx = pydermonkey.Runtime().new_context() + self.assertEqual(cx.get_stack(), None) + + def testGetStackWorks(self): + stack_holder = [] + + def func(cx, this, args): + stack_holder.append(cx.get_stack()) + + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.new_function(func, func.__name__) + self._clearOnTeardown(jsfunc) + cx.define_property(obj, func.__name__, jsfunc) + cx.evaluate_script(obj, '(function closure() { \nfunc() })()', + '', 1) + stack = stack_holder[0] + script = stack['caller']['caller']['script'] + pc = stack['caller']['caller']['pc'] + closure = stack['caller']['function'] + self.assertEqual(closure.name, 'closure') + self.assertEqual(closure.filename, '') + self.assertEqual(stack['caller']['script'], None) + self.assertEqual(stack['caller']['lineno'], 2) + self.assertEqual(script.filename, '') + self.assertEqual(stack['caller']['caller']['lineno'], 1) + self.assertTrue(pc >= 0 and pc < len(buffer(script))) + self.assertEqual(stack['caller']['caller']['caller'], None) + + def testScriptHasFilenameMember(self): + cx = pydermonkey.Runtime().new_context() + script = cx.compile_script('foo', '', 1) + self.assertEqual(script.filename, '') + + def testScriptHasLineInfo(self): + cx = pydermonkey.Runtime().new_context() + script = cx.compile_script('foo\nbar', '', 1) + self.assertEqual(script.base_lineno, 1) + self.assertEqual(script.line_extent, 2) + + def testScriptIsExposedAsBuffer(self): + rt = pydermonkey.Runtime() + cx = rt.new_context() + script = cx.compile_script('foo', '', 1) + self.assertTrue(len(buffer(script)) > 0) + + def testCompileScriptWorks(self): + self.assertEqual(self._execjs('5 + 1'), 6) + + def testErrorsRaisedIncludeStrings(self): + self.assertRaises(pydermonkey.error, self._evaljs, 'boop()') + self.assertEqual(self.last_exception.args[1], + u'ReferenceError: boop is not defined') + + def testThreadSafetyExceptionIsRaised(self): + stuff = {} + def make_runtime(): + stuff['rt'] = pydermonkey.Runtime() + thread = threading.Thread(target = make_runtime) + thread.start() + thread.join() + self.assertRaises(pydermonkey.error, + stuff['rt'].new_context) + self.assertEqual(self.last_exception.args[0], + 'Function called from wrong thread') + del stuff['rt'] + + def testClearObjectPrivateWorks(self): + class Foo(object): + pass + pyobj = Foo() + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object(pyobj) + pyobj = weakref.ref(pyobj) + self.assertEqual(pyobj(), cx.get_object_private(obj)) + cx.clear_object_private(obj) + self.assertEqual(cx.get_object_private(obj), None) + self.assertEqual(pyobj(), None) + + def testGetObjectPrivateWorks(self): + class Foo(object): + pass + pyobj = Foo() + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object(pyobj) + pyobj = weakref.ref(pyobj) + self.assertEqual(pyobj(), cx.get_object_private(obj)) + del obj + del cx + self.assertEqual(pyobj(), None) + + def testContextSupportsCyclicGc(self): + def makecx(): + cx = pydermonkey.Runtime().new_context() + + def opcb(othercx): + return cx + + cx.set_operation_callback(opcb) + return cx + + gc.disable() + cx = makecx() + wcx = weakref.ref(cx) + self.assertEqual(wcx(), cx) + del cx + self.assertTrue(wcx()) + gc.enable() + gc.collect() + self.assertEqual(wcx(), None) + + def testOperationCallbackIsCalled(self): + def opcb(cx): + raise Exception("stop eet!") + + cx = pydermonkey.Runtime().new_context() + cx.set_operation_callback(opcb) + obj = cx.new_object() + cx.init_standard_classes(obj) + + def watchdog(): + time.sleep(0.1) + cx.trigger_operation_callback() + + thread = threading.Thread(target = watchdog) + thread.start() + + self.assertRaises( + pydermonkey.error, + cx.evaluate_script, + obj, 'while (1) {}', '', 1 + ) + + def testUndefinedStrIsUndefined(self): + self.assertEqual(str(pydermonkey.undefined), + "pydermonkey.undefined") + + def testScriptedJsFuncHasIsPythonFalse(self): + cx = pydermonkey.Runtime().new_context() + jsfunc = cx.evaluate_script(cx.new_object(), + '(function(){})', '', 1) + self.assertFalse(jsfunc.is_python) + + def testJsWrappedPythonFuncHasIsPythonTrue(self): + def foo(cx, this, args): + pass + + cx = pydermonkey.Runtime().new_context() + jsfunc = cx.new_function(foo, foo.__name__) + self.assertTrue(jsfunc.is_python) + + def testJsWrappedPythonFuncHasNoFilename(self): + def foo(cx, this, args): + pass + + cx = pydermonkey.Runtime().new_context() + jsfunc = cx.new_function(foo, foo.__name__) + self.assertEqual(jsfunc.filename, None) + + def testJsScriptedFuncHasNoPrivate(self): + cx = pydermonkey.Runtime().new_context() + jsfunc = cx.evaluate_script(cx.new_object(), + '(function(){})', '', 1) + self.assertEqual(cx.get_object_private(jsfunc), None) + + def testGetPendingExceptionReturnsNone(self): + cx = pydermonkey.Runtime().new_context() + self.assertFalse(cx.is_exception_pending()) + self.assertEqual(cx.get_pending_exception(), None) + + def testThrowHookWorks(self): + exceptions = [] + def throwhook(cx): + self.assertTrue(cx.is_exception_pending()) + exceptions.append(cx.get_pending_exception()) + + cx = pydermonkey.Runtime().new_context() + cx.set_throw_hook(throwhook) + self.assertRaises( + pydermonkey.error, + cx.evaluate_script, + cx.new_object(), + '(function() { throw "hi"; })()', + '', 1 + ) + self.assertEqual(exceptions, ['hi', 'hi']) + self.assertFalse(cx.is_exception_pending()) + self.assertEqual(cx.get_pending_exception(), None) + + def testJsWrappedPythonFuncHasPrivate(self): + def foo(cx, this, args): + pass + + cx = pydermonkey.Runtime().new_context() + jsfunc = cx.new_function(foo, foo.__name__) + self.assertEqual(cx.get_object_private(jsfunc), foo) + + def testJsWrappedPythonFuncIsNotGCd(self): + def define(cx, obj): + def func(cx, this, args): + return u'func was called' + jsfunc = cx.new_function(func, func.__name__) + cx.define_property(obj, func.__name__, jsfunc) + return weakref.ref(func) + rt = pydermonkey.Runtime() + cx = rt.new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + ref = define(cx, obj) + cx.gc() + self.assertNotEqual(ref(), None) + result = cx.evaluate_script(obj, 'func()', '', 1) + self.assertEqual(result, u'func was called') + + # Now ensure that the wrapped function is GC'd when it's + # no longer reachable from JS space. + cx.define_property(obj, 'func', 0) + cx.gc() + self.assertEqual(ref(), None) + + def testCircularJsWrappedPythonFuncIsGCdIfPrivateCleared(self): + def define(cx, obj): + rt = cx.get_runtime() + def func(cx, this, args): + # Oh noes, a circular reference is born! + rt + jsfunc = cx.new_function(func, func.__name__) + cx.define_property(obj, func.__name__, jsfunc) + return (jsfunc, weakref.ref(func)) + rt = pydermonkey.Runtime() + cx = rt.new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc, ref = define(cx, obj) + + # This will break the circular reference. + cx.clear_object_private(jsfunc) + + del jsfunc + del rt + del cx + del obj + self.assertEqual(ref(), None) + + def testFunctionsWithClosuresAreNotIdentical(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + cx.evaluate_script( + obj, "function build(x) { return function foo() { return x; } }", + "", 1 + ) + func1 = cx.evaluate_script(obj, "build(1)", "", 1) + func2 = cx.evaluate_script(obj, "build(2)", "", 1) + self.assertNotEqual(func1, func2) + self.assertEqual(func1.name, 'foo') + self.assertEqual(func1.name, func2.name) + + def testAnonymousJsFunctionHasNullNameAttribute(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.evaluate_script(obj, "(function() {})", + "", 1) + self.assertEqual(jsfunc.name, None) + + def testJsFunctionHasNameAttribute(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.evaluate_script(obj, "(function blarg() {})", + "", 1) + self.assertEqual(jsfunc.name, "blarg") + + def testJsWrappedPythonFuncHasNameAttribute(self): + def func(cx, this, args): + return True + + cx = pydermonkey.Runtime().new_context() + jsfunc = cx.new_function(func, "foo") + self.assertEqual(jsfunc.name, "foo") + + def testJsWrappedPythonFuncIsGCdAtRuntimeDestruction(self): + def define(cx, obj): + def func(cx, this, args): + return u'func was called' + jsfunc = cx.new_function(func, func.__name__) + cx.define_property(obj, func.__name__, jsfunc) + return weakref.ref(func) + rt = pydermonkey.Runtime() + cx = rt.new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + ref = define(cx, obj) + del rt + del cx + del obj + self.assertEqual(ref(), None) + + def testJsWrappedPythonFuncThrowsExcIfPrivateCleared(self): + def func(cx, this, args): + return True + + code = "func()" + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.new_function(func, func.__name__) + cx.define_property(obj, func.__name__, jsfunc) + cx.clear_object_private(jsfunc) + self.assertRaises(pydermonkey.error, + cx.evaluate_script, + obj, code, '', 1) + self.assertEqual( + self._tostring(cx, self.last_exception.args[0]), + "Error: Wrapped Python function no longer exists" + ) + + def testJsWrappedPythonFuncPassesContext(self): + contexts = [] + + def func(cx, this, args): + contexts.append(cx) + return True + + code = "func()" + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.new_function(func, func.__name__) + self._clearOnTeardown(jsfunc) + cx.define_property(obj, func.__name__, jsfunc) + cx.evaluate_script(obj, code, '', 1) + self.assertEqual(contexts[0], cx) + + def testJsWrappedPythonFuncPassesThisArg(self): + thisObjs = [] + + def func(cx, this, args): + thisObjs.append(this) + return True + + code = "func()" + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.new_function(func, func.__name__) + self._clearOnTeardown(jsfunc) + cx.define_property(obj, func.__name__, jsfunc) + cx.evaluate_script(obj, code, '', 1) + self.assertEqual(thisObjs[0], obj) + + def testJsWrappedPythonFuncPassesFuncArgs(self): + funcArgs = [] + + def func(cx, this, args): + funcArgs.append(args) + return True + + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.new_function(func, func.__name__) + self._clearOnTeardown(jsfunc) + + cx.define_property(obj, func.__name__, jsfunc) + + cx.evaluate_script(obj, "func()", '', 1) + self.assertEqual(len(funcArgs[0]), 0) + self.assertTrue(isinstance(funcArgs[0], tuple)) + + cx.evaluate_script(obj, "func(1, 'foo')", '', 1) + self.assertEqual(len(funcArgs[1]), 2) + self.assertEqual(funcArgs[1][0], 1) + self.assertEqual(funcArgs[1][1], u'foo') + + def testJsWrappedPythonFunctionReturnsUnicodeWithEmbeddedNULs(self): + def hai2u(cx, this, args): + return args[0] + u"o hai" + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, + 'hai2u("blah\x00 ")'), + u"blah\x00 o hai") + + def testJsWrappedPythonFunctionReturnsString(self): + def hai2u(cx, this, args): + return "o hai" + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + "o hai") + + def testJsWrappedPythonFunctionReturnsUnicode(self): + def hai2u(cx, this, args): + return u"o hai\u2026" + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + u"o hai\u2026") + + def testJsWrappedPythonFunctionThrowsJsException(self): + def hai2u(cx, this, args): + raise pydermonkey.error(u"blarg") + self.assertRaises(pydermonkey.error, + self._evalJsWrappedPyFunc, + hai2u, 'hai2u()') + self.assertEqual(self.last_exception.args[0], u"blarg") + + def testJsWrappedPythonFunctionThrowsPyException(self): + thecx = [] + def hai2u(cx, this, args): + thecx.append(cx) + raise Exception("hello") + self.assertRaises(pydermonkey.error, + self._evalJsWrappedPyFunc, + hai2u, 'hai2u()') + exc = thecx[0].get_object_private(self.last_exception.args[0]) + self.assertEqual(exc.args[0], "hello") + + def testJsWrappedPythonFunctionReturnsNone(self): + def hai2u(cx, this, args): + pass + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + None) + + def testJsWrappedPythonFunctionReturnsTrue(self): + def hai2u(cx, this, args): + return True + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + True) + + def testJsWrappedPythonFunctionReturnsFalse(self): + def hai2u(cx, this, args): + return False + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + False) + + def testJsWrappedPythonFunctionReturnsSmallInt(self): + def hai2u(cx, this, args): + return 5 + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + 5) + + def testJsWrappedPythonFunctionReturnsFloat(self): + def hai2u(cx, this, args): + return 5.1 + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + 5.1) + + def testJsWrappedPythonFunctionReturnsNegativeInt(self): + def hai2u(cx, this, args): + return -5 + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + -5) + + def testJsWrappedPythonFunctionReturnsBigInt(self): + def hai2u(cx, this, args): + return 2147483647 + self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), + 2147483647) + + def testHasPropertyWorks(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + foo = cx.new_object() + cx.define_property(obj, u"foo\u2026", foo) + self.assertTrue(cx.has_property(obj, u"foo\u2026")) + self.assertFalse(cx.has_property(obj, "bar")) + + def testDefinePropertyWorksWithUnicodePropertyNames(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + foo = cx.new_object() + cx.define_property(obj, u"foo\u2026", foo) + self.assertEqual( + cx.get_property(obj, u"foo\u2026"), + foo + ) + + def testDefinePropertyWorksWithObject(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + foo = cx.new_object() + cx.define_property(obj, "foo", foo) + self.assertEqual( + cx.evaluate_script(obj, 'foo', '', 1), + foo + ) + + def testDefinePropertyWorksWithString(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + foo = cx.new_object() + cx.define_property(obj, "foo", u"hello") + self.assertEqual( + cx.evaluate_script(obj, 'foo', '', 1), + u"hello" + ) + + def testObjectIsIdentityPreserving(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + cx.evaluate_script(obj, 'var foo = {bar: 1}', '', 1) + self.assertTrue(isinstance(cx.get_property(obj, u"foo"), + pydermonkey.Object)) + self.assertTrue(cx.get_property(obj, u"foo") is + cx.get_property(obj, "foo")) + + def testObjectGetattrThrowsException(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + result = cx.evaluate_script(obj, '({get foo() { throw "blah"; }})', + '', 1) + self.assertRaises(pydermonkey.error, + cx.get_property, + result, + u"foo") + self.assertEqual(self.last_exception.args[0], u"blah") + + def testInfiniteRecursionRaisesError(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + self.assertRaises( + pydermonkey.error, + cx.evaluate_script, + obj, '(function foo() { foo(); })();', '', 1 + ) + self.assertEqual( + self._tostring(cx, self.last_exception.args[0]), + "InternalError: too much recursion" + ) + + def testObjectGetattrWorks(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + cx.evaluate_script(obj, 'var boop = 5', '', 1) + cx.evaluate_script(obj, 'this["blarg\u2026"] = 5', '', 1) + self.assertEqual(cx.get_property(obj, u"beans"), + pydermonkey.undefined) + self.assertEqual(cx.get_property(obj, u"blarg\u2026"), 5) + self.assertEqual(cx.get_property(obj, u"boop"), 5) + + def testContextIsInstance(self): + cx = pydermonkey.Runtime().new_context() + self.assertTrue(isinstance(cx, pydermonkey.Context)) + + def testContextTypeCannotBeInstantiated(self): + self.assertRaises(TypeError, pydermonkey.Context) + + def testObjectIsInstance(self): + obj = pydermonkey.Runtime().new_context().new_object() + self.assertTrue(isinstance(obj, pydermonkey.Object)) + self.assertFalse(isinstance(obj, pydermonkey.Function)) + + def testObjectTypeCannotBeInstantiated(self): + self.assertRaises(TypeError, pydermonkey.Object) + + def testFunctionIsInstance(self): + def boop(): + pass + obj = pydermonkey.Runtime().new_context().new_function(boop, "boop") + self.assertTrue(isinstance(obj, pydermonkey.Object)) + self.assertTrue(isinstance(obj, pydermonkey.Function)) + + def testFunctionTypeCannotBeInstantiated(self): + self.assertRaises(TypeError, pydermonkey.Function) + + def testObjectGetRuntimeWorks(self): + rt = pydermonkey.Runtime() + obj = rt.new_context().new_object() + self.assertEqual(obj.get_runtime(), rt) + + def testContextGetRuntimeWorks(self): + rt = pydermonkey.Runtime() + cx = rt.new_context() + self.assertEqual(cx.get_runtime(), rt) + + def testRuntimesAreWeakReferencable(self): + rt = pydermonkey.Runtime() + wrt = weakref.ref(rt) + self.assertEqual(rt, wrt()) + del rt + self.assertEqual(wrt(), None) + + def testContextsAreWeakReferencable(self): + rt = pydermonkey.Runtime() + cx = rt.new_context() + wcx = weakref.ref(cx) + self.assertEqual(cx, wcx()) + del cx + self.assertEqual(wcx(), None) + + def testUndefinedCannotBeInstantiated(self): + self.assertRaises(TypeError, pydermonkey.undefined) + + def testEvaluateThrowsException(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + self.assertRaises(pydermonkey.error, + cx.evaluate_script, + obj, 'hai2u()', '', 1) + self.assertEqual(self._tostring(cx, + self.last_exception.args[0]), + 'ReferenceError: hai2u is not defined') + + def testThrowingObjWithBadToStringWorks(self): + self.assertRaises( + pydermonkey.error, + self._evaljs, + "throw {toString: function() { throw 'dujg' }}" + ) + self.assertEqual( + self.last_exception.args[1], + "" + ) + + def testEvaluateTakesUnicodeCode(self): + self.assertEqual(self._evaljs(u"'foo\u2026'"), + u"foo\u2026") + + def testEvaluateReturnsUndefined(self): + retval = self._evaljs("") + self.assertTrue(retval is pydermonkey.undefined) + + def testEvaludateReturnsUnicodeWithEmbeddedNULs(self): + retval = self._evaljs("'\x00hi'") + self.assertEqual(retval, u'\x00hi') + + def testEvaluateReturnsSMPUnicode(self): + # This is 'LINEAR B SYLLABLE B008 A', in the supplementary + # multilingual plane (SMP). + retval = self._evaljs("'\uD800\uDC00'") + self.assertEqual(retval, u'\U00010000') + self.assertEqual(retval.encode('utf-16'), + '\xff\xfe\x00\xd8\x00\xdc') + + def testEvaluateReturnsBMPUnicode(self): + retval = self._evaljs("'o hai\u2026'") + self.assertTrue(type(retval) == unicode) + self.assertEqual(retval, u'o hai\u2026') + + def testEvaluateReturnsObject(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + obj = cx.evaluate_script(obj, '({boop: 1})', '', 1) + self.assertTrue(isinstance(obj, pydermonkey.Object)) + self.assertEqual(cx.get_property(obj, u"boop"), 1) + + def testScriptedFunctionsHaveFilenameInfo(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + jsfunc = cx.evaluate_script(obj, + '(function boop() { \nreturn 1; })', + 'somefile', 5) + self.assertEqual(jsfunc.filename, 'somefile') + self.assertEqual(jsfunc.base_lineno, 5) + self.assertEqual(jsfunc.line_extent, 2) + + def testEvaluateReturnsFunction(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + cx.init_standard_classes(obj) + obj = cx.evaluate_script(obj, '(function boop() { return 1; })', + '', 1) + self.assertTrue(isinstance(obj, pydermonkey.Function)) + + def testJsExceptionStateIsClearedAfterExceptionIsCaught(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + self.assertRaises(pydermonkey.error, + cx.evaluate_script, + obj, 'blah()', '', 1) + self.assertEqual(cx.evaluate_script(obj, '5+3', '', 1), + 8) + + def testCallFunctionRaisesErrorOnBadFuncArgs(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + obj = cx.evaluate_script( + obj, + '(function boop(a, b) { return a+b+this.c; })', + '', 1 + ) + self.assertRaises( + NotImplementedError, + cx.call_function, + obj, obj, (1, self) + ) + + def _tostring(self, cx, obj): + return cx.call_function(obj, + cx.get_property(obj, u"toString"), + ()) + + def testCallFunctionRaisesErrorFromJS(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + obj = cx.evaluate_script( + obj, + '(function boop(a, b) { blarg(); })', + '', 1 + ) + self.assertRaises(pydermonkey.error, + cx.call_function, + obj, obj, (1,)) + self.assertEqual(self._tostring(cx, + self.last_exception.args[0]), + 'ReferenceError: blarg is not defined') + + def testInitStandardClassesRaisesExcOnRuntimeMismatch(self): + cx2 = pydermonkey.Runtime().new_context() + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + self.assertRaises(ValueError, + cx2.init_standard_classes, + obj) + self.assertEqual(self.last_exception.args[0], + 'JS runtime mismatch') + + def testCallFunctionWorks(self): + cx = pydermonkey.Runtime().new_context() + obj = cx.new_object() + thisArg = cx.new_object() + cx.define_property(thisArg, "c", 3) + cx.init_standard_classes(obj) + obj = cx.evaluate_script( + obj, + '(function boop(a, b) { return a+b+this.c; })', + '', 1 + ) + self.assertEqual(cx.call_function(thisArg, obj, (1,2)), 6) + + def testEvaluateReturnsTrue(self): + self.assertTrue(self._evaljs('true') is True) + + def testEvaluateReturnsFalse(self): + self.assertTrue(self._evaljs('false') is False) + + def testEvaluateReturnsNone(self): + self.assertTrue(self._evaljs('null') is None) + + def testEvaluateReturnsIntegers(self): + self.assertEqual(self._evaljs('1+3'), 4) + + def testEvaluateReturnsNegativeIntegers(self): + self.assertEqual(self._evaljs('-5'), -5) + + def testEvaluateReturnsBigIntegers(self): + self.assertEqual(self._evaljs('2147483647*2'), + 2147483647*2) + + def testEvaluateReturnsFloats(self): + self.assertEqual(self._evaljs('1.1+3'), 4.1) + +if __name__ == '__main__': + unittest.main() diff -r 2b98d4643c44 -r dd32a92f6b4f tests/test_pymonkey.py --- a/tests/test_pymonkey.py Sun Aug 30 20:56:43 2009 -0700 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,830 +0,0 @@ -import gc -import sys -import unittest -import weakref -import time -import threading - -import pymonkey - -class PymonkeyTests(unittest.TestCase): - def setUp(self): - self._teardowns = [] - - def tearDown(self): - self.last_exception = None - while self._teardowns: - obj = self._teardowns.pop() - runtime = obj.get_runtime() - runtime.new_context().clear_object_private(obj) - del runtime - del obj - self.assertEqual(pymonkey.get_debug_info()['runtime_count'], 0) - - def _clearOnTeardown(self, obj): - self._teardowns.append(obj) - - def _evaljs(self, code): - rt = pymonkey.Runtime() - cx = rt.new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - return cx.evaluate_script(obj, code, '', 1) - - def _execjs(self, code): - rt = pymonkey.Runtime() - cx = rt.new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - script = cx.compile_script(code, '', 1) - return cx.execute_script(obj, script) - - def _evalJsWrappedPyFunc(self, func, code): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.new_function(func, func.__name__) - self._clearOnTeardown(jsfunc) - cx.define_property(obj, func.__name__, jsfunc) - return cx.evaluate_script(obj, code, '', 1) - - def assertRaises(self, exctype, func, *args): - was_raised = False - try: - func(*args) - except exctype, e: - self.last_exception = e - was_raised = True - self.assertTrue(was_raised) - - def testSyntaxErrorsAreRaised(self): - for run in [self._evaljs, self._execjs]: - self.assertRaises(pymonkey.error, run, '5f') - self.assertEqual( - self.last_exception.args[1], - u'SyntaxError: missing ; before statement' - ) - - def testGetStackOnEmptyStackReturnsNone(self): - cx = pymonkey.Runtime().new_context() - self.assertEqual(cx.get_stack(), None) - - def testGetStackWorks(self): - stack_holder = [] - - def func(cx, this, args): - stack_holder.append(cx.get_stack()) - - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.new_function(func, func.__name__) - self._clearOnTeardown(jsfunc) - cx.define_property(obj, func.__name__, jsfunc) - cx.evaluate_script(obj, '(function closure() { \nfunc() })()', - '', 1) - stack = stack_holder[0] - script = stack['caller']['caller']['script'] - pc = stack['caller']['caller']['pc'] - closure = stack['caller']['function'] - self.assertEqual(closure.name, 'closure') - self.assertEqual(closure.filename, '') - self.assertEqual(stack['caller']['script'], None) - self.assertEqual(stack['caller']['lineno'], 2) - self.assertEqual(script.filename, '') - self.assertEqual(stack['caller']['caller']['lineno'], 1) - self.assertTrue(pc >= 0 and pc < len(buffer(script))) - self.assertEqual(stack['caller']['caller']['caller'], None) - - def testScriptHasFilenameMember(self): - cx = pymonkey.Runtime().new_context() - script = cx.compile_script('foo', '', 1) - self.assertEqual(script.filename, '') - - def testScriptHasLineInfo(self): - cx = pymonkey.Runtime().new_context() - script = cx.compile_script('foo\nbar', '', 1) - self.assertEqual(script.base_lineno, 1) - self.assertEqual(script.line_extent, 2) - - def testScriptIsExposedAsBuffer(self): - rt = pymonkey.Runtime() - cx = rt.new_context() - script = cx.compile_script('foo', '', 1) - self.assertTrue(len(buffer(script)) > 0) - - def testCompileScriptWorks(self): - self.assertEqual(self._execjs('5 + 1'), 6) - - def testErrorsRaisedIncludeStrings(self): - self.assertRaises(pymonkey.error, self._evaljs, 'boop()') - self.assertEqual(self.last_exception.args[1], - u'ReferenceError: boop is not defined') - - def testThreadSafetyExceptionIsRaised(self): - stuff = {} - def make_runtime(): - stuff['rt'] = pymonkey.Runtime() - thread = threading.Thread(target = make_runtime) - thread.start() - thread.join() - self.assertRaises(pymonkey.error, - stuff['rt'].new_context) - self.assertEqual(self.last_exception.args[0], - 'Function called from wrong thread') - del stuff['rt'] - - def testClearObjectPrivateWorks(self): - class Foo(object): - pass - pyobj = Foo() - cx = pymonkey.Runtime().new_context() - obj = cx.new_object(pyobj) - pyobj = weakref.ref(pyobj) - self.assertEqual(pyobj(), cx.get_object_private(obj)) - cx.clear_object_private(obj) - self.assertEqual(cx.get_object_private(obj), None) - self.assertEqual(pyobj(), None) - - def testGetObjectPrivateWorks(self): - class Foo(object): - pass - pyobj = Foo() - cx = pymonkey.Runtime().new_context() - obj = cx.new_object(pyobj) - pyobj = weakref.ref(pyobj) - self.assertEqual(pyobj(), cx.get_object_private(obj)) - del obj - del cx - self.assertEqual(pyobj(), None) - - def testContextSupportsCyclicGc(self): - def makecx(): - cx = pymonkey.Runtime().new_context() - - def opcb(othercx): - return cx - - cx.set_operation_callback(opcb) - return cx - - gc.disable() - cx = makecx() - wcx = weakref.ref(cx) - self.assertEqual(wcx(), cx) - del cx - self.assertTrue(wcx()) - gc.enable() - gc.collect() - self.assertEqual(wcx(), None) - - def testOperationCallbackIsCalled(self): - def opcb(cx): - raise Exception("stop eet!") - - cx = pymonkey.Runtime().new_context() - cx.set_operation_callback(opcb) - obj = cx.new_object() - cx.init_standard_classes(obj) - - def watchdog(): - time.sleep(0.1) - cx.trigger_operation_callback() - - thread = threading.Thread(target = watchdog) - thread.start() - - self.assertRaises( - pymonkey.error, - cx.evaluate_script, - obj, 'while (1) {}', '', 1 - ) - - def testUndefinedStrIsUndefined(self): - self.assertEqual(str(pymonkey.undefined), - "pymonkey.undefined") - - def testScriptedJsFuncHasIsPythonFalse(self): - cx = pymonkey.Runtime().new_context() - jsfunc = cx.evaluate_script(cx.new_object(), - '(function(){})', '', 1) - self.assertFalse(jsfunc.is_python) - - def testJsWrappedPythonFuncHasIsPythonTrue(self): - def foo(cx, this, args): - pass - - cx = pymonkey.Runtime().new_context() - jsfunc = cx.new_function(foo, foo.__name__) - self.assertTrue(jsfunc.is_python) - - def testJsWrappedPythonFuncHasNoFilename(self): - def foo(cx, this, args): - pass - - cx = pymonkey.Runtime().new_context() - jsfunc = cx.new_function(foo, foo.__name__) - self.assertEqual(jsfunc.filename, None) - - def testJsScriptedFuncHasNoPrivate(self): - cx = pymonkey.Runtime().new_context() - jsfunc = cx.evaluate_script(cx.new_object(), - '(function(){})', '', 1) - self.assertEqual(cx.get_object_private(jsfunc), None) - - def testGetPendingExceptionReturnsNone(self): - cx = pymonkey.Runtime().new_context() - self.assertFalse(cx.is_exception_pending()) - self.assertEqual(cx.get_pending_exception(), None) - - def testThrowHookWorks(self): - exceptions = [] - def throwhook(cx): - self.assertTrue(cx.is_exception_pending()) - exceptions.append(cx.get_pending_exception()) - - cx = pymonkey.Runtime().new_context() - cx.set_throw_hook(throwhook) - self.assertRaises( - pymonkey.error, - cx.evaluate_script, - cx.new_object(), - '(function() { throw "hi"; })()', - '', 1 - ) - self.assertEqual(exceptions, ['hi', 'hi']) - self.assertFalse(cx.is_exception_pending()) - self.assertEqual(cx.get_pending_exception(), None) - - def testJsWrappedPythonFuncHasPrivate(self): - def foo(cx, this, args): - pass - - cx = pymonkey.Runtime().new_context() - jsfunc = cx.new_function(foo, foo.__name__) - self.assertEqual(cx.get_object_private(jsfunc), foo) - - def testJsWrappedPythonFuncIsNotGCd(self): - def define(cx, obj): - def func(cx, this, args): - return u'func was called' - jsfunc = cx.new_function(func, func.__name__) - cx.define_property(obj, func.__name__, jsfunc) - return weakref.ref(func) - rt = pymonkey.Runtime() - cx = rt.new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - ref = define(cx, obj) - cx.gc() - self.assertNotEqual(ref(), None) - result = cx.evaluate_script(obj, 'func()', '', 1) - self.assertEqual(result, u'func was called') - - # Now ensure that the wrapped function is GC'd when it's - # no longer reachable from JS space. - cx.define_property(obj, 'func', 0) - cx.gc() - self.assertEqual(ref(), None) - - def testCircularJsWrappedPythonFuncIsGCdIfPrivateCleared(self): - def define(cx, obj): - rt = cx.get_runtime() - def func(cx, this, args): - # Oh noes, a circular reference is born! - rt - jsfunc = cx.new_function(func, func.__name__) - cx.define_property(obj, func.__name__, jsfunc) - return (jsfunc, weakref.ref(func)) - rt = pymonkey.Runtime() - cx = rt.new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc, ref = define(cx, obj) - - # This will break the circular reference. - cx.clear_object_private(jsfunc) - - del jsfunc - del rt - del cx - del obj - self.assertEqual(ref(), None) - - def testFunctionsWithClosuresAreNotIdentical(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - cx.evaluate_script( - obj, "function build(x) { return function foo() { return x; } }", - "", 1 - ) - func1 = cx.evaluate_script(obj, "build(1)", "", 1) - func2 = cx.evaluate_script(obj, "build(2)", "", 1) - self.assertNotEqual(func1, func2) - self.assertEqual(func1.name, 'foo') - self.assertEqual(func1.name, func2.name) - - def testAnonymousJsFunctionHasNullNameAttribute(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.evaluate_script(obj, "(function() {})", - "", 1) - self.assertEqual(jsfunc.name, None) - - def testJsFunctionHasNameAttribute(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.evaluate_script(obj, "(function blarg() {})", - "", 1) - self.assertEqual(jsfunc.name, "blarg") - - def testJsWrappedPythonFuncHasNameAttribute(self): - def func(cx, this, args): - return True - - cx = pymonkey.Runtime().new_context() - jsfunc = cx.new_function(func, "foo") - self.assertEqual(jsfunc.name, "foo") - - def testJsWrappedPythonFuncIsGCdAtRuntimeDestruction(self): - def define(cx, obj): - def func(cx, this, args): - return u'func was called' - jsfunc = cx.new_function(func, func.__name__) - cx.define_property(obj, func.__name__, jsfunc) - return weakref.ref(func) - rt = pymonkey.Runtime() - cx = rt.new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - ref = define(cx, obj) - del rt - del cx - del obj - self.assertEqual(ref(), None) - - def testJsWrappedPythonFuncThrowsExcIfPrivateCleared(self): - def func(cx, this, args): - return True - - code = "func()" - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.new_function(func, func.__name__) - cx.define_property(obj, func.__name__, jsfunc) - cx.clear_object_private(jsfunc) - self.assertRaises(pymonkey.error, - cx.evaluate_script, - obj, code, '', 1) - self.assertEqual( - self._tostring(cx, self.last_exception.args[0]), - "Error: Wrapped Python function no longer exists" - ) - - def testJsWrappedPythonFuncPassesContext(self): - contexts = [] - - def func(cx, this, args): - contexts.append(cx) - return True - - code = "func()" - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.new_function(func, func.__name__) - self._clearOnTeardown(jsfunc) - cx.define_property(obj, func.__name__, jsfunc) - cx.evaluate_script(obj, code, '', 1) - self.assertEqual(contexts[0], cx) - - def testJsWrappedPythonFuncPassesThisArg(self): - thisObjs = [] - - def func(cx, this, args): - thisObjs.append(this) - return True - - code = "func()" - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.new_function(func, func.__name__) - self._clearOnTeardown(jsfunc) - cx.define_property(obj, func.__name__, jsfunc) - cx.evaluate_script(obj, code, '', 1) - self.assertEqual(thisObjs[0], obj) - - def testJsWrappedPythonFuncPassesFuncArgs(self): - funcArgs = [] - - def func(cx, this, args): - funcArgs.append(args) - return True - - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.new_function(func, func.__name__) - self._clearOnTeardown(jsfunc) - - cx.define_property(obj, func.__name__, jsfunc) - - cx.evaluate_script(obj, "func()", '', 1) - self.assertEqual(len(funcArgs[0]), 0) - self.assertTrue(isinstance(funcArgs[0], tuple)) - - cx.evaluate_script(obj, "func(1, 'foo')", '', 1) - self.assertEqual(len(funcArgs[1]), 2) - self.assertEqual(funcArgs[1][0], 1) - self.assertEqual(funcArgs[1][1], u'foo') - - def testJsWrappedPythonFunctionReturnsUnicodeWithEmbeddedNULs(self): - def hai2u(cx, this, args): - return args[0] + u"o hai" - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, - 'hai2u("blah\x00 ")'), - u"blah\x00 o hai") - - def testJsWrappedPythonFunctionReturnsString(self): - def hai2u(cx, this, args): - return "o hai" - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - "o hai") - - def testJsWrappedPythonFunctionReturnsUnicode(self): - def hai2u(cx, this, args): - return u"o hai\u2026" - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - u"o hai\u2026") - - def testJsWrappedPythonFunctionThrowsJsException(self): - def hai2u(cx, this, args): - raise pymonkey.error(u"blarg") - self.assertRaises(pymonkey.error, - self._evalJsWrappedPyFunc, - hai2u, 'hai2u()') - self.assertEqual(self.last_exception.args[0], u"blarg") - - def testJsWrappedPythonFunctionThrowsPyException(self): - thecx = [] - def hai2u(cx, this, args): - thecx.append(cx) - raise Exception("hello") - self.assertRaises(pymonkey.error, - self._evalJsWrappedPyFunc, - hai2u, 'hai2u()') - exc = thecx[0].get_object_private(self.last_exception.args[0]) - self.assertEqual(exc.args[0], "hello") - - def testJsWrappedPythonFunctionReturnsNone(self): - def hai2u(cx, this, args): - pass - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - None) - - def testJsWrappedPythonFunctionReturnsTrue(self): - def hai2u(cx, this, args): - return True - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - True) - - def testJsWrappedPythonFunctionReturnsFalse(self): - def hai2u(cx, this, args): - return False - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - False) - - def testJsWrappedPythonFunctionReturnsSmallInt(self): - def hai2u(cx, this, args): - return 5 - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - 5) - - def testJsWrappedPythonFunctionReturnsFloat(self): - def hai2u(cx, this, args): - return 5.1 - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - 5.1) - - def testJsWrappedPythonFunctionReturnsNegativeInt(self): - def hai2u(cx, this, args): - return -5 - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - -5) - - def testJsWrappedPythonFunctionReturnsBigInt(self): - def hai2u(cx, this, args): - return 2147483647 - self.assertEqual(self._evalJsWrappedPyFunc(hai2u, 'hai2u()'), - 2147483647) - - def testHasPropertyWorks(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - foo = cx.new_object() - cx.define_property(obj, u"foo\u2026", foo) - self.assertTrue(cx.has_property(obj, u"foo\u2026")) - self.assertFalse(cx.has_property(obj, "bar")) - - def testDefinePropertyWorksWithUnicodePropertyNames(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - foo = cx.new_object() - cx.define_property(obj, u"foo\u2026", foo) - self.assertEqual( - cx.get_property(obj, u"foo\u2026"), - foo - ) - - def testDefinePropertyWorksWithObject(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - foo = cx.new_object() - cx.define_property(obj, "foo", foo) - self.assertEqual( - cx.evaluate_script(obj, 'foo', '', 1), - foo - ) - - def testDefinePropertyWorksWithString(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - foo = cx.new_object() - cx.define_property(obj, "foo", u"hello") - self.assertEqual( - cx.evaluate_script(obj, 'foo', '', 1), - u"hello" - ) - - def testObjectIsIdentityPreserving(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - cx.evaluate_script(obj, 'var foo = {bar: 1}', '', 1) - self.assertTrue(isinstance(cx.get_property(obj, u"foo"), - pymonkey.Object)) - self.assertTrue(cx.get_property(obj, u"foo") is - cx.get_property(obj, "foo")) - - def testObjectGetattrThrowsException(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - result = cx.evaluate_script(obj, '({get foo() { throw "blah"; }})', - '', 1) - self.assertRaises(pymonkey.error, - cx.get_property, - result, - u"foo") - self.assertEqual(self.last_exception.args[0], u"blah") - - def testInfiniteRecursionRaisesError(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - self.assertRaises( - pymonkey.error, - cx.evaluate_script, - obj, '(function foo() { foo(); })();', '', 1 - ) - self.assertEqual( - self._tostring(cx, self.last_exception.args[0]), - "InternalError: too much recursion" - ) - - def testObjectGetattrWorks(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - cx.evaluate_script(obj, 'var boop = 5', '', 1) - cx.evaluate_script(obj, 'this["blarg\u2026"] = 5', '', 1) - self.assertEqual(cx.get_property(obj, u"beans"), - pymonkey.undefined) - self.assertEqual(cx.get_property(obj, u"blarg\u2026"), 5) - self.assertEqual(cx.get_property(obj, u"boop"), 5) - - def testContextIsInstance(self): - cx = pymonkey.Runtime().new_context() - self.assertTrue(isinstance(cx, pymonkey.Context)) - - def testContextTypeCannotBeInstantiated(self): - self.assertRaises(TypeError, pymonkey.Context) - - def testObjectIsInstance(self): - obj = pymonkey.Runtime().new_context().new_object() - self.assertTrue(isinstance(obj, pymonkey.Object)) - self.assertFalse(isinstance(obj, pymonkey.Function)) - - def testObjectTypeCannotBeInstantiated(self): - self.assertRaises(TypeError, pymonkey.Object) - - def testFunctionIsInstance(self): - def boop(): - pass - obj = pymonkey.Runtime().new_context().new_function(boop, "boop") - self.assertTrue(isinstance(obj, pymonkey.Object)) - self.assertTrue(isinstance(obj, pymonkey.Function)) - - def testFunctionTypeCannotBeInstantiated(self): - self.assertRaises(TypeError, pymonkey.Function) - - def testObjectGetRuntimeWorks(self): - rt = pymonkey.Runtime() - obj = rt.new_context().new_object() - self.assertEqual(obj.get_runtime(), rt) - - def testContextGetRuntimeWorks(self): - rt = pymonkey.Runtime() - cx = rt.new_context() - self.assertEqual(cx.get_runtime(), rt) - - def testRuntimesAreWeakReferencable(self): - rt = pymonkey.Runtime() - wrt = weakref.ref(rt) - self.assertEqual(rt, wrt()) - del rt - self.assertEqual(wrt(), None) - - def testContextsAreWeakReferencable(self): - rt = pymonkey.Runtime() - cx = rt.new_context() - wcx = weakref.ref(cx) - self.assertEqual(cx, wcx()) - del cx - self.assertEqual(wcx(), None) - - def testUndefinedCannotBeInstantiated(self): - self.assertRaises(TypeError, pymonkey.undefined) - - def testEvaluateThrowsException(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - self.assertRaises(pymonkey.error, - cx.evaluate_script, - obj, 'hai2u()', '', 1) - self.assertEqual(self._tostring(cx, - self.last_exception.args[0]), - 'ReferenceError: hai2u is not defined') - - def testThrowingObjWithBadToStringWorks(self): - self.assertRaises( - pymonkey.error, - self._evaljs, - "throw {toString: function() { throw 'dujg' }}" - ) - self.assertEqual( - self.last_exception.args[1], - "" - ) - - def testEvaluateTakesUnicodeCode(self): - self.assertEqual(self._evaljs(u"'foo\u2026'"), - u"foo\u2026") - - def testEvaluateReturnsUndefined(self): - retval = self._evaljs("") - self.assertTrue(retval is pymonkey.undefined) - - def testEvaludateReturnsUnicodeWithEmbeddedNULs(self): - retval = self._evaljs("'\x00hi'") - self.assertEqual(retval, u'\x00hi') - - def testEvaluateReturnsSMPUnicode(self): - # This is 'LINEAR B SYLLABLE B008 A', in the supplementary - # multilingual plane (SMP). - retval = self._evaljs("'\uD800\uDC00'") - self.assertEqual(retval, u'\U00010000') - self.assertEqual(retval.encode('utf-16'), - '\xff\xfe\x00\xd8\x00\xdc') - - def testEvaluateReturnsBMPUnicode(self): - retval = self._evaljs("'o hai\u2026'") - self.assertTrue(type(retval) == unicode) - self.assertEqual(retval, u'o hai\u2026') - - def testEvaluateReturnsObject(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - obj = cx.evaluate_script(obj, '({boop: 1})', '', 1) - self.assertTrue(isinstance(obj, pymonkey.Object)) - self.assertEqual(cx.get_property(obj, u"boop"), 1) - - def testScriptedFunctionsHaveFilenameInfo(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - jsfunc = cx.evaluate_script(obj, - '(function boop() { \nreturn 1; })', - 'somefile', 5) - self.assertEqual(jsfunc.filename, 'somefile') - self.assertEqual(jsfunc.base_lineno, 5) - self.assertEqual(jsfunc.line_extent, 2) - - def testEvaluateReturnsFunction(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - cx.init_standard_classes(obj) - obj = cx.evaluate_script(obj, '(function boop() { return 1; })', - '', 1) - self.assertTrue(isinstance(obj, pymonkey.Function)) - - def testJsExceptionStateIsClearedAfterExceptionIsCaught(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - self.assertRaises(pymonkey.error, - cx.evaluate_script, - obj, 'blah()', '', 1) - self.assertEqual(cx.evaluate_script(obj, '5+3', '', 1), - 8) - - def testCallFunctionRaisesErrorOnBadFuncArgs(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - obj = cx.evaluate_script( - obj, - '(function boop(a, b) { return a+b+this.c; })', - '', 1 - ) - self.assertRaises( - NotImplementedError, - cx.call_function, - obj, obj, (1, self) - ) - - def _tostring(self, cx, obj): - return cx.call_function(obj, - cx.get_property(obj, u"toString"), - ()) - - def testCallFunctionRaisesErrorFromJS(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - obj = cx.evaluate_script( - obj, - '(function boop(a, b) { blarg(); })', - '', 1 - ) - self.assertRaises(pymonkey.error, - cx.call_function, - obj, obj, (1,)) - self.assertEqual(self._tostring(cx, - self.last_exception.args[0]), - 'ReferenceError: blarg is not defined') - - def testInitStandardClassesRaisesExcOnRuntimeMismatch(self): - cx2 = pymonkey.Runtime().new_context() - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - self.assertRaises(ValueError, - cx2.init_standard_classes, - obj) - self.assertEqual(self.last_exception.args[0], - 'JS runtime mismatch') - - def testCallFunctionWorks(self): - cx = pymonkey.Runtime().new_context() - obj = cx.new_object() - thisArg = cx.new_object() - cx.define_property(thisArg, "c", 3) - cx.init_standard_classes(obj) - obj = cx.evaluate_script( - obj, - '(function boop(a, b) { return a+b+this.c; })', - '', 1 - ) - self.assertEqual(cx.call_function(thisArg, obj, (1,2)), 6) - - def testEvaluateReturnsTrue(self): - self.assertTrue(self._evaljs('true') is True) - - def testEvaluateReturnsFalse(self): - self.assertTrue(self._evaljs('false') is False) - - def testEvaluateReturnsNone(self): - self.assertTrue(self._evaljs('null') is None) - - def testEvaluateReturnsIntegers(self): - self.assertEqual(self._evaljs('1+3'), 4) - - def testEvaluateReturnsNegativeIntegers(self): - self.assertEqual(self._evaljs('-5'), -5) - - def testEvaluateReturnsBigIntegers(self): - self.assertEqual(self._evaljs('2147483647*2'), - 2147483647*2) - - def testEvaluateReturnsFloats(self): - self.assertEqual(self._evaljs('1.1+3'), 4.1) - -if __name__ == '__main__': - unittest.main()