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.

Usage:

>>> from chemspipy import ChemSpider
>>> cs = ChemSpider('<YOUR-SECURITY-TOKEN>')

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

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_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_spectrum(spectrum_id)¶

Return a Spectrum object for a given spectrum ID. Subscriber role security token is required.

Parameters:	spectrum_id (string\|int) – Spectrum ID.
Returns:	The Spectrum with the specified spectrum ID.
Return type:	`Spectrum`

get_spectra(spectrum_ids)¶

Return a Spectrum object for a given spectrum ID. Subscriber role security token is required.

Parameters:	spectrum_ids (list[string\|int]) – List of spectrum IDs.
Returns:	List of spectra with the specified spectrum IDs.
Return type:	list[`Spectrum`]

get_compound_spectra(csid)¶

Return Spectrum objects for all the spectra associated with a ChemSpider ID.

Parameters:	csid – string\|int csid: ChemSpider ID.
Returns:	List of spectra for the specified ChemSpider ID.
Return type:	list[`Spectrum`]

get_all_spectra()¶

Return a full list of Spectrum objects for all spectra in ChemSpider.

Subscriber role security token is required.

Returns:	Full list of spectra in ChemSpider.
Return type:	list[`Spectrum`]

search(query, order=None, direction=ASCENDING, raise_errors=False)¶

Search ChemSpider for the specified query and return the results. Security token is required.

Parameters:	query (string\|int) – Search query. order (string) – (Optional) `CSID`, `MASS_DEFECT`, `MOLECULAR_WEIGHT`, `REFERENCE_COUNT`, `DATASOURCE_COUNT`, `PUBMED_COUNT` or `RSC_COUNT`. direction (string) – (Optional) `ASCENDING` or `DESCENDING`. raise_errors (bool) – If True, raise exceptions. If False, store on Results `exception` property.
Returns:	Search Results list.
Return type:	Results

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`]

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_original_mol(csid)¶

Get original submitted MOL file. Security token is required.

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

get_compound_thumbnail(csid)¶

Get PNG image as binary data.

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

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

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_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=MOL2D, 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) – `MOL2D`, `MOL3D` or `BOTH`. include_reference_counts (bool) – Whether to include reference counts. include_external_references (bool) – Whether to include external references.

get_compound_spectra_info(csid)¶

Get information about all the spectra for a ChemSpider ID. Subscriber role security token is required.

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

get_spectrum_info(spectrum_id)¶

Get information for a specific spectrum ID. Subscriber role security token is required.

Parameters:	spectrum_id (string\|int) – spectrum ID.
Returns:	Spectrum info.
Return type:	dict

get_spectra_info_list(csids)¶

Get information about all the spectra for a list of ChemSpider IDs.

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

get_all_spectra_info()¶

Get full list of all spectra in ChemSpider. Subscriber role security token is required.

rtype: 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

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 (MassSpecAPI, Search, Spectra, InChI). endpoint (string) – ChemSpider API endpoint. params – (Optional) Parameters for the ChemSpider endpoint as keyword arguments.
Return type:	string

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=CSID, direction=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

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_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`]

simple_search_by_formula(formula)¶

Search ChemSpider by molecular formula.

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

simple_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`]

chemspipy.api.MOL2D = u'2d'¶: 2D coordinate dimensions

chemspipy.api.MOL3D = u'3d'¶: 3D coordinate dimensions

chemspipy.api.BOTH = u'both'¶: Both coordinate dimensions

chemspipy.api.ASCENDING = u'ascending'¶: Ascending sort direction

chemspipy.api.DESCENDING = u'descending'¶: Descending sort direction

chemspipy.api.CSID = u'csid'¶: CSID sort order

chemspipy.api.MASS_DEFECT = u'mass_defect'¶: Mass defect sort order

chemspipy.api.MOLECULAR_WEIGHT = u'molecular_weight'¶: Molecular weight sort order

chemspipy.api.REFERENCE_COUNT = u'reference_count'¶: Reference count sort order

chemspipy.api.DATASOURCE_COUNT = u'datasource_count'¶: Datasource count sort order

chemspipy.api.PUBMED_COUNT = u'pubmed_count'¶: Pubmed count sort order

chemspipy.api.RSC_COUNT = u'rsc_count'¶: RSC count sort order

chemspipy.objects¶

Objects returned by ChemSpiPy API methods.

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.

Return type:	string

smiles¶

Return the SMILES for this Compound.

Return type:	string

inchi¶

Return the InChI for this Compound.

Return type:	string

inchikey¶

Return the InChIKey for this Compound.

Return type:	string

average_mass¶

Return the average mass of this Compound.

Return type:	float

molecular_weight¶

Return the molecular weight of this Compound.

Return type:	float

monoisotopic_mass¶

Return the monoisotopic mass of this Compound.

Return type:	float

nominal_mass¶

Return the nominal mass of this Compound.

Return type:	float

alogp¶

Return the calculated AlogP for this Compound.

Return type:	float

xlogp¶

Return the calculated XlogP for this Compound.

Return type:	float

common_name¶

Return the common name for this Compound.

Return type:	string

mol_2d¶

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

Return type:	string

mol_3d¶

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

Return type:	string

mol_raw¶

Return unprocessed MOL file for this Compound.

Return type:	string

image¶

Return a 2D depiction of this Compound.

Return type:	bytes

spectra¶

Return all the available spectral data for this Compound.

Return type:	list[`Spectrum`]

class chemspipy.Spectrum[source]¶

A class for retrieving and caching details about a Spectrum.

Initializing a Spectrum from a spectrum ID requires a subscriber role security token.

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

classmethod from_info_dict(cs, info)[source]¶: Initialize a Spectrum from an info dict that has already been retrieved.

spectrum_id¶

Spectrum ID.

Return type:	int

csid¶

ChemSpider ID of related compound.

Return type:	int

spectrum_type¶

Spectrum type.

Possible values include HNMR, CNMR, IR, UV-Vis, NIR, EI, 2D1H1HCOSY, 2D1H13CD, APCI+, R, MALDI+, 2D1H13CLR, APPI-, CI+ve, ESI+, 2D1H1HOESY, FNMR, CI-ve, ESI-, PNMR.

Return type:	string

file_name¶

Spectrum file name.

Return type:	string

comments¶

Spectrum comments. Can be None.

Return type:	string

url¶

Spectrum URL.

Return type:	string

data¶

Spectrum data file contents. Requires an additional request. Result is cached.

Return type:	string

original_url¶

Original spectrum URL. Can be None.

Return type:	string

submitted_date¶

Spectrum submitted date.

Return type:	`datetime.datetime`

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. raise_errors (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.

Return type:	bool

success()[source]¶

Return True if the search finished with no errors.

Return type:	bool

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

status¶

Current status string returned by ChemSpider.

Returns:	‘Unknown’, ‘Created’, ‘Scheduled’, ‘Processing’, ‘Suspended’, ‘PartialResultReady’, ‘ResultReady’
Return type:	string

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.

Return type:	string

count¶

The number of search results. Blocks until the search is finished.

Return type:	int

duration¶

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

Return type:	`datetime.timedelta`

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.