API documentation¶

This part of the documentation is automatically generated from the ChemSpiPy source code and comments.

chemspipy.api¶

Core API for interacting with ChemSpider web services.

class chemspipy.ChemSpider[source]¶

Provides access to the ChemSpider API.

See BaseChemSpider further information.

Parameters:	security_token (string) – (Optional) Your ChemSpider security token. user_agent (string) – (Optional) Identify your application to ChemSpider servers.

async_simple_search(query)¶

Search ChemSpider with arbitrary query, returning results in order of the best match found.

This method returns a transaction ID which can be used with other methods to get search status and results.

Security token is required.

Parameters:	query (string) – Search query - a name, SMILES, InChI, InChIKey, CSID, etc.
Returns:	Transaction ID.
Return type:	string

async_simple_search_ordered(query, order=u'csid', direction=u'ascending')¶

Search ChemSpider with arbitrary query, returning results with a custom order.

This method returns a transaction ID which can be used with other methods to get search status and results.

Security token is required.

Parameters:	query (string) – Search query - a name, SMILES, InChI, InChIKey, CSID, etc. order (string) – ‘csid’, ‘mass_defect’, ‘molecular_weight’, ‘reference_count’, ‘datasource_count’, ‘pubmed_count’ or ‘rsc_count’. direction (string) – ‘ascending’ or ‘descending’.
Returns:	Transaction ID.
Return type:	string

construct_api_url(api, endpoint, **params)¶

Construct a Chemspider API url, encoded, with parameters as a GET querystring.

Parameters:	api (string) – The specific ChemSpider API to call (MassSpec, Search, Spectra, InChI). endpoint (string) – ChemSpider API endpoint. params – (optional) Parameters for the ChemSpider endpoint as keyword arguments.
Return type:	string

get_async_search_result(rid)¶

Get the results from a asynchronous search operation. Security token is required.

Parameters:	rid (string) – A transaction ID, returned by an asynchronous search method.
Returns:	A list of Compounds.
Return type:	list[Compound]

get_async_search_result_part(rid, start=0, count=-1)¶

Get a slice of the results from a asynchronous search operation. Security token is required.

Parameters:	rid (string) – A transaction ID, returned by an asynchronous search method. start (int) – The number of results to skip. count (int) – The number of results to return. -1 returns all through to end.
Returns:	A list of Compounds.
Return type:	list[Compound]

get_async_search_status(rid)¶

Check the status of an asynchronous search operation.

Security token is required.

Parameters:	rid (string) – A transaction ID, returned by an asynchronous search method.
Returns:	Unknown, Created, Scheduled, Processing, Suspended, PartialResultReady, ResultReady, Failed, TooManyRecords
Return type:	string

get_async_search_status_and_count(rid)¶

Check the status of an asynchronous search operation. If ready, a count and message are also returned.

Security token is required.

Parameters:	rid (string) – A transaction ID, returned by an asynchronous search method.
Return type:	dict

get_compound(csid)¶

Return a Compound object for a given ChemSpider ID. Security token is required.

Parameters:	csid (string\|int) – ChemSpider ID.
Returns:	The Compound with the specified ChemSpider ID.
Return type:	Compound

get_compound_info(csid)¶

Get SMILES, StdInChI and StdInChIKey for a given CSID. Security token is required.

Parameters:	csid (string\|int) – ChemSpider ID.
Return type:	dict

get_compound_thumbnail(csid)¶

Get PNG image as binary data.

Parameters:	csid (string\|int) – ChemSpider ID.
Return type:	bytes

get_compounds(csids)¶

Return a list of Compound objects, given a list ChemSpider IDs. Security token is required.

Parameters:	csids (list[string\|int]) – List of ChemSpider IDs.
Returns:	List of Compounds with the specified ChemSpider IDs.
Return type:	list[Compound]

get_databases()¶: Get the list of datasources in ChemSpider.

get_extended_compound_info(csid)¶

Get extended record details for a CSID. Security token is required.

Parameters:	csid (string\|int) – ChemSpider ID.

get_extended_compound_info_list(csids)¶

Get extended record details for a list of CSIDs. Security token is required.

Parameters:	csids (list[string\|int]) – ChemSpider IDs.

get_extended_mol_compound_info_list(csids, mol_type=u'e2D', include_reference_counts=False, include_external_references=False)¶

Get extended record details (including MOL) for a list of CSIDs.

A maximum of 250 CSIDs can be fetched per request. Security token is required.

Parameters:	csids (list[string\|int]) – ChemSpider IDs. mol_type (string) – 2d, 3d or both. include_reference_counts (bool) – Whether to include reference counts. include_external_references (bool) – Whether to include external references.

get_original_mol(csid)¶

Get original submitted MOL file. Security token is required.

Parameters:	csid (string\|int) – ChemSpider ID.

get_record_mol(csid, calc3d=False)¶

Get ChemSpider record in MOL format. Security token is required.

