No project description provided
Project description
Stack-Graphs Python bindings
Opinionated Python bindings for the tree-sitter-stack-graphs rust library.
It exposes a minimal, opinionated API to leverage the stack-graphs library for reference resolution in source code.
The rust bindings are built using PyO3 and maturin.
Note that this is a work in progress, and the API is subject to change. This project is not affiliated with GitHub.
Installation & Usage
pip install stack-graphs-python-bindings
Example
Given the following directory structure:
tests/js_sample
├── index.js
└── module.js
index.js
:
import { foo } from "./module"
const baz = foo
module.js
:
export const foo = "bar"
The following Python script:
import os
from stack_graphs_python import Indexer, Querier, Position, Language
db_path = os.path.abspath("./db.sqlite")
dir = os.path.abspath("./tests/js_sample")
# Index the directory (creates stack-graphs database)
indexer = Indexer(db_path, [Language.JavaScript])
indexer.index_all([dir])
# Instantiate a querier
querier = Querier(db_path)
# Query a reference at a given position (0-indexed line and column):
# foo in: const baz = foo
source_reference = Position(path=dir + "/index.js", line=2, column=12)
results = querier.definitions(source_reference)
for r in results:
print(r)
Will output:
Position(path="[...]/tests/js_sample/index.js", line=0, column=9)
Position(path="[...]/tests/js_sample/module.js", line=0, column=13)
That translates to:
// index.js
import { foo } from "./module"
// ^ line 0, column 9
// module.js
export const foo = "bar"
// ^ line 0, column 13
Note: All the paths are absolute, and line and column numbers are 0-indexed (first line is 0, first column is 0).
Known stack-graphs / tree-sitter issues
- Python: module resolution / imports seems to be broken: https://github.com/github/stack-graphs/issues/430
- Typescript: module resolution doesn't work with file extensions (eg.
import { foo } from "./module"
is ok, butimport { foo } from "./module.ts"
is not). An issue should be opened on the stack-graphs repo. See:tests/ts_ok_test.py
- Typescript: tree-sitter-typescript fails when passing a generic type to a decorator: https://github.com/tree-sitter/tree-sitter-typescript/issues/283
Development
Ressources
https://pyo3.rs/v0.21.2/getting-started
Requirements
- Rust
- Python 3.11+
Setup
# Setup venv and install dev dependencies
make setup
Testing
make test
Manual testing
# build the package
make develop
# activate the venv
. venv/bin/activate
Roadmap
Before releasing 0.1.0, which I expect to be a first stable API, the following needs to be done:
- Add more testing, especially:
- Test all supported languages (Java,
Python,TypeScript,JavaScript) - Test failing cases, eg. files that cannot be indexed
- Test all supported languages (Java,
- Add options to the classes:
- Verbosity
- Force for the Indexer
- Fail on error for the Indexer, or continue indexing
- Handle the storage (database) in a dedicated class, and pass it to the Indexer and Querier
- Add methods to query the indexing status (eg. which files have been indexed, which failed, etc.)
- Rely on the main branch of stack-graphs, and update the bindings accordingly
- Better error handling, return clear errors, test them and add them to the
.pyi
interface - Lint and format the rust code
- CI/CD for the rust code
- Lint and format the python code
- Propper changelog, starting in 0.1.0
I'd also like to add the following features, after 0.1.0:
- Expose the exact, lower-level API of stack-graphs, for more flexibility, in a separate module (eg.
stack_graphs_python.core
) - Benchmark performance
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for stack_graphs_python_bindings-0.0.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 005c93fa552cae4872c98dbde59aa0726204599a1b0466b7c6537bf16a4d1e1d |
|
MD5 | 7214e2138b891a4ac17844ccd3b42a1c |
|
BLAKE2b-256 | 0f849303067a2aa6adfff386fd9bba9f9465d41e4bb80b769b3810af19d40472 |
Hashes for stack_graphs_python_bindings-0.0.10-cp312-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a082860301e0bdcc90dac2fd94958fe758f48dd693ce4a1e80433be964b046e5 |
|
MD5 | a4bdf076f45e8ca0048bb1238ccf991c |
|
BLAKE2b-256 | a24130ae0db8255641aee0998135b41c0d74623cfd6995a84d188ec32fecf3d0 |
Hashes for stack_graphs_python_bindings-0.0.10-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2a84268b250837abc36391418d8da3c7b6eed5a15298eb1a7e595c134aadc7c0 |
|
MD5 | be8a22e7e9260f2f47f8f53c4408a547 |
|
BLAKE2b-256 | ae07ad348b6d93d2109f4b772391370dfc606f7ee868af26cba0e0eb6fbd0a82 |
Hashes for stack_graphs_python_bindings-0.0.10-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9047ca8096d3f628e90bbe073f31e654567089ae49d870763150e223d388eed9 |
|
MD5 | 69895795cd1a0a07c0ca3d587298868a |
|
BLAKE2b-256 | f5a36110e4e373a75fb4449ee07f536769db4f8c3ffbaf12c1ad9484ed72233c |
Hashes for stack_graphs_python_bindings-0.0.10-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4aa8bec9885c815421d9b369ac9b3acd6f2e81e64f2363e4d29f7ab8acdda799 |
|
MD5 | a73061c8b1b43bc1dc692fa258728b11 |
|
BLAKE2b-256 | c5cc27814b1daef905119d9542845f3f1f8ba6e5ec46250cb1ca78728d72d2f3 |
Hashes for stack_graphs_python_bindings-0.0.10-cp312-cp312-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c2619b841874fade0f5027f954e823f2b8f284f2bcf6e443a578fb910db18737 |
|
MD5 | 6bebf8fc24ad8123fcc7c8b90c943c01 |
|
BLAKE2b-256 | 39e9cd4a5f2f587d2bb2962761fc2bf78367de0cf539b61c7f496b83ad2afcf4 |
Hashes for stack_graphs_python_bindings-0.0.10-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1d1391ec544a670351b013ed587d6822609e1244e1c99873277b1b2790ec874a |
|
MD5 | 6c5312c2a10ff3394630c79153e8ca82 |
|
BLAKE2b-256 | cfabae8bb07c57617a00443eb7128004488cb8f8c86224ea0ef060e714858284 |
Hashes for stack_graphs_python_bindings-0.0.10-cp311-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f67b32677a56c90552de6800c92af9c1c5364bd606ee8f53386fc90bded5032d |
|
MD5 | 327a49a8335805d8fd896658bc0183f0 |
|
BLAKE2b-256 | dcbf5b31b7e27443e61560485e1569ae279c9a829abdf242e95fd468abbfa6a8 |
Hashes for stack_graphs_python_bindings-0.0.10-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0ae8232daed5599e4de97e3261a0e55a56c2b36791428e42cbe6b9c9d9a5ea33 |
|
MD5 | c86569d3ce25beb746c85e03fc136e07 |
|
BLAKE2b-256 | b39e3246bcdbb12278e86ee60cff83a42dd6869c71af68913cc3822836fed658 |
Hashes for stack_graphs_python_bindings-0.0.10-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5bda016a7d805c4c12113b4fd7480beaac27335f24e13d34f9bc1a5a35edcd12 |
|
MD5 | 896160fb1ea5c23a86279424fc4bd56f |
|
BLAKE2b-256 | be1b121ae71c0c55929cba8d3eafaaedbb6f2161b354773b22a457c2b2e8c283 |
Hashes for stack_graphs_python_bindings-0.0.10-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a71b7b996692c1961143e828aa4494004e81ffdcdb81a793d80582579a5bd6c0 |
|
MD5 | b2cdad34ba34b7fad4276a58627ec18f |
|
BLAKE2b-256 | dec45bc225e82a2403f590db505b3bd6f386c3ae4010b94fb16237ac55742672 |
Hashes for stack_graphs_python_bindings-0.0.10-cp311-cp311-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 815e695413dc94291a34b992704a12539b55c7b595aa8e326bf34aba006885d8 |
|
MD5 | 7ab741514451153855a8cbef5b305671 |
|
BLAKE2b-256 | 4361029721f5ca829eaadc453371acba752a5ac45ea2166467191a385f5078b7 |
Hashes for stack_graphs_python_bindings-0.0.10-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 64e26744edc0ad0a7ef3ac8bb8d51419d42309e48dd71491d1f6683da7cd13a4 |
|
MD5 | 50728deeced4aef142f8d9bb58c7e474 |
|
BLAKE2b-256 | 68c1e89c5f1877de68975c19edfb91d2ee84a0ef8d05d960b744bfc9253064de |