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

jaclang/vendor/mypyc/doc/differences_from_python.rst

@@ -0,0 +1,332 @@
+.. _differences-from-python:
+
+Differences from Python
+=======================
+
+Mypyc aims to be sufficiently compatible with Python semantics so that
+migrating code to mypyc often doesn't require major code
+changes. There are various differences to enable performance gains
+that you need to be aware of, however.
+
+This section documents notable differences from Python. We discuss
+many of them also elsewhere, but it's convenient to have them here in
+one place.
+
+Running compiled modules
+------------------------
+
+You can't use ``python3 <module>.py`` or ``python3 -m <module>``
+to run compiled modules. Use ``python3 -c "import <module>"`` instead,
+or write a wrapper script that imports your module.
+
+As a side effect, you can't rely on checking the ``__name__`` attribute in compiled
+code, like this::
+
+    if __name__ == "__main__":  # Can't be used in compiled code
+        main()
+
+Type errors prevent compilation
+-------------------------------
+
+You can't compile code that generates mypy type check errors. You can
+sometimes ignore these with a ``# type: ignore`` comment, but this can
+result in bad code being generated, and it's considered dangerous.
+
+.. note::
+
+    In the future, mypyc may reject ``# type: ignore`` comments that
+    may be unsafe.
+
+Runtime type checking
+---------------------
+
+Non-erased types in annotations will be type checked at runtime. For example,
+consider this function::
+
+    def twice(x: int) -> int:
+        return x * 2
+
+If you try to call this function with a ``float`` or ``str`` argument,
+you'll get a type error on the call site, even if the call site is not
+being type checked::
+
+    twice(5)  # OK
+    twice(2.2)  # TypeError
+    twice("blah")  # TypeError
+
+Also, values with *inferred* types will be type checked. For example,
+consider a call to the stdlib function ``socket.gethostname()`` in
+compiled code. This function is not compiled (no stdlib modules are
+compiled with mypyc), but mypyc uses a *library stub file* to infer
+the return type as ``str``. Compiled code calling ``gethostname()``
+will fail with ``TypeError`` if ``gethostname()`` would return an
+incompatible value, such as ``None``::
+
+    import socket
+
+    # Fail if returned value is not a str
+    name = socket.gethostname()
+
+Note that ``gethostname()`` is defined like this in the stub file for
+``socket`` (in typeshed)::
+
+    def gethostname() -> str: ...
+
+Thus mypyc verifies that library stub files and annotations in
+non-compiled code match runtime values. This adds an extra layer of
+type safety.
+
+Casts such as ``cast(str, x)`` will also result in strict type
+checks. Consider this example::
+
+    from typing import cast
+    ...
+    x = cast(str, y)
+
+The last line is essentially equivalent to this Python code when compiled::
+
+    if not isinstance(y, str):
+        raise TypeError(...)
+    x = y
+
+In interpreted mode ``cast`` does not perform a runtime type check.
+
+Native classes
+--------------
+
+Native classes behave differently from Python classes.  See
+:ref:`native-classes` for the details.
+
+Primitive types
+---------------
+
+Some primitive types behave differently in compiled code to improve
+performance.
+
+``int`` objects use an unboxed (non-heap-allocated) representation for small
+integer values. A side effect of this is that the exact runtime type of
+``int`` values is lost. For example, consider this simple function::
+
+    def first_int(x: List[int]) -> int:
+        return x[0]
+
+    print(first_int([True]))  # Output is 1, instead of True!
+
+``bool`` is a subclass of ``int``, so the above code is
+valid. However, when the list value is converted to ``int``, ``True``
+is converted to the corresponding ``int`` value, which is ``1``.
+
+Note that integers still have an arbitrary precision in compiled code,
+similar to normal Python integers.
+
+Fixed-length tuples are unboxed, similar to integers. The exact type
+and identity of fixed-length tuples is not preserved, and you can't
+reliably use ``is`` checks to compare tuples that are used in compiled
+code.
+
+.. _early-binding:
+
+Early binding
+-------------
+
+References to functions, types, most attributes, and methods in the
+same :ref:`compilation unit <compilation-units>` use *early binding*:
+the target of the reference is decided at compile time, whenever
+possible. This contrasts with normal Python behavior of *late
+binding*, where the target is found by a namespace lookup at
+runtime. Omitting these namespace lookups improves performance, but
+some Python idioms don't work without changes.
+
+Note that non-final module-level variables still use late binding.
+You may want to avoid these in very performance-critical code.
+
+Examples of early and late binding::
+
+    from typing import Final
+
+    import lib  # "lib" is not compiled
+
+    x = 0
+    y: Final = 1
+
+    def func() -> None:
+        pass
+
+    class Cls:
+        def __init__(self, attr: int) -> None:
+            self.attr = attr
+
+        def method(self) -> None:
+            pass
+
+    def example() -> None:
+        # Early binding:
+        var = y
+        func()
+        o = Cls()
+        o.x
+        o.method()
+
+        # Late binding:
+        var = x  # Module-level variable
+        lib.func()  # Accessing library that is not compiled
+
+Pickling and copying objects
+----------------------------
+
+Mypyc tries to enforce that instances native classes are properly
+initialized by calling ``__init__`` implicitly when constructing
+objects, even if objects are constructed through ``pickle``,
+``copy.copy`` or ``copy.deepcopy``, for example.
+
+If a native class doesn't support calling ``__init__`` without arguments,
+you can't pickle or copy instances of the class. Use the
+``mypy_extensions.mypyc_attr`` class decorator to override this behavior
+and enable pickling through the ``serializable`` flag::
+
+    from mypy_extensions import mypyc_attr
+    import pickle
+
+    @mypyc_attr(serializable=True)
+    class Cls:
+        def __init__(self, n: int) -> None:
+            self.n = n
+
+    data = pickle.dumps(Cls(5))
+    obj = pickle.loads(data)  # OK
+
+Additional notes:
+
+* All subclasses inherit the ``serializable`` flag.
+* If a class has the ``allow_interpreted_subclasses`` attribute, it
+  implicitly supports serialization.
+* Enabling serialization may slow down attribute access, since compiled
+  code has to be always prepared to raise ``AttributeError`` in case an
+  attribute is not defined at runtime.
+* If you try to pickle an object without setting the ``serializable``
+  flag, you'll get a ``TypeError`` about missing arguments to
+  ``__init__``.
+
+
+Monkey patching
+---------------
+
+Since mypyc function and class definitions are immutable, you can't
+perform arbitrary monkey patching, such as replacing functions or
+methods with mocks in tests.
+
+.. note::
+
+    Each compiled module has a Python namespace that is initialized to
+    point to compiled functions and type objects. This namespace is a
+    regular ``dict`` object, and it *can* be modified. However,
+    compiled code generally doesn't use this namespace, so any changes
+    will only be visible to non-compiled code.
+
+Stack overflows
+---------------
+
+Compiled code currently doesn't check for stack overflows. Your
+program may crash in an unrecoverable fashion if you have too many
+nested function calls, typically due to out-of-control recursion.
+
+.. note::
+
+   This limitation will be fixed in the future.
+
+Final values
+------------
+
+Compiled code replaces a reference to an attribute declared ``Final`` with
+the value of the attribute computed at compile time. This is an example of
+:ref:`early binding <early-binding>`. Example::
+
+    MAX: Final = 100
+
+    def limit_to_max(x: int) -> int:
+         if x > MAX:
+             return MAX
+         return x
+
+The two references to ``MAX`` don't involve any module namespace lookups,
+and are equivalent to this code::
+
+    def limit_to_max(x: int) -> int:
+         if x > 100:
+             return 100
+         return x
+
+When run as interpreted, the first example will execute slower due to
+the extra namespace lookups. In interpreted code final attributes can
+also be modified.
+
+Unsupported features
+--------------------
+
+Some Python features are not supported by mypyc (yet). They can't be
+used in compiled code, or there are some limitations. You can
+partially work around some of these limitations by running your code
+in interpreted mode.
+
+Nested classes
+**************
+
+Nested classes are not supported.
+
+Conditional functions or classes
+********************************
+
+Function and class definitions guarded by an if-statement are not supported.
+
+Dunder methods
+**************
+
+Native classes **cannot** use these dunders. If defined, they will not
+work as expected.
+
+* ``__del__``
+* ``__index__``
+* ``__getattr__``, ``__getattribute__``
+* ``__setattr__``
+* ``__delattr__``
+
+Generator expressions
+*********************
+
+Generator expressions are not supported. To make it easier to compile
+existing code, they are implicitly replaced with list comprehensions.
+*This does not always produce the same behavior.*
+
+To work around this limitation, you can usually use a generator
+function instead.  You can sometimes replace the generator expression
+with an explicit list comprehension.
+
+Descriptors
+***********
+
+Native classes can't contain arbitrary descriptors. Properties, static
+methods and class methods are supported.
+
+Introspection
+*************
+
+Various methods of introspection may break by using mypyc. Here's an
+non-exhaustive list of what won't work:
+
+- Instance ``__annotations__`` is usually not kept
+- Frames of compiled functions can't be inspected using ``inspect``
+- Compiled methods aren't considered methods by ``inspect.ismethod``
+- ``inspect.signature`` chokes on compiled functions
+
+Profiling hooks and tracing
+***************************
+
+Compiled functions don't trigger profiling and tracing hooks, such as
+when using the ``profile``, ``cProfile``, or ``trace`` modules.
+
+Debuggers
+*********
+
+You can't set breakpoints in compiled functions or step through
+compiled functions using ``pdb``. Often you can debug your code in
+interpreted mode instead.

jaclang/vendor/mypyc/doc/float_operations.rst

@@ -0,0 +1,50 @@
+.. _float-ops:
+
+Native float operations
+========================
+
+These ``float`` operations have fast, optimized implementations. Other
+floating point operations use generic implementations that are often
+slower.
+
+Construction
+------------
+
+* Float literal
+* ``float(x: int)``
+* ``float(x: i64)``
+* ``float(x: i32)``
+* ``float(x: i16)``
+* ``float(x: u8)``
+* ``float(x: str)``
+* ``float(x: float)`` (no-op)
+
+Operators
+---------
+
+* Arithmetic (``+``, ``-``, ``*``, ``/``, ``//``, ``%``)
+* Comparisons (``==``, ``!=``, ``<``, etc.)
+* Augmented assignment (``x += y``, etc.)
+
+Functions
+---------
+
+* ``int(f)``
+* ``i64(f)`` (convert to 64-bit signed integer)
+* ``i32(f)`` (convert to 32-bit signed integer)
+* ``i16(f)`` (convert to 16-bit signed integer)
+* ``u8(f)`` (convert to 8-bit unsigned integer)
+* ``abs(f)``
+* ``math.sin(f)``
+* ``math.cos(f)``
+* ``math.tan(f)``
+* ``math.sqrt(f)``
+* ``math.exp(f)``
+* ``math.log(f)``
+* ``math.floor(f)``
+* ``math.ceil(f)``
+* ``math.fabs(f)``
+* ``math.pow(x, y)``
+* ``math.copysign(x, y)``
+* ``math.isinf(f)``
+* ``math.isnan(f)``

jaclang/vendor/mypyc/doc/future.md

@@ -0,0 +1,42 @@
+# Future
+
+This document introduces some ideas for future improvements.
+
+## Basic Optimizations
+
+Implement basic optimizations such as common subexpression elimination and
+loop invariant code motion.
+
+Importantly, common subexpression elimination could be used to avoid
+redundant type checks.
+
+## Operation-specific Optimizations
+
+Some operations or combinations of successive operations can be
+replaced with more efficient operations. Examples:
+
+* If `s` is a string, `s[i] == 'x'` doesn't need to construct the
+  intermediate single-character string object `s[i]` but just compare
+  the character value to `ord('x')`.
+
+* `a + ':' + b` (two string concetenations) can be implemented as
+  single three-operand concatenation that doesn't construct an
+  intermediate object.
+
+* `x in {1, 3}` can be translated into `x == 1 or x == 3` (more
+  generally we need to evaluate all right-hand-side items).
+
+## Integer Range Analysis
+
+Implement integer range analysis. This can be used in various ways:
+
+* Use untagged representations for some registers.
+* Use faster integer arithmetic operations for operations that
+  only deal with short integers or that can't overflow.
+* Remove redundant list and string index checks.
+
+## Always Defined Attributes
+
+Somehow make it possible to enforce that attributes in a class are always
+defined. This makes attribute access faster since we don't need to explicitly
+check if the attribute is defined.

jaclang/vendor/mypyc/doc/getting_started.rst

@@ -0,0 +1,240 @@
+Getting started
+===============
+
+Here you will learn some basic things you need to know to get started with mypyc.
+
+Prerequisites
+-------------
+
+You need a Python C extension development environment. The way to set this up
+depends on your operating system.
+
+macOS
+*****
+
+Install Xcode command line tools:
+
+.. code-block::
+
+    $ xcode-select --install
+
+Linux
+*****
+
+You need a C compiler and CPython headers and libraries. The specifics
+of how to install these varies by distribution. Here are instructions for
+Ubuntu 18.04, for example:
+
+.. code-block::
+
+    $ sudo apt install python3-dev
+
+Windows
+*******
+
+From `Build Tools for Visual Studio 2022 <https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2022>`_, install MSVC C++ build tools for your architecture and a Windows SDK. (latest versions recommended)
+
+Installation
+------------
+
+Mypyc is shipped as part of the mypy distribution. Install mypy like
+this (you need Python 3.8 or later):
+
+.. code-block::
+
+    $ python3 -m pip install -U 'mypy[mypyc]'
+
+On some systems you need to use this instead:
+
+.. code-block::
+
+    $ python -m pip install -U 'mypy[mypyc]'
+
+Example program
+---------------
+
+Let's start with a classic micro-benchmark, recursive fibonacci. Save
+this file as ``fib.py``:
+
+.. code-block:: python
+
+   import time
+
+   def fib(n: int) -> int:
+       if n <= 1:
+           return n
+       else:
+           return fib(n - 2) + fib(n - 1)
+
+   t0 = time.time()
+   fib(32)
+   print(time.time() - t0)
+
+Note that we gave the ``fib`` function a type annotation. Without it,
+performance won't be as impressive after compilation.
+
+.. note::
+
+   `Mypy documentation
+   <https://mypy.readthedocs.io/en/stable/index.html>`_ is a good
+   introduction if you are new to type annotations or mypy. Mypyc uses
+   mypy to perform type checking and type inference, so some familiarity
+   with mypy is very useful.
+
+Compiling and running
+---------------------
+
+We can run ``fib.py`` as a regular, interpreted program using CPython:
+
+.. code-block:: console
+
+    $ python3 fib.py
+    0.4125328063964844
+
+It took about 0.41s to run on my computer.
+
+Run ``mypyc`` to compile the program to a binary C extension:
+
+.. code-block:: console
+
+    $ mypyc fib.py
+
+This will generate a C extension for ``fib`` in the current working
+directory.  For example, on a Linux system the generated file may be
+called ``fib.cpython-37m-x86_64-linux-gnu.so``.
+
+Since C extensions can't be run as programs, use ``python3 -c`` to run
+the compiled module as a program:
+
+.. code-block:: console
+
+    $ python3 -c "import fib"
+    0.04097270965576172
+
+After compilation, the program is about 10x faster. Nice!
+
+.. note::
+
+   ``__name__`` in ``fib.py`` would now be ``"fib"``, not ``"__main__"``.
+
+You can also pass most
+`mypy command line options <https://mypy.readthedocs.io/en/stable/command_line.html>`_
+to ``mypyc``.
+
+Deleting compiled binary
+------------------------
+
+You can manually delete the C extension to get back to an interpreted
+version (this example works on Linux):
+
+.. code-block::
+
+    $ rm fib.*.so
+
+Using setup.py
+--------------
+
+You can also use ``setup.py`` to compile modules using mypyc. Here is an
+example ``setup.py`` file::
+
+    from setuptools import setup
+
+    from mypyc.build import mypycify
+
+    setup(
+        name='mylib',
+        packages=['mylib'],
+        ext_modules=mypycify([
+            'mylib/__init__.py',
+            'mylib/mod.py',
+        ]),
+    )
+
+We used ``mypycify(...)`` to specify which files to compile using
+mypyc.  Your ``setup.py`` can include additional Python files outside
+``mypycify(...)`` that won't be compiled.
+
+Now you can build a wheel (.whl) file for the package::
+
+    python3 setup.py bdist_wheel
+
+The wheel is created under ``dist/``.
+
+You can also compile the C extensions in-place, in the current directory (similar
+to using ``mypyc`` to compile modules)::
+
+    python3 setup.py build_ext --inplace
+
+You can include most `mypy command line options
+<https://mypy.readthedocs.io/en/stable/command_line.html>`_ in the
+list of arguments passed to ``mypycify()``. For example, here we use
+the ``--disallow-untyped-defs`` flag to require that all functions
+have type annotations::
+
+    ...
+    setup(
+        name='frobnicate',
+        packages=['frobnicate'],
+        ext_modules=mypycify([
+            '--disallow-untyped-defs',  # Pass a mypy flag
+            'frobnicate.py',
+        ]),
+    )
+
+.. note:
+
+   You may be tempted to use `--check-untyped-defs
+   <https://mypy.readthedocs.io/en/stable/command_line.html#cmdoption-mypy-check-untyped-defs>`_
+   to type check functions without type annotations. Note that this
+   may reduce performance, due to many transitions between type-checked and unchecked
+   code.
+
+Recommended workflow
+--------------------
+
+A simple way to use mypyc is to always compile your code after any
+code changes, but this can get tedious, especially if you have a lot
+of code. Instead, you can do most development in interpreted mode.
+This development workflow has worked smoothly for developing mypy and
+mypyc (often we forget that we aren't working on a vanilla Python
+project):
+
+1. During development, use interpreted mode. This gives you a fast
+   edit-run cycle.
+
+2. Use type annotations liberally and use mypy to type check your code
+   during development. Mypy and tests can find most errors that would
+   break your compiled code, if you have good type annotation
+   coverage. (Running mypy is pretty quick.)
+
+3. After you've implemented a feature or a fix, compile your project
+   and run tests again, now in compiled mode. Usually nothing will
+   break here, assuming your type annotation coverage is good. This
+   can happen locally or in a Continuous Integration (CI) job. If you
+   have CI, compiling locally may be rarely needed.
+
+4. Release or deploy a compiled version. Optionally, include a
+   fallback interpreted version for platforms that mypyc doesn't
+   support.
+
+This mypyc workflow only involves minor tweaks to a typical Python
+workflow. Most of development, testing and debugging happens in
+interpreted mode. Incremental mypy runs, especially when using the
+mypy daemon, are very quick (often a few hundred milliseconds).
+
+Next steps
+----------
+
+You can sometimes get good results by just annotating your code and
+compiling it. If this isn't providing meaningful performance gains, if
+you have trouble getting your code to work under mypyc, or if you want
+to optimize your code for maximum performance, you should read the
+rest of the documentation in some detail.
+
+Here are some specific recommendations, or you can just read the
+documentation in order:
+
+* :ref:`using-type-annotations`
+* :ref:`native-classes`
+* :ref:`differences-from-python`
+* :ref:`performance-tips`