chemql-python 0.2.2__py3-none-any.whl → 1.0.1__py3-none-any.whl

chemql/__init__.py

@@ -5,9 +5,13 @@ import re
 import ast
 import argparse
 import time
+import subprocess
+import sys
 from pathlib import Path
 from prompt_toolkit import PromptSession
 from prompt_toolkit.lexers import Lexer
+import atexit
+import uuid
 from prompt_toolkit.styles import Style
 from prompt_toolkit.completion import Completer, Completion
 import urllib.parse
@@ -28,9 +32,91 @@ __all__ = [
     "balance_stoichiometry",
     "execute_query",
     "execute_query_text",
+    "ChemQLQuery",
+    "search",
+    "union",
+    "intersection",
 ]
 
 
+
+_shell_process = None
+
+
+def get_shell():
+    """Start Bash once and reuse the same session."""
+    global _shell_process
+
+    if _shell_process is None or _shell_process.poll() is not None:
+        _shell_process = subprocess.Popen(
+            ["bash", "--noprofile", "--norc"],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+
+    return _shell_process
+
+
+def run_shell_command(command):
+    """Run a command in the persistent Bash session."""
+    shell = get_shell()
+    marker = f"__CHEMQL_END_{uuid.uuid4().hex}__"
+
+    try:
+        shell.stdin.write(command + "\n") #type:ignore
+        shell.stdin.write( #type:ignore
+            f"printf '\\n%s:%s\\n' '{marker}' \"$?\"\n"
+        )
+        shell.stdin.flush() #type:ignore
+
+        output = []
+        exit_code = None
+
+        while True:
+            line = shell.stdout.readline() #type:ignore
+
+            if not line:
+                break
+
+            line = line.rstrip("\n")
+
+            if line.startswith(marker + ":"):
+                exit_code = int(line[len(marker) + 1:])
+                break
+
+            output.append(line)
+
+        result = "\n".join(output)
+
+        if exit_code is None:
+            return result or "Shell session terminated."
+
+        if exit_code != 0 and not result:
+            return f"Command exited with status {exit_code}"
+
+        return result
+
+    except (BrokenPipeError, OSError) as exc:
+        return f"Shell error: {exc}"
+
+
+def close_shell():
+    """Clean up the persistent shell on exit."""
+    global _shell_process
+
+    if _shell_process is not None:
+        if _shell_process.poll() is None:
+            _shell_process.terminate()
+            _shell_process.wait(timeout=2)
+
+        _shell_process = None
+
+
+atexit.register(close_shell)
+
 class Unknown:
     """Represents a Chemql query result that cannot be resolved to a known object."""
 
@@ -112,7 +198,7 @@ with (DATA_DIR / "MoleculeBonds.json").open("r", encoding="utf-8") as f:
 with (DATA_DIR / "BondEnergies.json").open("r", encoding="utf-8") as f:
     bondEnergies = json.load(f)
 
-operators = {"has", "like", "like!", "=", ">", "<", ">=", "<="}
+operators = {"has", "like", "like!", "likep", "=", "!=", ">", "<", ">=", "<="}
 
 queryOperations = {"sort", "limit", "count"}
 
@@ -1252,7 +1338,7 @@ def apply_query_operations(results, tokens, keys, positions=None):
     return results
 
 
-functionMap = {"=": "__eq__", ">": "__gt__", "<": "__lt__", ">=": "__ge__", "<=": "__le__"}
+functionMap = {"=": "__eq__", "!=": "__ne__", ">": "__gt__", "<": "__lt__", ">=": "__ge__", "<=": "__le__"}
 
 
 def convert_value(value, sample):
@@ -1296,14 +1382,35 @@ def parse_condition(tokens, index, source, keys, positions=None):
 
     key = tokens[index]
     operator = tokens[index + 1]
-    value = tokens[index + 2]
+    negated = operator.casefold() == "not"
+    if negated:
+        if index + 3 >= len(tokens):
+            raise ChemQLError("Expected an operator and value after `not`", *(error_position(positions, index + 1) if positions else (None, 1)))  # type: ignore
+        operator = tokens[index + 2]
+        value = tokens[index + 3]
+        consumed = index + 4
+    else:
+        value = tokens[index + 2]
+        consumed = index + 3
 
     if key not in keys:
         pos, length = error_position(positions, index) if positions else (None, 1)
         raise ChemQLError(f"There is no key `{key}`", pos, length)
 
-    if operator == "like" or operator == "like!":
+    if operator in {"like", "like!", "likep"}:
         pattern = value
+        if operator == "likep":
+            try:
+                compiled_pattern = re.compile(pattern)
+            except re.error as exc:
+                pos, length = error_position(positions, index + 2) if positions else (None, 1)
+                raise ChemQLError(f"Invalid regex: {exc}", pos, length) from exc
+
+            def regex_condition(item):
+                actual = getattr(item, key)
+                return isinstance(actual, str) and compiled_pattern.search(actual) is not None
+
+            return (lambda item, fn=regex_condition: not fn(item)) if negated else regex_condition, consumed
         case_sensitive = operator == "like!"
 
         def like_condition(item):
@@ -1318,7 +1425,7 @@ def parse_condition(tokens, index, source, keys, positions=None):
                 case_sensitive
             )
 
-        return like_condition, index + 3
+        return (lambda item, fn=like_condition: not fn(item)) if negated else like_condition, consumed
 
     if operator == "has":
         def has_condition(item):
