jaclang 0.6.1__py3-none-any.whl → 0.6.2__py3-none-any.whl

jaclang/vendor/mypyc/doc/index.rst

@@ -0,0 +1,61 @@
+.. mypyc documentation master file, created by
+   sphinx-quickstart on Sun Apr  5 14:01:55 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to mypyc documentation!
+===============================
+
+Mypyc compiles Python modules to C extensions. It uses standard Python
+`type hints
+<https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_ to
+generate fast code.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: First steps
+
+   introduction
+   getting_started
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Using mypyc
+
+   using_type_annotations
+   native_classes
+   differences_from_python
+   compilation_units
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Native operations reference
+
+   native_operations
+   int_operations
+   bool_operations
+   float_operations
+   str_operations
+   list_operations
+   dict_operations
+   set_operations
+   tuple_operations
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Advanced topics
+
+   performance_tips_and_tricks
+
+.. toctree::
+   :hidden:
+   :caption: Project Links
+
+   GitHub <https://github.com/python/mypy>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

jaclang/vendor/mypyc/doc/int_operations.rst

@@ -0,0 +1,162 @@
+.. _int-ops:
+
+Native integer operations
+=========================
+
+Mypyc supports these integer types:
+
+* ``int`` (arbitrary-precision integer)
+* ``i64`` (64-bit signed integer)
+* ``i32`` (32-bit signed integer)
+* ``i16`` (16-bit signed integer)
+* ``u8`` (8-bit unsigned integer)
+
+``i64``, ``i32``, ``i16`` and ``u8`` are *native integer types* and
+are available in the ``mypy_extensions`` module. ``int`` corresponds
+to the Python ``int`` type, but uses a more efficient runtime
+representation (tagged pointer). Native integer types are value types.
+
+All integer types have optimized primitive operations, but the native
+integer types are more efficient than ``int``, since they don't
+require range or bounds checks.
+
+Operations on integers that are listed here have fast, optimized
+implementations. Other integer operations use generic implementations
+that are generally slower. Some operations involving integers and other
+types, such as list indexing, are documented elsewhere.
+
+Construction
+------------
+
+``int`` type:
+
+* Integer literal
+* ``int(x: float)``
+* ``int(x: i64)``
+* ``int(x: i32)``
+* ``int(x: i16)``
+* ``int(x: u8)``
+* ``int(x: str)``
+* ``int(x: str, base: int)``
+* ``int(x: int)`` (no-op)
+
+``i64`` type:
+
+* ``i64(x: int)``
+* ``i64(x: float)``
+* ``i64(x: i64)`` (no-op)
+* ``i64(x: i32)``
+* ``i64(x: i16)``
+* ``i64(x: u8)``
+* ``i64(x: str)``
+* ``i64(x: str, base: int)``
+
+``i32`` type:
+
+* ``i32(x: int)``
+* ``i32(x: float)``
+* ``i32(x: i64)`` (truncate)
+* ``i32(x: i32)`` (no-op)
+* ``i32(x: i16)``
+* ``i32(x: u8)``
+* ``i32(x: str)``
+* ``i32(x: str, base: int)``
+
+``i16`` type:
+
+* ``i16(x: int)``
+* ``i16(x: float)``
+* ``i16(x: i64)`` (truncate)
+* ``i16(x: i32)`` (truncate)
+* ``i16(x: i16)`` (no-op)
+* ``i16(x: u8)``
+* ``i16(x: str)``
+* ``i16(x: str, base: int)``
+
+Conversions from ``int`` to a native integer type raise
+``OverflowError`` if the value is too large or small. Conversions from
+a wider native integer type to a narrower one truncate the value and never
+fail. More generally, operations between native integer types don't
+check for overflow.
+
+Implicit conversions
+--------------------
+
+``int`` values can be implicitly converted to a native integer type,
+for convenience. This means that these are equivalent::
+
+   from mypy_extensions import i64
+
+   def implicit() -> None:
+       # Implicit conversion of 0 (int) to i64
+       x: i64 = 0
+
+   def explicit() -> None:
+       # Explicit conversion of 0 (int) to i64
+       x = i64(0)
+
+Similarly, a native integer value can be implicitly converted to an
+arbitrary-precision integer. These two functions are equivalent::
+
+   def implicit(x: i64) -> int:
+       # Implicit conversion from i64 to int
+       return x
+
+   def explicit(x: i64) -> int:
+       # Explicit conversion from i64 to int
+       return int(x)
+
+Operators
+---------
+
+* Arithmetic (``+``, ``-``, ``*``, ``//``, ``/``, ``%``)
+* Bitwise operations (``&``, ``|``, ``^``, ``<<``, ``>>``, ``~``)
+* Comparisons (``==``, ``!=``, ``<``, etc.)
+* Augmented assignment (``x += y``, etc.)
+
+If one of the above native integer operations overflows or underflows
+with signed operands, the behavior is undefined. Signed native integer
+types should only be used if all possible values are small enough for
+the type. For this reason, the arbitrary-precision ``int`` type is
+recommended for signed values unless the performance of integer
+operations is critical.
+
+Operations on unsigned integers (``u8``) wrap around on overflow.
+
+It's a compile-time error to mix different native integer types in a
+binary operation such as addition. An explicit conversion is required::
+
+    from mypy_extensions import i64, i32
+
+    def add(x: i64, y: i32) -> None:
+        a = x + y  # Error (i64 + i32)
+        b = x + i64(y)  # OK
+
+You can freely mix a native integer value and an arbitrary-precision
+``int`` value in an operation. The native integer type is "sticky"
+and the ``int`` operand is coerced to the native integer type::
+
+  def example(x: i64, y: int) -> None:
+      a = x * y
+      # Type of "a" is "i64"
+      ...
+      b = 1 - x
+      # Similarly, type of "b" is "i64"
+
+Statements
+----------
+
+For loop over a range is compiled efficiently, if the ``range(...)`` object
+is constructed in the for statement (after ``in``):
+
+* ``for x in range(end)``
+* ``for x in range(start, end)``
+* ``for x in range(start, end, step)``
+
+If one of the arguments to ``range`` in a for loop is a native integer
+type, the type of the loop variable is inferred to have this native
+integer type, instead of ``int``::
+
+  for x in range(i64(n)):
+      # Type of "x" is "i64"
+      ...

jaclang/vendor/mypyc/doc/introduction.rst

@@ -0,0 +1,150 @@
+Introduction
+============
+
+Mypyc compiles Python modules to C extensions. It uses standard Python
+`type hints
+<https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html>`_ to
+generate fast code.
+
+The compiled language is a strict, *gradually typed* Python variant. It
+restricts the use of some dynamic Python features to gain performance,
+but it's mostly compatible with standard Python.
+
+Mypyc uses `mypy <https://www.mypy-lang.org/>`_ to perform type
+checking and type inference. Most type system features in the stdlib
+`typing <https://docs.python.org/3/library/typing.html>`_ module are
+supported.
+
+Compiled modules can import arbitrary Python modules and third-party
+libraries. You can compile anything from a single performance-critical
+module to your entire codebase. You can run the modules you compile
+also as normal, interpreted Python modules.
+
+Existing code with type annotations is often **1.5x to 5x** faster
+when compiled. Code tuned for mypyc can be **5x to 10x** faster.
+
+Mypyc currently aims to speed up non-numeric code, such as server
+applications. Mypyc is also used to compile itself (and mypy).
+
+Why mypyc?
+----------
+
+**Easy to get started.** Compiled code has the look and feel of
+regular Python code. Mypyc supports familiar Python syntax and idioms.
+
+**Expressive types.** Mypyc fully supports standard Python type hints.
+Mypyc has local type inference, generics, optional types, tuple types,
+union types, and more. Type hints act as machine-checked
+documentation, making code not only faster but also easier to
+understand and modify.
+
+**Python ecosystem.** Mypyc runs on top of CPython, the
+standard Python implementation. You can use any third-party libraries,
+including C extensions, installed with pip. Mypyc uses only valid Python
+syntax, so all Python editors and IDEs work perfectly.
+
+**Fast program startup.** Mypyc uses ahead-of-time compilation, so
+compilation does not slow down program startup. Slow program startup
+is a common issue with JIT compilers.
+
+**Migration path for existing code.** Existing Python code often
+requires only minor changes to compile using mypyc.
+
+**Waiting for compilation is optional.** Compiled code also runs as
+normal Python code. You can use interpreted Python during development,
+with familiar and fast workflows.
+
+**Runtime type safety.** Mypyc protects you from segfaults and memory
+corruption. Any unexpected runtime type safety violation is a bug in
+mypyc. Runtime values are checked against type annotations. (Without
+mypyc, type annotations are ignored at runtime.)
+
+**Find errors statically.** Mypyc uses mypy for static type checking
+that helps catch many bugs.
+
+Use cases
+---------
+
+**Fix only performance bottlenecks.** Often most time is spent in a few
+Python modules or functions. Add type annotations and compile these
+modules for easy performance gains.
+
+**Compile it all.** During development you can use interpreted mode,
+for a quick edit-run cycle. In releases all non-test code is compiled.
+This is how mypy achieved a 4x performance improvement over interpreted
+Python.
+
+**Take advantage of existing type hints.** If you already use type
+annotations in your code, adopting mypyc will be easier. You've already
+done most of the work needed to use mypyc.
+
+**Alternative to a lower-level language.** Instead of writing
+performance-critical code in C, C++, Cython or Rust, you may get good
+performance while staying in the comfort of Python.
+
+**Migrate C extensions.** Maintaining C extensions is not always fun
+for a Python developer. With mypyc you may get performance similar to
+the original C, with the convenience of Python.
+
+Differences from Cython
+-----------------------
+
+Mypyc targets many similar use cases as Cython. Mypyc does many things
+differently, however:
+
+* No need to use non-standard syntax, such as ``cpdef``, or extra
+  decorators to get good performance. Clean, normal-looking
+  type-annotated Python code can be fast without language extensions.
+  This makes it practical to compile entire codebases without a
+  developer productivity hit.
+
+* Mypyc has first-class support for features in the ``typing`` module,
+  such as tuple types, union types and generics.
+
+* Mypyc has powerful type inference, provided by mypy. Variable type
+  annotations are not needed for optimal performance.
+
+* Mypyc fully integrates with mypy for robust and seamless static type
+  checking.
+
+* Mypyc performs strict enforcement of type annotations at runtime,
+  resulting in better runtime type safety and easier debugging.
+
+Unlike Cython, mypyc doesn't directly support interfacing with C libraries
+or speeding up numeric code.
+
+How does it work
+----------------
+
+Mypyc uses several techniques to produce fast code:
+
+* Mypyc uses *ahead-of-time compilation* to native code. This removes
+  CPython interpreter overhead.
+
+* Mypyc enforces type annotations (and type comments) at runtime,
+  raising ``TypeError`` if runtime values don't match annotations.
+  Value types only need to be checked in the boundaries between
+  dynamic and static typing.
+
+* Compiled code uses optimized, type-specific primitives.
+
+* Mypyc uses *early binding* to resolve called functions and name
+  references at compile time. Mypyc avoids many dynamic namespace
+  lookups.
+
+* Classes are compiled to *C extension classes*. They use `vtables
+  <https://en.wikipedia.org/wiki/Virtual_method_table>`_ for fast
+  method calls and attribute access.
+
+* Mypyc treats compiled functions, classes, and attributes declared
+  ``Final`` as immutable.
+
+* Mypyc has memory-efficient, unboxed representations for integers and
+  booleans.
+
+Development status
+------------------
+
+Mypyc is currently alpha software. It's only recommended for
+production use cases with careful testing, and if you are willing to
+contribute fixes or to work around issues you will encounter.

