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
orRSC_COUNT
. - direction (string) – (Optional)
ASCENDING
orDESCENDING
. - raise_errors (bool) – If True, raise exceptions. If False, store on Results
exception
property.
Returns: Search Results list.
Return type:
-
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:
-
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
orRSC_COUNT
. - direction (string) –
ASCENDING
orDESCENDING
.
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: 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
-
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
- cs (ChemSpider) –
-
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_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
-
original_url
¶ Original spectrum URL. Can be None.
Return type: string
-
submitted_date
¶ Spectrum submitted date.
Return type: datetime.datetime
- cs (ChemSpider) –
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.
-
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
-
duration
¶ The time taken to perform the search. Blocks until the search is finished.
Return type: datetime.timedelta
- cs (ChemSpider) –
chemspipy.errors¶
Exceptions raised by ChemSpiPy.
-
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.