ChemQL
The Python chemistry query language. Query chemistry, automate calculations, and build reusable programs, from an interactive prompt, from script files, or from Python.
| Distribution name | chemql-python |
| Import / CLI name | chemql |
| Current version | 1.6.6 |
| Python | 3.12+ |
| Editor | CodecQL, a terminal editor for .cql files, bundled (chemql edit) |
search elements number > 10 and number < 20 return name symbol
search molecules molecular_weight < 50 sort molecular_weight limit 10
search reactions reactants has "O2" and products has "H2O"
balance H2 + O2 -> H2O
Contents
- Features
- Installation
- Quick start
- Querying data
- Chemistry tools
- The language
- Standard library and packages
- Python API
- Command-line reference
- Configuration and environment
- Data sources
- Safety
- CodecQL editor
Features
- SQL-like queries over three bundled datasets: periodic-table elements, molecules and reactions, with comparison operators, wildcard and regex matching,
and/or/not, grouping, sorting, limiting, counting, projection and set operations. - Online lookups when the bundled data has no answer: PubChem, ChemSpider (with an API key) and NIST WebBook for molecules; Chempirical and Rhea for reactions.
- Equation balancing (
balance H2 + O2 -> H2O) with exact rational arithmetic, and reaction lookup under a given temperature, pressure and set of catalysts. - A complete scripting language: variables, user-defined functions, macros and definitions,
if/for/while, structured error handling (risk/fix/cleanup), enums, structs, records, namespaces with public/private members. - Python everywhere: embed Python expressions in
[ ... ], multi-line Python in[[[ ... ]]], and queries inside Python with{{ ... }}. - Shell integration: run system commands from backticks or fenced blocks in a persistent shell session.
- Built-in functions and a standard library (
math,text,datetime,json,random, ...). - A package manager and registry:
chemql install,chemql init,chemql build,chemql upload. - A Python API (
execute_query_text, a fluentsearch(...)builder, and plain data classes). - An interactive prompt with syntax highlighting, context-aware completion and automatic multi-line block detection.
Installation
pip install chemql-python
chemql --version
Requirements
| Requirement | Notes |
|---|---|
| Python 3.12 or newer | The source uses PEP 701 f-string syntax. |
prompt_toolkit 3.x |
Interactive prompt. Use a recent 3.0 release. |
rich (optional) |
Renders Markdown help for installed packages. |
colorama (optional, Windows) |
ANSI colour support in CodecQL; falls back to enabling virtual-terminal mode directly. |
Upgrading
chemql --upgrade # latest release
chemql --upgrade 1.6.6 # a specific version
chemql --upgrade --force # force a reinstall, overriding system-package protections
Quick start
chemql # interactive prompt
chemql -c 'search elements symbol = "O"' # run one command
chemql -f script.cql # run a file
chemql -f script.cql -o out.txt # write output to a file (ANSI stripped)
echo 'findel "He"' | chemql # piped input is executed as a script
At the prompt, type help (or ?) for the full reference, help{function} for details on a built-in, and exit (or Ctrl+C) to leave. Blocks such as func ... endfunc, if ... endif and [[[ ... ]]] are detected automatically: pressing Enter inserts a new line until the block is closed.
>>> findel "Fe" return name number
>>> let h = {{ search elements symbol = "H" }}
>>> [h.atomic_mass]
>>> balance N2 + H2 <-> NH3
Comments use
//for a line and/// ... ///for a block. Several commands can share a line, separated by;. A trailing\continues a command on the next line.
Querying data
Sources
| Source | Contents | Fields |
|---|---|---|
elements |
The periodic table | name symbol number atomic_mass category phase period group block density melt boil molar_heat appearance electron_configuration electron_configuration_semantic electronegativity_pauling electron_affinity ionization_energies shells discovered_by named_by summary source image bohr_model_image bohr_model_3d spectral_img xpos ypos wxpos wypos |
molecules |
Common molecules with bonding data | name formula molecular_weight elements iupac_name smiles cid state melting_point boiling_point density bonds total_bond_energy |
reactions |
Stored reactions | id name equation reaction_type reversible reactants products conditions notes source |
source molecules // make molecules the default source
list all // list the fields of the current source (or the sources if none is set)
search molecular_weight < 20
Anatomy of a query
search [first|last|all] [SOURCE] CONDITIONS [sort FIELD [asc|desc]] [limit N] [count] [return FIELD ...]
search elements symbol = "Fe" return name symbol number
search molecules molecular_weight < 20 sort molecular_weight asc limit 5
search reactions reversible = true return name equation source
search first molecules name like "*acid" sort molecular_weight desc
search elements number > 100 count
- With no
first/last, a single match returns the object itself and several matches return a list. No match printsNo matching item. returnprojects fields after filtering, sorting and limiting. One field gives a list; several give a table.countmust be the last operation and cannot be combined withfirst,lastorreturn.- A query may begin directly with an operation to act on the whole source:
search molecules count.
Operators
| Operator | Meaning |
|---|---|
= != > < >= <= |
Comparison. Numeric and boolean values are converted from the query text (reversible = true). |
like |
Wildcard match, case-insensitive, against the entire value. |
like! |
Wildcard match, case-sensitive. |
likep |
Regular-expression search (re.search) on string fields. |
has |
Containment for lists and dictionaries. Molecule identifiers match exactly (O2 does not match CO2); other strings match as case-insensitive substrings. |
not |
Negation: name not like "H*", or not (number > 10). |
and or |
Combine conditions. and binds tighter than or; use parentheses to group. |
union intersection |
Combine whole queries, evaluated left to right. |
search elements category = "noble gas" and (period = 2 or period = 3)
search reactions reactants has "O2" and products has "H2O"
search elements symbol likep "^(He|Ne|Ar)$" return name
search molecules name like "*water*" union search molecules name like "*acid*"
like wildcards
| Wildcard | Matches |
|---|---|
* |
Any run of characters |
_ |
Any single character |
# |
One digit |
? |
One letter |
% |
Zero or more digits |
& |
Zero or more letters |
\ |
Escapes the next character |
Shortcuts
findel "He" // name or symbol
findel "Fe" return name number
findmol "Water" // name or formula; bundled data first, then online sources
findmol "aspirin" return formula molecular_weight
findre "Haber process" // name, id or equation; then Chempirical and Rhea (RHEA:nnnnn ids work)
findre "Haber" return name equation // project fields, as with search
Using variables in queries
define MAX 9
search elements number <= @MAX // literal text substitution
let limit_value = 20
search elements number < [limit_value] // Python expression evaluated inside the query
Chemistry tools
Balancing equations
balance H2 + O2 -> H2O
balance N2 + H2 <-> NH3 // <-> marks the reaction as reversible
The result is a reaction with integer coefficients. When a reversibility flag is set, the equation also shows an estimated ΔH computed from the bundled bond energies. Formulas may contain nested parentheses, e.g. Fe2(SO4)3. Equations without a unique positive solution are rejected with an error.
Finding a stored reaction
Reactions in the bundled dataset are only matched when their conditions match the current state.
set temperature 150C // C, F or K; or `standard` (273.15 K) / `room` (298.15 K)
set pressure 1atm // Pa kPa MPa hPa mbar bar atm torr mmHg psi kpsi N/m^2; or standard / room
set catalysts iron zinc // replace the catalyst list; `set catalysts` clears it
add catalyst "Iron"
remove catalyst "Zinc"
conditions // show the current state
react N2 3H2 // coefficients can be written as 3H2 or 3 H2
A reaction matches when its reactants are exactly those given and its conditions are met: if it specifies a temperature, the current one must be within 5 K; if it specifies a pressure, within 5 %; and every catalyst it requires must be in the catalyst list. Reversible reactions can also be matched from their products. One product returns a molecule; several return a table.
The language
Variables, Python and embedded queries
let answer = 42
[answer * 2] // evaluate a Python expression
[x = 10] // run a Python statement
let h = {{ search elements symbol = "H" }} // a query as a value
[h.atomic_mass]
variables // list variables
unset answer
[[[
for n in range(3):
print(n)
]]]
Variables, Python names and query results all live in one shared session. The value of the last expression is available as _.
Definitions and macros
define MAX 9 // literal text replacement, also inside strings
search elements number <= @MAX
definitions // list definitions
remove definition MAX
Definitions are expanded in source order, once, and are not retroactive. Macros generate source text:
define element_by_number{}
search elements number = \1
enddefine
@element_by_number{8}
macros
Functions and built-ins
func square
return [\1 * \1]
endfunc
square{5} // 25
let total = int{1} + square{3} // calls compose with Python expressions
Function calls use braces and commas: name{arg1, arg2}, and arguments are available in the body as \1, \2, and so on. Quote text that contains spaces. Keep comments outside function bodies. static func and func Type.method (with this) define static and instance methods on structs; operator methods such as func Type.__add__ enable overloading. User-defined functions take precedence over built-ins with the same name.
| Category | Built-ins |
|---|---|
| Numbers | abs round min max sum |
| Core | len type |
| Conversion | str int float bool |
| Strings | upper lower contains replace split join |
| Collections | first last unique sort reversed |
| Files | read_text read_lines write_text file_exists list_files |
| Data files | read_csv write_csv read_json write_json |
| Chemistry | element count_atoms molar_mass empirical_formula |
| Help | help |
molar_mass{"H2SO4"}
count_atoms{"H2SO4", "O"} // 4
empirical_formula{"C6H12O6"} // CH2O
element{"Na", "atomic_mass"}
let rows = read_csv{"data.csv"}
write_json{"out.json", rows}
help{read_csv} // detailed help for any built-in
Control flow
for i in range(5)
let value = i
endfor
if answer > 10
[print("big")]
elif answer > 5
[print("medium")]
else
[print("small")]
endif
[x = 0]
while x < 3
[x += 1]
endwhile
break, continue and skip control loops. The Python-style bracket form [for ...] ... [endblock] is also accepted.
Error handling
risk
signal "Something went wrong" // raise a recoverable error
fix
let handled = error // `error` holds the error type, or None after success
cleanup
[print("always runs")]
endrisk
warn "careful" // prints a warning; the latest is stored in `warnings`
Inside a risk block, errors are raised rather than printed, so fix can handle them. --suppress-warnings silences warn output. Built-in functions raise TooFewArguments, TooManyArguments, InvalidArgumentType, InvalidArgumentValue, FileReadError and FileWriteError; help{errors} lists all error signals.
Enums, structs and records
enum Levels
LOW = 50
MEDIUM // omitted values are generated automatically
HIGH
endenum
struct Animal
name! // required field (also written `required name`)
sound = "..." // field with a default
endstruct
struct Dog from Animal // structs inherit from structs, records or Python classes
color!
endstruct
let rex = Dog{name = "Rex", color = "brown"}
func Dog.describe
return ["Dog named " + this.name]
endfunc
[rex.describe()]
record Point // immutable; supports arithmetic between records
x
y = 0 // fields with defaults must come last
endrecord
let p = Point{1, 2}
[p + p]
Records inherit only from records. Structs cannot inherit from enums.
Namespaces and visibility
Members are private by default; mark them public to expose them.
namespace Geometry
public let PI = 3.14159
public func area
return [\1 * \2]
endfunc
private let secret = 42
endnamespace
Geometry::area{3, 4}
Geometry::PI
Calling a private member from outside raises PermissionError. Namespaces nest.
Shell commands
`ls -la` // one command
```bash
cd /tmp
echo "state persists between commands"
```
The shell is persistent: cd and shell variables carry over. ChemQL uses bash on Linux and macOS and PowerShell on Windows. Output is streamed live, and interactive programs that read the keyboard work.
History
dump session.txt // queries and results
dump good queries ok.cql // only successful queries
dump bad results errors.txt // only the output of failed commands
Syntax: dump [all|good|bad] [queries|results] FILE.
Other commands
| Command | Purpose |
|---|---|
view |
Open the interactive periodic table in your browser |
clear |
Clear the terminal |
version |
Print the version |
help, ?, help{topic} |
Help; topics include syntax, errors, files, chemistry, stdlib, built-in names, modules and installed packages |
exit |
Quit |
Standard library and packages
Loading modules
load math // then call math::function{...}
math::sqrt{81} // 9.0
load math::statistics
math::statistics::mean{2, 4, 6} // 4
load text as t // alias
t::upper{"hello"}
load sqrt from math // import one public member
Qualified calls require an explicit load. Use help{stdlib} to list modules and help{math::sqrt} for individual functions.
| Module | Highlights |
|---|---|
math |
PI E TAU, sqrt cbrt floor ceil factorial gcd lcm hypot pow, trigonometry, log log10 log2 exp, isfinite isinf isnan isclose |
math::statistics |
mean median mode multimode quantiles variance stdev pvariance pstdev harmonic_mean geometric_mean |
text |
case conversion, strip, startswith, endswith, find, count, isalpha and friends, regex_search regex_findall regex_replace |
collections |
unique flatten zip pairwise frequencies group_count product sorted reversed |
datetime |
today now utcnow date time timestamp from_timestamp weekday date_add_days date_difference_days |
json |
dumps dumps_pretty loads json_type |
random |
seed random randint randrange choice sample shuffle uniform |
decimal |
create add subtract multiply divide quantize to_string |
fractions |
create add subtract multiply divide numerator denominator to_float |
pathlib |
name stem suffix parent join exists is_file is_dir read_text write_text |
Package manager
chemql search "periodic" # search the registry
chemql info NAME # registry metadata
chemql install NAME # latest release
chemql install NAME --version 1.2.0
chemql upgrade NAME # re-download, replacing the installed copy
chemql list # installed packages
chemql uninstall NAME
Inside the interactive prompt, use install PACKAGE [--version VERSION]. Packages install to ~/.chemql/packages/NAME/VERSION and are then loaded with load NAME. When resolving load a::b, ChemQL looks for a/b.cql in the current directory, then in installed packages (newest version first, honouring the manifest's main entry), then in the bundled stdlib. Releases that the registry has not marked as safe are refused.
Creating a package
chemql init mypkg # scaffolds cqlpackage.json, mypkg.cql and README.md
cd mypkg
chemql build # dist/mypkg-1.0.0.tar.gz
chemql upload # to the registry (10 MB limit)
cqlpackage.json (a cqlpackage.toml with the same keys is also accepted):
{
"name": "mypkg",
"author": "",
"version": "1.0.0",
"description": "A ChemQL package named mypkg.",
"help": "README.md",
"main": "mypkg.cql",
"submodules": [],
"buildsystem": "chemql-build",
"chemql-dependencies": [],
"python-dependencies": [],
"readme": "README.md",
"license": "MIT",
"source-code": {},
"help-individual": {}
}
// mypkg.cql
public func hello
return "Hello from mypkg!"
endfunc
load mypkg
mypkg::hello{}
help{mypkg} // renders the manifest's `help` Markdown file
help{mypkg::hello} // uses the `help-individual` entry for `hello`
A build needs a manifest and at least one .cql file. Version control folders, virtual environments and dist are excluded from the archive.
Python API
from chemql import execute_query_text
oxygen = execute_query_text('search elements symbol = "O"')
print(oxygen.name, oxygen.atomic_mass)
execute_query_text(text) returns the raw result: an Element, Molecule or Reaction, a list, a table (ReturnTable), a count or a string. Query-level mistakes (a typo in a key, a bad operator) are usually returned as a formatted Error: ... string rather than raised.
execute_query(text) is a typed variant: it returns str, Molecule, Element, Reaction or Unknown, and wraps anything else (lists, tables, counts) in Unknown, whose .value holds the raw result.
Fluent query builder
from chemql import search, union, intersection
noble = search("elements").category.condition(like="noble gas").return_("name", "symbol")
print(noble.execute())
light = search("elements").atomic_mass.condition(lt=10)
metals = search("elements").category.condition(like="*metal")
print((light & metals).execute()) # intersection; `|` is union
print(union(light, metals).execute())
condition() accepts exactly one keyword: eq ne lt lte gt gte like likep has.
Lookups and chemistry helpers
from chemql import (
ELEMENTS, MOLECULES, REACTIONS,
find_molecule, find_reaction, search_reactions, balance_stoichiometry,
)
find_molecule("water") # bundled data only; matches name, formula or IUPAC name
find_reaction("Haber", external=False) # local data only; external=True also tries Chempirical and Rhea
search_reactions(reversible=True, name="acid") # strings are case-insensitive substrings; other values are compared exactly
reaction = balance_stoichiometry("H2 + O2", "H2O")
print(reaction)
balance_stoichiometry(reactants, products, reversible=None) accepts "A + B" strings or iterables of formulas and raises ValueError if the reaction cannot be balanced uniquely.
Exported names (chemql.__all__): Element, Molecule, Reaction, MOLECULES, REACTIONS, find_molecule, find_reaction, search_reactions, balance_stoichiometry, execute_query, execute_query_text, ChemQLQuery, search, union, intersection, ReturnTable, Unknown, __version__, and the exceptions ChemQLError, ChemQLBuiltinError, TooFewArguments, TooManyArguments, InvalidArgumentType, InvalidArgumentValue, FileReadError, FileWriteError. (ELEMENTS is importable but not listed in __all__.)
Command-line reference
chemql [options]
chemql SUBCOMMAND ...
chemql edit [codecql options] [FILE]
| Option | Description |
|---|---|
| (none) | Start the interactive prompt (or run piped input) |
-c, --command CODE |
Execute one command |
-f, --file FILE |
Execute a file |
-o, --output FILE |
Write -c/-f output to a file, without ANSI sequences |
--no-ansi |
Strip ANSI styling from output |
--suppress-warnings |
Hide warn messages |
-v, --version |
Print the version |
--upgrade [VERSION] |
Upgrade ChemQL with pip |
--force, --dangerously |
With --upgrade: force a reinstall, overriding system-package protections |
| Subcommand | Description |
|---|---|
install NAME [--version V] |
Install a package from the registry |
upgrade NAME [--version V] |
Re-download a package, replacing the installed copy |
search QUERY |
Search the registry |
info NAME |
Show registry metadata as JSON |
list |
List installed packages |
uninstall NAME |
Remove an installed package |
init [NAME] [-d DIR] |
Scaffold a package project |
build |
Build dist/NAME-VERSION.tar.gz from the current directory |
upload |
Upload the built archive to the registry |
edit [FILE] |
Open the CodecQL editor |
Subcommands cannot be combined with -c, -f or -o.
Configuration and environment
| Variable | Purpose | Default |
|---|---|---|
CHEMQL_PACKAGE_DIR |
Where packages are installed and searched | ~/.chemql/packages |
CHEMQL_INSTALLED_FILE |
Installed-package record | ~/.chemql/installed.json |
CHEMSPIDER_API_KEY |
Enables ChemSpider as a molecule source | (unset) |
Data sources
ChemQL always consults its bundled data first, so offline queries over the bundled data keep working.
| Data | Source |
|---|---|
| Elements | data/PeriodicTableJSON.json |
| Molecules, bonds | data/Molecules.json, data/MoleculeBonds.json |
| Bond energies (used for ΔH estimates) | data/BondEnergies.json |
| Reactions | data/Reactions.json |
| Molecules, online fallback | PubChem (PUG REST and PUG-View), ChemSpider, NIST WebBook |
| Reactions, online fallback | Chempirical, Rhea |
The package also bundles html/periodic_table.html (used by view) and a stdlib/ directory of .cql modules.
Safety
ChemQL runs real code with your permissions: [ ... ] and [[[ ... ]]] execute Python, backticks and fenced blocks execute shell commands, and load runs the source of a package. Only run scripts and install packages you trust. Online lookups need network access and send your query text to the services listed above.
CodecQL editor
CodecQL is a small terminal editor built for ChemQL, with syntax highlighting, inline suggestions and one-key execution.
chemql edit script.cql
See CODECQL.md for key bindings, configuration and the suggestion-rule format.
License
MIT. See LICENSE
Metadata
Release files for chemql-python 1.6.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chemql_python-1.6.6.tar.gz | 318.1 kB | Without provenance | Details for chemql_python-1.6.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chemql_python-1.6.6-py3-none-any.whl | Python 3 | none | any | Details for chemql_python-1.6.6-py3-none-any.whl |
Total release size: 633.8 kB
Release files / chemql_python-1.6.6.tar.gz
| Download URL | chemql_python-1.6.6.tar.gz |
|---|---|
| Size | 318.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7927ce62b6383deef9547cdb7c0e45c0a59f45747e773b64554c226b599dfd32
|
|
BLAKE2b-256 checksum How to use checksums |
0d1a8a0d51d50f4d16b709a3b9fddb51f67b8332e68e3229e016b1873a59eb6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.9
|
Release files / chemql_python-1.6.6-py3-none-any.whl
| Download URL | chemql_python-1.6.6-py3-none-any.whl |
|---|---|
| Size | 315.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c1df1cc1712560f77d85fb2f6c981cbb40ffae8d1e25356fd00491a0cd14639d
|
|
BLAKE2b-256 checksum How to use checksums |
83f9055773176f6b0ce44c7972ebd839be355f600c31616ba82f3d0a2d0cdac7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.9
|
Security for chemql-python 1.6.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.