jaclang/vendor/mypyc/doc/list_operations.rst

@@ -0,0 +1,65 @@
+.. _list-ops:
+
+Native list operations
+======================
+
+These ``list`` operations have fast, optimized implementations. Other
+list operations use generic implementations that are often slower.
+
+Construction
+------------
+
+Construct list with specific items:
+
+* ``[item0, ..., itemN]``
+
+Construct empty list:
+
+* ``[]``
+* ``list()``
+
+Construct list from iterable:
+
+* ``list(x: Iterable)``
+
+List comprehensions:
+
+* ``[... for ... in ...]``
+* ``[... for ... in ... if ...]``
+
+Operators
+---------
+
+* ``lst[n]`` (get item by integer index)
+* ``lst[n:m]``, ``lst[n:]``, ``lst[:m]``, ``lst[:]`` (slicing)
+* ``lst * n``, ``n * lst``
+* ``obj in lst``
+
+Statements
+----------
+
+Set item by integer index:
+
+* ``lst[n] = x``
+
+For loop over a list:
+
+* ``for item in lst:``
+
+Methods
+-------
+
+* ``lst.append(obj)``
+* ``lst.extend(x: Iterable)``
+* ``lst.insert(index, obj)``
+* ``lst.pop(index=-1)``
+* ``lst.remove(obj)``
+* ``lst.count(obj)``
+* ``lst.index(obj)``
+* ``lst.reverse()``
+* ``lst.sort()``
+
+Functions
+---------
+
+* ``len(lst: list)``

