rapydscript-ns 0.8.2 → 0.8.3

package/README.md

@@ -108,9 +108,6 @@ Here are a few features of RapydScript:
 - similar to above, ability to use both, Python's and JavaScript's tutorials (as well as widgets)
 - it's self-hosting, that means the compiler is itself written in RapydScript and compiles into JavaScript
 
-Let's not waste any more time with the introductions, however. The best way to
-learn a new language/framework is to dive in.
-
 
 Installation
 ------------
@@ -357,17 +354,10 @@ math_ops = {
 }
 ```
 
-I'm sure you will agree that the above code is cleaner than declaring 5
-temporary variables first and assigning them to the object literal keys after.
 Note that the example puts the function header (def()) and content on the same
-line. I'll refer to it as function inlining. This is meant as a feature of
-RapydScript to make the code cleaner in cases like the example above. While you
-can use it in longer functions by chaining statements together using `;`, a
-good rule of thumb (to keep your code clean) is if your function needs
-semi-colons ask yourself whether you should be inlining, and if it needs more
-than 2 semi-colons, the answer is probably no (note that you can also use
-semi-colons as newline separators within functions that aren't inlined, as in
-the example in the previous section).
+line (function inlining). This is a feature of RapydScript that can be used
+to make the code cleaner in cases like the example above. You can also use it 
+in longer functions by chaining statements together using `;`.
 
 
 Lambda Expressions
@@ -543,7 +533,7 @@ $(element)\
 	.show()
 ```
 
-Some of you might welcome this feature, some of you might not. RapydScript always aims to make its unique features unobtrusive to regular Python, which means that you don't have to use them if you disagree with them. Recently, we have enhanced this feature to handle `do/while` loops as well:
+This feature handles `do/while` loops as well:
 
 ```js
 a = 0
@@ -646,7 +636,9 @@ into the names optional parameters you specified in the function definition.
 
 Inferred Tuple Packing/Unpacking
 --------------------------------
-Like Python, RapydScript allows inferred tuple packing/unpacking and assignment. While inferred/implicit logic is usually bad, it can sometimes make the code cleaner, and based on the order of statements in the Zen of Python, 'beautiful' takes priority over 'explicit'. For example, if you wanted to swap two variables, the following looks cleaner than explicitly declaring a temporary variable:
+Like Python, RapydScript allows inferred tuple packing/unpacking and assignment. For 
+example, if you wanted to swap two variables, the following is simpler than explicitly 
+declaring a temporary variable:
 
 ```py
 a, b = b, a
@@ -766,14 +758,19 @@ Containers (lists/sets/dicts)
 ### Lists
 
 Lists in RapydScript are almost identical to lists in Python, but are also
-native JavaScript arrays. The only small caveats are that the ``sort()`` and
-``pop()`` methods are renamed to ``pysort()`` and ``pypop()``. This is so that
-you can pass RapydScript lists to external JavaScript libraries without any
-conflicts. Note that even list literals in RapydScript create python like list
-objects, and you can also use the builtin ``list()`` function to create lists
-from other iterable objects, just as you would in python.  You can create a
-RapydScript list from a plain native JavaScript array by using the ``list_wrap()``
-function, like this:
+native JavaScript arrays. The ``sort()`` and ``pop()`` methods behave exactly
+as in Python: ``sort()`` performs a numeric sort (in-place, with optional ``key``
+and ``reverse`` arguments) and ``pop()`` performs a bounds-checked pop (raises
+``IndexError`` for out-of-bounds indices). If you need the native JavaScript
+behavior for interop with external JS libraries, use ``jssort()`` (lexicographic
+sort) and ``jspop()`` (no bounds check, always pops the last element). The old
+``pysort()`` and ``pypop()`` names are kept as backward-compatible aliases.
+
+Note that even list literals in RapydScript create Python-like list objects,
+and you can also use the builtin ``list()`` function to create lists from other
+iterable objects, just as you would in Python. You can create a RapydScript
+list from a plain native JavaScript array by using the ``list_wrap()`` function,
+like this:
 
 ```py
 a = v'[1, 2]'
@@ -781,6 +778,29 @@ pya = list_wrap(a)
  # Now pya is a python like list object that satisfies pya === a
 ```
 