@@ -1329,7 +1436,7 @@ def parse_condition(tokens, index, source, keys, positions=None):
             except TypeError:
                 return False
 
-        return has_condition, index + 3
+        return (lambda item, fn=has_condition: not fn(item)) if negated else has_condition, consumed
 
     if operator not in functionMap:
         pos, length = error_position(positions, index + 1) if positions else (None, 1)
@@ -1354,12 +1461,16 @@ def parse_condition(tokens, index, source, keys, positions=None):
         except (TypeError, AttributeError):
             return False
 
-    return comparison_condition, index + 3
+    return (lambda item, fn=comparison_condition: not fn(item)) if negated else comparison_condition, consumed
 
 def parse_primary(tokens, index, source, keys, positions=None):
     if index >= len(tokens):
         raise ChemQLError("Expected condition", *(error_position(positions, index) if positions else (None, 1)))#type:ignore
 
+    if tokens[index].casefold() == "not":
+        expression, next_index = parse_primary(tokens, index + 1, source, keys, positions)
+        return (lambda item, fn=expression: not fn(item)), next_index
+
     if tokens[index] == "(":
         expression, index = parse_or(
             tokens,
@@ -1582,9 +1693,107 @@ def interpolate_python_queries(code):
     python_globals.update(query_values)
     return "".join(rewritten)
 
+def _space_query_operators(text):
+    """Separate comparison operators and parentheses outside quoted strings."""
+    out, quote, escaped = [], None, False
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if quote:
+            out.append(ch)
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch in ("'", '"'):
+            quote = ch
+            out.append(ch)
+            i += 1
+            continue
+        if ch in "()":
+            out.extend((" ", ch, " "))
+            i += 1
+            continue
+        if ch in "<>!=" and i + 1 < len(text) and text[i + 1] == "=":
+            out.extend((" ", ch + "=", " "))
+            i += 2
+            continue
+        if ch in "<>!=":
+            out.extend((" ", ch, " "))
+            i += 1
+            continue
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def _split_set_operations(text):
+    """Split top-level union/intersection outside quotes and parentheses, left-to-right."""
+    parts, ops, start, depth = [], [], 0, 0
+    quote, escaped = None, False
+    words = re.finditer(r"\b(union|intersection)\b", text, re.IGNORECASE)
+    for match in words:
+        i = match.start()
+        quote = None
+        escaped = False
+        depth = 0
+        j = 0
+        while j < i:
+            ch = text[j]
+            if quote:
+                if escaped: escaped = False
+                elif ch == "\\": escaped = True
+                elif ch == quote: quote = None
+            elif ch in ("'", '"'): quote = ch
+            elif ch == "(": depth += 1
+            elif ch == ")": depth -= 1
+            j += 1
+        if quote is None and depth == 0:
+            parts.append(text[start:i].strip())
+            ops.append(match.group(1).casefold())
+            start = match.end()
+    if not ops:
+        return None
+    parts.append(text[start:].strip())
+    if any(not part for part in parts):
+        raise ChemQLError("Missing query around union/intersection")
+    return parts, ops
+
+
+def _as_result_list(result):
+    if result is None or result == "No matching item":
+        return []
+    return result if isinstance(result, list) else [result]
+
+
 def execute_query_text(text):
     """Execute plain query-language text."""
-    text = interpolate_query(text.strip())
+    text = text.strip()
+    set_expression = _split_set_operations(text)
+    if set_expression:
+        parts, ops = set_expression
+        result = _as_result_list(execute_query_text(parts[0]))
+        for operator, part in zip(ops, parts[1:]):
+            right = _as_result_list(execute_query_text(part))
+            def identity(item):
+                if hasattr(item, "id"): return ("id", getattr(item, "id"))
+                if hasattr(item, "number"): return ("number", getattr(item, "number"))
+                if hasattr(item, "cid") and getattr(item, "cid") is not None: return ("cid", getattr(item, "cid"))
+                return (type(item).__name__, repr(item))
+            right_map = {identity(item): item for item in right}
+            if operator == "union":
+                seen = {identity(item) for item in result}
+                result.extend(item for item in right if identity(item) not in seen and not seen.add(identity(item)))
+            else:
+                result = [item for item in result if identity(item) in right_map]
+        return result
+
+    text = interpolate_query(text)
+    text = _space_query_operators(text)
     positions = token_positions(text)
 
     try:
@@ -1968,6 +2177,12 @@ def process_inline(text):
         if not stripped[end + 2:].strip():
             return execute_query_block(stripped[2:end].strip())
 
+    # Backtick-wrapped commands use the persistent Bash session.
+    if len(stripped) >= 2 and stripped.startswith("`") and stripped.endswith("`"):
+        command = stripped[1:-1]
+        return run_shell_command(command)
+
+
     # Everything else is query language.
     return execute_query_text(stripped)
 
@@ -2099,12 +2314,13 @@ def parse_temperature_setting(value):
     if normalized == "room":
         return 298.15
 
-    match = re.fullmatch(r"([+-]?(?:\d+(?:\.\d*)?|\.\d+))\s*°?\s*([cfk])", normalized)
+    match = re.fullmatch(r"([+-]?(?:\d+(?:\.\d*)?|\.\d+))\s*(?:°\s*)?(celsius|fahrenheit|kelvin|degc|degf|degk|c|f|k)", normalized)
     if not match:
         raise ValueError("Temperature must use C, F, or K, or be `standard` or `room`")
 
     temperature = float(match.group(1))
     unit = match.group(2)
+    unit = {"celsius": "c", "degc": "c", "fahrenheit": "f", "degf": "f", "kelvin": "k", "degk": "k", "K":"k", "C":"c", "F": "f","k":"k", "c":"c", "f": "f"}[unit]
     if unit == "f":
         temperature = (temperature - 32) * 5 / 9 + 273.15
     elif unit == "c":
@@ -2130,14 +2346,16 @@ def parse_pressure_setting(value):
     pressure = float(match.group(1))
     unit = re.sub(r"\s+", "", match.group(2)).replace("²", "^2")
     unit_scales = {
-        "pa": 1.0,
-        "n/m^2": 1.0,
-        "nm^-2": 1.0,
-        "bar": 100000.0,
-        "atm": 101325.0,
+        "pa": 1.0, "pascal": 1.0, "pascals": 1.0,
+        "kpa": 1_000.0, "mpa": 1_000_000.0,
+        "hpa": 100.0, "mbar": 100.0,
+        "n/m^2": 1.0, "n/m2": 1.0, "nm^-2": 1.0, "n·m^-2": 1.0,
+        "bar": 100_000.0, "mbar": 100.0,
+        "atm": 101_325.0, "torr": 101_325.0 / 760, "mmhg": 101_325.0 / 760,
+        "psi": 6894.757293168, "kpsi": 6_894_757.293168,
     }
     if unit not in unit_scales:
-        raise ValueError("Pressure must use Pa, N/m^2, Nm^-2, bar, or atm")
+        raise ValueError("Unsupported pressure unit. Try Pa, kPa, MPa, hPa, bar, atm, torr, mmHg, or psi")
 
     return pressure * unit_scales[unit]
 
@@ -2550,6 +2768,8 @@ def execute(arguments, query_text=None, positions=None):
             )
 
         source, keys = SOURCES[source_name]