jaclang/vendor/mypyc/doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

jaclang/vendor/mypyc/doc/native_classes.rst

@@ -0,0 +1,206 @@
+.. _native-classes:
+
+Native classes
+==============
+
+Classes in compiled modules are *native classes* by default (some
+exceptions are discussed below). Native classes are compiled to C
+extension classes, which have some important differences from normal
+Python classes. Native classes are similar in many ways to built-in
+types, such as ``int``, ``str``, and ``list``.
+
+Immutable namespaces
+--------------------
+
+The type object namespace of native classes is mostly immutable (but
+class variables can be assigned to)::
+
+    class Cls:
+        def method1(self) -> None:
+            print("method1")
+
+        def method2(self) -> None:
+            print("method2")
+
+    Cls.method1 = Cls.method2  # Error
+    Cls.new_method = Cls.method2  # Error
+
+Only attributes defined within a class definition (or in a base class)
+can be assigned to (similar to using ``__slots__``)::
+
+    class Cls:
+        x: int
+
+        def __init__(self, y: int) -> None:
+            self.x = 0
+            self.y = y
+
+        def method(self) -> None:
+            self.z = "x"
+
+    o = Cls(0)
+    print(o.x, o.y)  # OK
+    o.z = "y"  # OK
+    o.extra = 3  # Error: no attribute "extra"
+
+.. _inheritance:
+
+Inheritance
+-----------
+
+Only single inheritance is supported (except for :ref:`traits
+<trait-types>`). Most non-native classes can't be used as base
+classes.
+
+These non-native classes can be used as base classes of native
+classes:
+
+* ``object``
+* ``dict`` (and ``Dict[k, v]``)
+* ``BaseException``
+* ``Exception``
+* ``ValueError``
+* ``IndexError``
+* ``LookupError``
+* ``UserWarning``
+* ``typing.NamedTuple``
+* ``enum.Enum``
+
+By default, a non-native class can't inherit a native class, and you
+can't inherit from a native class outside the compilation unit that
+defines the class. You can enable these through
+``mypy_extensions.mypyc_attr``::
+
+    from mypy_extensions import mypyc_attr
+
+    @mypyc_attr(allow_interpreted_subclasses=True)
+    class Cls:
+        ...
+
+Allowing interpreted subclasses has only minor impact on performance
+of instances of the native class.  Accessing methods and attributes of
+a *non-native* subclass (or a subclass defined in another compilation
+unit) will be slower, since it needs to use the normal Python
+attribute access mechanism.
+
+You need to install ``mypy-extensions`` to use ``@mypyc_attr``:
+
+.. code-block:: text
+
+    pip install --upgrade mypy-extensions
+
+Class variables
+---------------
+
+Class variables must be explicitly declared using ``attr: ClassVar``
+or ``attr: ClassVar[<type>]``. You can't assign to a class variable
+through an instance. Example::
+
+    from typing import ClassVar
+
+    class Cls:
+        cv: ClassVar = 0
+
+    Cls.cv = 2  # OK
+    o = Cls()
+    print(o.cv)  # OK (2)
+    o.cv = 3  # Error!
+
+.. tip::
+
+    Constant class variables can be declared using ``typing.Final`` or
+    ``typing.Final[<type>]``.
+
+Generic native classes
+----------------------
+
+Native classes can be generic. Type variables are *erased* at runtime,
+and instances don't keep track of type variable values.
+
+Compiled code thus can't check the values of type variables when
+performing runtime type checks. These checks are delayed to when
+reading a value with a type variable type::
+
+    from typing import TypeVar, Generic, cast
+
+    T = TypeVar('T')
+
+    class Box(Generic[T]):
+        def __init__(self, item: T) -> None:
+            self.item = item
+
+    x = Box(1)  # Box[int]
+    y = cast(Box[str], x)  # OK (type variable value not checked)
+    y.item  # Runtime error: item is "int", but "str" expected
+
+Metaclasses
+-----------
+
+Most metaclasses aren't supported with native classes, since their
+behavior is too dynamic. You can use these metaclasses, however:
+
+* ``abc.ABCMeta``
+* ``typing.GenericMeta`` (used by ``typing.Generic``)
+
+.. note::
+
+   If a class definition uses an unsupported metaclass, *mypyc
+   compiles the class into a regular Python class*.
+
+Class decorators
+----------------
+
+Similar to metaclasses, most class decorators aren't supported with
+native classes, as they are usually too dynamic. These class
+decorators can be used with native classes, however:
+
+* ``mypy_extensions.trait`` (for defining :ref:`trait types <trait-types>`)
+* ``mypy_extensions.mypyc_attr`` (see :ref:`above <inheritance>`)
+* ``dataclasses.dataclass``
+* ``@attr.s(auto_attribs=True)``
+
+Dataclasses and attrs classes have partial native support, and they aren't as
+efficient as pure native classes.
+
+.. note::
+
+   If a class definition uses an unsupported class decorator, *mypyc
+   compiles the class into a regular Python class*.
+
+Deleting attributes
+-------------------
+
+By default, attributes defined in native classes can't be deleted. You
+can explicitly allow certain attributes to be deleted by using
+``__deletable__``::
+
+   class Cls:
+       x: int = 0
+       y: int = 0
+       other: int = 0
+
+       __deletable__ = ['x', 'y']  # 'x' and 'y' can be deleted
+
+   o = Cls()
+   del o.x  # OK
+   del o.y  # OK
+   del o.other  # Error
+
+You must initialize the ``__deletable__`` attribute in the class body,
+using a list or a tuple expression with only string literal items that
+refer to attributes. These are not valid::
+
+   a = ['x', 'y']
+
+   class Cls:
+       x: int
+       y: int
+
+       __deletable__ = a  # Error: cannot use variable 'a'
+
+   __deletable__ = ('a',)  # Error: not in a class body
+
+Other properties
+----------------
+
+Instances of native classes don't usually have a ``__dict__`` attribute.