+### List Concatenation
+
+The `+` operator concatenates two lists and returns a new list, exactly as in Python:
+
+```py
+a = [1, 2]
+b = [3, 4]
+c = a + b   # [1, 2, 3, 4]  — a and b are unchanged
+```
+
+The `+=` operator extends a list in-place (the original list object is mutated):
+
+```py
+a = [1, 2]
+ref = a      # ref and a point to the same list
+a += [3, 4]  # mutates a in-place
+print(ref)   # [1, 2, 3, 4]  — ref sees the update
+```
+
+No special flag is required. The `+` operator compiles to a lightweight helper
+(`ρσ_list_add`) that uses `Array.concat` for lists and falls back to native JS
+`+` for numbers and strings.
+
 ### Sets
 
 Sets in RapydScript are identical to those in python. You can create them using
@@ -1346,6 +1366,20 @@ str.format('{0:02d} {n}', 1, n=2) == '01 2'
 ...
 ```
 
+The `format(value[, spec])` builtin is also supported. It applies the Python
+format-spec mini-language to a single value — the same mini-language that
+follows `:` in f-strings and `str.format()` fields:
+
+```py
+format(42, '08b')     # '00101010'  — zero-padded binary
+format(3.14159, '.2f') # '3.14'     — fixed-point
+format('hi', '>10')   # '        hi' — right-aligned in 10-char field
+format(42)            # '42'        — no spec: same as str(42)
+```
+
+Objects with a `__format__` method are dispatched to it, matching Python's
+protocol exactly.
+
 String predicate methods are also available:
 
 ```py
