Searching

ChemSpiPy provides a number of different ways to search ChemSpider.

Asynchronous searching

Certain types of search can sometimes take slightly longer, which can be inconvenient if the search method blocks the Python interpreter until the search results are returned. Fortunately, the ChemSpiPy search method works asynchronously.

Once a search is executed, ChemSpiPy immediately returns the Results object, which is actually empty at first:

>>> results = cs.search('O=C(OCC)C')
>>> print(results.ready())
False

In a background thread, ChemSpiPy is making the search request and waiting for the response. But in the meantime, it is possible to continue performing other tasks in the main Python interpreter process. Call ready() at any point to check if the results have been returned and are available.

Any attempt to access the results will just block until the results are ready, like a simple synchronous search. To manually block the main thread until the results are ready, use the wait() method:

>>> results.wait()
>>> results.ready()
True

For more detailed information about the status of a search, use the status property:

>>> results.status
u'Created'
>>> results.wait()
>>> results.status
u'ResultReady'

The possible statuses are Unknown, Created, Scheduled, Processing, Suspended, PartialResultReady, ResultReady.

Search by formula

Searching by molecular formula is supported by the main search method, but there is the possibility that a formula could be interpreted as a name or SMILES or another query type. To specifically search by formula, use:

>>> cs.search_by_formula('C44H30N4Zn')
[Compound(436642), Compound(3232330), Compound(24746832), Compound(26995124)]

Search by mass

It is also possible to search ChemSpider by mass by specifying a certain range:

>>> cs.search_by_mass(680, 0.001)
[Compound(8298180), Compound(12931939), Compound(12931969), Compound(21182158)]

The first parameter specifies the desired molecular mass, while the second parameter specifies the allowed ± range of values.