Parameters:	csid (string\|int) – ChemSpider ID. calc3d (bool) – Whether 3D coordinates should be calculated before returning record data.

get_spectra_info_list(csids)¶

Get information about all the spectra for a list of CSIDs.

Parameters:	csids (list[string\|int]) – ChemSpider IDs.
Returns:	List of spectrum info.
Return type:	list[dict]

request(api, endpoint, **params)¶

Construct API request and return the XML response.

Parameters:	api (string) – The specific ChemSpider API to call (MassSpec, Search, Spectra, InChI). endpoint (string) – ChemSpider API endpoint. params – (optional) Parameters for the ChemSpider endpoint as keyword arguments.
Return type:	xml tree

search(query)¶: Search ChemSpider for the specified query and return the results. Security token is required.

search_by_formula(formula)¶

Search ChemSpider by molecular formula.

Parameters:	formula (string) – Molecular formula
Returns:	A list of Compounds.
Return type:	list[Compound]

search_by_mass(mass, mass_range)¶

Search ChemSpider by mass +/- range.

Parameters:	mass (float) – The mass to search for. mass_range (float) – The +/- mass range to allow.
Returns:	A list of Compounds.
Return type:	list[Compound]

simple_search(query)¶

Search ChemSpider with arbitrary query.

A maximum of 100 results are returned. Security token is required.

Parameters:	query (string) – Search query - a name, SMILES, InChI, InChIKey, CSID, etc.
Returns:	List of Compounds.
Return type:	list[Compound]

chemspipy.objects¶

class chemspipy.Compound[source]¶

A class for retrieving and caching details about a specific ChemSpider record.

The purpose of this class is to provide access to various parts of the ChemSpider API that return information about a compound given its ChemSpider ID. Information is loaded lazily when requested, and cached for future access.

Parameters:	cs (ChemSpider) – `ChemSpider` session. csid (int\|string) – ChemSpider ID.

csid¶: ChemSpider ID.

image_url¶: Return the URL of a PNG image of the 2D chemical structure.

molecular_formula¶: Return the molecular formula for this Compound.

smiles¶: Return the SMILES for this Compound.

inchi¶: Return the InChI for this Compound.

inchikey¶: Return the InChIKey for this Compound.

average_mass¶: Return the average mass of this Compound.

molecular_weight¶: Return the molecular weight of this Compound.

monoisotopic_mass¶: Return the monoisotopic mass of this Compound.

nominal_mass¶: Return the nominal mass of this Compound.

alogp¶: Return the calculated AlogP for this Compound.

xlogp¶: Return the calculated XlogP for this Compound.

common_name¶: Return the common name for this Compound.

mol_2d¶: Return the MOL file for this Compound with 2D coordinates.

mol_3d¶: Return the MOL file for this Compound with 3D coordinates.

mol_raw¶: Return unprocessed MOL file for this Compound.

image¶: Return a 2D depiction of this Compound.

spectra¶: Return all the available spectral data for this Compound.

chemspipy.search¶

A wrapper for asynchronous search requests.

class chemspipy.Results[source]¶

Container class to perform a search on a background thread and hold the results when ready.

Generally shouldn’t be instantiated directly. See search() instead.

Parameters:	cs (ChemSpider) – `ChemSpider` session. searchfunc (function) – Search function that returns a transaction ID. searchargs (tuple) – Arguments for the search function. propagate (bool) – If True, raise exceptions. If False, store on `exception` property. max_requests (int) – Maximum number of times to check if search results are ready.

ready()[source]¶: Return True if the search finished.

success()[source]¶: Return True if the search finished with no errors.

wait()[source]¶: Block until the search has completed and optionally raise any resulting exception.

status¶

Current status string returned by ChemSpider.

One of: ‘Unknown’, ‘Created’, ‘Scheduled’, ‘Processing’, ‘Suspended’, ‘PartialResultReady’, ‘ResultReady’

exception¶: Any Exception raised during the search. Blocks until the search is finished.

message¶: A contextual message about the search. Blocks until the search is finished.

count¶: The number of search results. Blocks until the search is finished.

duration¶: The time taken to perform the search. Blocks until the search is finished.

chemspipy.errors¶

Exceptions raised by ChemSpiPy.

exception chemspipy.errors.ChemSpiPyError[source]¶: Root ChemSpiPy Exception.

exception chemspipy.errors.ChemSpiPyParseError[source]¶: Raised when ChemSpiPy fails to parse a response from the ChemSpider servers.

exception chemspipy.errors.ChemSpiPyAuthError[source]¶: Raised when the security token doesn’t have access to an endpoint.

exception chemspipy.errors.ChemSpiPyNotFoundError[source]¶: Raised when no record is present for the requested CSID.

exception chemspipy.errors.ChemSpiPyTimeoutError[source]¶: Raised when an asynchronous request times out.

exception chemspipy.errors.ChemSpiPyServerError[source]¶: Raised when ChemSpider returns a 500 status code with an error message.