+        if i >= len(arguments):
+            return list(source)
         return_attributes = None
 
         if "return" in arguments[i:]:
@@ -2941,6 +3161,18 @@ class ChemqlLexer(Lexer):
 
                     i = end + 2
                     continue
+                
+                if line.startswith("//", i):
+
+                    end = len(line)
+
+                    tokens.append((
+                        "class:comment",
+                        line[i:end]
+                    ))
+
+                    i = end
+                    continue
 
                 if line[i] == "[":
                     end = line.find("]", i + 1)
@@ -2955,6 +3187,20 @@ class ChemqlLexer(Lexer):
 
                     i = end + 1
                     continue
+                
+                if line[i] == "`":
+                    end = line.find("`", i + 1)
+
+                    if end == -1:
+                        end = len(line) - 1
+
+                    tokens.append((
+                        "class:terminalcommand",
+                        line[i:end + 1]
+                    ))
+
+                    i = end + 1
+                    continue
 
                 # Strings
                 if line[i] in "\"'":
@@ -2983,7 +3229,7 @@ class ChemqlLexer(Lexer):
                 # Operators
                 matched_operator = None
 
-                for operator in (">=", "<=", "=", ">", "<"):
+                for operator in ("!=", ">=", "<=", "=", ">", "<"):
                     if line.startswith(operator, i):
                         matched_operator = operator
                         break
@@ -3040,7 +3286,9 @@ class ChemqlLexer(Lexer):
                         "conditions",
                         "view",
                         "help",
-                        "dump"
+                        "dump",
+                        "union",
+                        "intersection",
                     }:
                         style = "class:command"
 
@@ -3058,6 +3306,7 @@ class ChemqlLexer(Lexer):
                         "has",
                         "like",
                         "like!",
+                        "likep",
                         "sort",
                         "limit",
                         "count",
@@ -3152,7 +3401,7 @@ class ChemqlCompleter(Completer):
             if source_name in SOURCES:
                 _, keys = SOURCES[source_name]
                 suggestions = list(keys) + [
-                    "=", ">", "<", ">=", "<=", "like", "like!", "has",
+                    "=", ">", "<", ">=", "<=", "!=", "like", "like!", "likep", "has",
                     "sort", "limit", "count", "asc", "desc", "return",
                 ]
 
