chemfst 0.2.0

Python bindings for ChemFST - a high-performance chemical name search library

ChemFST Python

Python bindings for ChemFST: a high-performance chemical name search library using Finite State Transducers (FSTs).

Features

• Memory-efficient indexing using Finite State Transducers
• Extremely fast prefix searches for autocomplete functionality
• Case-insensitive substring searches for finding chemical names
• Memory-mapped file access for optimal performance
• Native Rust implementation with Python bindings
• Comprehensive logging integrated with Python's logging system

Installation

pip install chemfst

Requires Python 3.11 or higher.

Quick Start

from chemfst import ChemicalFST, build_fst
import logging

# Optional: Configure logging to see operation details
logging.basicConfig(level=logging.INFO, format='%(asctime)s [%(name)s] %(levelname)s: %(message)s')

# Build an FST index from chemical names (one name per line)
build_fst("data/chemical_names.txt", "data/chemical_names.fst")

# Load the FST for searching
fst = ChemicalFST("data/chemical_names.fst")

# Prefix search (autocomplete)
matches = fst.prefix_search("acet", max_results=10)
print(f"Chemicals starting with 'acet': {matches}")

# Substring search
matches = fst.substring_search("benz", max_results=10)
print(f"Chemicals containing 'benz': {matches}")

# Preload for better performance
count = fst.preload()
print(f"Preloaded {count} entries")

API Reference

build_fst(input_path, output_path)

Create an FST index from a text file containing chemical names (one per line).

ChemicalFST(fst_path)

Initialize a chemical name search engine from an FST file.

Methods:

• prefix_search(prefix, max_results=100) - Find names starting with prefix
• substring_search(substring, max_results=100) - Find names containing substring
• preload() - Load all data into memory for faster searches

Logging

ChemFST integrates with Python's standard logging module to provide detailed operation insights.

Basic Logging Setup

import logging
import chemfst

logging.basicConfig(level=logging.INFO)
# ChemFST operations will now generate log messages

Log Levels

• ERROR: File errors, operation failures
• INFO: Operation summaries, result counts, timing
• DEBUG: Detailed parameters, internal operations

Advanced Logging

# DEBUG level for development
logging.getLogger('chemfst').setLevel(logging.DEBUG)

# Custom formatting
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s [%(name)s] %(levelname)s: %(message)s',
    filename='chemfst.log'
)

Example Log Output

2024-01-15 10:30:15 [chemfst] INFO: Building FST from input file: data/chemicals.txt
2024-01-15 10:30:15 [chemfst] INFO: Read 50000 chemical names from input file
2024-01-15 10:30:16 [chemfst] INFO: Successfully built FST with 50000 entries
2024-01-15 10:30:20 [chemfst] INFO: Prefix search for 'acet' found 3 results (checked 3 entries)

Performance

• Fast loading: Memory-mapped FST files, no full loading required
• Low memory usage: Compact FST representation
• Quick searches: Typically < 1ms for prefix searches
• Efficient substring searches: Faster than regex or database lookups

Performance logging available at DEBUG level for optimization.

Input Format

Chemical names file (one per line):

acetone
benzene
methanol
ethanol

Development

Building from Source

git clone https://github.com/username/ChemFST
cd ChemFST/chemfst-py
pip install maturin
maturin develop

Running Tests

python -m pytest python/tests/ -v

Examples

See python/examples/ for complete usage examples including logging configuration.

License

MIT