QCodeSitter 0.1.0__py3-none-any.whl

QCodeSitter/languages/python.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from collections.abc import Collection
+from typing import TYPE_CHECKING
+
+from ..utils import leading_whitespace
+from .base import IndentRules, LanguageSpec
+from .python_highlights import HIGHLIGHT_QUERY
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+# Statements whose body starts after a colon
+_BLOCK_TYPES = frozenset(
+    {
+        "if_statement",
+        "for_statement",
+        "while_statement",
+        "function_definition",
+        "class_definition",
+        "with_statement",
+        "try_statement",
+        "except_clause",
+        "finally_clause",
+        "elif_clause",
+        "else_clause",
+        "match_statement",
+        "case_clause",
+    }
+)
+_COLLECTION_TYPES = frozenset(
+    {"list", "dictionary", "set", "tuple", "argument_list", "parameters"}
+)
+# Statements that end their block, so the next line dedents
+_TERMINAL_TYPES = frozenset(
+    {
+        "return_statement",
+        "break_statement",
+        "continue_statement",
+        "pass_statement",
+        "raise_statement",
+    }
+)
+_OPEN_BRACKETS = frozenset("([{")
+_CLOSE_BRACKETS = frozenset(")]}")
+
+
+def _child_of_type(node: Node, types: Collection[str]) -> Node | None:
+    for child in node.children:
+        if child.type in types:
+            return child
+    return None
+
+
+def _opens_block(node: Node, row: int) -> bool:
+    """Whether this node starts an indented block or open bracket on the row"""
+    if node.type in _BLOCK_TYPES:
+        # The colon can be followed by a comment, like "def foo():  # comment"
+        colon = _child_of_type(node, (":",))
+        return colon is not None and colon.start_point.row == row
+    if node.type in _OPEN_BRACKETS:
+        # Incomplete code can leave a bare bracket in an ERROR node
+        return node.start_point.row == row
+    if node.type in _COLLECTION_TYPES:
+        opening = _child_of_type(node, _OPEN_BRACKETS)
+        closing = _child_of_type(node, _CLOSE_BRACKETS)
+        if opening is None or opening.start_point.row != row:
+            return False
+        return closing is None or closing.start_point.row != row
+    return False
+
+
+class PythonIndentRules(IndentRules):
+    def should_indent_after(self, row: int, col: int) -> bool:
+        node = self.node_at(row, col)
+        while node is not None:
+            if _opens_block(node, row):
+                return True
+            node = node.parent
+        return False
+
+    def should_dedent_after(self, row: int, col: int) -> bool:
+        node = self.node_at(row, col)
+        if node is None:
+            return False
+        if self._closes_earlier_bracket(row, col):
+            return True
+        while node is not None:
+            if node.type in _TERMINAL_TYPES:
+                return True
+            node = node.parent
+        return False
+
+    def _closes_earlier_bracket(self, row: int, col: int) -> bool:
+        """Whether the line starts with a bracket, after the column, that closes
+        a bracket opened on an earlier line
+        """
+        line_text = self.document.findBlockByNumber(row).text()
+        # The indent is all whitespace, so its length is also its UTF-16 length
+        bracket_col = len(leading_whitespace(line_text))
+        if line_text[bracket_col : bracket_col + 1] not in _CLOSE_BRACKETS:
+            return False
+        # Enter after the bracket keeps the indent of the closing line
+        if col >= bracket_col:
+            return False
+        bracket = self.node_at(row, bracket_col)
+        if bracket is None or bracket.parent is None:
+            return False
+        opening = _child_of_type(bracket.parent, _OPEN_BRACKETS)
+        return opening is not None and opening.start_point.row < row
+
+
+IDENTIFIER_QUERY = """
+(function_definition name: (identifier) @function)
+(class_definition name: (identifier) @class)
+(assignment left: (identifier) @variable)
+(parameters (identifier) @parameter)
+(import_statement name: (dotted_name (identifier) @import))
+(import_from_statement name: (dotted_name (identifier) @import))
+(aliased_import name: (dotted_name (identifier) @import))
+(aliased_import alias: (identifier) @import)
+"""
+
+PYTHON = LanguageSpec(
+    name="python",
+    comment_prefix="# ",
+    highlight_query=HIGHLIGHT_QUERY,
+    identifier_query=IDENTIFIER_QUERY,
+    fold_hide_last_line=frozenset(
+        {
+            "class_definition",
+            "for_statement",
+            "function_definition",
+            "if_statement",
+            "match_statement",
+            "try_statement",
+            "while_statement",
+            "with_statement",
+        }
+    ),
+    fold_keep_last_line=frozenset({"argument_list", "dictionary", "list", "tuple"}),
+    indent_rules=PythonIndentRules,
+    no_completion_types=frozenset({"string", "comment", "string_start", "string_end"}),
+    string_type="string",
+    string_delimiter_types=("string_start", "string_end"),
+)