@@ -3167,6 +3416,8 @@ class ChemqlCompleter(Completer):
         
 chemql_style = Style.from_dict({
     "command": "ansicyan",
+    "terminalcommand": "ansipurple",
+    "comment": "#545454 bold underline",
     "source": "ansiblue",
     "key": "ansimagenta",
     "operator": "ansiyellow",
@@ -3178,6 +3429,138 @@ chemql_style = Style.from_dict({
 })
 
 
+
+
+class _ChemQLField:
+    """Field selector used by the fluent Python query API."""
+    def __init__(self, query, field):
+        self.query = query
+        self.field = field
+
+    def condition(self, **conditions):
+        operators = {
+            "eq": "=", "ne": "!=", "lt": "<", "lte": "<=",
+            "gt": ">", "gte": ">=", "like": "like", "likep": "likep",
+            "has": "has",
+        }
+        if len(conditions) != 1:
+            raise ValueError("condition() expects exactly one condition, e.g. lt=10")
+        name, value = next(iter(conditions.items()))
+        if name not in operators:
+            raise ValueError(f"Unknown condition {name!r}; use {', '.join(operators)}")
+        rendered = shlex.quote(str(value))
+        return ChemQLQuery(f"{self.query.query} {self.field} {operators[name]} {rendered}")
+
+
+class ChemQLQuery:
+    """Composable ChemQL query. Use .execute() to evaluate it."""
+    def __init__(self, query):
+        self.query = str(query).strip()
+
+    def __getattr__(self, field):
+        if field.startswith("_"):
+            raise AttributeError(field)
+        return _ChemQLField(self, field)
+
+    def return_(self, *attributes):
+        if not attributes:
+            raise ValueError("return_() requires at least one attribute")
+        return ChemQLQuery(f"{self.query} return " + " ".join(attributes))
+
+    def execute(self):
+        return execute_query_text(self.query)
+
+    def __or__(self, other):
+        if not isinstance(other, ChemQLQuery):
+            return NotImplemented
+        return ChemQLQuery(f"{self.query} union {other.query}")
+
+    def __and__(self, other):
+        if not isinstance(other, ChemQLQuery):
+            return NotImplemented
+        return ChemQLQuery(f"{self.query} intersection {other.query}")
+
+    def __str__(self):
+        return f"Query of `{self.query}`"
+
+    def __repr__(self):
+        return str(self)
+
+
+def search(source):
+    """Create a native Python API query, e.g. search('elements')."""
+    source = str(source).strip()
+    if source not in SOURCES:
+        raise ValueError(f"Unknown ChemQL source {source!r}; expected one of {', '.join(SOURCES)}")
+    return ChemQLQuery(f"search {source}")
+
+
+def union(x, y):
+    """Return the left-to-right union of two ChemQLQuery objects."""
+    if not isinstance(x, ChemQLQuery) or not isinstance(y, ChemQLQuery):
+        raise TypeError("union() expects two ChemQLQuery objects")
+    return x | y
+
+
+def intersection(x, y):
+    """Return the intersection of two ChemQLQuery objects."""
+    if not isinstance(x, ChemQLQuery) or not isinstance(y, ChemQLQuery):
+        raise TypeError("intersection() expects two ChemQLQuery objects")
+    return x & y
+
+PACKAGE_NAME = "chemql-python"
+
+def upgrade_package(version=None):
+    """Upgrade ChemQL, optionally to a specific version."""
+
+    if version is not None:
+        # Accept ordinary numeric release versions, optionally with
+        # prerelease or post-release suffixes.
+        if not re.fullmatch(
+            r"\d+(?:\.\d+)*(?:(?:a|b|rc)\d+)?(?:\.post\d+)?(?:\.dev\d+)?",
+            version,
+            re.IGNORECASE,
+        ):
+            print(f"Invalid version: {version}", file=sys.stderr)
+            return 2
+
+        target = f"{PACKAGE_NAME}=={version}"
+        print(f"Installing {target}...")
+        cmd = [
+            sys.executable, "-m", "pip", "install",
+            "--force-reinstall", target,
+        ]
+    else:
+        print(f"Upgrading {PACKAGE_NAME} to the latest version...")
+        cmd = [
+            sys.executable, "-m", "pip", "install",
+            "--upgrade", PACKAGE_NAME,
+        ]
+
+    try:
+        result = subprocess.run(cmd, check=False)
+        if result.returncode != 0:
+            print(
+                f"Installation failed (exit code {result.returncode}).",
+                file=sys.stderr,
+            )
+            return result.returncode
+
+    except KeyboardInterrupt:
+        print("\nUpgrade cancelled.", file=sys.stderr)
+        return 130
+    except OSError as exc:
+        print(f"Could not run pip: {exc}", file=sys.stderr)
+        return 1
+
+    print("ChemQL installation completed.")
+    return 0
+
+
+ChemQLQuery.__name__ = "ChemQLQuery"
+ChemQLQuery.__qualname__ = "ChemQLQuery"
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Chemql query and chemistry language"
@@ -3199,19 +3582,40 @@ def main():
         "-v",
         "--version",
         action="version",
-        version="0.2.2",
+        version="1.0.1",
     )
 
+
+    parser.add_argument(
+        "--upgrade",
+        nargs="?",
+        const="latest",
+        default=None,
+        metavar="VERSION",
+        help="Upgrade ChemQL, optionally to a specific version.",
+    )
+
+
     args = parser.parse_args()
 
-    if args.command:
-        process_lines(args.command.splitlines())
+    if args.upgrade is not None:
+        version_target = (
+            None if args.upgrade == "latest" else args.upgrade
+        )
+        sys.exit(upgrade_package(version_target))
+
 
     elif args.file:
         with open(args.file) as f:
             code = f.read()
         process_lines(code.splitlines())
 
+    elif not sys.stdin.isatty():
+        piped = sys.stdin.read()
+        if piped.strip():
+            process_lines([piped.strip()])
+        else:
+            run_interactive()
     else:
         run_interactive()
 

chemql_python-1.0.1.dist-info/METADATA

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: chemql-python
+Version: 1.0.1
+Summary: A chemistry-focused query language and REPL
+Author-email: Mohammad Rakibul Islam <rakibulofficial1017@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prompt_toolkit>=3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# ChemQL
+
+**ChemQL** is a chemistry-focused query language for searching and
+working with chemical data from Python or an interactive terminal. It
+provides a compact way to query elements, molecules, and chemical
+reactions using filters, logical conditions, sorting, and result
+projections.
+
+> Package: `chemql-python`\
+> Python import: `chemql`
+
+## Features
+
+-   Query element, molecule, and reaction datasets.
+-   Filter records with comparisons and logical conditions.
+-   Match text using wildcard patterns with `like` and case-sensitive
+    `like!`.
+-   Use `and`, `or`, `not`, and parentheses to combine conditions.
+-   Use `likep` for Python regular-expression matching.
+-   Combine list results with `union` and `intersection`.
+-   Sort, limit, count, and project results with `return`.
+-   Look up elements, molecules, and reactions using `findel`,
+    `findmol`, and `findre`.
+-   Balance chemical equations.
+-   Set reaction conditions, including temperature, pressure, and
+    catalysts.
+-   Use Python expressions and control blocks alongside ChemQL queries.
+-   Use ChemQL from the command line or through its Python API.
+
+## Installation
+
+Install the Python package from PyPI:
+
+``` bash
+pip install chemql-python
+```
+
+## Upgrading the package or switching versions
+
+If your chemql-python version is >=1.0.1, you can simply run
+```bash
+chemql --upgrade
+``` 
+Or to switch versions to for example 0.2.2
+```bash
+chemql --upgrade 0.2.2
+``` 
+However if you do not have chemql-python version >=1.0.1
+```bash
+pip install --upgrade chemql-python
+```
+Or to switch versions to for example 0.2.2
+```bash
+pip install --force-reinstall chemql-python==0.2.2
+```
+
+## Quick start
+
+Start the interactive terminal:
+
+``` bash
+chemql
+```
+
+Then try:
+
+``` text
+search elements name = "Hydrogen"
+findel "He"
+findmol "H2O"
+search molecules molecular_weight < 20 return name formula molecular_weight
+search reactions reaction_type = "combustion" return name equation
+```
+
+Show the built-in command reference from the REPL:
+
+``` text
+help
+```
+
+## Command-line usage
+
+Run a single command with `-c`:
+
+``` bash
+chemql -c 'search elements name = "Hydrogen"'
+```
+
+Run commands from a file with `-f`:
+
+``` bash
+chemql -f queries.chemql
+```
+
+Check the installed version:
+
+``` bash
+chemql --version
+```
+
+A query file can contain multiple ChemQL commands, one per line. Use the
+`//` comment marker for comments and a trailing backslash (`\`) to
+continue a command onto the next line.
+
+Example `queries.chemql`:
+
+``` text
+// Find lighter molecules
+search molecules molecular_weight < 20 return name formula molecular_weight
+
+// Show a subset of the periodic table
+search elements atomic_number > 10 and atomic_number < 20 sort atomic_number desc limit 5
+```
+
+## Query language
+
+### Data sources
+
+ChemQL provides three main sources:
+
+  Source        Contents
+  ------------- ----------------------------------------------
+  `elements`    Periodic-table element data
+  `molecules`   Molecule properties and identifiers
+  `reactions`   Reaction equations, conditions, and metadata
+
+Search a source explicitly:
+
+``` text
+search elements
+search molecules
+search reactions
+```
+
+You can also use `search all` before a source name, for example:
+
+``` text
+search all elements atomic_mass < 100
+```
+
+Change the active source in an interactive session with:
+
+``` text
+source elements
+source molecules
+source reactions
+```
+
+### Filtering
+
+Use comparison operators to filter records:
+
+  Operator   Meaning
+  ---------- ----------------------------------------
+  `=`        Equal
+  `!=`       Not equal
+  `>`        Greater than
+  `<`        Less than
+  `>=`       Greater than or equal
+  `<=`       Less than or equal
+  `like`     Case-insensitive wildcard match
+  `like!`    Case-sensitive wildcard match
+  `likep`    Python regular-expression match
+  `has`      Check whether a value contains an item
+
+Examples:
+
+``` text
+search elements atomic_number > 10
+search molecules molecular_weight <= 20
+search molecules name like "*water*"
+search reactions id likep ".*haber(\s*|-|_)process.*"
+```
+
+The wildcard matcher supports `*` for a sequence of characters and other
+wildcard tokens supported by ChemQL's pattern matcher. Use `likep` when
+you need regular expressions rather than wildcard patterns.
+
+### Logical conditions and parentheses
+
+Combine conditions with `and`, `or`, and `not`. Parentheses group
+conditions. Comparison operators and parentheses can be written without
+surrounding spaces.
+
+``` text
+search elements name not like "*ium"
+search elements name not like "*ium" and not atomic_mass < 50
+search elements atomic_mass > 50 and (density<10 or boil<100)
+```
+
+### Combining query results
+
+Use `union` to combine results and `intersection` to keep records
+present in both result lists. Operations are evaluated from left to
+right.
+
+``` text
+search elements name not like "*ium" intersection search elements name like "*um"
+```
+
+Use the Python API's query-object operators `|` and `&` for union and
+intersection, respectively, when working with `ChemQLQuery` objects.
+
+### Sorting, limiting, counting, and returning fields
+
+``` text
+search elements sort atomic_number
+search molecules sort molecular_weight desc
+search molecules limit 10
+search molecules count
+search molecules molecular_weight < 20 return name
+search molecules molecular_weight < 20 return name formula molecular_weight
+```
+
+-   `sort <field> [asc|desc]` sorts results.
+-   `limit <number>` limits the number of results.
+-   `count` returns the number of matches.
+-   `return <field...>` returns only selected fields. One field produces
+    a list; multiple fields produce a table-like result.
+-   `first` and `last` can be used to select one result.
+
+### Find commands
+
+``` text
+findel "He"
+findel "Hydrogen"
+
+findmol "H2O"
+findmol "Water"
+
+findre "Haber process"
+findre "RHEA:10000" return name equation source
+```
+
+`findmol` searches the local molecule dataset first and can use external
+chemical-data services when a local match is not found. External lookups
+require an internet connection and may be unavailable if the service is
+down.
+
+## Reactions and equation balancing
+
+ChemQL includes reaction data and commands for working with reaction
+conditions.
+
+``` text
+findre "Haber process"
+balance O2 + H2 -> H2O
+balance O2 + H2 <-> H2O
+```
+
+The `->` arrow denotes an irreversible reaction, while `<->` denotes a
+reversible reaction.
+
+Set conditions before using `react`:
+
+``` text
+set temperature 723K
+set pressure 20265000pa
+set catalysts iron zinc
+conditions
+react N2 3H2
+```
+
+Temperature can be supplied in Celsius (`C`), Fahrenheit (`F`), or
+Kelvin (`K`). Pressure supports units such as pascals and bar; the
+available unit conversions depend on the installed version. Preset
+conditions are also available:
+
+``` text
+set temperature standard
+set pressure room
+```
+
+Use `help` in the terminal for the command reference included with your
+installed version.
+
+## Python API
+
+Import ChemQL from Python:
+
+``` python
+import chemql
+
+result = chemql.execute_query_text(
+    'search elements name = "Hydrogen"'
+)
+print(result)
+```
+
+You can also use `execute_query` for a query string:
+
+``` python
+import chemql
+
+result = chemql.execute_query('search molecules molecular_weight < 20')
+print(result)
+```
+
+The package exposes chemistry data classes and helpers, including
+`Element`, `Molecule`, `Reaction`, `ChemQLError`, `Unknown`,
+`ReturnTable`, and `balance_stoichiometry`.
+
+### Query builder API
+
+Versions that include the query-builder API also support chaining query
+conditions:
+
+``` python
+import chemql
+
+x = chemql.search("elements")
+y = x.atomic_mass.condition(lt=10)
+z = y.return_("name")
+
+print(z)          # The query as text
+print(z.execute())  # Execute the query
+```
+
+Query objects can be combined with `|` (union) and `&` (intersection).
+The convenience functions `chemql.union(x, y)` and
+`chemql.intersection(x, y)` are also available in versions that include
+this API.
+
+## Hybrid Python
+
+ChemQL can execute Python expressions inside square brackets:
+
+``` text
+[x = 10]
+[print(x)]
+```
+
+It also supports Python control blocks using `[for ...]`, `[if ...]`,
+`[elif ...]`, `[else]`, `[while ...]`, `[break]`, `[continue]`, and
+`[endblock]`.
+
+Use `{{ ... }}` to evaluate a ChemQL query and insert its result into
+Python:
+
+``` text
+[print({{ search elements atomic_number = 1 }})]
+```
+
+Only run Python code and shell commands from sources you trust.
+
+## Shell Commands
+
+ChemQL supports executing system shell commands by enclosing them in backticks (`` ` ``). Commands execute in a **persistent shell session**, allowing shell state to be preserved between commands.
+
+**Syntax**
+
+```chemql
+`command`
+```
+
+**Examples**
+
+Execute system commands:
+
+```chemql
+`whoami`
+`dir`
+`echo Hello`
+```
+
+Change the working directory:
+
+```chemql
+`cd ..`
+`cd ~`
+`dir`
+```
+
+The working directory persists between commands.
+
+Environment variables and other shell state can also persist between commands, depending on the shell being used.
+
+**Platform support**
+
+- **Linux:** Bash
+- **macOS:** Bash
+- **Windows:** Command Prompt (`cmd.exe`)
+
+PowerShell is not supported by the current implementation.
+
+**How it works**
+
+ChemQL maintains a persistent shell process and sends commands to it sequentially. Command output is captured and displayed in the ChemQL interface, allowing shell state to persist throughout the session.
+
+**Notes**
+
+- Commands must be enclosed in backticks to be interpreted as shell commands rather than ChemQL statements.
+- Shell syntax differs between operating systems. Use commands appropriate for your platform.
+- Commands run with the permissions of the process running ChemQL and may modify files or affect your system.
+- Interactive terminal programs and commands requiring direct terminal input may not work correctly because the shell uses pipes rather than a real terminal.
+
+## Data and external services
+
+ChemQL loads bundled JSON datasets for elements, molecules, reactions,
+molecule bonds, and bond energies. Some molecule lookups may query
+PubChem or other external sources when the local dataset does not
+contain a match.
+
+The periodic-table dataset is based on PeriodicTableJSON by
+Bowserinator. Review the dataset's accompanying license and attribution
+requirements when redistributing it or derivative data. The licenses and
+sources for the other bundled datasets should be checked in their
+respective files before redistribution.
+
+## Safety note
+
+ChemQL's hybrid Python functionality can execute Python code. If your
+installed version supports backtick-wrapped shell commands, those can
+execute operating-system commands as well. Do not run untrusted ChemQL
+scripts or queries.
+
+## Development notes
+
+-   The interactive shell uses `prompt_toolkit`.
+-   The command-line interface supports single-command execution (`-c`)
+    and file execution (`-f`).
+-   Consult the package's source and included `help` output for the
+    exact commands and fields supported by your installed version.
+
+## License
+
+[MIT License](https://github.com/rakibulofficial1017/ChemQL/blob/main/LICENSE)
+
+Created by [Mohammad Rakibul Islam](https://github.com/rakibulofficial1017).
+Source code: [rakibulofficial1017/ChemQL](https://github.com/rakibulofficial1017/ChemQL).

{chemql_python-0.2.2.dist-info → chemql_python-1.0.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-chemql/__init__.py,sha256=c0qkGIxP9o0z45qnlzXrwx-e_7Yms4M_W7q5aaqPAzA,96023
+chemql/__init__.py,sha256=QVKr8cWmQyaiLjGkWX0KijyOIj9qWMUYJJ9PJR-4F9A,109275
 chemql/__main__.py,sha256=3Q52s0hyuouhvSSqFEQFDr6mtJ-azkCwI2AD4c7f7A8,28
 chemql/data/BondEnergies.json,sha256=QZN3iWZrD8125jV41EG1GiRohBtP0CzAP_EDQTfaEKc,8269
 chemql/data/MoleculeBonds.json,sha256=Iw2shYxJScH_tI80IytBYoqVDSbgT7OSqPJUIgKZme4,84262
@@ -8,9 +8,9 @@ chemql/data/Reactions.json,sha256=BFpkKEWwLzG54ot96BVOWwU3btpimRJlOM57yGclGgc,15
 chemql/data/THIRD_PARTY_LICENSES/PeriodicTableJSON.txt,sha256=9wih5q8s58qR3vJEGpooa4ESyAGZHcmGvzwMMkMHNKk,322
 chemql/data/THIRD_PARTY_LICENSES/RHEA.txt,sha256=nXTeCP6vJBW5B_mtaVGFLr0w7vnjrSTBnv6_eOk3KKo,634
 chemql/html/periodic_table.html,sha256=ftVgXWjRO2AsTAGEekTrvgE5ZvcwRfoby9UWoixc9Y8,361560
-chemql_python-0.2.2.dist-info/licenses/LICENSE,sha256=o4ywHC0EwRy2zgIASiRD2sK3Vcsf7LBcTHjDvoJgRE0,1079
-chemql_python-0.2.2.dist-info/METADATA,sha256=QSmDmVczOBEgJVBUeZdqhE_pz3YlMIIDXMWm4-hDnl4,6177
-chemql_python-0.2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-chemql_python-0.2.2.dist-info/entry_points.txt,sha256=j98ObVWR743an524z24AiWeRsppag-py5cc7l0D0HkI,39
-chemql_python-0.2.2.dist-info/top_level.txt,sha256=9UzHwnk_F6W19Q9nayaFgVyAELQXXwoYjeBgB6MWNr8,7
-chemql_python-0.2.2.dist-info/RECORD,,
+chemql_python-1.0.1.dist-info/licenses/LICENSE,sha256=o4ywHC0EwRy2zgIASiRD2sK3Vcsf7LBcTHjDvoJgRE0,1079
+chemql_python-1.0.1.dist-info/METADATA,sha256=wKVfuyvrj4AH0XDj-wgP_HySSfQeT447ZUvWLbvDQbo,11613
+chemql_python-1.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+chemql_python-1.0.1.dist-info/entry_points.txt,sha256=j98ObVWR743an524z24AiWeRsppag-py5cc7l0D0HkI,39
+chemql_python-1.0.1.dist-info/top_level.txt,sha256=9UzHwnk_F6W19Q9nayaFgVyAELQXXwoYjeBgB6MWNr8,7
+chemql_python-1.0.1.dist-info/RECORD,,

chemql_python-0.2.2.dist-info/METADATA

@@ -1,309 +0,0 @@
-Metadata-Version: 2.4
-Name: chemql-python
-Version: 0.2.2
-Summary: A chemistry-focused query language and REPL
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: prompt_toolkit>=3.0
-Provides-Extra: test
-Requires-Dist: pytest>=8.0; extra == "test"
-Dynamic: license-file
-
-# ChemQL
-
-![ChemQL logo](logo.png)
-
-ChemQL is a chemistry-focused query language and REPL for exploring element, molecule, and reaction datasets. It lets you search the built-in chemistry data, filter results with expressions, set reaction conditions, and combine queries with small Python snippets when needed.
-
-## What ChemQL does
-
-ChemQL supports:
-
-- Searching the built-in `elements`, `molecules`, and `reactions` datasets
-- Filtering by field, comparison operator, pattern matching, and boolean logic
-- Quick lookup commands like `findel`, `findmol`, and `findre`
-- Reaction setup with temperature, pressure, and catalyst configuration
-- Running reactions with `react`
-- Embedding Python in `[ ... ]` blocks and templates in `{{ ... }}`
-- Running from a terminal REPL or executing a command/file from the shell
-
-## Install the library
-
-Install from this `chemql/` directory, which contains `pyproject.toml`:
-
-```bash
-cd /path/to/ChemQL/Language/chemql
-python -m pip install -e ".[test]"
-```
-
-This installs the Python package and the `chemql` CLI:
-
-```bash
-chemql -c "search elements name = 'Hydrogen'"
-```
-
-Start the interactive REPL with:
-
-```bash
-python -m chemql
-```
-
-You will see the interactive prompt:
-
-```text
->>> 
-```
-
-Type:
-
-```text
-help
-```
-
-or:
-
-```text
-?
-```
-
-to display the built-in help.
-
-## Command-line usage
-
-You can also execute a single ChemQL command or a file:
-
-```bash
-chemql -c 'search elements name = "Hydrogen"'
-chemql -f examples/script.cql
-```
-
-The Python package is `chemql`. Its query engine, chemistry types, and bundled
-datasets can be imported directly:
-
-```python
-from chemql import balance_stoichiometry, execute_query_text
-
-result = execute_query_text('search elements name = "Hydrogen"')
-reaction = balance_stoichiometry(["O2", "H2"], ["H2O"], reversible=True)
-print(reaction)
-```
-
-## Core query syntax
-
-### Search a dataset
-
-```text
-search elements
-search molecules
-search reactions
-```
-
-### Search with filters
-
-```text
-search elements atomic_number > 10 and atomic_number < 20
-search molecules name like "*water*"
-search reactions reaction_type = "combustion"
-```
-
-### Sort, limit, and count
-
-```text
-search molecules sort molecular_weight desc
-search molecules limit 10
-search molecules count
-```
-
-### Return selected fields
-
-```text
-search molecules molecular_weight < 20 return name formula molecular_weight
-search reactions reversible = true return name conditions
-```
-
-### Set the current source
-
-```text
-source elements
-source molecules
-source reactions
-```
-
-### List available keys
-
-```text
-list all
-```
-
-## Convenience lookup commands
-
-```text
-findel "He"
-findel "Hydrogen"
-
-findmol "H2O"
-findmol "Water"
-
-findre "Haber process"
-findre "RHEA:10000" return name equation source
-```
-
-## Reactions
-
-Set reaction conditions before running a reaction:
-
-```text
-set temperature 723K
-set temperature standard
-set pressure 20265000pa
-set pressure room
-set catalysts iron zinc
-add catalyst "Vanadium oxide"
-remove catalyst "Vanadium oxide"
-conditions
-react N2 3H2
-balance O2 + H2 -> H2O
-balance O2 + H2 <-> H2O
-```
-
-Temperature accepts `C`, `F`, or `K`; pressure accepts `Pa`, `N/m^2`, `Nm^-2`, `bar`, or `atm`. The keywords `standard` and `room` are also accepted.
-
-`balance` accepts chemical formulas on each side, separated by `+`. It returns
-a `Reaction` with the smallest positive integer stoichiometric coefficients.
-The arrow determines reaction direction: `->` is irreversible and `<->` is
-reversible. `//` begins a comment, as it does elsewhere in ChemQL. The function
-API is `balance_stoichiometry(reactants, products, reversible=None)`.
-
-## Operators
-
-ChemQL supports these comparison operators:
-
-- `=`
-- `>`
-- `<`
-- `>=`
-- `<=`
-- `like`
-- `like!`
-- `has`
-
-Boolean logic:
-
-```text
-and
-or
-```
-
-Parentheses may be used to group expressions.
-
-## Result controls
-
-```text
-search molecules first
-search molecules last
-search molecules sort atomic_number desc limit 5
-search molecules count
-```
-
-## General commands
-
-```text
-list all
-view
-clear
-dump my_session.txt
-help
-exit
-```
-
-`view` opens the periodic table in a browser. `dump` writes recent command history to a file.
-
-## Hybrid Python mode
-
-ChemQL can be mixed with Python inside square-bracket blocks:
-
-```text
-[x = 10]
-[print(x)]
-```
-
-Conditional and loop blocks are also supported:
-
-```text
-[for x in range(3)]
-[print(x)]
-[endblock]
-
-[if x > 0]
-[print("positive")]
-[else]
-[print("not positive")]
-[endblock]
-```
-
-Embedded ChemQL queries can also be used with double-brace syntax. This executes a query and uses the result as a value in the surrounding Python:
-
-```text
-[print({{ search elements number = 1 }})]
-[for i in {{search elements number <= 10}}]
-    [print(i.name)]
-[endblock]
-```
-
-The `{{ ... }}` form is a convenient way to make a query return actual data to Python, rather than only writing a plain query line.
-
-## Line continuation
-
-If a line ends with `\`, it continues onto the next line:
-
-```text
-search elements \
-name = "Hydrogen"
-```
-
-This is treated as:
-
-```text
-search elements name = "Hydrogen"
-```
-
-## Examples
-
-```text
-search elements name = "Hydrogen"
-findel "He"
-findmol "H2O"
-
-search molecules molecular_weight < 20 \
-return name formula molecular_weight
-
-search elements atomic_number > 10 \
-and atomic_number < 20 \
-sort atomic_number desc \
-limit 5
-
-search molecules count
-```
-
-## Repository layout
-
-```text
-chemql/
-├── pyproject.toml
-├── src/
-│   └── chemql/
-│       ├── __init__.py
-│       ├── __main__.py
-│       ├── data/
-│       └── html/
-├── tests/
-├── scripts/
-└── examples/
-```
-
-The installable package contains the language implementation and its bundled
-chemical datasets.
-
-Created by [Mohammad Rakibul Islam](https://github.com/rakibulofficial1017).
-Source code: [rakibulofficial1017/ChemQL](https://github.com/rakibulofficial1017/ChemQL).