feat!: rewrite API

.editorconfig

@@ -0,0 +1,17 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+indent_size = 2
+
+[*.rst]
+indent_size = 3
+
+[*.{c,h,py}]
+indent_size = 4
+max_line_length = 100

.github/workflows/ci.yml

@@ -17,51 +17,11 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build_asan:
-    runs-on: ubuntu-latest
-    if: github.event_name == 'workflow_dispatch'
-    env:
-      PYTHON_VERSION: "3.8"
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          submodules: true
-      - name: Set Python path
-        run: echo "PYTHON_PATH=$RUNNER_TOOL_CACHE/Python/ASAN" >> "$GITHUB_ENV"
-      - name: Cache Python
-        uses: actions/cache@v4
-        id: python-cache
-        with:
-          path: ${{env.PYTHON_PATH}}
-          key: python-${{env.PYTHON_VERSION}}
-      - name: Build Python+ASAN
-        if: steps.python-cache.outputs.cache-hit != 'true'
-        run: |
-          git clone --depth=1 -b $PYTHON_VERSION \
-            https://github.com/python/cpython "$RUNNER_TEMP/cpython"
-          cd "$RUNNER_TEMP/cpython"
-          ./configure \
-              --with-pydebug \
-              --with-assertions \
-              --with-address-sanitizer \
-              --with-undefined-behavior-sanitizer \
-              --disable-shared \
-              --prefix="$PYTHON_PATH"
-          make -j2 && make install
-          "$PYTHON_PATH/bin/python3" -mensurepip
-      - name: Sanitize
-        run: |-
-          "$PYTHON_PATH/bin/pip3" install -e .
-          "$PYTHON_PATH/bin/python3" -c 'import tree_sitter'
-        env:
-          CFLAGS: "-O0 -g"
-
   build:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.8", "3.9", "3.10", "3.11"]
+        python: ["3.9", "3.10", "3.11", "3.12"]
         os: [ubuntu-latest, macos-13, windows-latest]
     runs-on: ${{matrix.os}}
     steps:
@@ -74,10 +34,11 @@ jobs:
         with:
           python-version: ${{matrix.python}}
       - name: Lint
-        run: pipx run ruff check .
+        continue-on-error: true
+        run: pipx run ruff check . --output-format=github
       - name: Build
-        run: pip install -e .
+        run: pip install -v -e .[tests]
         env:
-          CFLAGS: "-O0 -g"
+          CFLAGS: -Wextra -Og -g -fno-omit-frame-pointer
       - name: Test