QCodeSitter/languages/python_highlights.py

@@ -0,0 +1,444 @@
+HIGHLIGHT_QUERY = """
+; From tree-sitter-python licensed under MIT License
+; Copyright (c) 2016 Max Brunsfeld
+; Variables
+(identifier) @variable
+
+; Reset highlighting in f-string interpolations
+(interpolation) @none
+
+; Identifier naming conventions
+((identifier) @type
+  (#match? @type "^[A-Z].*[a-z]"))
+
+((identifier) @constant
+  (#match? @constant "^[A-Z][A-Z_0-9]*$"))
+
+((identifier) @constant.builtin
+  (#match? @constant.builtin "^__[a-zA-Z0-9_]*__$"))
+
+((identifier) @constant.builtin
+  (#any-of? @constant.builtin
+    ; https://docs.python.org/3/library/constants.html
+    "NotImplemented" "Ellipsis" "quit" "exit" "copyright" "credits" "license"))
+
+"_" @character.special ; match wildcard
+
+((assignment
+  left: (identifier) @type.definition
+  (type
+    (identifier) @_annotation))
+  (#eq? @_annotation "TypeAlias"))
+
+((assignment
+  left: (identifier) @type.definition
+  right: (call
+    function: (identifier) @_func))
+  (#any-of? @_func "TypeVar" "NewType"))
+
+; Function definitions
+(function_definition
+  name: (identifier) @function)
+
+(type
+  (identifier) @type)
+
+(type
+  (subscript
+    (identifier) @type)) ; type subscript: Tuple[int]
+
+((call
+  function: (identifier) @_isinstance
+  arguments: (argument_list
+    (_)
+    (identifier) @type))
+  (#eq? @_isinstance "isinstance"))
+
+; Literals
+(none) @constant.builtin
+
+[
+  (true)
+  (false)
+] @boolean
+
+(integer) @number
+
+(float) @number.float
+
+(comment) @comment @spell
+
+((module
+  .
+  (comment) @keyword.directive @nospell)
+  (#match? @keyword.directive "^#!/"))
+
+(string) @string
+
+[
+  (escape_sequence)
+  (escape_interpolation)
+] @string.escape
+
+; doc-strings
+(expression_statement
+  (string
+    (string_content) @spell) @string.documentation)
+
+; Tokens
+[
+  "-"
+  "-="
+  ":="
+  "!="
+  "*"
+  "**"
+  "**="
+  "*="
+  "/"
+  "//"
+  "//="
+  "/="
+  "&"
+  "&="
+  "%"
+  "%="
+  "^"
+  "^="
+  "+"
+  "+="
+  "<"
+  "<<"
+  "<<="
+  "<="
+  "<>"
+  "="
+  "=="
+  ">"
+  ">="
+  ">>"
+  ">>="
+  "@"
+  "@="
+  "|"
+  "|="
+  "~"
+  "->"
+] @operator
+
+; Keywords
+[
+  "and"
+  "in"
+  "is"
+  "not"
+  "or"
+  "is not"
+  "not in"
+  "del"
+] @keyword.operator
+
+[
+  "def"
+  "lambda"
+] @keyword.function
+
+[
+  "assert"
+  "exec"
+  "global"
+  "nonlocal"
+  "pass"
+  "print"
+  "with"
+  "as"
+] @keyword
+
+[
+  "type"
+  "class"
+] @keyword.type
+
+[
+  "async"
+  "await"
+] @keyword.coroutine
+
+[
+  "return"
+  "yield"
+] @keyword.return
+
+(yield
+  "from" @keyword.return)
+
+(future_import_statement
+  "from" @keyword.import
+  "__future__" @module.builtin)
+
+(import_from_statement
+  "from" @keyword.import)
+
+"import" @keyword.import
+
+(aliased_import
+  "as" @keyword.import)
+
+(wildcard_import
+  "*" @character.special)
+
+(import_statement
+  name: (dotted_name
+    (identifier) @module))
+
+(import_statement
+  name: (aliased_import
+    name: (dotted_name
+      (identifier) @module)
+    alias: (identifier) @module))
+
+(import_from_statement
+  module_name: (dotted_name
+    (identifier) @module))
+
+(import_from_statement
+  module_name: (relative_import
+    (dotted_name
+      (identifier) @module)))
+
+[
+  "if"
+  "elif"
+  "else"
+  "match"
+  "case"
+] @keyword.conditional
+
+[
+  "for"
+  "while"
+  "break"
+  "continue"
+] @keyword.repeat
+
+[
+  "try"
+  "except"
+  "raise"
+  "finally"
+] @keyword.exception
+
+(raise_statement
+  "from" @keyword.exception)
+
+(try_statement
+  (else_clause
+    "else" @keyword.exception))
+
+[
+  "("
+  ")"
+  "["
+  "]"
+  "{"
+  "}"
+] @punctuation.bracket
+
+(interpolation
+  "{" @punctuation.special
+  "}" @punctuation.special)
+
+(type_conversion) @function.macro
+
+[
+  ","
+  "."
+  ":"
+  ";"
+  (ellipsis)
+] @punctuation.delimiter
+
+((identifier) @type.builtin
+  (#any-of? @type.builtin
+    ; https://docs.python.org/3/library/exceptions.html
+    "BaseException" "Exception" "ArithmeticError" "BufferError" "LookupError" "AssertionError"
+    "AttributeError" "EOFError" "FloatingPointError" "GeneratorExit" "ImportError"
+    "ModuleNotFoundError" "IndexError" "KeyError" "KeyboardInterrupt" "MemoryError" "NameError"
+    "NotImplementedError" "OSError" "OverflowError" "RecursionError" "ReferenceError" "RuntimeError"
+    "StopIteration" "StopAsyncIteration" "SyntaxError" "IndentationError" "TabError" "SystemError"
+    "SystemExit" "TypeError" "UnboundLocalError" "UnicodeError" "UnicodeEncodeError"
+    "UnicodeDecodeError" "UnicodeTranslateError" "ValueError" "ZeroDivisionError" "EnvironmentError"
+    "IOError" "WindowsError" "BlockingIOError" "ChildProcessError" "ConnectionError"
+    "BrokenPipeError" "ConnectionAbortedError" "ConnectionRefusedError" "ConnectionResetError"
+    "FileExistsError" "FileNotFoundError" "InterruptedError" "IsADirectoryError"
+    "NotADirectoryError" "PermissionError" "ProcessLookupError" "TimeoutError" "Warning"
+    "UserWarning" "DeprecationWarning" "PendingDeprecationWarning" "SyntaxWarning" "RuntimeWarning"
+    "FutureWarning" "ImportWarning" "UnicodeWarning" "BytesWarning" "ResourceWarning"
+    ; https://docs.python.org/3/library/stdtypes.html
+    "bool" "int" "float" "complex" "list" "tuple" "range" "str" "bytes" "bytearray" "memoryview"
+    "set" "frozenset" "dict" "type" "object"))
+
+; Normal parameters
+(parameters
+  (identifier) @variable.parameter)
+
+; Lambda parameters
+(lambda_parameters
+  (identifier) @variable.parameter)
+
+(lambda_parameters
+  (tuple_pattern
+    (identifier) @variable.parameter))
+
+; Default parameters
+(keyword_argument
+  name: (identifier) @variable.parameter)
+
+; Naming parameters on call-site
+(default_parameter
+  name: (identifier) @variable.parameter)
+
+(typed_parameter
+  (identifier) @variable.parameter)
+
+(typed_default_parameter
+  name: (identifier) @variable.parameter)
+
+; Variadic parameters *args, **kwargs
+(parameters
+  (list_splat_pattern ; *args
+    (identifier) @variable.parameter))
+
+(parameters
+  (dictionary_splat_pattern ; **kwargs
+    (identifier) @variable.parameter))
+
+; Typed variadic parameters
+(parameters
+  (typed_parameter
+    (list_splat_pattern ; *args: type
+      (identifier) @variable.parameter)))
+
+(parameters
+  (typed_parameter
+    (dictionary_splat_pattern ; *kwargs: type
+      (identifier) @variable.parameter)))
+
+; Lambda parameters
+(lambda_parameters
+  (list_splat_pattern
+    (identifier) @variable.parameter))
+
+(lambda_parameters
+  (dictionary_splat_pattern
+    (identifier) @variable.parameter))
+
+((identifier) @variable.builtin
+  (#eq? @variable.builtin "self"))
+
+((identifier) @variable.builtin
+  (#eq? @variable.builtin "cls"))
+
+; After @type.builtin bacause builtins (such as `type`) are valid as attribute name
+((attribute
+  attribute: (identifier) @variable.member)
+  (#match? @variable.member "^[%l_].*$"))
+
+; Class definitions
+(class_definition
+  name: (identifier) @type)
+
+(class_definition
+  body: (block
+    (function_definition
+      name: (identifier) @function.method)))
+
+(class_definition
+  superclasses: (argument_list
+    (identifier) @type))
+
+((class_definition
+  body: (block
+    (expression_statement
+      (assignment
+        left: (identifier) @variable.member))))
+  (#match? @variable.member "^[%l_].*$"))
+
+((class_definition
+  body: (block
+    (expression_statement
+      (assignment
+        left: (_
+          (identifier) @variable.member)))))
+  (#match? @variable.member "^[%l_].*$"))
+
+((class_definition
+  (block
+    (function_definition
+      name: (identifier) @constructor)))
+  (#any-of? @constructor "__new__" "__init__"))
+
+; Function calls
+(call
+  function: (identifier) @function.call)
+
+(call
+  function: (attribute
+    attribute: (identifier) @function.method.call))
+
+((call
+  function: (identifier) @constructor)
+  (#match? @constructor "^%u"))
+
+((call
+  function: (attribute
+    attribute: (identifier) @constructor))
+  (#match? @constructor "^%u"))
+
+; Builtin functions
+((call
+  function: (identifier) @function.builtin)
+  (#any-of? @function.builtin
+    "abs" "all" "any" "ascii" "bin" "bool" "breakpoint" "bytearray" "bytes" "callable" "chr"
+    "classmethod" "compile" "complex" "delattr" "dict" "dir" "divmod" "enumerate" "eval" "exec"
+    "filter" "float" "format" "frozenset" "getattr" "globals" "hasattr" "hash" "help" "hex" "id"
+    "input" "int" "isinstance" "issubclass" "iter" "len" "list" "locals" "map" "max" "memoryview"
+    "min" "next" "object" "oct" "open" "ord" "pow" "print" "property" "range" "repr" "reversed"
+    "round" "set" "setattr" "slice" "sorted" "staticmethod" "str" "sum" "super" "tuple" "type"
+    "vars" "zip" "__import__"))
+
+; Regex from the `re` module
+(call
+  function: (attribute
+    object: (identifier) @_re)
+  arguments: (argument_list
+    .
+    (string
+      (string_content) @string.regexp))
+  (#eq? @_re "re"))
+
+; Decorators
+((decorator
+  "@" @attribute)
+  (#set! priority 101))
+
+(decorator
+  (identifier) @attribute)
+
+(decorator
+  (attribute
+    attribute: (identifier) @attribute))
+
+(decorator
+  (call
+    (identifier) @attribute))
+
+(decorator
+  (call
+    (attribute
+      attribute: (identifier) @attribute)))
+
+((decorator
+  (identifier) @attribute.builtin)
+  (#any-of? @attribute.builtin "classmethod" "property" "staticmethod"))
+"""

