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

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.

jaclang/vendor/mypyc/doc/native_operations.rst

@@ -0,0 +1,55 @@
+Miscellaneous native operations
+===============================
+
+This is a list of various non-type-specific operations that have
+custom native implementations.  If an operation has no native
+implementation, mypyc will use fallback generic implementations that
+are often not as fast.
+
+.. note::
+
+  Operations specific to various primitive types are described
+  in the following sections.
+
+Operators
+---------
+
+* ``x is y`` (this is very fast for all types)
+
+Functions
+---------
+
+* ``isinstance(obj, type: type)``
+* ``isinstance(obj, type: tuple)``
+* ``cast(<type>, obj)``
+* ``type(obj)``
+* ``len(obj)``
+* ``abs(obj)``
+* ``id(obj)``
+* ``iter(obj)``
+* ``next(iter: Iterator)``
+* ``hash(obj)``
+* ``getattr(obj, attr)``
+* ``getattr(obj, attr, default)``
+* ``setattr(obj, attr, value)``
+* ``hasattr(obj, attr)``
+* ``delattr(obj, name)``
+* ``slice(start, stop, step)``
+* ``globals()``
+
+Method decorators
+-----------------
+
+* ``@property``
+* ``@staticmethod``
+* ``@classmethod``
+* ``@abc.abstractmethod``
+
+Statements
+----------
+
+These variants of statements have custom implementations:
+
+* ``for ... in seq:`` (for loop over a sequence)
+* ``for ... in enumerate(...):``
+* ``for ... in zip(...):``

jaclang/vendor/mypyc/doc/performance_tips_and_tricks.rst

