Merge pull request #26 from juanjux/bug/pypi_fix

Pypi fix, versioned SDK, improved README

MANIFEST.in

@@ -0,0 +1,6 @@
+include *.md
+include *.txt
+include DCO
+include LICENSE
+include MAINTAINERS
+include Makefile

Makefile

@@ -3,26 +3,31 @@ PYTHON ?= python3
 makefile_dir := $(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
 
 LIBUAST_VERSION = v0.2.0
+SDK_VERSION = v0
 
 .PHONY : all clean deps
 
 all: deps \
 	bblfsh/github/com/gogo/protobuf/gogoproto/gogo_pb2.py \
-	bblfsh/github/com/bblfsh/sdk/uast/generated_pb2.py \
-	bblfsh/github/com/bblfsh/sdk/protocol/generated_pb2_*.py \
+	bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/uast/generated_pb2.py \
+	bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol/generated_pb2_*.py \
 	bblfsh/github/__init__.py \
 	bblfsh/github/com/__init__.py \
 	bblfsh/github/com/gogo/__init__.py \
 	bblfsh/github/com/gogo/protobuf/__init__.py \
 	bblfsh/github/com/gogo/protobuf/gogoproto/__init__.py \
-	bblfsh/github/com/bblfsh/__init__.py \
-	bblfsh/github/com/bblfsh/sdk/__init__.py \
-	bblfsh/github/com/bblfsh/sdk/uast/__init__.py \
-	bblfsh/github/com/bblfsh/sdk/protocol/__init__.py
+	bblfsh/gopkg/__init__.py \
+	bblfsh/gopkg/in/__init__.py \
+	bblfsh/gopkg/in/bblfsh/__init__.py \
+	bblfsh/gopkg/in/bblfsh/sdk/__init__.py \
+	bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/__init__.py \
+	bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/uast/__init__.py \
+	bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol/__init__.py
 
 clean:
 	rm -rf bblfsh/libuast
 	rm -rf bblfsh/github
+	rm -rf bblfsh/gopkg
 
 deps: bblfsh/libuast
 
@@ -35,18 +40,24 @@ bblfsh/libuast:
 bblfsh/github/com/gogo/protobuf/gogoproto/gogo_pb2.py: github.com/gogo/protobuf/gogoproto/gogo.proto
 	protoc --python_out bblfsh github.com/gogo/protobuf/gogoproto/gogo.proto
 
-bblfsh/github/com/bblfsh/sdk/uast/generated_pb2.py: github.com/bblfsh/sdk/uast/generated.proto
-	protoc --python_out bblfsh github.com/bblfsh/sdk/uast/generated.proto
+bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/uast/generated_pb2.py: gopkg.in/bblfsh/sdk.$(SDK_VERSION)/uast/generated.proto
+	protoc --python_out bblfsh gopkg.in/bblfsh/sdk.$(SDK_VERSION)/uast/generated.proto
 
-bblfsh/github/com/bblfsh/sdk/protocol:
+bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol:
 	@mkdir -p $@
 
-bblfsh/github/com/bblfsh/sdk/protocol/generated_pb2_*.py: \
-	bblfsh/github/com/bblfsh/sdk/protocol github.com/bblfsh/sdk/protocol/generated.proto
-	$(PYTHON) -m grpc.tools.protoc --python_out=bblfsh/github/com/bblfsh/sdk/protocol \
-	    --grpc_python_out=bblfsh/github/com/bblfsh/sdk/protocol \
-	    -I github.com/bblfsh/sdk/protocol -I $(makefile_dir) \
-	    github.com/bblfsh/sdk/protocol/generated.proto
+bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/uast:
+	@mkdir -p $@
+
+bblfsh/github/com/gogo/protobuf/gogoproto:
+	@mkdir -p $@
+
+bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol/generated_pb2_*.py: \
+	bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol gopkg.in/bblfsh/sdk.$(SDK_VERSION)/protocol/generated.proto
+	$(PYTHON) -m grpc.tools.protoc --python_out=bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol \
+	    --grpc_python_out=bblfsh/gopkg/in/bblfsh/sdk/$(SDK_VERSION)/protocol \
+	    -I gopkg.in/bblfsh/sdk.$(SDK_VERSION)/protocol -I $(makefile_dir) \
+	    gopkg.in/bblfsh/sdk.$(SDK_VERSION)/protocol/generated.proto
 
 %/__init__.py:
 	@touch $@

README.md

@@ -5,20 +5,41 @@ This a pure Python implementation of querying [Babelfish](https://doc.bblf.sh/)
 ### Usage
 
 API
-```
-from bblfsh import BblfshClient
+```python
+from bblfsh import BblfshClient, filter
 
 client = BblfshClient("0.0.0.0:9432")
 print(client.parse("/path/to/file.py"))
+# "filter' allows you to use XPath queries to filter on result nodes:
+print(client.filter("//Import[@roleImportDeclaration]//alias")
 ```
 
+*TODO*: Link to `libuast` XPath documentation when available.
+
 Command line
-```
+```bash
 python3 -m bblfsh -f file.py
 ```
 
+This will usually download and run a server Docker image automatically, but it'll
+also use an existing image if it's previously running. You could run a bblfsh
+server image with:
+
+```bash
+docker run --privileged -d -p 9432:9432 --name bblfsh bblfsh/server
+```
+
 ### Installation
 
+#### Dependencies
+
+You need to install `libxml2` and its header files. The command for 
+Debian and derived distributions would be:
+
+```bash
+sudo apt install libxml2-dev
+```
+
 #### From the source code
 
 ```bash

bblfsh/client.py

@@ -1,13 +1,17 @@
 import os
 import sys
+import importlib
 
 import grpc
 
+from bblfsh.sdkversion import VERSION
+
 # The following two insertions fix the broken pb import paths
 sys.path.insert(0, os.path.join(os.path.dirname(__file__),
-                                "github/com/bblfsh/sdk/protocol"))
+                                "gopkg/in/bblfsh/sdk/%s/protocol" % VERSION))
 sys.path.insert(0, os.path.dirname(__file__))
 
+
 class BblfshClient(object):
     """
     Babelfish gRPC client. Currently it is only capable of fetching UASTs.
@@ -21,7 +25,9 @@ def __init__(self, endpoint):
                          for example "0.0.0.0:9432"
         :type endpoint: str
         """
-        from bblfsh.github.com.bblfsh.sdk.protocol.generated_pb2_grpc import ProtocolServiceStub
+        ProtocolServiceStub = importlib.import_module(
+                "bblfsh.gopkg.in.bblfsh.sdk.%s.protocol.generated_pb2_grpc" % VERSION
+                ).ProtocolServiceStub
 
         self._channel = grpc.insecure_channel(endpoint)
         self._stub = ProtocolServiceStub(self._channel)
@@ -48,7 +54,9 @@ def parse(self, filename, language=None, contents=None, timeout=None,
         :type timeout: float
         :return: UAST object.
         """
-        from bblfsh.github.com.bblfsh.sdk.protocol.generated_pb2 import ParseRequest
+        ParseRequest = importlib.import_module(
+                "bblfsh.gopkg.in.bblfsh.sdk.%s.protocol.generated_pb2" % VERSION
+                ).ParseRequest
 
         if contents is None:
             with open(filename, errors=unicode_errors) as fin:
@@ -58,7 +66,6 @@ def parse(self, filename, language=None, contents=None, timeout=None,
                                language=self._scramble_language(language))
         return self._stub.Parse(request, timeout=timeout)
 
-
     @staticmethod
     def _scramble_language(lang):
         if lang is None: