chemfp.text_toolkit module

Methods to work with SD and SMILES files as records rather than molecules.

The text_toolkit implements the chemfp toolkit API but where the “molecules” are simple `TextRecord instances which store the records as text strings. It does not use a back-end chemistry toolkit, and it cannot convert between different chemistry representations.

The TextRecord is a base class. The actual records depend on the format, and will be one of:

The text toolkit will let you “convert” between the different SMILES formats, but it doesn’t actually change the SMILES string. The SMILES records have the attributes id, record and smiles.

The toolkit also knows a bit about the SD format. The SDF records have the attributes id, id_bytes and record, and there are methods to get SD tag values and add a tag to the end of the tag data block.

The text_toolkit also supports a few SDF-specific I/O functions to read SDF records directly as a string instead of wrapped in a TextRecord.

The record types also have the attributes encoding and encoding_errors which affect how the record bytes are parsed.

chemfp.text_toolkit.is_licensed()

Return True - chemfp’s text toolkit is always licensed

Returns:True
chemfp.text_toolkit.get_formats(include_unavailable=False)

Get the list of structure formats that chemfp’s text toolkit supports

This version of chemfp will always support the structure formats available to chemfp so ‘include_unavailable’ does not affect anything. (It may affect other toolkits.)

Parameters:include_unavailable – include unavailable formats?
Value include_unavailable:
 True or False
Returns:a list of chemfp.base_toolkit.Format objects
chemfp.text_toolkit.get_input_formats()

Get the list of supported chemfp text toolkit input formats

Returns:a list of chemfp.base_toolkit.Format objects
chemfp.text_toolkit.get_output_formats()

Get the list of supported chemfp text toolkit output formats

Returns:a list of chemfp.base_toolkit.Format objects
chemfp.text_toolkit.get_format(format_name)

Get the named format, or raise a ValueError

This will raise a ValueError for unknown format names.

Parameters:format_name – the format name
Value format_name:
 a string
Returns:a chemfp.base_toolkit.Format object
chemfp.text_toolkit.get_input_format(format_name)

Get the named input format, or raise a ValueError

This will raise a ValueError for unknown format names or if that format is not an input format.

Parameters:format_name – the format name
Value format_name:
 a string
Returns:a chemfp.base_toolkit.Format object
chemfp.text_toolkit.get_output_format(format_name)

Get the named format, or raise a ValueError

This will raise a ValueError for unknown format names or if that format is not an output format.

Parameters:format_name – the format name
Value format_name:
 a string
Returns:a chemfp.base_toolkit.Format object
chemfp.text_toolkit.get_input_format_from_source(source=None, format=None)

Get the most appropriate format given the available source and format information

If format is a chemfp.base_toolkit.Format then return it. If it’s a Format-like object with “name” and “compression” attributes use it to make a real Format object with the same attributes. If it’s a string then use it to create a Format object.

If format is None, use the source to auto-detect the format. If auto-detection is not possible, assume it’s an uncompressed SMILES file.

Parameters:
  • source (A filename (as a string), a file object, or None to read from stdin) – The structure data source.
  • format (A Format(-like) object, string, or None) – Format information, if known.
Returns:

a chemfp.base_toolkit.Format object
chemfp.text_toolkit.get_output_format_from_destination(destination=None, format=None)

Get the most appropriate format given the available destination and format information

If format is a chemfp.base_toolkit.Format then return it. If it’s a Format-like object with “name” and “compression” attributes use it to make a real Format object with the same attributes. If it’s a string then use it to create a Format object.

If format is None, use the destination to auto-detect the format. If auto-detection is not possible, assume it’s an uncompressed SMILES file.

Parameters:
  • destination (A filename (as a string), a file object, or None to read from stdin) – The structure data source.
  • format (A Format(-like) object, string, or None) – format information, if known.
Returns:

A chemfp.base_toolkit.Format object
chemfp.text_toolkit.read_sdf_records(source=None, reader_args=None, compression=None, errors='strict', location=None, block_size=327680)

Return an iterator that reads each record from an SD file as a string.

Iterate through the records in source, which must be in SD format. If compression is None or “auto” then auto-detect the compression type based on source, and default to uncompressed when it can’t be determined. Use “gz” when the input is gzip compressed, and “none” or “” if uncompressed.

The reader_args parameter is currently unused. It exists for future compatability.

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a chemfp.io.Location instance. If None then a default Location will be created.

The block_size parameter is the number of bytes to read from the SD file. The current implementation reads a block, iterates through the records in the block, then prepends any remaining text to the start of the next block. You shouldn’t need to change this parameter, but if you do, please let me know.

Note: to prevent accidental memory consumption if the input is in the wrong format, a complete record must be found within the first 327680 bytes or 5*block_size bytes, whichever is larger.

The parser has only a basic understanding of the SD format. It knows how to handle the counts line, the SKP property, and even tag data with the value ‘$$$$’. It is not a full validator and it does not know chemistry.

See read_sdf_ids_and_records() if you want (id, record) pairs, and read_sdf_ids_and_values() if you want (id, tag data) pairs. See read_sdf_ids_and_records_from_string() to read from a string instead of a file or file-like object.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the SDF source
  • reader_args (currently ignored) – currently ignored
  • compression (one of "auto", "none", "", or "gz") – the data content compression method
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
Returns:

a chemfp.base_toolkit.RecordReader() iterating over the records as a string
chemfp.text_toolkit.read_sdf_ids_and_records(source=None, id_tag=None, reader_args=None, compression=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict', block_size=327680)

Return an iterator that reads the (id, record string) pairs from an SD file

See read_sdf_records() for most parameter details. That function iterates over the records, while this one iterates over the (id, record) pairs. By default the id comes from the title line. Use id_tag to get the record id from the given SD tag instead.

See read_sdf_ids_and_values() if you want to read an identifier and tag value, or two tag values, instead of returning the full record.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the SDF source
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (currently ignored) – currently ignored
  • compression (one of "auto", "none", "", or "gz") – the data content compression method
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
Returns:

a chemfp.base_toolkit.IdAndRecordReader iterating (id, record string) pairs
chemfp.text_toolkit.read_sdf_ids_and_values(source=None, id_tag=None, value_tag=None, reader_args=None, compression=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict', block_size=327680)

Return an iterator that reads the (id, tag value string) pairs from an SD file

See read_sdf_records() for most parameter details. That function iterates over the records, while this one iterates over the (id, tag value) pairs.

By default this uses the title line for both the id and tag value strings. Use id_tag and value_tag, respectively, to use a given tag value instead. If a tag doesn’t exist then None will be used.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the SDF source
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • value_tag (string, or None to use the record title) – SD tag containing the value
  • reader_args (currently ignored) – currently ignored
  • compression (one of "auto", "none", "", or "gz") – the data content compression method
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
Returns:

a chemfp.base_toolkit.IdAndRecordReader iterating (id, value string) pairs
chemfp.text_toolkit.read_sdf_records_from_string(content, reader_args=None, compression=None, errors='strict', location=None, block_size=327680)

Return an iterator that reads each record from a string containing SD records

See read_sdf_records_from_string() for the parameter details. The main difference is that this function reads from content, which is a string containing 0 or more SDF records.

If content is a (Unicode) string then it must only contain ASCII characters, the records will be returned as strings, and the compression option is not supported. If content is a byte string then the records will be returned as byte strings, and compression is supported.

See read_sdf_ids_and_records_from_string() to read (id, record) pairs and read_sdf_ids_and_values_from_string() to read (id, tag value) pairs.

Parameters:
  • content (string or bytes) – a string containing zero or more SD records
  • reader_args (currently ignored) – currently ignored
  • compression (one of "auto", "none", "", or "gz") – the data content compression method
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
Returns:

a chemfp.base_toolkit.RecordReader iterating over each record as a string
chemfp.text_toolkit.read_sdf_ids_and_records_from_string(content=None, id_tag=None, reader_args=None, compression=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict', block_size=327680)

Return an iterator that reads the (id, record) pairs from a string containing SD records

This function reads the records from content, which is a string containing 0 or more SDF records. It iterates over the (id, record) pairs. By default the id comes from the first line of the SD record. Use id_tag to use a given tag value instead. See read_sdf_records() for details about the other parameters.

If content is a (Unicode) string then it must only contain ASCII characters, the records will be returned as strings, the compression option is not supported, and the encoding and encoding_errors parameters are ignored.

If content is a byte string then the records will be returned as byte strings, compression is supported, and the encoding and encoding_errors parameters are used to parse the id.

Parameters:
  • content (string or bytes) – a string containing zero or more SD records
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (currently ignored) – currently ignored
  • compression (one of "auto", "none", "", or "gz") – the data content compression method
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
Returns:

a chemfp.base_toolkit.IdAndRecordReader iterating over the (id, record string) pairs
chemfp.text_toolkit.read_sdf_ids_and_values_from_string(content=None, id_tag=None, value_tag=None, compression=None, reader_args=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict', block_size=327680)

Return an iterator that reads the (id, value) pairs from a string containing SD records

This function reads the records from content, which is a string containing 0 or more SDF records. It iterates over the (id, value) pairs, which by default both contain the title line. Use id_tag and value_tag, respectively, to use a given tag value instead. If a tag doesn’t exist then None will be used.

If content is a (Unicode) string then it must only contain ASCII characters, the compression option is not supported, and the encoding and encoding_errors parameters are ignored.

If content is a byte string then the records will be returned as byte strings, compression is supported, and the encoding and encoding_errors parameters are used to parse the id and value.

See read_sdf_records() for details about the other parameters.

Parameters:
  • content (string or bytes) – a string containing zero or more SD records
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • value_tag (string, or None to use the record title) – SD tag containing the value
  • reader_args (currently ignored) – currently ignored
  • compression (one of "auto", "none", "", or "gz") – the data content compression method
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
Returns:

a chemfp.base_toolkit.IdAndRecordReader iterating over the (id, value) pairs
chemfp.text_toolkit.read_molecules(source=None, format=None, id_tag=None, reader_args=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict')

Return an iterator that reads TextRecord instances from a structure file

Iterate through the format structure records in source. If format is None then auto-detect the format based on the source. For SD files, use id_tag to get the record id from the given SD tag instead of the title line. (read_molecules() will ignore the id_tag. It exists to make it easier to switch between reader functions.)

Only the SMILES formats use the reader_args dictionary. The supported parameters are:

  • delimiter - one of “tab”, “space”, “to-eol”, the space or tab characters, or None
  • has_header - True or False

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a chemfp.io.Location instance. If None then a default Location will be created.

See read_ids_and_molecules() if you want (id, TextRecord) pairs instead of just the molecules.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the structure source
  • format (a format name string, or Format object, or None to auto-detect) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader parameters passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
Returns:

a chemfp.base_toolkit.MoleculeReader iterating TextRecord molecules
chemfp.text_toolkit.read_molecules_from_string(content, format, id_tag=None, reader_args=None, errors='strict', location=None)

Return an iterator that reads TextRecord instances from a string containing structure records

content is a string containing 0 or more records in the format format. See read_molecules() for details about the other parameters. See read_ids_and_molecules_from_string() if you want to read (id, TextRecord) pairs instead of just molecules.

Parameters:
  • content (a string) – the string containing structure records
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
Returns:

a chemfp.base_toolkit.MoleculeReader iterating TextRecord molecules
chemfp.text_toolkit.read_ids_and_molecules(source=None, format=None, id_tag=None, reader_args=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict')

Return an iterator that reads (id, TextRecord) pairs from a structure file

See chemfp.text_toolkit.read_molecules() for full parameter details. The major difference is that this returns an iterator of (id, TextRecord) pairs instead of just the molecules.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the structure source
  • format (a format name string, or Format object, or None to auto-detect) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
Returns:

a chemfp.text_toolkit.IdAndMoleculeReader iterating (id, TextRecord) pairs
chemfp.text_toolkit.read_csv_ids_and_molecules(source, *, id_column=1, mol_column=2, dialect=None, has_header=True, compression='auto', format='smi', id_tag=None, reader_args=None, errors='report', csv_errors='strict', location=None, encoding='utf8', encoding_errors='strict')

Read ids and TextRecors from column(s) of a CSV file

Read from source, which may be a filename, a file-like object, or None to read from stdin.

Use id_column and mol_column to specify the columns containing the record identifier and molecule record. By default the identifiers come from column 1 (the first column) and the molecules from column 2 (the second column). Columns can be specified by integer position (starting with 1), or by a string matching the title from the header line. If id_column is None then the molecule id will come from parsing the molecule record.

Use dialect to specify the type of CSV file. The default of None infers the dialect from the filename extension; *.csv for comma-separated, and *.tsv for tab-separated. The dialect can be specified directly as “csv” or “tsv”, as a registered Python csv dialect at https://docs.python.org/3/library/csv.html (though “excel” is the same as “csv” and “excel-tab” is the same as “tsv”), or as a csv.Dialect or a .class:CSVDialect instance.

If has_header is True then the first line/record contains column titles, and if False then there are no column titles.

Use compression to specify how the file compression format. The default “auto” uses the filename extension. Other options are “gz” and “zst”, or the empty string “” to mean no compresssion.

Use format to specify the structure format for how to parse the molecule column. The default of ‘smi’ will parse it as a SMILES string and, if id_column=None, will also parse any identifier.

The id_tag and reader_args arguments contain additional format configuration parameters.

The errors and csv_errors describe how to handle failures in molecule parsing and CSV parsing, respectively. The default is to report molecule parse failures to stderr, and to stop parsing if a CSV row does not contain enough columns.

The location parameter takes a chemfp.io.Location instance. If None then a default Location will be created.

The encoding and encoding_errors are strings describing the input file character encoding, and how to handle decoding errors. See https://docs.python.org/3/library/codecs.html#error-handlers and https://docs.python.org/3/library/codecs.html#error-handlers for details.

Parameters:
  • source (a filename, file object, or None to read from stdin) – the CSV source
  • id_column (integer position (starting from 1), string, or None) – the column position or column title containing the identifier
  • mol_column (integer position (starting from 1), string) – the column position or column title containing the structure record
  • dialect (None, a string name, or a Dialect instance) – the CSV dialect
  • has_header (bool) – True if the first record contains titles, False of it does not
  • compression (string or None) – file compression format
  • format (a format name string, or Format object) – the molecule structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle molecule parse errors
  • csv_errors (one of "strict", "report", or "ignore") – specify how to handle CSV errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
  • encoding (string) – the name of the file’s character encoding
  • encoding_errors (string) – the method used handle decoding errors
Returns:

a chemfp.base_toolkit.IdAndMoleculeReader iterating (id, RDKit molecule) pairs
chemfp.text_toolkit.read_ids_and_molecules_from_string(content, format, id_tag=None, reader_args=None, errors='strict', location=None)

Return an iterator that reads (id, TextRecord) pairs from a string containing structure records

content is a string containing 0 or more records in the format format. See chemfp.rdkit_toolkit.read_molecules() for details about the other parameters. See chemfp.rdkit_toolkit.read_molecules_from_string() if you just want to read the TextRecord molecules instead of (id, TextRecord) pairs.

Parameters:
  • content (a string) – the string containing structure records
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track parser state information
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
Returns:

a chemfp.base_toolkit.IdAndMoleculeReader iterating (id, TextRecord) pairs
chemfp.text_toolkit.make_id_and_molecule_parser(format, id_tag=None, reader_args=None, errors='strict')

Create a specialized function which takes a record and returns an (id, TextRecord) pair

The returned function is optimized for reading many records from individual strings because it only does parameter validation once. However, I haven’t really noticed much of a performance difference between this and chemfp.text_toolkit.parse_id_and_molecule() so I suggest you use that function directly instead of making a specialized function. (Let me know if making a specialized function is useful.)

See chemfp.text_toolkit.read_molecules() for details about the other parameters. The specific TextRecord subclass returned depends on the format.

Parameters:
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

a function of the form parser(record string) -> (id, text_record)
chemfp.text_toolkit.parse_molecule(content, format, id_tag=None, reader_args=None, errors='strict')

Parse the first structure record from the content string and return a TextRecord.

content is a string containing a single structure record in format format. (Additional records are ignored). See chemfp.text_toolkit.read_molecules() for details about the other parameters. See chemfp.text_toolkit.parse_id_and_molecule() if you want the (id, TextRecord) pair instead of just the text record.

Parameters:
  • content (a string) – the string containing a structure record
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
Returns:

a TextRecord
chemfp.text_toolkit.parse_id_and_molecule(content, format, id_tag=None, reader_args=None, errors='strict')

Parse the first structure record from content and return the (id, TextRecord) pair.

content is a string containing a single structure record in format format. (Additional records are ignored). See chemfp.rdkit_toolkit.read_molecules() for details about the other parameters.

See chemfp.rdkit_toolkit.read_molecules() for details about the other parameters. See chemfp.rdkit_toolkit.parse_molecule() if just want the TextRecord and not the the (id, TextRecord) pair.

Parameters:
  • content (a string) – the string containing a structure record
  • format (a format name string, or Format object) – the input structure format
  • id_tag (string, or None to use the record title) – SD tag containing the record id
  • reader_args (a dictionary) – reader arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
Returns:

an (id, TextRecord molecule) pair
chemfp.text_toolkit.create_string(mol, format, id=None, writer_args=None, errors='strict')

Convert a TextRecord into a structure record in the given format as a Unicode string

If id is not None then use it instead of the molecule’s own id.

Parameters:
  • mol (a TextRecord) – the molecule to use for the output
  • format (a format name string, or Format object) – the output structure format
  • id (a string, or None to use the molecule's own id) – an alternate record id
  • writer_args (a dictionary) – writer arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
Returns:

a Unicode string
chemfp.text_toolkit.create_bytes(mol, format, id=None, writer_args=None, errors='strict', level=None)

Convert a TextRecord into a structure record in the given format as a byte string

If id is not None then use it instead of the molecule’s own id.

Parameters:
  • mol (a TextRecord) – the molecule to use for the output
  • format (a format name string, or Format object) – the output structure format
  • id (a string, or None to use the molecule's own id) – an alternate record id
  • writer_args (a dictionary) – writer arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • level (None, a positive integer, or one of the strings 'min', 'default', or 'max') – compression level to use for compressed formats
Returns:

a byte string
chemfp.text_toolkit.open_molecule_writer(destination=None, format=None, writer_args=None, errors='strict', location=None, encoding='utf8', encoding_errors='strict', level=None)

Return a MoleculeWriter which can write TextRecord instances to a destination.

A chemfp.base_toolkit.MoleculeWriter has the methods write_molecule, write_molecules, and write_ids_and_molecules, which are ways to write an TextRecord, an TextRecord iterator, or an (id, TextRecord) pair iterator to a file.

TextRecords are written to destination. The output format can be a string like “sdf.gz” or “smi”, a chemfp.base_toolkit.Format, or Format-like object with “name” and “compression” attributes, or None to auto-detect based on the destination. If auto-detection is not possible, the output will be written as uncompressed SMILES.

That said, the text toolkit doesn’t know how to convert between SMILES and SDF formats, and will raise an exception if you try.

The writer_args is only used for the “smi”, “can”, and “usm” output formats. The only supported parameter is:

* delimiter - one of "tab", "space", "to-eol", the space or tab characters, or None

The errors parameter specifies how to handle errors. “strict” raises an exception, “report” sends a message to stderr and goes to the next record, and “ignore” goes to the next record.

The location parameter takes a chemfp.io.Location instance. If None then a default Location will be created.

Parameters:
  • destination (a filename, file object, or None to write to stdout) – the structure destination
  • format (a format name string, or Format(-like) object, or None to auto-detect) – the output structure format
  • writer_args (a dictionary) – writer arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track writer state information
  • encoding (string (typically 'utf8' or 'latin1')) – the byte encoding
  • encoding_errors (string (typically 'strict', 'ignore', or 'replace')) – how to handle decoding failure
  • level (None, a positive integer, or one of the strings 'min', 'default', or 'max') – compression level to use for compressed formats
Returns:

a chemfp.base_toolkit.MoleculeWriter expecting TextRecord instances
chemfp.text_toolkit.open_molecule_writer_to_string(format, writer_args=None, errors='strict', location=None)

Return a MoleculeStringWriter which can write TextRecord instances to a string.

See chemfp.text_toolkit.open_molecule_writer() for full parameter details.

Use the writer’s chemfp.base_toolkit.MoleculeStringWriter.getvalue() to get the output as a Unicode string.

Parameters:
  • format (a format name string, or Format(-like) object, or None to auto-detect) – the output structure format
  • writer_args (a dictionary) – writer arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track writer state information
Returns:

a chemfp.base_toolkit.MoleculeStringWriter expecting TextRecord instances
chemfp.text_toolkit.open_molecule_writer_to_bytes(format, writer_args=None, errors='strict', location=None, level=None)

Return a MoleculeStringWriter which can write TextRecord instances to a string.

See chemfp.text_toolkit.open_molecule_writer() for full parameter details.

Use the writer’s chemfp.base_toolkit.MoleculeStringWriter.getvalue() to get the output as a byte string.

Parameters:
  • format (a format name string, or Format(-like) object, or None to auto-detect) – the output structure format
  • writer_args (a dictionary) – writer arguments passed to the underlying toolkit
  • errors (one of "strict", "report", or "ignore") – specify how to handle errors
  • location (a chemfp.io.Location object, or None) – object used to track writer state information
  • level (None, a positive integer, or one of the strings 'min', 'default', or 'max') – compression level to use for compressed formats
Returns:

a chemfp.base_toolkit.MoleculeStringWriter expecting TextRecord instances
chemfp.text_toolkit.copy_molecule(mol)

Return a new TextRecord which is a copy of the given TextRecord

Parameters:mol (a TextRecord) – the text record
Returns:a new TextRecord
chemfp.text_toolkit.add_tag(mol, tag, value)

Add an SD tag value to the TextRecord

If the mol is in “sdf” format then this will modify mol.record to append the new tag and value to the end of the tag block. The other tags will not be modified, including tags with the same tag name.

Parameters:
  • mol (a TextRecord) – the text record
  • tag (string) – the SD tag name
  • value (string) – the text for the tag
Returns:

None
chemfp.text_toolkit.get_tag(mol, tag)

Get the named SD tag value, or None if it doesn’t exist

If the mol is in “sdf” format then this will return the corresponding tag value from mol.record, or None if the tag does not exist.

If the record is in any other format then it will return None.

Parameters:
  • mol (a TextRecord) – the molecule
  • tag (string) – the SD tag name
Returns:

a string, or None
chemfp.text_toolkit.get_tag_pairs(mol)

Get a list of all SD tag (name, value) pairs for the TextRecord

If the mol is in “sdf” format then this will return the list of (tag, value) pairs in mol.record, where the tag and value are strings.

If the record is in any other format then it will return an empty list.

Parameters:mol (a TextRecord) – the molecule
Returns:a list of (tag name, tag value) pairs
chemfp.text_toolkit.get_id(mol)

Get the molecule’s id from the TextRecord’s id field

This is toolkit-portable way to get mol.id.

Parameters:mol (a TextRecord) – the molecule
Returns:a string
chemfp.text_toolkit.set_id(mol, id)

Set the TextRecord’s id to the new id

This is the toolkit-portable way to write mol.id = id.

Note: this does not modify mol.record. Use chemfp.text_toolkit.create_string() or similar text_toolkit functions to get the record text with a new identifier.

Parameters:
  • mol (a TextRecord) – the molecule
  • id (string) – the new id
Returns:

None
chemfp.text_toolkit.get_sdf_tag(sdf_record, tag)

Return the value for a named tag in an SDF record string

Get the value for the tag named tag from the string sdf_record containing an SD record.

Parameters:
  • sdf_record (string) – an SD record
  • tag (string) – a tag name
Returns:

the corresponding tag value as a string, or None
chemfp.text_toolkit.add_sdf_tag(sdf_record, tag, value)

Add an SD tag value to an SD record string

This will append the new tag and value to the end of the tag data block in the sdf_record string.

Parameters:
  • sdf_record (string) – an SD record
  • tag (string) – a tag name
  • value (string) – the new tag value
Returns:

a new SD record string with the new tag and value
chemfp.text_toolkit.get_sdf_tag_pairs(sdf_record)

Return the (tag, value) entries in the SDF record string

Parse the sdf_record and return the tag data as a list of (tag, value) pairs. The type of the returned strings will be the same as the type of the input sdf_record string.

Parameters:sdf_record (string) – an SDF record
Returns:a list of (tag, value) pairs
chemfp.text_toolkit.get_sdf_id(sdf_record)

Return the id for the SDF record string

The id is the first line of the sdf_record. A future version of this function may support an id_tag parameter. Let me know if that would be useful.

The returned id string will have the same type as the input sdf_record.

Parameters:sdf_record (string) – an SD record
Returns:the first line of the SD record
chemfp.text_toolkit.set_sdf_id(sdf_record, id)

Set the id of the SDF record string to a new value

Set the first line of sdf_record to the new id, which must not contain a newline.

The sdf_record and the id must have the same string type.

Parameters:
  • sdf_record (string) – an SDF record
  • id (string) – the new id
chemfp.text_toolkit.parse_smistring(content: Union[str, bytes], *, cxsmiles: bool = True, errors: str = 'strict')

Parse a SMILES string using the text toolkit

This is equivalent to calling:

parse_molecule(content, "smistring", reader_args={...}, errors=errors)
Parameters:
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a TextRecord instance object
chemfp.text_toolkit.create_smistring(mol: Any, *, id: Optional[str, None] = None, cxsmiles: bool = False, errors: str = 'strict') → Optional[str, None]

Generate a SMILES string from a TextRecord instance

This is equivalent to calling:

create_string(mol, "smistring", id=id, writer_args={...}, errors=errors)
Parameters:
  • mol (a TextRecord instance) – a molecule object
  • id (None or a string (default: None)) – an alternate identifier for the output record, if relevant
  • cxsmiles (Boolean (default: False)) – If true, include any CXSmiles term
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a string, or None if errors are ignored
chemfp.text_toolkit.parse_smi(content: Union[str, bytes], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = 'to-eol', has_header: bool = False, cxsmiles: bool = True, errors: str = 'strict')

Parse a SMILES string and its id using the text toolkit

This is equivalent to calling:

parse_molecule(content, "smi", reader_args={...}, errors=errors)
Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: "to-eol")) – The separator between the SMILES and the id
  • has_header (Boolean (default: False)) – If true, treat the first line of the SMILES file as a header
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a TextRecord instance object
chemfp.text_toolkit.create_smi(mol: Any, *, id: Optional[str, None] = None, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = None, cxsmiles: bool = False, errors: str = 'strict') → Optional[str, None]

Generate a SMILES string and its id from a TextRecord instance

This is equivalent to calling:

create_string(mol, "smi", id=id, writer_args={...}, errors=errors)
Parameters:
  • mol (a TextRecord instance) – a molecule object
  • id (None or a string (default: None)) – an alternate identifier for the output record, if relevant
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: None)) – The separator between the SMILES and the id
  • cxsmiles (Boolean (default: False)) – If true, include any CXSmiles term
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a string, or None if errors are ignored
chemfp.text_toolkit.read_smi_molecules(source: Union[None, str, BinaryIO], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = 'to-eol', has_header: bool = False, cxsmiles: bool = True, errors: str = 'strict')

Read molecules from a SMILES file using the text toolkit

This is mostly equivalent to calling:

read_molecules(source, "smi", reader_args={...}, errors=errors)

along with decompression based on the source filename’s extension.

Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: "to-eol")) – The separator between the SMILES and the id
  • has_header (Boolean (default: False)) – If true, treat the first line of the SMILES file as a header
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.MoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.read_smi_ids_and_molecules(source: Union[None, str, BinaryIO], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = 'to-eol', has_header: bool = False, cxsmiles: bool = True, errors: str = 'strict')

Read ids and molecules from a SMILES file using the text toolkit

This is mostly equivalent to calling:

read_ids_and_molecules(source, "smi", reader_args={...}, errors=errors)

along with decompression based on the source filename’s extension.

Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: "to-eol")) – The separator between the SMILES and the id
  • has_header (Boolean (default: False)) – If true, treat the first line of the SMILES file as a header
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.IdAndMoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.read_smi_molecules_from_string(content: Union[str, bytes], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = 'to-eol', has_header: bool = False, cxsmiles: bool = True, errors: str = 'strict')

Read molecules from a string containing a SMILES file using the text toolkit

This is equivalent to calling:

read_molecules_from_string(content, "smi", reader_args={...}, errors=errors)

Use read_molecules_from_string() if the content is compressed.

Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: "to-eol")) – The separator between the SMILES and the id
  • has_header (Boolean (default: False)) – If true, treat the first line of the SMILES file as a header
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.MoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.read_smi_ids_and_molecules_from_string(content: Union[str, bytes], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = 'to-eol', has_header: bool = False, cxsmiles: bool = True, errors: str = 'strict')

Read ids and molecules from a string containing a SMILES file using the text toolkit

This is equivalent to calling:

read_ids_and_molecules_from_string(content, "smi", reader_args={...}, errors=errors)

Use read_ids_and_molecules_from_string() if the content is compressed.

Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: "to-eol")) – The separator between the SMILES and the id
  • has_header (Boolean (default: False)) – If true, treat the first line of the SMILES file as a header
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.IdAndMoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.open_smi_writer(destination: Union[None, str, BinaryIO], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = None, cxsmiles: bool = False, errors: str = 'strict')

Open a SMILES file to write instances of TextRecord

This is mostly equivalent to calling:

open_molecule_writer(destination, "smi", writer_args={...}, errors=errors)

along with compression based on the destination filename’s extension.

Parameters:
  • destination (None, a filename string, or a file-like object) – where to write the molecules
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: None)) – The separator between the SMILES and the id
  • cxsmiles (Boolean (default: False)) – If true, include any CXSmiles term
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.MoleculeWriter expecting instances of TextRecord
chemfp.text_toolkit.open_smi_writer_to_string(*, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = None, cxsmiles: bool = False, errors: str = 'strict')

Open a SMILES file to write instances of TextRecord to an in-memory string

This is equivalent to calling:

open_molecule_writer_to_string("smi", writer_args={...}, errors=errors)

Use write_molecules_to_string() to write compressed output.

Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: None)) – The separator between the SMILES and the id
  • cxsmiles (Boolean (default: False)) – If true, include any CXSmiles term
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.MoleculeWriter expecting instances of TextRecord
chemfp.text_toolkit.parse_sdf(content: Union[str, bytes], *, errors: str = 'strict')

Parse an SDF record using the text toolkit

This is equivalent to calling:

parse_molecule(content, "sdf", reader_args={...}, errors=errors)
Parameters:errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:a TextRecord instance object
chemfp.text_toolkit.create_sdf(mol: Any, *, id: Optional[str, None] = None, errors: str = 'strict') → Optional[str, None]

Generate an SDF record from a TextRecord instance

This is equivalent to calling:

create_string(mol, "sdf", id=id, writer_args={...}, errors=errors)
Parameters:
  • mol (a TextRecord instance) – a molecule object
  • id (None or a string (default: None)) – an alternate identifier for the output record, if relevant
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a string, or None if errors are ignored
chemfp.text_toolkit.read_sdf_molecules(source: Union[None, str, BinaryIO], *, errors: str = 'strict')

Read molecules from an SDF file using the text toolkit

This is mostly equivalent to calling:

read_molecules(source, "sdf", reader_args={...}, errors=errors)

along with decompression based on the source filename’s extension.

Parameters:errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:a chemfp.base_toolkit.MoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.read_sdf_ids_and_molecules(source: Union[None, str, BinaryIO], *, id_tag: Optional[None, str] = None, errors: str = 'strict')

Read ids and molecules from an SDF file using the text toolkit

This is mostly equivalent to calling:

read_ids_and_molecules(source, "sdf", id_tag=id_tag, reader_args={...}, errors=errors)

along with decompression based on the source filename’s extension.

Parameters:
  • id_tag (a string, or None to use the title) – get the id from the named data item instead of using the record title
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.IdAndMoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.read_sdf_molecules_from_string(content: Union[str, bytes], *, errors: str = 'strict')

Read molecules from a string containing an SDF file using the text toolkit

This is equivalent to calling:

read_molecules_from_string(content, "sdf", reader_args={...}, errors=errors)

Use read_molecules_from_string() if the content is compressed.

Parameters:errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:a chemfp.base_toolkit.MoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.read_sdf_ids_and_molecules_from_string(content: Union[str, bytes], *, id_tag: Optional[None, str] = None, errors: str = 'strict')

Read ids and molecules from a string containing an SDF file using the text toolkit

This is equivalent to calling:

read_ids_and_molecules_from_string(content, "sdf", id_tag=id_tag, reader_args={...}, errors=errors)

Use read_ids_and_molecules_from_string() if the content is compressed.

Parameters:
  • id_tag (a string, or None to use the title) – get the id from the named data item instead of using the record title
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.IdAndMoleculeReader iterating instances of TextRecord
chemfp.text_toolkit.open_sdf_writer(destination: Union[None, str, BinaryIO], *, errors: str = 'strict')

Open an SDF file to write instances of TextRecord

This is mostly equivalent to calling:

open_molecule_writer(destination, "sdf", writer_args={...}, errors=errors)

along with compression based on the destination filename’s extension.

Parameters:
  • destination (None, a filename string, or a file-like object) – where to write the molecules
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a chemfp.base_toolkit.MoleculeWriter expecting instances of TextRecord
chemfp.text_toolkit.open_sdf_writer_to_string(*, errors: str = 'strict')

Open an SDF file to write instances of TextRecord to an in-memory string

This is equivalent to calling:

open_molecule_writer_to_string("sdf", writer_args={...}, errors=errors)

Use write_molecules_to_string() to write compressed output.

Parameters:errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:a chemfp.base_toolkit.MoleculeWriter expecting instances of TextRecord
chemfp.text_toolkit.parse_smiles(content: Union[str, bytes], *, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = 'to-eol', has_header: bool = False, cxsmiles: bool = True, errors: str = 'strict')

Parse a SMILES string and its id using the text toolkit

This is equivalent to calling:

parse_molecule(content, "smi", reader_args={...}, errors=errors)
Parameters:
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: "to-eol")) – The separator between the SMILES and the id
  • has_header (Boolean (default: False)) – If true, treat the first line of the SMILES file as a header
  • cxsmiles (Boolean (default: True)) – If true, look for ChemAxon CXSMILES extensions after the SMILES string
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a TextRecord instance object
chemfp.text_toolkit.create_smiles(mol: Any, *, id: Optional[str, None] = None, delimiter: Optional[Literal[to_eol, space, tab, comma, whitespace, native, , ], None] = None, cxsmiles: bool = False, errors: str = 'strict') → Optional[str, None]

Generate a SMILES string and its id from a TextRecord instance

This is equivalent to calling:

create_string(mol, "smi", id=id, writer_args={...}, errors=errors)
Parameters:
  • mol (a TextRecord instance) – a molecule object
  • id (None or a string (default: None)) – an alternate identifier for the output record, if relevant
  • delimiter (One of None, 'to_eol', 'space', 'tab', 'comma', 'whitespace', 'native', or the space or tab characters (default: None)) – The separator between the SMILES and the id
  • cxsmiles (Boolean (default: False)) – If true, include any CXSmiles term
  • errors (one of "strict", "ignore", or "log") – specify how to handle errors
Returns:

a string, or None if errors are ignored