@@ -0,0 +1,244 @@
+.. _performance-tips:
+
+Performance tips and tricks
+===========================
+
+Performance optimization is part art, part science. Just using mypyc
+in a simple manner will likely make your code faster, but squeezing
+the most performance out of your code requires the use of some
+techniques we'll summarize below.
+
+Profiling
+---------
+
+If you are speeding up existing code, understanding where time is
+spent is important. Mypyc speeds up code that you compile. If most of
+the time is spent elsewhere, you may come back disappointed. For
+example, if you spend 40% of time outside compiled code, even if
+compiled code would go 100x faster, overall performance will only be
+2.5x faster.
+
+A simple (but often effective) approach is to record the time in
+various points of program execution using ``time.time()``, and to
+print out elapsed time (or to write it to a log file).
+
+The stdlib modules ``profile`` and ``cProfile`` can provide much more
+detailed data. (But these only work well with non-compiled code.)
+
+Avoiding slow libraries
+-----------------------
+
+If profiling indicates that a lot of time is spent in the stdlib or
+third-party libraries, you still have several options.
+
+First, if most time is spent in a few library features, you can
+perhaps easily reimplement them in type-annotated Python, or extract
+the relevant code and annotate it. Now it may be easy to compile this
+code to speed it up.
+
+Second, you may be able to avoid the library altogether, or use an
+alternative, more efficient library to achieve the same purpose.
+
+Type annotations
+----------------
+
+As discussed earlier, type annotations are key to major performance
+gains. You should at least consider adding annotations to any
+performance-critical functions and classes.  It may also be helpful to
+annotate code called by this code, even if it's not compiled, since
+this may help mypy infer better types in the compile code. If you use
+libraries, ensure they have stub files with decent type annotation
+coverage. Writing a stub file is often easy, and you only need to
+annotate features you use a lot.
+
+If annotating external code or writing stubs feel too burdensome, a
+simple workaround is to annotate variables explicitly. For example,
+here we call ``acme.get_items()``, but it has no type annotation. We
+can use an explicit type annotation for the variable to which we
+assign the result::
+
+    from typing import List, Tuple
+    import acme
+
+    def work() -> None:
+        # Annotate "items" to help mypyc
+        items: List[Tuple[int, str]] = acme.get_items()
+        for item in items:
+            ...  # Do some work here
+
+Without the annotation on ``items``, the type would be ``Any`` (since
+``acme`` has no type annotation), resulting in slower, generic
+operations being used later in the function.
+
+Avoiding slow Python features
+-----------------------------
+
+Mypyc can optimize some features more effectively than others. Here
+the difference is sometimes big -- some things only get marginally
+faster at best, while others can get 10x faster, or more. Avoiding
+these slow features in performance-critical parts of your code can
+help a lot.
+
+These are some of the most important things to avoid:
+
+* Using class decorators or metaclasses in compiled code (that aren't
+  properly supported by mypyc)
+
+* Heavy reliance on interpreted Python libraries (C extensions are
+  usually fine)
+
+These things also tend to be relatively slow:
+
+* Using Python classes and instances of Python classes (native classes
+  are much faster)
+
+* Calling decorated functions (``@property``, ``@staticmethod``, and
+  ``@classmethod`` are special cased and thus fast)
+
+* Calling nested functions
+
+* Calling functions or methods defined in other compilation units
+
+* Using ``*args`` or ``**kwargs``
+
+* Using generator functions
+
+* Using callable values (i.e. not leveraging early binding to call
+  functions or methods)
+
+Nested functions can often be replaced with module-level functions or
+methods of native classes.
+
+Callable values and nested functions can sometimes be replaced with an
+instance of a native class with a single method only, such as
+``call(...)``. You can derive the class from an ABC, if there are
+multiple possible functions.
+
+.. note::
+
+   Some slow features will likely get efficient implementations in the
+   future. You should check this section every once in a while to see
+   if some additional operations are fast.
+
+Using fast native features
+--------------------------
+
+Some native operations are particularly quick relative to the
+corresponding interpreted operations. Using them as much as possible
+may allow you to see 10x or more in performance gains.
+
+Some things are not much (or any) faster in compiled code, such as set
+math operations. In contrast, calling a method of a native class is
+much faster in compiled code.
+
+If you are used to optimizing for CPython, you might have replaced
+some class instances with dictionaries, as they can be
+faster. However, in compiled code, this "optimization" would likely
+slow down your code.
+
+Similarly, caching a frequently called method in a local variable can
+help in CPython, but it can slow things down in compiled code, since
+the code won't use :ref:`early binding <early-binding>`::
+
+    def squares(n: int) -> List[int]:
+        a = []
+        append = a.append  # Not a good idea in compiled code!
+        for i in range(n):
+            append(i * i)
+        return a
+
+Here are examples of features that are fast, in no particular order
+(this list is *not* exhaustive):
+
+* Calling compiled functions directly defined in the same compilation
+  unit (with positional and/or keyword arguments)
+
+* Calling methods of native classes defined in the same compilation
+  unit (with positional and/or keyword arguments)
+
+* Many integer operations
+
+* Many ``float`` operations
+
+* Booleans
+
+* :ref:`Native list operations <list-ops>`, such as indexing,
+  ``append``, and list comprehensions
+
+* While loops
+
+* For loops over ranges and lists, and with ``enumerate`` or ``zip``
+
+* Reading dictionary items
+
+* ``isinstance()`` checks against native classes and instances of
+  primitive types (and unions of them)
+
+* Accessing local variables
+
+* Accessing attributes of native classes
+
+* Accessing final module-level attributes
+
+* Comparing strings for equality
+
+These features are also fast, but somewhat less so (relative to other
+related operations):
+
+* Constructing instances of native classes
+
+* Constructing dictionaries
+
+* Setting dictionary items
+
+* Native :ref:`dict <dict-ops>` and :ref:`set <set-ops>` operations
+
+* Accessing module-level variables
+
+Generally anything documented as a native operation is fast, even if
+it's not explicitly mentioned here
+
+Adjusting garbage collection
+----------------------------
+
+Compilation does not speed up cyclic garbage collection. If everything
+else gets much faster, it's possible that garbage collection will take
+a big fraction of time. You can use ``gc.set_threshold()`` to adjust
+the garbage collector to run less often::
+
+    import gc
+
+    # Spend less time in gc; do this before significant computation
+    gc.set_threshold(150000)
+
+    ...  # Actual work happens here
+
+Fast interpreter shutdown
+-------------------------
+
+If you allocate many objects, it's possible that your program spends a
+lot of time cleaning up when the Python runtime shuts down. Mypyc
+won't speed up the shutdown of a Python process much.
+
+You can call ``os._exit(code)`` to immediately terminate the Python
+process, skipping normal cleanup. This can give a nice boost to a
+batch process or a command-line tool.
+
+.. note::
+
+   This can be dangerous and can lose data. You need to ensure
+   that all streams are flushed and everything is otherwise cleaned up
+   properly.
+
+Work smarter
+------------
+
+Usually there are many things you can do to improve performance, even
+if most tweaks will yield only minor gains. The key to being effective
+is to focus on things that give a large gain with a small effort.
+
+For example, low-level optimizations, such as avoiding a nested
+function, can be pointless, if you could instead avoid a metaclass --
+to allow a key class to be compiled as a native class. The latter
+optimization could speed up numerous method calls and attribute
+accesses, just like that.