QCodeSitter/queries/__init__.py

@@ -0,0 +1,73 @@
+"""Compiling and running tree-sitter queries
+
+Every query is compiled with `compile_query` and run with `query_byte_range`.
+Tree-sitter can't evaluate text predicates like #eq? on our UTF-16 trees, so
+compile_query renames them and query_byte_range evaluates them against the
+document text. predicates.py has the details
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from collections.abc import Callable
+from typing import Literal
+
+from tree_sitter import Language, Node, Query, QueryCursor, QueryError
+
+from .predicates import QueryPredicates, prepare_query_source
+
+# A predicate argument is (value, "capture" or "string")
+PredicateArgs = list[tuple[str, Literal["capture", "string"]]]
+# Capture name -> the nodes it captured
+Captures = dict[str, list[Node]]
+
+
+@functools.lru_cache(maxsize=64)
+def compile_query(language: Language, source: str) -> Query | None:
+    """Compile a query once, and share it between every editor and behavior
+
+    A query with an error warns once, and gives None so the behavior that
+    uses it does nothing, like an invalid #match? pattern matches nothing
+    """
+    try:
+        return Query(language, prepare_query_source(source))
+    except QueryError as err:
+        warnings.warn(
+            f"Invalid tree-sitter query for {language.name}: {err}", stacklevel=2
+        )
+        return None
+
+
+def query_byte_range(
+    query: Query,
+    root: Node,
+    start_byte: int,
+    end_byte: int,
+    get_text: Callable[[Node], str] | None = None,
+) -> Captures:
+    """Run a query over a byte range of a tree, returning nodes by capture name
+
+    A byte range that ends before it starts warns once and returns no
+    captures.
+
+    Args:
+        get_text: Returns a node's source text, to evaluate the query's text
+            predicates with. Without it, the text predicates match everything.
+            Errors it raises propagate
+    """
+    cursor = QueryCursor(query)
+    try:
+        cursor.set_byte_range(start_byte, end_byte)
+    except ValueError:
+        # Tree-sitter rejects a range that ends before it starts
+        warnings.warn(
+            f"Skipped a tree-sitter query over the reversed byte range "
+            f"{start_byte}..{end_byte}",
+            stacklevel=2,
+        )
+        return {}
+    if get_text is None:
+        # Tree-sitter doesn't accept predicate=None
+        return cursor.captures(root)
+    return cursor.captures(root, QueryPredicates(get_text))