rapydscript-ns 0.8.3 → 0.9.0

package/src/lib/typing.pyj

@@ -0,0 +1,577 @@
+# vim:fileencoding=utf-8
+# License: BSD
+# RapydScript implementation of Python's typing standard library.
+#
+# Supported:
+#   TYPE_CHECKING, Any, Union, Optional, ClassVar, Final, Literal, NoReturn,
+#   List, Dict, Set, FrozenSet, Tuple, Type, Callable,
+#   Iterator, Iterable, Generator, Sequence, MutableSequence,
+#   Mapping, MutableMapping, Awaitable, Coroutine,
+#   AsyncGenerator, AsyncIterator, AsyncIterable,
+#   IO, TextIO, BinaryIO, Pattern, Match,
+#   TypeVar, Generic, Protocol,
+#   cast, overload, no_type_check, no_type_check_decorator,
+#   runtime_checkable, get_type_hints,
+#   TypedDict, NamedTuple, AnyStr, ByteString, Text
+#
+# Type annotations are not enforced at runtime.  All typing constructs
+# transpile to lightweight JavaScript objects that carry the same
+# introspection attributes (__origin__, __args__, _name) as their
+# CPython equivalents, so that annotation-aware code works identically.
+
+
+# ── Constants ──────────────────────────────────────────────────────────────────
+
+# Always False at runtime; True only when a static type-checker is running.
+TYPE_CHECKING = False
+
+
+# ── Internal representation ────────────────────────────────────────────────────
+
+class _GenericAlias:
+    """Represents a parameterized generic type such as List[int] or Dict[str, int].
+
+    Attributes:
+        __origin__  The origin type (list, dict, …) or None for abstract types.
+        __args__    Tuple of type arguments; empty tuple when not parameterised.
+        _name       Display name used in repr().
+    """
+
+    def __init__(self, origin, args, name=None):
+        self.__origin__ = origin
+        if args is None:
+            self.__args__ = []
+        elif Array.isArray(args):
+            self.__args__ = args
+        else:
+            self.__args__ = [args]
+        self._name = name
+        # Allow _GenericAlias to be used as a base class in `class Foo(Generic[T])`.
+        # ρσ_extends reads parent.prototype, so we proxy it to the origin's prototype.
+        if origin and jstype(origin.prototype) is not 'undefined':
+            self.prototype = origin.prototype
+
+    def __repr__(self):
+        if self._name:
+            base = 'typing.' + self._name
+        else:
+            base = 'typing._GenericAlias'
+        if self.__args__:
+            parts = []
+            for a in self.__args__:
+                if a is None:
+                    parts.append('None')
+                elif jstype(a.__name__) is 'string' and a.__name__:
+                    parts.append(a.__name__)
+                else:
+                    parts.append(repr(a))
+            return base + '[' + parts.join(', ') + ']'
+        return base
+
+
+# ── Special forms ──────────────────────────────────────────────────────────────
+
+class Any:
+    """Special form: matches any type.  Every type is compatible with Any."""
+
+    def __repr__(self):
+        return 'typing.Any'
+
+
+class Union:
+    """Union[X, Y] means either type X or type Y.
+
+    Example::
+
+        from typing import Union
+        def f(x: Union[str, int]) -> None: ...
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Union')
+
+
+class Optional:
+    """Optional[X] is shorthand for Union[X, None].
+
+    Example::
+
+        from typing import Optional
+        def f(x: Optional[str] = None) -> Optional[int]: ...
+    """
+
+    def __class_getitem__(cls, params):
+        return _GenericAlias(None, [params, None], 'Optional')
+
+
+class ClassVar:
+    """ClassVar[T] marks that a variable is intended as a class variable."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'ClassVar')
+
+
+class Final:
+    """Final[T] marks that a variable may not be reassigned after first assignment."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Final')
+
+
+class Literal:
+    """Literal[v, …] marks a type that may only take one of the given literal values.
+
+    Example::
+
+        from typing import Literal
+        Mode = Literal['r', 'w', 'a']
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Literal')
+
+
+class NoReturn:
+    """NoReturn marks a function that never returns normally."""
+    pass
+
+
+# ── Concrete generic aliases ───────────────────────────────────────────────────
+
+class List:
+    """Generic alias for the built-in list type.
+
+    Example::
+
+        from typing import List
+        def f(xs: List[int]) -> List[str]: ...
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(list, params, 'List')
+
+
+class Dict:
+    """Generic alias for the built-in dict type."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(dict, params, 'Dict')
+
+
+class Set:
+    """Generic alias for the built-in set type."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(set, params, 'Set')
+
+
+class FrozenSet:
+    """Generic alias for the built-in frozenset type."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(frozenset, params, 'FrozenSet')
+
+
+class Tuple:
+    """Generic alias for the built-in tuple type.
+
+    Use Tuple[X, Y] for a two-element tuple or Tuple[X, ...] for a
+    variable-length homogeneous tuple.
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(tuple, params, 'Tuple')
+
+
+class Type:
+    """Type[C] represents the class C itself rather than an instance of C."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(type, params, 'Type')
+
+
+class Callable:
+    """Callable[[ArgType, …], ReturnType] — any callable object.
+
+    Example::
+
+        from typing import Callable
+        f: Callable[[int, str], bool]
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Callable')
+
+
+# ── Abstract-base / protocol aliases ──────────────────────────────────────────
+
+class Iterator:
+    """Generic alias for an iterator (has __next__)."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Iterator')
+
+
+class Iterable:
+    """Generic alias for an iterable (has __iter__)."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Iterable')
+
+
+class Generator:
+    """Generic alias for a generator (yield / send / throw)."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Generator')
+
+
+class Sequence:
+    """Generic alias for a read-only sequence."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Sequence')
+
+
+class MutableSequence:
+    """Generic alias for a mutable sequence."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'MutableSequence')
+
+
+class Mapping:
+    """Generic alias for a read-only key-value mapping."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Mapping')
+
+
+class MutableMapping:
+    """Generic alias for a mutable key-value mapping."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'MutableMapping')
+
+
+class Awaitable:
+    """Generic alias for an awaitable object."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Awaitable')
+
+
+class Coroutine:
+    """Generic alias for a coroutine."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Coroutine')
+
+
+class AsyncGenerator:
+    """Generic alias for an async generator."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'AsyncGenerator')
+
+
+class AsyncIterator:
+    """Generic alias for an async iterator."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'AsyncIterator')
+
+
+class AsyncIterable:
+    """Generic alias for an async iterable."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'AsyncIterable')
+
+
+# ── IO type aliases ────────────────────────────────────────────────────────────
+
+class IO:
+    """Generic IO type; IO[str] for text or IO[bytes] for binary."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'IO')
+
+
+class TextIO:
+    """Text-mode IO stream (IO[str])."""
+    pass
+
+
+class BinaryIO:
+    """Binary-mode IO stream (IO[bytes])."""
+    pass
+
+
+# ── Pattern / Match aliases (for re module) ────────────────────────────────────
+
+class Pattern:
+    """Generic alias for compiled regular-expression pattern objects."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Pattern')
+
+
+class Match:
+    """Generic alias for regular-expression match objects."""
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(None, params, 'Match')
+
+
+# ── TypeVar ────────────────────────────────────────────────────────────────────
+
+class TypeVar:
+    """Type variable.  Used to parameterise generic classes and functions.
+
+    Example::
+
+        from typing import TypeVar
+        T = TypeVar('T')
+        S = TypeVar('S', str, bytes)       # constrained TypeVar
+    """
+
+    def __init__(self, name, *constraints):
+        self.__name__ = name
+        self.__constraints__ = constraints
+        self.__bound__ = None
+        self.__covariant__ = False
+        self.__contravariant__ = False
+
+    def __repr__(self):
+        return '~' + self.__name__
+
+
+# ── Generic and Protocol base classes ─────────────────────────────────────────
+
+class Generic:
+    """Base class for generic classes.
+
+    Example::
+
+        from typing import Generic, TypeVar
+        T = TypeVar('T')
+        class Stack(Generic[T]):
+            def push(self, item: T) -> None: ...
+            def pop(self) -> T: ...
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(cls, params)
+
+
+class Protocol:
+    """Base class for protocol classes (structural subtyping).
+
+    Example::
+
+        from typing import Protocol, runtime_checkable
+        @runtime_checkable
+        class Drawable(Protocol):
+            def draw(self) -> None: ...
+    """
+
+    def __class_getitem__(cls, params):
+        if not Array.isArray(params):
+            params = [params]
+        return _GenericAlias(cls, params)
+
+
+# ── Utility functions and decorators ──────────────────────────────────────────
+
+def cast(typ, val):
+    """Cast *val* to type *typ*.
+
+    At runtime this is a no-op: *val* is returned unchanged.  Type checkers
+    treat the result as having type *typ*.
+    """
+    return val
+
+
+def overload(func):
+    """Decorator for overloaded function definitions.
+
+    Returns *func* unchanged; the last non-``@overload``-decorated definition
+    is the one called at runtime.
+    """
+    return func
+
+
+def no_type_check(arg):
+    """Decorator to opt a function or class out of type checking."""
+    return arg
+
+
+def no_type_check_decorator(decorator):
+    """Decorator that disables type checking for the decorated decorator."""
+    return decorator
+
+
+def runtime_checkable(cls):
+    """Decorator to mark a Protocol as runtime-checkable via isinstance()."""
+    return cls
+
+
+def get_type_hints(obj, globalns=None, localns=None):
+    """Return the type hints for *obj* (a function, method, module, or class).
+
+    Returns a copy of ``obj.__annotations__``, or an empty dict when the
+    object carries no annotations.
+    """
+    a = obj.__annotations__
+    if jstype(a) is 'undefined' or a is None:
+        return {}
+    result = {}
+    keys = Object.keys(a)
+    for i in range(keys.length):
+        k = keys[i]
+        result[k] = a[k]
+    return result
+
+
+# ── TypedDict ──────────────────────────────────────────────────────────────────
+
+class TypedDict:
+    """Base class for typed dictionaries (class-based syntax).
+
+    Example::
+
+        from typing import TypedDict
+
+        class Movie(TypedDict):
+            name: str
+            year: int
+
+    At runtime, TypedDict subclasses are plain classes; no type enforcement
+    occurs.  Fields are declared via class-body annotations and accessible
+    via normal attribute access on instances.
+    """
+    pass
+
+
+# ── NamedTuple factory (functional form) ───────────────────────────────────────
+
+def NamedTuple(typename, fields):
+    """Create a typed named-tuple class (functional form).
+
+    *fields* is a list of (name, type) pairs::
+
+        from typing import NamedTuple
+        Point = NamedTuple('Point', [('x', float), ('y', float)])
+        p = Point(1.0, 2.0)
+        print(p.x)   # 1.0
+        print(p.y)   # 2.0
+
+    The returned class stores fields as plain attributes, carries a
+    ``__annotations__`` dict of name → type, and supports positional
+    construction.
+    """
+    field_names = [f[0] for f in fields]
+    annotations = {f[0]: f[1] for f in fields}
+    n = len(field_names)
+
+    class _NT:
+        def __init__(self, *args):
+            for i in range(n):
+                name = field_names[i]
+                val = args[i] if i < args.length else None
+                v'this[name] = val'
+
+        def __getitem__(self, idx):
+            if idx < 0:
+                idx = n + idx
+            if idx < 0 or idx >= n:
+                raise IndexError('tuple index out of range')
+            return v'this[field_names[idx]]'
+
+        def __repr__(self):
+            parts = []
+            for i in range(n):
+                val = v'this[field_names[i]]'
+                parts.append(repr(val))
+            return typename + '(' + ', '.join(parts) + ')'
+
+    _NT.__name__ = typename
+    _NT.__annotations__ = annotations
+    return _NT
+
+
+# ── ByteString ─────────────────────────────────────────────────────────────────
+
+class ByteString:
+    """Type covering bytes-like objects: bytes and bytearray.
+
+    Use as a type annotation when a function accepts any bytes-like object::
+
+        from typing import ByteString
+        def process(data: ByteString) -> None: ...
+    """
+    pass
+
+
+# ── Convenience aliases ────────────────────────────────────────────────────────
+
+# AnyStr: a TypeVar constrained to str or bytes
+AnyStr = TypeVar('AnyStr', str, bytes)
+
+# Python 2 → Python 3 compatibility alias
+Text = str