@@ -1697,7 +1731,7 @@ E.a(onclick=def():
 
 Classes
 -------
-This is where RapydScript really starts to shine. JavaScript is known for having really crappy class implementation (it's basically a hack on top of a normal function, most experienced users suggest using external libraries for creating those instead of creating them in pure JavaScript). Luckily RapydScript fixes that. Let's imagine we want a special text field that takes in a user color string and changes color based on it. Let's create such field via a class.
+JavaScript is not known for having excellent class implementation - but RapydScript improves on that. Imagine we want a special text field that takes in a user color string and changes color based on it. Let's create such field via a class:
 
 ```js
 class ColorfulTextField:
@@ -1880,6 +1914,65 @@ print(Counter.get_count())  # 2
 
 The `@classmethod` decorator compiles to a method placed directly on the class (not its prototype), with `cls` mapped to `this`. A prototype delegation shim is also generated so instance calls work correctly.
 
+### Nested Classes
+
+A class may be defined inside another class. The nested class becomes an attribute of the outer class (accessible as `Outer.Inner`) and is also reachable via instances (`self.Inner` inside methods). This mirrors Python semantics exactly.
+
+```py
+class Molecule:
+    class Atom:
+        def __init__(self, element):
+            self.element = element
+        def __repr__(self):
+            return 'Atom(' + self.element + ')'
+
+    def __init__(self, elements):
+        self.structure = []
+        for e in elements:
+            self.structure.push(Molecule.Atom(e))
+
+water = Molecule(['H', 'H', 'O'])
+print(len(water.structure))          # 3
+print(water.structure[0].element)    # H
+print(isinstance(water.structure[0], Molecule.Atom))  # True
+```
+
+The nested class is a full class in every respect — it can have its own methods, inherit from other classes, and contain further nested classes:
+
+```py
+class Universe:
+    class Galaxy:
+        class Star:
+            def __init__(self, name):
+                self.name = name
+        def __init__(self, star_name):
+            self.star = Universe.Galaxy.Star(star_name)
+    def __init__(self, star_name):
+        self.galaxy = Universe.Galaxy(star_name)
+
+u = Universe('Sol')
+print(u.galaxy.star.name)                    # Sol
+print(isinstance(u.galaxy.star, Universe.Galaxy.Star))  # True
+```
+
+A nested class may also inherit from classes defined in the outer scope:
+
+```py
+class Animal:
+    def __init__(self, sound):
+        self.sound = sound
+
+class Zoo:
+    class Dog(Animal):
+        def __init__(self):
+            Animal.__init__(self, 'woof')
+
+fido = Zoo.Dog()
+print(fido.sound)             # woof
+print(isinstance(fido, Animal))    # True
+print(isinstance(fido, Zoo.Dog))   # True
+```
+
 ### External Classes
 
 RapydScript will automatically detect classes declared within the same scope (as long as the declaration occurs before use), as well as classes properly imported into the module (each module making use of a certain class should explicitly import the module containing that class). RapydScript will also properly detect native JavaScript classes (String, Array, Date, etc.). Unfortunately, RapydScript has no way of detecting classes from third-party libraries. In those cases, you could use the `new` keyword every time you create an object from such class. Alternatively, you could mark the class as external.
@@ -2029,6 +2122,26 @@ next(it)         # raises StopIteration
 When the iterator is exhausted and no default is given, ``StopIteration``
 is raised — matching standard Python behaviour.
 
+The two-argument form ``iter(callable, sentinel)`` repeatedly calls
+``callable`` (with no arguments) and yields each return value until it equals
+``sentinel``, at which point the iterator stops:
+
+```python
+count = [0]
+def next_val():
+    count[0] += 1
+    return count[0]
+
+list(iter(next_val, 4))   # [1, 2, 3]
+
+for val in iter(next_val, 7):
+    print(val)            # 5, 6
+```
+
+The callable may be any function or object with a ``__call__`` method.
+Sentinel comparison uses strict equality (``===``), matching Python's
+``is``-then-``==`` semantics for the common case of plain values.
+
 Generators
 ------------
 
@@ -2039,18 +2152,19 @@ def f():
 	for i in range(3):
 		yield i
 
-[x for x in f()] == [1, 2, 3]
+[x for x in f()] == [0, 1, 2]
 ```
 
 There is full support for generators including the Python 3, ```yield from```
-syntax. 
+syntax.
 
 Generators create JavaScript iterator objects. For differences between python
-and JavaScript iterators, see the section on iterators above. 
+and JavaScript iterators, see the section on iterators above.
 
-Currently, generators are down-converted to ES 5 switch statements. In the
-future, when ES 6 support is widespread, they will be converted to native
-JavaScript ES 6 generators.
+By default, generators are down-converted to ES 5 switch statements. Pass
+``--js-version 6`` to the compiler (or set ``js_version: 6`` in the embedded
+compiler options) to emit native ES 6 generator functions instead, which are
+smaller and faster.
 
 Modules
 -------
@@ -2191,7 +2305,7 @@ finally:
 ```
 
 You can create your own Exception classes by inheriting from `Exception`, which
-is the JavaScript Error class, for more details on this, see (the MDN documentation)[https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error]. 
+is the JavaScript Error class, for more details on this, see the [MDN documentation](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error).
 
 ```py
 class MyError(Exception):
@@ -2288,30 +2402,31 @@ Shadowing is preferred in most cases, since it can't accidentally damage outside
 Available Libraries
 -------------------
 
-One of Python's main strengths is the number of libraries available to the developer. This is something very few other `Python-in-a-browser` frameworks understand. In the browser JavaScript is king, and no matter how many libraries the community for the given project will write, the readily-available JavaScript libraries will always outnumber them. This is why RapydScript was designed with JavaScript and DOM integration in mind from the beginning. Indeed, plugging `underscore.js` in place of RapydScript's `stdlib` will work just as well, and some developers may choose to do so, after all, `underscore.js` is very Pythonic and very complete. 
+One of Python's main strengths is the number of libraries available to the developer. The large number of readily-available JavaScript libraries will always outnumber community-made Rapydscript libraries. This is why RapydScript was designed with JS and DOM integration in mind from the beginning. For example, plugging in `lodash` in place of RapydScript's `stdlib` will work fine!
 
-It is for that reason that I try to keep RapydScript bells and whistles to a minimum. RapydScript's main strength is easy integration with JavaScript and DOM, which allows me to stay sane and not rewrite my own versions of the libraries that are already available. That doesn't mean, however, that pythonic libraries can't be written for RapydScript. To prove that, I have implemented lightweight clones of several popular Python libraries and bundled them into RapydScript, you can find them in `src` directory. The following libraries are included:
+ RapydScript's main strength is easy integration with JavaScript and DOM, and easy use of libraries that are already available. That doesn't mean, however, that pythonic libraries can't be written for RapydScript. Rapydscript comes with lightweight clones of several popular Python libraries, which you can find them in `src` directory.
 
 	math                # replicates almost all of the functionality from Python's math library
 	re                  # replicates almost all of the functionality from Python's re library
 	random              # replicates most of the functionality from Python's random library
+	numpy               # NumPy-compatible array library (ndarray, ufuncs, numpy.random, numpy.linalg)
 	elementmaker        # easily construct DOM trees
 	aes                 # Implement AES symmetric encryption
 	encodings           # Convert to/from UTF-8 bytearrays, base64 strings and native strings
 	gettext             # Support for internationalization of your RapydScript app
-	operator            # a subset of python;s operator module
+	operator            # a subset of Python's operator module
 	functools           # reduce, partial, wraps, lru_cache, cache, total_ordering, cmp_to_key
 	collections         # namedtuple, deque, Counter, OrderedDict, defaultdict
 	itertools           # count, cycle, repeat, accumulate, chain, compress, dropwhile, filterfalse,
 	                    # groupby, islice, pairwise, starmap, takewhile, zip_longest,
 	                    # product, permutations, combinations, combinations_with_replacement
 
-For the most part, the logic implemented in these libraries functions identically to the Python versions.  I'd be happy to include more libraries, if other members of the community want to implement them (it's fun to do, `re.pyj` is a good example), but I want to reemphasize that unlike most other Python-to-JavaScript compilers, RapydScript doesn't need them to be complete since there are already tons of available JavaScript libraries that it can use natively.
+For the most part, the logic implemented in these libraries functions identically to the Python versions. I'd be happy to include more libraries, if other members of the community want them. However, unlike most other Python-to-JavaScript compilers, RapydScript doesn't need them to be complete since there are already tons of available JavaScript libraries that it can use natively.
 
 Linter
 ---------
 
-The RapydScript compiler includes its own, built in linter. The linter is
+The RapydScript compiler includes its own, built-in linter. The linter is
 modeled on pyflakes, it catches instances of unused/undefined variables,
 functions, symbols, etc. While this sounds simple, it is surprisingly effective
 in practice. To run the linter:
@@ -2391,13 +2506,12 @@ RapydScript will pick up any classes you declare yourself as well as native
 JavaScript classes. It will not, however, pick up class-like objects created by
 outside frameworks. There are two approaches for dealing with those. One is via
 `@external` decorator, the other is via `new` operator when declaring such
-object. To keep code legible and consistent, I strongly prefer the use of
-`@external` decorator over the `new` operator for several reasons, even if it
-may be more verbose:
+object. The `@external` decorator is recommended over the `new` operator for 
+several reasons, even if it may be more verbose:
 
 - `@external` decorator makes classes declared externally obvious to anyone looking at your code
 - class declaration that uses `@external` decorator can be exported into a reusable module
-- developers are much more likely to forget a single instance of `new` operator when declaring an object than to forget an import, the errors due to omitted `new` keyword are also likely to be more subtle and devious to debug
+- developers are much more likely to forget a single instance of `new` operator when declaring an object than to forget an import. the errors due to omitted `new` keyword are also likely to be more subtle and devious to debug
 
 #### Embedding the RapydScript compiler in your webpage
 
@@ -2417,7 +2531,7 @@ HTML below for an example.
     <head>
         <meta charset="UTF-8">
         <title>Test embedded RapydScript</title>
-        <script charset="UTF-8" src="https://github.com/ficocelliguy/rapydscript-ns/blob/master/web-repl/rapydscript.js"></script>
+        <script charset="UTF-8" src="rapydscript.js"></script>
         <script>
 var compiler = RapydScript.create_embedded_compiler();
 var js = compiler.compile("def hello_world():\n a='RapydScript is cool!'\n print(a)\n alert(a)");
@@ -2511,9 +2625,10 @@ to an experienced Python developer. The most important such gotchas are listed
 below:
 
 - Truthiness in JavaScript is very different from Python. Empty lists and dicts
-  are ``False`` in Python but ``True`` in JavaScript. The compiler could work
-  around that, but not without a significant performance cost, so it is best to
-  just get used to checking the length instead of the object directly.
+  are ``False`` in Python but ``True`` in JavaScript. You can opt in to full
+  Python truthiness semantics (where empty containers are falsy and ``__bool__``
+  is dispatched) with ``from __python__ import truthiness``. Without that flag,
+  test the length explicitly instead of the container directly.
 
 - Operators in JavaScript are very different from Python. ``1 + '1'`` would be
   an error in Python, but results in ``'11'`` in JavaScript. Similarly, ``[1] +
@@ -2574,7 +2689,7 @@ npm run build:ls
 node tools/build-language-service.js --out path/to/language-service.js
 ```
 
-The output is written to `web-repl/language-service.js` by default.
+The output is written to `language-service/index.js` by default.
 
 ### Basic setup
 
@@ -2769,7 +2884,7 @@ and assembled into the standard `mappings` field.  The implementation lives in
 
 ```bash
 node bin/web-repl-export web-repl          # rebuilds web-repl/rapydscript.js
-node tools/build-language-service.js       # rebuilds web-repl/language-service.js
+node tools/build-language-service.js       # rebuilds language-service/index.js
 ```
 
 ### Running the tests