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

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`

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