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.11.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8b5cee87ea7156526e139d32e2fe0c44305e78a2ebd7c75f5cb3357bbcdb2cf2 |
|
MD5 | ba694444d8232c0905fb8ee7435f0b1f |
|
BLAKE2b-256 | 1a617f68321d05f8b72e237f5ce57d1d8248c8d7841c36a6edd12202eac8d7e9 |
Hashes for stack_graphs_python_bindings-0.0.11-cp312-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d196454a314d39d1d1b12d4d47213ed046b46db6350861c7cd2c4674d0e1a785 |
|
MD5 | c9eb49959f1f06ef3886e4d1501888cf |
|
BLAKE2b-256 | e743c41d4076f640f8d323da878e7f1f3740d131c8b1a9fa605f6c6db2e8c94c |
Hashes for stack_graphs_python_bindings-0.0.11-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 46902b6b024a01968272a6a7099273fe00ccdab23c7a76f8b48382278ff107f8 |
|
MD5 | ab0a1e32607c2454a61e2f4f1195e406 |
|
BLAKE2b-256 | 8b7636af8be49d552535c02766e14919d32c8d5693599f723dcba9ffce6de6fd |
Hashes for stack_graphs_python_bindings-0.0.11-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 16c9fed491b01dee1aa711cbccb1ea3599674725e53f4be402b5b529d431c77c |
|
MD5 | a0d80dfeae258ec43f7821d5b7c4932d |
|
BLAKE2b-256 | 8d9b96fdc7d8b4b57b7c2f4098f711333847257b882289134c7da24134fcd89b |
Hashes for stack_graphs_python_bindings-0.0.11-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 287c2342708dd99c071fec5015ffc43fa28907701916c968ef3965c4eca9cac4 |
|
MD5 | 53f6b0c27f4f531b8514bc6178d35136 |
|
BLAKE2b-256 | 3855091468e22bfcafeb84118208e3d93cf288fc561b3d0c7e9dfdbda0a53818 |
Hashes for stack_graphs_python_bindings-0.0.11-cp312-cp312-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52bfc8836eba718287f6d7a5fb3497a6d3e5a3d34d58e4d2fc99d781e0352800 |
|
MD5 | be410fb9e77b4b08bbf159da4f767d31 |
|
BLAKE2b-256 | 15644a735a0111a595c421f1332287b99d07cbefd1e3e28d0acf80253e3683d0 |
Hashes for stack_graphs_python_bindings-0.0.11-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a5477b285ac7ee76519ef8db99468109dca24eafd1b2ff84b99164c83887174e |
|
MD5 | 14171360d7d178b8ebaec8f9156f9a38 |
|
BLAKE2b-256 | 65eba83ad1e348c45be34fab337cfba2a37c7f4515eb2dbd27d60696b1ac4b18 |
Hashes for stack_graphs_python_bindings-0.0.11-cp311-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 140a90128fb07b62995d2e88cd189472b6de7cc62e40d3351926e2589097373f |
|
MD5 | c3bc294bba2ed719881e82ef402b65e4 |
|
BLAKE2b-256 | 35bff14231267318b4ab47febc094881eb07a395a924a784c27c011586b29d5f |
Hashes for stack_graphs_python_bindings-0.0.11-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ec239d8241fc1cc0d6ecca617346fdcf0cab01fd7a292e778413facb32e3a9e5 |
|
MD5 | eaf6009bd9853d3a58ac2934d940e74a |
|
BLAKE2b-256 | 71d26769f082350c98d38977e1ba0bc705cc4d84d4e8fe750433bf100a31a7f2 |
Hashes for stack_graphs_python_bindings-0.0.11-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 81a36d2f067295fc79b8be59176b169609d79129d2abb5bf1520b9afebc53470 |
|
MD5 | d628d487555e4989394b9dc3a50c09e7 |
|
BLAKE2b-256 | 4ca90da43fa59f8de88bfcc392e8fc21ca5742446c0932cfb0a719703b6aa6bb |
Hashes for stack_graphs_python_bindings-0.0.11-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0ab816ae861077daee7807da6195764791a9bf8338ca69313486bb534174068b |
|
MD5 | 99a8050ebefce54d60f194133f5a2156 |
|
BLAKE2b-256 | bb4cfc05e2e3aec3eafac5873f84bc954773dc802d778a204f5b840c863d9be4 |
Hashes for stack_graphs_python_bindings-0.0.11-cp311-cp311-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6867a21d932a628acf3246f86ff678c73ff269a398a5915ec85880f059c8769d |
|
MD5 | d95b3fc15a1370aaf3ebb30e91f3add1 |
|
BLAKE2b-256 | c11b93e9c45be76ab7bffd364cb7052e33481b7a41ba6fa90ae6aed9ffe6a4df |
Hashes for stack_graphs_python_bindings-0.0.11-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d7a53b422d6d8e800402941278e7ebb7ab5b0498e018c40bb98bafbb72dc41fd |
|
MD5 | 8efbce74b98332e694d8ab909c5a5ffb |
|
BLAKE2b-256 | b08dd599eab660a8f66bec8ffae3002a6696361213e4814845001cb0743e216e |