Skip to content
Python library for accessing Chromium CodeSearch via https://cs.chromium.org
Python Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
codesearch
doc
.gitignore
.style.yapf
.travis.yml
CONTRIBUTING.md
LICENSE
README.md
__init__.py
ccs
format_code.sh
refresh_cached_responses.sh
run_tests.sh
setup.cfg
setup.py

README.md

Chromium CodeSearch Library

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.

Support

Feel free to submit issues on GitHub and/or contact the authors. This project is not officially supported by Google or the Chromium project.

Contributing

See CONTRIBUTING for details on contributing.

Build Status

You can’t perform that action at this time.