package/src/monaco-language-service/builtins.js

@@ -79,6 +79,11 @@ const STUBS = [
         return_type: 'str',
         doc: 'Return the string representing a character at Unicode code point i.' }),
 
+    new BuiltinInfo({ name: 'complex', kind: 'class',
+        params: [p('real_or_string', { optional: true }), p('imag', { type: 'number', optional: true })],
+        return_type: 'complex',
+        doc: 'Create a complex number.\n\nForms:\n- `complex()` → `0j`\n- `complex(x)` → `x+0j` (from int/float/bool/complex), or parse Python complex string\n- `complex(real, imag)` → `real + imag*j`\n\nLiteral syntax: `4j` is equivalent to `complex(0, 4)`, and `3+4j` creates a complex number via addition.\n\nAttributes:\n- `.real` — the real part (float)\n- `.imag` — the imaginary part (float)\n\nMethods:\n- `.conjugate()` — return the complex conjugate `(real - imag*j)`\n\nSupports: `+`, `-`, `*`, `/`, `**`, unary `-`/`+`, `abs()`, `bool()`, `==`, `repr()`, `str()`.\n\nExample:\n\n    c = complex(3, 4)\n    c.real            # 3\n    c.imag            # 4\n    abs(c)            # 5.0\n    c.conjugate()     # (3-4j)\n    c * complex(1, 2) # (-5+10j)\n    3 + 4j            # (3+4j)  — literal syntax' }),
+
     new BuiltinInfo({ name: 'dict', kind: 'class',
         params: [p('**kwargs', { rest: true })],
         return_type: 'dict',
@@ -112,7 +117,7 @@ const STUBS = [
     new BuiltinInfo({ name: 'float', kind: 'class',
         params: [p('x', { optional: true })],
         return_type: 'float',
-        doc: 'Return a floating-point number from x.' }),
+        doc: 'Return a floating-point number from x.\n\nInstance method:\n- `.is_integer()` — return `True` if the float has no fractional part (i.e. is a whole number), `False` otherwise. `Infinity` and `NaN` return `False`.\n\nExample:\n\n    (1.0).is_integer()   # True\n    (1.5).is_integer()   # False\n    (1e10).is_integer()  # True' }),
 
     new BuiltinInfo({ name: 'getattr',
         params: [p('obj'), p('name', { type: 'str' }), p('default', { optional: true })],
@@ -142,7 +147,7 @@ const STUBS = [
     new BuiltinInfo({ name: 'int', kind: 'class',
         params: [p('x', { optional: true }), p('base', { type: 'int', optional: true })],
         return_type: 'int',
-        doc: 'Return an integer from x, optionally in the given base.' }),
+        doc: 'Return an integer from x, optionally in the given base.\n\nInstance method:\n- `.bit_length()` — return the number of bits needed to represent the integer in binary, excluding the sign and leading zeros. Equivalent to `floor(log2(abs(n))) + 1` for nonzero `n`; returns `0` for `0`.\n\nExample:\n\n    (0).bit_length()    # 0\n    (1).bit_length()    # 1\n    (255).bit_length()  # 8\n    (256).bit_length()  # 9\n    (-5).bit_length()   # 3  (sign ignored)' }),
 
     new BuiltinInfo({ name: 'isinstance',
         params: [p('obj'), p('classinfo')],
@@ -169,6 +174,16 @@ const STUBS = [
         return_type: 'list',
         doc: 'Create a list from an iterable, or an empty list.' }),
 
+    new BuiltinInfo({ name: 'next',
+        params: [p('iterator'), p('default', { optional: true })],
+        return_type: 'any',
+        doc: 'Retrieve the next item from an iterator. If the iterator is exhausted, return default; if default is not given, raise StopIteration.' }),
+
+    new BuiltinInfo({ name: 'object', kind: 'class',
+        params: [],
+        return_type: 'object',
+        doc: 'Create a new featureless base object instance.\n\nThe base class of all Python classes. Calling `object()` with no arguments returns a new, unique instance useful as a sentinel value:\n\n    MISSING = object()   # unique sentinel\n    if value is MISSING:\n        ...\n\nKey behaviours:\n- Each call returns a distinct instance (`object() is not object()`).\n- `isinstance(x, object)` returns `True` for any `object()` instance (and subclasses).\n- `class Foo(object):` works as an explicit base class.\n- `repr()` returns `\'<object object at 0x…>\'`.\n- `hash()` returns a stable identity hash.\n\nNote: unlike Python, you *can* add arbitrary attributes to an `object()` instance in RapydScript (JS objects are open by default).' }),
+
     new BuiltinInfo({ name: 'map',
         params: [p('function'), p('iterable'), p('*iterables', { rest: true })],
         return_type: 'iterable',
@@ -260,9 +275,9 @@ const STUBS = [
         doc: 'Return the type of an object.' }),
 
     new BuiltinInfo({ name: 'zip',
-        params: [p('*iterables', { rest: true })],
+        params: [p('*iterables', { rest: true }), p('strict', { optional: true })],
         return_type: 'iterable',
-        doc: 'Return an iterator of tuples, where each tuple groups the i-th element from each iterable.' }),
+        doc: 'Return an iterator of tuples, where each tuple groups the i-th element from each iterable. With strict=True, raises ValueError if the iterables have different lengths.' }),
 
     // ── RapydScript-specific ──────────────────────────────────────────────
     new BuiltinInfo({ name: 'jstype',