No project description provided
Project description
Stack-Graphs Python bindings
Opinionated Python bindings for the tree-sitter-stack-graphs rust library.
(Note: the project curretly relies on fork)
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). PR opened, fixed on the fork. 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 -> this might not be necessary
- 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.12.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1acaf7855ae92b72ef324719bdfc22dc1f7155f077eb26215fccbf6da4507db3 |
|
MD5 | e43472623ace48052d246dfd592fc235 |
|
BLAKE2b-256 | 8c030f1cdd8424da1d1f782a05fe66be36d9b31b91e50f504f93384655cd83e3 |
Hashes for stack_graphs_python_bindings-0.0.12-cp312-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f6600974d072e3eb87f09efc893fb5a0d6c003d894eded892a4e47c9e1871120 |
|
MD5 | ad3e32a7b9f0071bec942bd27ee05397 |
|
BLAKE2b-256 | 48ef7a90d90495b1a43b346d359f795fb995fefbca986b45ab544c99d1c02e9d |
Hashes for stack_graphs_python_bindings-0.0.12-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5acd782e619969247013ad1de40308d7fbca5edf7687e6386fddfcc3e6a0976f |
|
MD5 | 097be0896e9444f7526ba47884311047 |
|
BLAKE2b-256 | d8b9e617468f005206619895e1d178e16619c9e01ef2ff59044b37625487d765 |
Hashes for stack_graphs_python_bindings-0.0.12-cp312-cp312-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e6263c948e0a130b4fbe1e3b5147a52a9d80bf1d4991c6accdfc02d44ad5b74e |
|
MD5 | 94d313a5681ee8ca3374c3f9951bc2b4 |
|
BLAKE2b-256 | 9c4257fda7f913ece71e2ebafd884ffd2fe55cf68a744d1758da49fc14fe65b3 |
Hashes for stack_graphs_python_bindings-0.0.12-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 74ad40ee4bb334063e273d7574d74387cd165bc1a70f818e50eb2fdb4b464d8c |
|
MD5 | a279fc54c965fb9f8364dca6b944d4c4 |
|
BLAKE2b-256 | dee05bcb293d7a8eb5c54a2b92b141b32a85360388aa9c058a89feae518f5bc2 |
Hashes for stack_graphs_python_bindings-0.0.12-cp312-cp312-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4ecf8b5b3d9d800b551bc3c21a4b483b8efd5b614a5410a2ac74c938d11c2957 |
|
MD5 | dc9b95625b1b0ea263b46966f48d72ce |
|
BLAKE2b-256 | f9d3f76876f36eacc51ce98a7984ace0c06c450a98c7aa4003244ed4c7e78953 |
Hashes for stack_graphs_python_bindings-0.0.12-cp312-cp312-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4be96dcafcb73b11b443f1bcccfbcdae5f43f5742e377a5fe8c53ed099ebe151 |
|
MD5 | 4c9a8815f0a71a1f810ea9a260e85189 |
|
BLAKE2b-256 | 816f14abed349275500971266c1039e5519094a4aff5658eb34299ee65a8bef0 |
Hashes for stack_graphs_python_bindings-0.0.12-cp311-none-win32.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 404413d7d34ef5b446f66ad1c6c14c56b01f2914e414b5433a49fac4d5658974 |
|
MD5 | 312248369a2b7846d942d1a6898caba3 |
|
BLAKE2b-256 | a4fc96f303c081f79ae7ae1eeca1068d96820e3a2856fa24c0bcd8a638bc28a3 |
Hashes for stack_graphs_python_bindings-0.0.12-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c181ff39d7027eca35975db37f60ce65a3f4e535749491261940094e94197256 |
|
MD5 | a28c075924a24f288f5cbdca2192a694 |
|
BLAKE2b-256 | ef7c4a6a019b9d4dd36d62a16f46dc3ce5884b5d6b51a6840ae44b73e709b40c |
Hashes for stack_graphs_python_bindings-0.0.12-cp311-cp311-manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c7b98bcc4d8f4e71d1e82a25ab28fc97c46a7c8a6c030853d872fe73d49feb46 |
|
MD5 | 418d2b6ae42c8d4bd2c29be097781e43 |
|
BLAKE2b-256 | 421cc6a6711ee4d7bf1fdd73324de6f613d552dcb623271e8e2b2bd1a0f9c5ce |
Hashes for stack_graphs_python_bindings-0.0.12-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5a758b20a3276c8983425c1e105e50e647cf2b044a91e5b852554089efc25e3a |
|
MD5 | c1249fa05fcfebfe38c60fb7fa77cc02 |
|
BLAKE2b-256 | 8d15b104d16bdcfbe4aa717ade2fd6cec83a9e8b1d529a5cd28e0aa97ff42525 |
Hashes for stack_graphs_python_bindings-0.0.12-cp311-cp311-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ff36339112a8e6ca40e3f1a9dad7ba6d3bf58959ca68ef09ee6593a7e392f7ce |
|
MD5 | 7fff17a4157fed8492806d4eae34f7ad |
|
BLAKE2b-256 | 2ae191cfeea7f146a4199583c18bc4eb195ed26723f76f814d0974e489fd72a6 |
Hashes for stack_graphs_python_bindings-0.0.12-cp311-cp311-macosx_10_12_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4de08f9cc9c6b414b42c8ad0397921bac3598faa847058e9626a41f1f248b1b6 |
|
MD5 | f60480407404a68678c2afe827921239 |
|
BLAKE2b-256 | 34a8b6668135cf5a7e1dcb6131db0aa0917e33d28c9610fa848c0ee504f38221 |