jaclang/vendor/mypyc/doc/set_operations.rst

@@ -0,0 +1,47 @@
+.. _set-ops:
+
+Native set operations
+======================
+
+These ``set`` operations have fast, optimized implementations. Other
+set operations use generic implementations that are often slower.
+
+Construction
+------------
+
+Construct set with specific items:
+
+* ``{item0, ..., itemN}``
+
+Construct empty set:
+
+* ``set()``
+
+Construct set from iterable:
+
+* ``set(x: Iterable)``
+
+Set comprehensions:
+
+* ``{... for ... in ...}``
+* ``{... for ... in ... if ...}``
+
+Operators
+---------
+
+* ``item in s``
+
+Methods
+-------
+
+* ``s.add(item)``
+* ``s.remove(item)``
+* ``s.discard(item)``
+* ``s.update(x: Iterable)``
+* ``s.clear()``
+* ``s.pop()``
+
+Functions
+---------
+
+* ``len(s: set)``

jaclang/vendor/mypyc/doc/str_operations.rst

@@ -0,0 +1,35 @@
+.. _str-ops:
+
+Native string operations
+========================
+
+These ``str`` operations have fast, optimized implementations. Other
+string operations use generic implementations that are often slower.
+
+Construction
+------------
+
+* String literal
+* ``str(x: int)``
+* ``str(x: object)``
+
+Operators
+---------
+
+* Concatenation (``s1 + s2``)
+* Indexing (``s[n]``)
+* Slicing (``s[n:m]``, ``s[n:]``, ``s[:m]``)
+* Comparisons (``==``, ``!=``)
+* Augmented assignment (``s1 += s2``)
+
+Methods
+-------
+
+* ``s1.endswith(s2: str)``
+* ``s.join(x: Iterable)``
+* ``s.replace(old: str, new: str)``
+* ``s.replace(old: str, new: str, count: int)``
+* ``s.split()``
+* ``s.split(sep: str)``
+* ``s.split(sep: str, maxsplit: int)``
+* ``s1.startswith(s2: str)``

jaclang/vendor/mypyc/doc/tuple_operations.rst

@@ -0,0 +1,33 @@
+.. _tuple-ops:
+
+Native tuple operations
+=======================
+
+These ``tuple`` operations have fast, optimized implementations. Other
+tuple operations use generic implementations that are often slower.
+
+Unless mentioned otherwise, these operations apply to both fixed-length
+tuples and variable-length tuples.
+
+Construction
+------------
+
+* ``item0, ..., itemN`` (construct a tuple)
+* ``tuple(lst: list)`` (construct a variable-length tuple)
+* ``tuple(lst: Iterable)`` (construct a variable-length tuple)
+
+Operators
+---------
+
+* ``tup[n]`` (integer index)
+* ``tup[n:m]``, ``tup[n:]``, ``tup[:m]`` (slicing)
+
+Statements
+----------
+
+* ``item0, ..., itemN = tup`` (for fixed-length tuples)
+
+Functions
+---------
+
+* ``len(tup: tuple)``