The codesearch
Python library provides an interface for talking to the
Chromium CodeSearch backend at https://cs.chromium.org/
The primary entry point into the library is the CodeSearch
class. Various
message classes you are likely to encounter are defined in messages.py
.
A quick example:
'''
Step 1 is to import codesearch.
>>> import codesearch
The following examples are written out as Python doctests and are run as a part
of the run_tests.sh suite. The InstallTestRequestHandler() sets up a test rig
that is used during testing to ensure that tests are reproducible and can be run
without a network connection. Feel free to use InstallTestRequestHandler() in
your own code if you need to test against the CodeSearch library. See
documentation for details.
>>> codesearch.InstallTestRequestHandler()
The plugin can optionally work with a local Chromium checkout (see the
documentation for CodeSearch.__init__()), but for this example, we are going use
the API without a local checkout. This is indicated by setting the |source_root|
to '.'.
>>> cs = codesearch.CodeSearch(source_root='.')
Let's look up a class:
The SearchForSymbol function searches for a symbol of a specific type. In this
case we are looking for a class named File. There may be more than one such
class, so the function returns an array. We only need the first one.
>>> file_class = cs.SearchForSymbol('FieldTrial$', codesearch.NodeEnumKind.CLASS)[0]
SearchForSymbol returns an XrefNode object. This is a starting point for cross
reference lookups.
>>> isinstance(file_class, codesearch.XrefNode)
True
We can look for references to this class.
>>> references = file_class.Traverse(codesearch.KytheXrefKind.REFERENCE)
There will be a number of these.
>>> len(references) > 30
True
In addition to the above, there are lower level APIs to talk to the unofficial
endpoints in the https://cs.chromium.org backend. One such API is
SendRequestToServer.
SendRequestToServer takes a CompoundRequest object ...
>>> response = cs.SendRequestToServer(codesearch.CompoundRequest(
... search_request=[
... codesearch.SearchRequest(query='hello world',
... return_line_matches=True,
... lines_context=0,
... max_num_results=10)
... ]))
.. and returns a CompoundResponse
>>> isinstance(response, codesearch.CompoundResponse)
True
Both CompoundRequest and CompoundResponse are explained in
codesearch/messages.py. Since our request was a |search_request| which is a list
of SearchRequest objects, our CompoundResponse object is going to have a
|search_response| field ...
>>> hasattr(response, 'search_response')
True
.. containing a list of SearchResponse objects ...
>>> isinstance(response.search_response, list)
True
.. which contains exactly one element ...
>>> len(response.search_response)
1
.. whose type is SearchResponse.
>>> isinstance(response.search_response[0], codesearch.SearchResponse)
True
It should indicate an estimate of how many results exist. This could diverge
from the number of results included in this response message. If that's the
case, then |hit_max_results| would be true.
>>> response.search_response[0].hit_max_results
True
We can now examine the SearchResult objects to see what the server sent us. The
fields are explained in message.py.
>>> lines_left = 10
>>> for search_result in response.search_response[0].search_result:
... assert isinstance(search_result, codesearch.SearchResult)
...
... for match in search_result.match:
... print("{}:{}: {}".format(search_result.top_file.file.name,
... match.line_number,
... match.line_text.strip()))
... lines_left -= 1
... if lines_left == 0: break
... if lines_left == 0: break
src/v8/samples/hello-world.cc:40: v8::String::NewFromUtf8(isolate, "'Hello' + ', World!'",
src/v8/samples/hello-world.cc:34: // Enter the context for compiling and running the hello world script.
src/gin/shell/hello_world.js:5: log("Hello World");
src/v8/test/fuzzer/parser/hello-world:1: console.log('hello world');
src/native_client/tests/hello_world/hello_world.c:13: void hello_world(void) {
src/native_client/tests/hello_world/hello_world.c:14: printf("Hello, World!\n");
src/native_client/tests/hello_world/hello_world.c:18: hello_world();
src/tools/gn/tutorial/hello_world.cc:8: printf("Hello, world.\n");
infra/go/src/go.chromium.org/luci/grpc/prpc/e2etest/helloworld_test.proto:19: service Hello {
infra/go/src/go.chromium.org/luci/grpc/prpc/e2etest/helloworld_test.proto:15: message HelloReply {
Note that in the example above:
* search_result.match was available because |return_line_matches| was set to
True when making the server request. Otherwise the server response will not
contain line matches.
* The line matches will have multiple lines of context. This was suppressed in
the example by setting |lines_context| to 0.
'''
In addition, the library also includes facilities for maintaining an ephemeral or persistent cache in order to minimize generated network traffic.
Note: The library uses an unsupported interface to talk to the backend. If you are using the library and it suddenly stops working, file an issue and/or monitor the project on GitHub for updates.
Note: This is not an official Google product.
Feel free to submit issues on GitHub and/or contact the authors. This project is not officially supported by Google or the Chromium project.
See CONTRIBUTING for details on contributing.