jaclang 0.7.34__py3-none-any.whl → 0.8.0__py3-none-any.whl

jaclang/vendor/mypyc/doc/differences_from_python.rst

@@ -1,332 +0,0 @@
-.. _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

@@ -1,50 +0,0 @@
-.. _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

@@ -1,42 +0,0 @@
-# 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

@@ -1,240 +0,0 @@
-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`