-        run: python -Wignore:::tree_sitter -munittest
+        run: python -munittest -v

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - tree_sitter/**
+      - docs/**
+
+concurrency:
+  group: ${{github.workflow}}-${{github.ref}}
+  cancel-in-progress: true
+
+permissions:
+  pages: write
+  id-token: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{steps.deploy.outputs.page_url}}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: true
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install
+        run: pip install -e .[docs]
+        env:
+          CFLAGS: "-O0 -g"
+      - name: Build docs
+        run: sphinx-build -M html docs docs/_build
+      - name: Upload docs artifact
+        uses: actions/deploy-pages@v3
+        with:
+          path: docs/_build/html
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@v4

.github/workflows/pypi.yml

@@ -48,7 +48,7 @@ jobs:
           CIBW_ARCHS_WINDOWS: AMD64
           CIBW_ARCHS_LINUX: x86_64 aarch64
           CIBW_ARCHS_MACOS: x86_64 arm64
-          CIBW_TEST_SKIP: cp312* *arm64 *aarch64
+          CIBW_TEST_SKIP: "*arm64 *aarch64"
       - name: Upload wheels
         uses: actions/upload-artifact@v4
         with:

.gitignore

@@ -7,3 +7,4 @@ dist
 *.so
 __pycache__
 wheelhouse
+docs/_build

.gitmodules

@@ -1,21 +1,3 @@
 [submodule "tree-sitter"]
 	path = tree_sitter/core
 	url = https://github.com/tree-sitter/tree-sitter
-[submodule "tree-sitter-embedded-template"]
-	path = tests/fixtures/tree-sitter-embedded-template
-	url = https://github.com/tree-sitter/tree-sitter-embedded-template
-[submodule "tree-sitter-html"]
-	path = tests/fixtures/tree-sitter-html
-	url = https://github.com/tree-sitter/tree-sitter-html
-[submodule "tree-sitter-javascript"]
-	path = tests/fixtures/tree-sitter-javascript
-	url = https://github.com/tree-sitter/tree-sitter-javascript
-[submodule "tree-sitter-json"]
-	path = tests/fixtures/tree-sitter-json
-	url = https://github.com/tree-sitter/tree-sitter-json
-[submodule "tree-sitter-python"]
-	path = tests/fixtures/tree-sitter-python
-	url = https://github.com/tree-sitter/tree-sitter-python
-[submodule "tree-sitter-rust"]
-	path = tests/fixtures/tree-sitter-rust
-	url = https://github.com/tree-sitter/tree-sitter-rust

README.md

@@ -2,6 +2,7 @@
 
 [![CI][ci]](https://github.com/tree-sitter/py-tree-sitter/actions/workflows/ci.yml)
 [![pypi][pypi]](https://pypi.org/project/tree-sitter/)
+[![docs][docs]](https://tree-sitter.github.io/py-tree-sitter/)
 
 This module provides Python bindings to the [tree-sitter] parsing library.
 
@@ -35,45 +36,7 @@ Then, you can load it as a `Language` object:
 import tree_sitter_python as tspython
 from tree_sitter import Language, Parser
 
-PY_LANGUAGE = Language(tspython.language(), "python")
-```
-
-#### Build from source
-
-> [!WARNING]
-> This method of loading languages is deprecated and will be removed in `v0.22.0`.
-> You should only use it if you need languages that have not updated their bindings.
-> Keep in mind that you will need a C compiler in this case.
-
-First you'll need a Tree-sitter language implementation for each language that you want to parse.
-
-```sh
-git clone https://github.com/tree-sitter/tree-sitter-go
-git clone https://github.com/tree-sitter/tree-sitter-javascript
-git clone https://github.com/tree-sitter/tree-sitter-python
-```
-
-Use the `Language.build_library` method to compile these into a library that's
-usable from Python. This function will return immediately if the library has
-already been compiled since the last time its source code was modified:
-
-```python
-from tree_sitter import Language, Parser
-
-Language.build_library(
-    # Store the library in the `build` directory
-    "build/my-languages.so",
-    # Include one or more languages
-    ["vendor/tree-sitter-go", "vendor/tree-sitter-javascript", "vendor/tree-sitter-python"],
-)
-```
-
-Load the languages into your app as `Language` objects:
-
-```python
-GO_LANGUAGE = Language("build/my-languages.so", "go")
-JS_LANGUAGE = Language("build/my-languages.so", "javascript")
-PY_LANGUAGE = Language("build/my-languages.so", "python")
+PY_LANGUAGE = Language(tspython.language())
 ```
 
 ### Basic parsing
@@ -324,5 +287,6 @@ To try out and explore the code referenced in this README, check out [examples/u
 [tree query]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
 [ci]: https://img.shields.io/github/actions/workflow/status/tree-sitter/py-tree-sitter/ci.yml?logo=github&label=CI
 [pypi]: https://img.shields.io/pypi/v/tree-sitter?logo=pypi&logoColor=ffd242&label=PyPI
+[docs]: https://img.shields.io/github/deployments/tree-sitter/py-tree-sitter/github-pages?logo=sphinx&label=Docs
 [examples/walk_tree.py]: https://github.com/tree-sitter/py-tree-sitter/blob/master/examples/walk_tree.py
 [examples/usage.py]: https://github.com/tree-sitter/py-tree-sitter/blob/master/examples/usage.py

docs/classes/tree_sitter.Language.rst

@@ -0,0 +1,53 @@
+Language
+========
+
+.. autoclass:: tree_sitter.Language
+
+   .. versionchanged:: 0.22.0
+
+      No longer accepts a ``name`` parameter.
+
+
+   Methods
+   -------
+
+   .. automethod:: field_id_for_name
+   .. automethod:: field_name_for_id
+   .. automethod:: id_for_node_kind
+   .. automethod:: lookahead_iterator
+   .. automethod:: next_state
+   .. automethod:: node_kind_for_id
+   .. automethod:: node_kind_is_named
+   .. automethod:: node_kind_is_visible
+   .. automethod:: query
+
+   Special Methods
+   ---------------
+
+   .. automethod:: __eq__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __hash__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __index__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __int__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __ne__
+
+      .. versionadded:: 0.22.0
+   .. automethod:: __repr__
+
+      .. versionadded:: 0.22.0
+
+
+   Attributes
+   ----------
+
+   .. autoattribute:: field_count
+   .. autoattribute:: node_kind_count
+   .. autoattribute:: parse_state_count
+   .. autoattribute:: version

docs/classes/tree_sitter.LookaheadIterator.rst

@@ -0,0 +1,24 @@
+LookaheadIterator
+=================
+
+.. autoclass:: tree_sitter.LookaheadIterator
+
+   Methods
+   -------
+
+   .. automethod:: iter_names
+   .. automethod:: reset
+   .. automethod:: reset_state
+
+   Special methods
+   ---------------
+
+   .. automethod:: __iter__
+   .. automethod:: __next__
+
+   Attributes
+   ----------
+
+   .. autoattribute:: current_symbol
+   .. autoattribute:: current_symbol_name
+   .. autoattribute:: language

docs/classes/tree_sitter.Node.rst

@@ -0,0 +1,65 @@
+Node
+====
+
+.. autoclass:: tree_sitter.Node
+
+   Methods
+   -------
+
+   .. automethod:: child
+   .. automethod:: child_by_field_id
+   .. automethod:: child_by_field_name
+   .. automethod:: children_by_field_id
+   .. automethod:: children_by_field_name
+   .. automethod:: descendant_for_byte_range
+   .. automethod:: descendant_for_point_range
+   .. automethod:: edit
+   .. automethod:: field_name_for_child
+   .. automethod:: named_child
+   .. automethod:: named_descendant_for_byte_range
+   .. automethod:: named_descendant_for_point_range
+   .. automethod:: sexp
+   .. automethod:: walk
+
+   Special Methods
+   ---------------
+
+   .. automethod:: __eq__
+   .. automethod:: __hash__
+   .. automethod:: __ne__
+   .. automethod:: __repr__
+   .. automethod:: __str__
+
+   Attributes
+   ----------
+
+   .. autoattribute:: byte_range
+   .. autoattribute:: child_count
+   .. autoattribute:: children
+   .. autoattribute:: descendant_count
+   .. autoattribute:: end_byte
+   .. autoattribute:: end_point
+   .. autoattribute:: grammar_id
+   .. autoattribute:: grammar_name
+   .. autoattribute:: has_changes
+   .. autoattribute:: has_error
+   .. autoattribute:: id
+   .. autoattribute:: is_error
+   .. autoattribute:: is_extra
+   .. autoattribute:: is_missing
+   .. autoattribute:: is_named
+   .. autoattribute:: kind_id
+   .. autoattribute:: named_child_count
+   .. autoattribute:: named_children
+   .. autoattribute:: next_named_sibling
+   .. autoattribute:: next_parse_state
+   .. autoattribute:: next_sibling
+   .. autoattribute:: parent
+   .. autoattribute:: parse_state
+   .. autoattribute:: prev_named_sibling
+   .. autoattribute:: prev_sibling
+   .. autoattribute:: range
+   .. autoattribute:: start_byte
+   .. autoattribute:: start_point
+   .. autoattribute:: text
+   .. autoattribute:: type