python-library.texi

SEL exports a Python library which exposes functionality for parsing,
traversing, and inspecting source code from multiple languages.
Specifically, this library exposes SEL's tree-sitter based asts (see
@ref{Source Code with @code{tree-sitter}}) and the generic functions
defined upon those ASTs.  The ultimate Python library then has two
large sources of functionality, (i) the tree-sitter libraries which
provide the ability to parse a large number of programming languages
into ASTs and (ii) the SEL machinery leveraging Common Lisp's object
system (CLOS) and generic functions to build a large multi-language
API for software analysis and transformation over these ASTs.

This library is available on PyPi with pre-packaged tree-sitter
libraries for use on any Linux system (see
@url{https://pypi.org/project/asts/}).  The remainder of this section
walks through building the library locally, running, and
troubleshooting local builds of this Python Library.

@menu
* Building the SEL Python Library::
* Running the SEL Python Library::
* Troubleshooting the SEL Python Library::
@end menu

@node Building the SEL Python Library, Running the SEL Python Library, Python Library, Python Library
@section Building the SEL Python Library
@cindex building the sel python library

There are two pieces to the SEL Python Library; the LISP interface thru which
the python library interacts with SEL and the python library itself.

To begin, we will start with the LISP interface and tree-sitter python class
generator.  From the base of the SEL repository, the following is sufficient
to build the interface and tree-sitter python class generator and place
both on your @code{$PATH}:

@example
make bin/tree-sitter-interface bin/tree-sitter-py-generator
export PATH=$(pwd)/bin:$PATH
@end example

Now that we have built the LISP interface and tree-sitter python class
generator, we need to add the python library to our
@code{$PYTHONPATH}.  From the base of the SEL repository, the following
is sufficient to accomplish this:

@example
export PYTHONPATH=$(pwd)/python:$PYTHONPATH
@end example

@node Running the SEL Python Library, Troubleshooting the SEL Python Library, Building the SEL Python Library, Python Library
@section Running the SEL Python Library
@cindex running the sel python library

To test that you have successfully installed the python library, you
may run the following code snippet:

@example
$ python3
Python 3.8.5
Type "help", "copyright", "credits" or "license" for more information.
>>> import asts
>>> it = asts.AST.from_string("x + 88", language=asts.ASTLanguage.Python)
>>> it.children
[<asts.types.PythonExpressionStatement0 0x2>]
@end example

If no errors are thrown, the library is successfully installed.  For more
examples, consult the documentation at @url{https://pypi.org/project/asts/},
or to view the implementation code, see @code{python/asts/asts.py}.

@node Troubleshooting the SEL Python Library, , Running the SEL Python Library, Python Library
@section Troubleshooting the SEL Python Library
@cindex troubleshooting the sel python library

@enumerate
@item
If you see the error @code{"tree-sitter-interface binary must be on your $PATH."},
then the @code{tree-sitter-interface} binary has not been built and placed on your
@code{$PATH} environment variable as described in @ref{Building the SEL Python Library}.

@item
If you see the error @code{"tree-sitter-py-generator binary must be on your $PATH."},
then the @code{tree-sitter-py-generator} binary has not been built and placed on your
@code{$PATH} environment variable as described in @ref{Building the SEL Python Library}.

@end enumerate