chemql-python 1.4.0__py3-none-any.whl → 1.4.2__py3-none-any.whl

chemql/__init__.py

@@ -61,7 +61,7 @@ __all__ = [
     "__version__"
 ]
 
-__version__ = "1.4.0"
+__version__ = "1.4.2"
 
 # Persistent preprocessor/function state for the current ChemQL session.
 DEFINITIONS = {}
@@ -407,6 +407,104 @@ _HELP_TOPICS = {
     "chemistry": ("Chemistry Functions", ["molar_mass{formula}", "count_atoms{formula, element_symbol}", "empirical_formula{formula}", "element{symbol, field?}"]),
 }
 
+_STDLIB_HELP = {
+    "math": (
+        "Mathematical constants and numeric functions.",
+        [
+            "PI, E, TAU — Common mathematical constants.",
+            "sqrt{number}, cbrt{number}, abs{number}, floor{number}, ceil{number}, factorial{integer}",
+            "gcd{integer, ...}, lcm{integer, ...}, hypot{number, ...}, pow{x, y}",
+            "sin{radians}, cos{radians}, tan{radians}, asin{x}, acos{x}, atan{x}, atan2{y, x}",
+            "log{x}, log10{x}, log2{x}, exp{x}, degrees{radians}, radians{degrees}",
+            "isfinite{x}, isinf{x}, isnan{x}, isclose{x, y}",
+            "Example: math::sqrt{81}  # 9.0",
+        ],
+    ),
+    "math::statistics": (
+        "Descriptive statistics for numeric data.",
+        [
+            "mean{values...}, median{values...}, median_low{values...}, median_high{values...}",
+            "mode{values...}, multimode{values...}, quantiles{values...}",
+            "variance{values...}, stdev{values...}, pvariance{values...}, pstdev{values...}",
+            "harmonic_mean{values...}, geometric_mean{values...}",
+            "Example: math::statistics::mean{2, 4, 6}  # 4",
+        ],
+    ),
+    "text": (
+        "String transformations, searching, splitting, and regular expressions.",
+        [
+            "upper{text}, lower{text}, title{text}, capitalize{text}, casefold{text}",
+            "strip{text, chars?}, lstrip{text}, rstrip{text}, reverse{text}",
+            "startswith{text, prefix}, endswith{text, suffix}, replace{text, old, new}",
+            "split{text, separator?}, join{separator, values...}, count{text, substring}, find{text, substring}",
+            "isalpha{text}, isdigit{text}, isalnum{text}, isspace{text}",
+            "regex_search{pattern, text}, regex_findall{pattern, text}, regex_replace{pattern, replacement, text}",
+            'Example: text::upper{"hello"}  # HELLO',
+        ],
+    ),
+    "collections": (
+        "Collection helpers for sequences and iterables.",
+        [
+            "unique{values...}, flatten{groups...}, zip{values...}, pairwise{values...}",
+            "frequencies{values...}, group_count{values...}, product{numbers...}",
+            "sorted{values...}, reversed{values...}",
+            'Example: collections::frequencies{"red", "blue", "red"}',
+        ],
+    ),
+    "datetime": (
+        "Date and time values, ISO parsing, timestamps, and date arithmetic.",
+        [
+            "today{}, now{}, utcnow{}",
+            "date{year, month, day}, time{hour, minute?, second?, microsecond?}",
+            "timestamp{iso_datetime}, from_timestamp{seconds}, weekday{iso_date}",
+            "date_add_days{iso_date, days}, date_difference_days{date1, date2}",
+            'Example: datetime::date_add_days{"2026-10-20", 7}',
+        ],
+    ),
+    "json": (
+        "JSON serialization, parsing, and decoded value type inspection.",
+        [
+            "dumps{value}, dumps_pretty{value}, loads{json_text}, json_type{json_text}",
+            'Example: json::loads{"{\\"formula\\": \\"H2O\\"}"}',
+        ],
+    ),
+    "random": (
+        "Pseudo-random values and sequence sampling using Python's random module.",
+        [
+            "seed{value}, random{}, randint{minimum, maximum}, randrange{stop} or randrange{start, stop, step}",
+            "choice{values}, sample{values, count}, shuffle{values}, uniform{minimum, maximum}",
+            "Use seed{value} when repeatable pseudo-random output is required.",
+            "Example: random::randint{1, 6}",
+        ],
+    ),
+    "decimal": (
+        "Base-10 decimal arithmetic, useful when decimal rounding matters.",
+        [
+            "create{value}, add{x, y}, subtract{x, y}, multiply{x, y}, divide{x, y}",
+            "quantize{value, quantum}, to_string{value}",
+            'Pass decimal values as strings for exact input, e.g. decimal::add{"0.1", "0.2"}.',
+        ],
+    ),
+    "fractions": (
+        "Rational arithmetic using reduced fractions.",
+        [
+            "create{value} or create{numerator, denominator}",
+            "add{x, y}, subtract{x, y}, multiply{x, y}, divide{x, y}",
+            "numerator{value}, denominator{value}, to_float{value}",
+            "Example: fractions::create{1, 3}",
+        ],
+    ),
+    "pathlib": (
+        "Path inspection and UTF-8 text file operations using pathlib.",
+        [
+            "name{path}, stem{path}, suffix{path}, parent{path}, join{path, part...}",
+            "exists{path}, is_file{path}, is_dir{path}",
+            "read_text{path, encoding?}, write_text{path, content, encoding?}",
+            "File reads and writes operate with the current process permissions.",
+        ],
+    ),
+}
+
 
 def _help_text(topic=None):
     if topic is None or not str(topic).strip():
@@ -415,16 +513,34 @@ def _help_text(topic=None):
         for name in names:
             category = _BUILTIN_HELP[name][0]
             categories.setdefault(category, []).append(name)
-        lines = [f"ChemQL {__version__} help", "", "Usage: help{topic} or help topic", "Use help{function_name} for details, or help{syntax}, help{errors}, help{files}, help{chemistry}.", ""]
+        lines = [f"ChemQL {__version__} help", "", "Usage: help{topic} or help topic", "Use help{function_name} for details, or help{syntax}, help{errors}, help{files}, help{chemistry}, help{stdlib}.", ""]
         for category, items in categories.items():
             lines.append(f"{category}: " + ", ".join(items))
         lines += ["", "User-defined functions:"]
         lines += [f"  {name}{{...}}" for name in sorted(FUNCTIONS)] or ["  (none defined in this session)"]
         lines += ["", "Packages: load package_name; then use package_name::function{...}."]
+        lines += ["Standard library: " + ", ".join(_STDLIB_HELP)]
         return "\n".join(lines)
 
     key = str(topic).strip().strip("`\"'")
-    key = key.replace("::", "::")
+    if key == "stdlib":
+        return "\n".join([
+            "ChemQL Standard Library",
+            "Load a package with `load package_name`, then call `package_name::function{...}`.",
+            "Get module details with `help{module}` and function details with `help{module::function}`.",
+            "",
+            *[f"{name} — {details[0]}" for name, details in _STDLIB_HELP.items()],
+        ])
+    resolved_key = _resolve_package_qualified_name(key)
+    if resolved_key in _STDLIB_HELP:
+        description, entries = _STDLIB_HELP[resolved_key]
+        return "\n".join([
+            f"{resolved_key} — Standard library",
+            description,
+            f"Load with: load {resolved_key}",
+            "Functions and constants:",
+            *[f"  {entry}" for entry in entries],
+        ])
     if key in _BUILTIN_HELP:
         category, signature, description, examples = _BUILTIN_HELP[key]
         return "\n".join([f"{key} — {category}", f"Signature: {signature}", description, "", "Examples:", *[f"  {line}" for line in examples]])
@@ -434,12 +550,16 @@ def _help_text(topic=None):
     if key in FUNCTIONS:
         return f"User-defined ChemQL function: {key}{{...}}\nDefined in the current session. Use `view`/`dump` where appropriate to inspect program state."
     if "::" in key:
-        resolved = _resolve_package_qualified_name(key)
-        if resolved in FUNCTIONS:
-            return f"ChemQL package function: {key}{{...}}\nCanonical name: {resolved}"
-        package = key.rsplit("::", 1)[0]
+        package, _, member = resolved_key.rpartition("::")
+        if package in _STDLIB_HELP:
+            _, entries = _STDLIB_HELP[package]
+            match = next((entry for entry in entries if entry.split("{", 1)[0].endswith(member)), None)
+            if match:
+                return f"{package}::{member} — Standard library\n{match}"
+        if resolved_key in FUNCTIONS:
+            return f"ChemQL package function: {key}{{...}}\nCanonical name: {resolved_key}"
         return f"Package/member help is not registered for `{key}`.\nTry `load {package}` and inspect the package namespace, or use `help{{{package}}}` if documented."
-    return f"No help available for `{key}`. Try `help` to list built-ins, or `help{{syntax}}`, `help{{errors}}`, `help{{files}}`, and `help{{chemistry}}`."
+    return f"No help available for `{key}`. Try `help` to list built-ins, `help{{stdlib}}` for standard-library packages, or `help{{syntax}}`, `help{{errors}}`, `help{{files}}`, and `help{{chemistry}}`."
 
 
 def _call_builtin(name, arguments):
@@ -587,7 +707,13 @@ def _call_function(name, arguments):
                         return result
                     python_globals["error"] = None
                 except Exception as exc:
-                    python_globals["error"] = exc.error_type if isinstance(exc, ChemQLSignal) else type(exc).__name__
+                    python_globals["error"] = (
+                        exc.error_type
+                        if isinstance(exc, ChemQLSignal)
+                        else "ChemQLError"
+                        if isinstance(exc, ChemQLError)
+                        else type(exc).__name__
+                    )
                     if sections["fix"]:
                         result = execute_function_lines(sections["fix"])
                         if result is not _NO_RETURN:
@@ -822,6 +948,9 @@ def _expand_function_calls(text):
                 continue
             if ch in ("'", '"'):
                 quote = ch; i += 1; continue
+            if i and re.match(r"[A-Za-z0-9_.:]", text[i - 1]):
+                i += 1
+                continue
             match = re.match(r"([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*(?:\.[A-Za-z_][A-Za-z0-9_]*)?)\{", text[i:])
             if match:
                 name = match.group(1)
@@ -835,9 +964,18 @@ def _expand_function_calls(text):
                     value = _call_function(resolved_name, args)
                 elif "::" not in resolved_name and resolved_name in BUILTIN_FUNCTIONS:
                     value = _call_builtin(resolved_name, args)
+                elif (
+                    "::" not in resolved_name
+                    and isinstance(python_globals.get(resolved_name), type)
+                ):
+                    replacement = (
+                        f"{resolved_name}({text[opening + 1:end]})"
+                    )
+                    text = text[:i] + replacement + text[end + 1:]
+                    changed = True
+                    break
                 else:
-                    i += 1
-                    continue
+                    raise ChemQLError(f"Unknown function `{name}`")
                 replacement = repr(value) if isinstance(value, str) else ("None" if value is None else str(value))
                 text = text[:i] + replacement + text[end + 1:]
                 changed = True
@@ -1391,10 +1529,17 @@ class ChemQLError(Exception):
         self.length = length
 
 
+class _ChemQLUnknownCommand(ChemQLError):
+    pass
+
+
 _CHEMQL_RISK_DEPTH = 0
 
 
 def format_error(message, text=None, position=None, length=1):
+    if _CHEMQL_RISK_DEPTH:
+        raise ChemQLError(message, position, length)
+
     output = ""
     if (text is not None) and (position is not None) and (not NO_ANSI):
         output += f"\033[1;31m{' ' * (position+4)}{'^' * max(1, length)}\n\033[0m"
@@ -4084,14 +4229,20 @@ def process_inline(text):
         return evaluate_python(stripped)
 
     # A standalone user-defined function call returns its value directly.
-    function_call = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*)\s*\{(.*)\}", stripped, re.DOTALL)
+    function_call = re.match(
+        r"([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*)\s*\{",
+        stripped,
+    )
     if function_call:
-        function_name = _resolve_package_qualified_name(function_call.group(1))
-        arguments = _split_function_arguments(function_call.group(2))
-        if function_name in FUNCTIONS:
-            return _call_function(function_name, arguments)
-        if "::" not in function_name and function_name in BUILTIN_FUNCTIONS:
-            return _call_builtin(function_name, arguments)
+        opening = function_call.end() - 1
+        closing = find_matching(stripped, opening, "{", "}")
+        if not stripped[closing + 1:].strip():
+            function_name = _resolve_package_qualified_name(function_call.group(1))
+            arguments = _split_function_arguments(stripped[opening + 1:closing])
+            if function_name in FUNCTIONS:
+                return _call_function(function_name, arguments)
+            if "::" not in function_name and function_name in BUILTIN_FUNCTIONS:
+                return _call_builtin(function_name, arguments)
 
     # [ ... ] is Python.
     if stripped.startswith("["):
@@ -4134,11 +4285,33 @@ def process_inline(text):
             except (SyntaxError, NameError):
                 pass
 
+    # Function calls can compose into ordinary Python expressions, e.g.
+    # `int{1} + int{1}`. Expand them before deciding whether this is a query;
+    # otherwise the query parser sees the resulting `1 + 1` as a command.
+    if re.search(
+        r"(?<![A-Za-z0-9_.:])[A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*(?:\.[A-Za-z_][A-Za-z0-9_]*)?\s*\{",
+        stripped,
+    ):
+        expanded = _expand_function_calls(stripped)
+        try:
+            ast.parse(expanded, mode="eval")
+        except SyntaxError:
+            stripped = expanded
+        else:
+            return evaluate_python(expanded)
+
     # Try ChemQL first. If the parser specifically reports an unknown command,
     # treat the input as a possible Python expression. Only Python SyntaxError
     # or NameError falls back to the original ChemQL error; other Python errors
     # (e.g. TypeError) are meaningful and should remain visible.
-    result = execute_query_text(stripped)
+    try:
+        result = execute_query_text(stripped)
+    except _ChemQLUnknownCommand as error:
+        try:
+            return evaluate_python(stripped)
+        except (SyntaxError, NameError):
+            raise error
+
     plain_result = strip_ansi(result) if isinstance(result, str) else ""
     # The query engine formats unknown-command failures as text (including a
     # caret line), so detect the diagnostic independently of any leading ANSI
@@ -4504,11 +4677,11 @@ def process_lines(lines):
                 field_line = remove_comments(field_line).strip()
                 if not field_line:
                     continue
-                required_match = re.fullmatch(r"required\s+([A-Za-z_]\w*)", field_line, re.IGNORECASE)
+                required_match = re.fullmatch(r"(?:required\s+([A-Za-z_]\w*)|([A-Za-z_]\w*)!)", field_line, re.IGNORECASE)
                 if required_match:
                     if kind != "struct":
                         raise SyntaxError("`required` fields are supported only in structs")
-                    field = required_match.group(1)
+                    field = required_match.group(1) if required_match.group(1) is not None else required_match.group(2)
                     default = None
                     is_required = True
                 else:
@@ -4624,7 +4797,13 @@ def process_lines(lines):
                     process_lines(sections["risk"])
                     python_globals["error"] = None
                 except Exception as exc:
-                    python_globals["error"] = exc.error_type if isinstance(exc, ChemQLSignal) else type(exc).__name__
+                    python_globals["error"] = (
+                        exc.error_type
+                        if isinstance(exc, ChemQLSignal)
+                        else "ChemQLError"
+                        if isinstance(exc, ChemQLError)
+                        else type(exc).__name__
+                    )
                     if sections["fix"]:
                         process_lines(sections["fix"])
                     elif not isinstance(exc, ChemQLSignal):
@@ -4858,15 +5037,7 @@ def process_lines(lines):
             i += 1
             continue
 
-        # Python imports belong inside Python blocks, e.g. `[import math]`.
         top_level_statement = remove_comments(_expand_definitions(raw_line)).strip()
-        if top_level_statement.startswith("import ") or top_level_statement.startswith("from "):
-            message = "Python imports must be inside a Python block, e.g. `[import math]`; use `load` for ChemQL packages."
-            print(f"Error: {message}", file=sys.stderr)
-            _record_execution(top_level_statement, message, False)
-            i += 1
-            continue
-
         # ChemQL package loading is separate from Python imports.
         load_statement = top_level_statement
         if load_statement == "load" or load_statement.startswith("load "):
@@ -4943,13 +5114,7 @@ def process_lines(lines):
                     result = _dump_history(command)
                 else:
                     result = process_inline(command)
-                    # Query parsing can report an error as formatted text instead
-                    # of raising. Inside `risk`, promote that result to an exception
-                    # so `fix` runs and the `error` variable is populated.
-                    if _CHEMQL_RISK_DEPTH and isinstance(result, str):
-                        plain_result = strip_ansi(result).lstrip()
-                        if plain_result.startswith("Error:"):
-                            raise ChemQLError(plain_result[6:].strip())
+
                 rendered = "" if result is None else str(result)
                 if result is not None:
                     if NO_ANSI:
@@ -5568,14 +5733,20 @@ def execute(arguments, query_text=None, positions=None):
 
     if query_text is not None and positions:
         pos, length = error_position(positions, 0)
+        message = f"Unknown command `{arguments[0]}`"
+        if _CHEMQL_RISK_DEPTH:
+            raise _ChemQLUnknownCommand(message, pos, length)
         return format_error(
-            (f"Unknown command `{arguments[0]}`" if NO_ANSI else f"Unknown command \033[1m{arguments[0]}\033[22m"),
+            (message if NO_ANSI else f"Unknown command \033[1m{arguments[0]}\033[22m"),
             query_text,
             pos,
             length
         )
 
-    return format_error((f"Unknown command `{arguments[0]}`" if NO_ANSI else f"Unknown command \033[1m{arguments[0]}\033[22m"))
+    message = f"Unknown command `{arguments[0]}`"
+    if _CHEMQL_RISK_DEPTH:
+        raise _ChemQLUnknownCommand(message)
+    return format_error(message if NO_ANSI else f"Unknown command \033[1m{arguments[0]}\033[22m")
 
 
 HELP = (
@@ -5594,6 +5765,9 @@ HELP = (
     "  \x1b[92mbalance H2 + O2 -> H2O       \x1b[0m \x1b[90m│\x1b[0m Balance a chemical equation\n"
     "  \x1b[92mhelp  or  ?                  \x1b[0m \x1b[90m│\x1b[0m Display this help message\n"
     "  \x1b[92mhelp{read_csv}               \x1b[0m \x1b[90m│\x1b[0m Show detailed built-in documentation\n"
+    "  \x1b[92mhelp{stdlib}                 \x1b[0m \x1b[90m│\x1b[0m List standard-library packages\n"
+    "  \x1b[92mhelp{math}                   \x1b[0m \x1b[90m│\x1b[0m Show package documentation\n"
+    "  \x1b[92mhelp{math::sqrt}             \x1b[0m \x1b[90m│\x1b[0m Show package function help\n"
     "  \x1b[92mversion                      \x1b[0m \x1b[90m│\x1b[0m Display the installed version\n"
     "  \x1b[92mexit                         \x1b[0m \x1b[90m│\x1b[0m Exit the interactive prompt\n"
     "\n"
@@ -5765,7 +5939,7 @@ class ChemqlLexer(Lexer):
         "view", "help", "dump", "version", "return", "union", "intersection",
         "let", "unset", "variables", "macros", "definitions", "arguments",
         "define", "func", "struct", "record", "risk", "fix", "cleanup",
-        "signal", "import", "remove", "install",
+        "signal", "import", "remove", "load"
     }
     OPERATORS = {
         "and", "or", "has", "like", "like!", "likep", "sort", "limit",
@@ -5956,7 +6130,7 @@ class ChemqlCompleter(Completer):
         "endfor", "endwhile", "endif", "endrisk", "endstruct", "endrecord", "endfunc", "enddefine",
     )
     QUERY_OPERATORS = ["=", "!=", ">", "<", ">=", "<=", "like", "like!", "likep", "has", "sort", "limit", "count", "asc", "desc", "return", "and", "or", "union", "intersection"]
-    CONTROL_COMPLETIONS = ["if ", "for ", "while ", "endfor", "endwhile", "endif", "risk", "fix", "cleanup", "endrisk", "struct ", "endstruct", "record ", "endrecord", "func ", "endfunc", "define ", "enddefine"]
+    CONTROL_COMPLETIONS = ["if ", "for ", "while ", "endfor", "endwhile", "endif", "risk", "fix", "cleanup", "endrisk", "endstruct", "record ", "endrecord", "func ", "endfunc", "define ", "enddefine"]
 
     @staticmethod
     def _names():
@@ -6550,7 +6724,37 @@ def run_interactive():
                         break
                 if not lines:
                     continue
+                        # Collect risk/fix/cleanup blocks as complete REPL units.
+            if lines and lines[0].strip().casefold() == "risk":
+                depth = 0
+
+                for existing_line in lines:
+                    token = existing_line.strip().casefold()
+                    if token == "risk":
+                        depth += 1
+                    elif token == "endrisk":
+                        depth -= 1
 
+                while depth > 0:
+                    try:
+                        next_line = session.prompt("... ")
+                    except (KeyboardInterrupt, EOFError):
+                        print("\nIncomplete risk block")
+                        lines = []
+                        break
+
+                    added_lines = next_line.splitlines() or [next_line]
+                    lines.extend(added_lines)
+
+                    for added_line in added_lines:
+                        token = added_line.strip().casefold()
+                        if token == "risk":
+                            depth += 1
+                        elif token == "endrisk":
+                            depth -= 1
+
+                if not lines:
+                    continue
             # Collect new multiline Python, terminal, and comment blocks in the REPL.
             if lines and lines[0].strip() in {"[[[", "```", "```bash", "```sh", "```cmd", "```terminal"}:
                 opener = lines[0].strip()

chemql/stdlib/README.md

@@ -11,6 +11,10 @@ directory next to the interpreter module and preserve the folder layout.
 | `collections` | Uniqueness, flattening, pairing, frequency counts, product |
 | `datetime` | Dates, timestamps, local/UTC time and date arithmetic |
 | `json` | JSON encode/decode helpers |
+| `random` | Pseudo-random numbers and sequence sampling |
+| `decimal` | Base-10 decimal arithmetic and quantization |
+| `fractions` | Exact rational numbers and fraction arithmetic |
+| `pathlib` | Path inspection and UTF-8 text file operations |
 
 Examples:
 
@@ -37,4 +41,28 @@ datetime::date_add_days{"2026-10-20", 7}
 
 load json
 json::loads{"{\"formula\": \"H2O\"}"}
+
+load random
+random::seed{42}
+random::randint{1, 6}
+
+load decimal
+decimal::add{"0.1", "0.2"}
+decimal::quantize{"3.14159", "0.01"}
+
+load fractions
+fractions::create{1, 3}
+fractions::add{"1/3", "1/6"}
+
+load pathlib
+pathlib::name{"data/results.csv"}
+pathlib::join{"data", "results.csv"}
 ```
+
+Use `help{stdlib}` for the package index, `help{math}` for a module
+overview, and `help{math::sqrt}` for function help. The help pages are
+available whether or not a package has been loaded.
+
+`pathlib::read_text` and `pathlib::write_text` access files using the
+current process permissions. `random` uses Python's pseudo-random
+generator; call `random::seed{value}` when repeatable results are needed.

chemql/stdlib/decimal.cql

@@ -0,0 +1,23 @@
+# ChemQL standard library: decimal
+[import decimal as _chemql_decimal]
+public func create
+    return _chemql_decimal.Decimal(str(arguments[0]))
+endfunc
+public func add
+    return _chemql_decimal.Decimal(str(arguments[0])) + _chemql_decimal.Decimal(str(arguments[1]))
+endfunc
+public func subtract
+    return _chemql_decimal.Decimal(str(arguments[0])) - _chemql_decimal.Decimal(str(arguments[1]))
+endfunc
+public func multiply
+    return _chemql_decimal.Decimal(str(arguments[0])) * _chemql_decimal.Decimal(str(arguments[1]))
+endfunc
+public func divide
+    return _chemql_decimal.Decimal(str(arguments[0])) / _chemql_decimal.Decimal(str(arguments[1]))
+endfunc
+public func quantize
+    return _chemql_decimal.Decimal(str(arguments[0])).quantize(_chemql_decimal.Decimal(str(arguments[1])))
+endfunc
+public func to_string
+    return str(_chemql_decimal.Decimal(str(arguments[0])))
+endfunc

chemql/stdlib/fractions.cql

@@ -0,0 +1,29 @@
+# ChemQL standard library: fractions
+[import fractions as _chemql_fractions]
+public func create
+    [if len(arguments) > 1]
+        return _chemql_fractions.Fraction(arguments[0], arguments[1])
+    [endblock]
+    return _chemql_fractions.Fraction(str(arguments[0]))
+endfunc
+public func add
+    return _chemql_fractions.Fraction(arguments[0]) + _chemql_fractions.Fraction(arguments[1])
+endfunc
+public func subtract
+    return _chemql_fractions.Fraction(arguments[0]) - _chemql_fractions.Fraction(arguments[1])
+endfunc
+public func multiply
+    return _chemql_fractions.Fraction(arguments[0]) * _chemql_fractions.Fraction(arguments[1])
+endfunc
+public func divide
+    return _chemql_fractions.Fraction(arguments[0]) / _chemql_fractions.Fraction(arguments[1])
+endfunc
+public func numerator
+    return _chemql_fractions.Fraction(arguments[0]).numerator
+endfunc
+public func denominator
+    return _chemql_fractions.Fraction(arguments[0]).denominator
+endfunc
+public func to_float
+    return float(_chemql_fractions.Fraction(arguments[0]))
+endfunc

chemql/stdlib/pathlib.cql

@@ -0,0 +1,38 @@
+# ChemQL standard library: pathlib
+[import pathlib as _chemql_pathlib]
+public func name
+    return _chemql_pathlib.Path(str(arguments[0])).name
+endfunc
+public func stem
+    return _chemql_pathlib.Path(str(arguments[0])).stem
+endfunc
+public func suffix
+    return _chemql_pathlib.Path(str(arguments[0])).suffix
+endfunc
+public func parent
+    return str(_chemql_pathlib.Path(str(arguments[0])).parent)
+endfunc
+public func join
+    return str(_chemql_pathlib.Path(str(arguments[0])).joinpath(*(str(part) for part in arguments[1:])))
+endfunc
+public func exists
+    return _chemql_pathlib.Path(str(arguments[0])).exists()
+endfunc
+public func is_file
+    return _chemql_pathlib.Path(str(arguments[0])).is_file()
+endfunc
+public func is_dir
+    return _chemql_pathlib.Path(str(arguments[0])).is_dir()
+endfunc
+public func read_text
+    [if len(arguments) > 1]
+        return _chemql_pathlib.Path(str(arguments[0])).read_text(encoding=str(arguments[1]))
+    [endblock]
+    return _chemql_pathlib.Path(str(arguments[0])).read_text(encoding="utf-8")
+endfunc
+public func write_text
+    [if len(arguments) > 2]
+        return _chemql_pathlib.Path(str(arguments[0])).write_text(str(arguments[1]), encoding=str(arguments[2]))
+    [endblock]
+    return _chemql_pathlib.Path(str(arguments[0])).write_text(str(arguments[1]), encoding="utf-8")
+endfunc

chemql/stdlib/random.cql

@@ -0,0 +1,29 @@
+# ChemQL standard library: random
+[import random as _chemql_random]
+public func seed
+    _chemql_random.seed(arguments[0])
+    return None
+endfunc
+public func random
+    return _chemql_random.random()
+endfunc
+public func randint
+    return _chemql_random.randint(arguments[0], arguments[1])
+endfunc
+public func randrange
+    return _chemql_random.randrange(*arguments)
+endfunc
+public func choice
+    return _chemql_random.choice(arguments[0])
+endfunc
+public func sample
+    return _chemql_random.sample(arguments[0], arguments[1])
+endfunc
+public func shuffle
+    values = list(arguments[0])
+    _chemql_random.shuffle(values)
+    return values
+endfunc
+public func uniform
+    return _chemql_random.uniform(arguments[0], arguments[1])
+endfunc

{chemql_python-1.4.0.dist-info → chemql_python-1.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemql-python
-Version: 1.4.0
+Version: 1.4.2
 Summary: A chemistry-focused query language and REPL
 Author-email: Mohammad Rakibul Islam <rakibulofficial1017@gmail.com>
 Requires-Python: >=3.10
@@ -19,7 +19,7 @@ SQL-inspired syntax, inspect elements and molecules, look up reactions,
 balance equations, and combine chemistry queries with Python and shell
 commands.
 
--   **Version:** `1.4.0`
+-   **Version:** `1.4.1`
 -   **PyPI distribution:** `chemql-python`
 -   **Python import / CLI name:** `chemql`
 -   **Author:** Mohammad Rakibul Islam
@@ -522,49 +522,55 @@ ChemQL provides `risk`, `fix`, `cleanup`, and `signal` for handling errors, resp
 
 ### `risk`
 
-Use `risk` to mark a block of code that may encounter an error and needs special handling.
+`risk` executes its body. If a command raises an exception, ChemQL stores
+the error type name in the Python variable `error` and runs the optional
+`fix` body. A returned string that happens to contain error-looking text
+does not trigger `fix`.
 
 ```text
 risk
-    [result = 10 / 0]
+    [result = 10 / 2]
+    print(result)
+fix
+    print(error)
+cleanup
+    print("Always runs")
 endrisk
 ```
 
-This illustrates the idea of protecting potentially failing code. The exact behaviour depends on ChemQL's implementation of `risk`.
-
 ### `fix`
 
-Use `fix` to define how ChemQL should respond when an error occurs in a corresponding `risk` block.
+The `fix` section runs only when the `risk` section raises an exception.
+The `error` variable contains the exception type name, such as
+`ChemQLError`, `ValueError`, or the error name carried by `signal`.
 
 ```text
 risk
     [result = 10 / 0]
 fix
-    [print("An error occurred")]
+    print("Handled:", error)
 endrisk
 ```
 
-This example illustrates the intended relationship between `risk` and `fix`. Check the implementation for the precise syntax and whether execution continues after an error.
-
 ### `cleanup`
 
-Use `cleanup` to organize code that should run as part of a cleanup phase associated with a protected operation.
+The optional `cleanup` section runs whether the `risk` section succeeds
+or fails, after the risk body and any fix body.
 
 ```text
 risk
-    [print("Performing operation")]
+    print("Performing operation")
 fix
-    [print("Handling an error")]
+    print("Handling an error")
 cleanup
-    [print("Cleaning up")]
+    print("Cleaning up")
 endrisk
 ```
 
-Cleanup logic is useful for keeping resource-management steps separate from the main operation and its error-handling logic.
-
 ### `signal`
 
-Use `signal` to explicitly raise or report an error when a condition cannot be handled normally.
+Use `signal` to raise a named ChemQL error that can be handled by
+`fix`.
 
 ```text
 if temperature < 0
@@ -572,19 +578,18 @@ if temperature < 0
 endif
 ```
 
-A signal can make an invalid state or failed operation explicit instead of allowing execution to proceed silently.
-
 ### Summary
 
 | Keyword | Purpose |
 |---|---|
-| `risk` | Marks potentially failing code for special handling |
-| `fix` | Specifies error-handling behaviour |
-| `cleanup` | Organizes cleanup logic |
-| `signal` | Raises or reports an error |
+| `risk` | Executes the protected body |
+| `fix` | Runs when the risk body raises an exception |
+| `cleanup` | Runs after the risk and fix bodies |
+| `signal` | Raises a named error |
 | `endrisk` | Ends the risk handler |
 
-These features help make ChemQL scripts easier to maintain by separating normal execution, error handling, and cleanup responsibilities.
+Without a `fix` section, an ordinary exception propagates. `cleanup`
+still runs during exception propagation.
 
 ## Functions, definitions, and macros
 
@@ -647,7 +652,8 @@ command lists definitions in the current session.
 
 ## Structs and records
 
-ChemQL v1.4.0 allows required fields defined by a trailing exclamation mark `!` or the `required` keyword
+ChemQL 1.4.1 supports required fields, marked with a trailing `!` or the
+`required` keyword:
 
 ```text
 struct Fruit
@@ -661,8 +667,8 @@ apple.name
 apple.price
 let orange = Fruit{"Orange", 20} // you can use position rather than just keyword arguments
 let banana = Fruit{"Banana", price = 10} // or you can even mix
-
 ```
+
 ```text
 struct Vegetable
     name!
@@ -680,24 +686,24 @@ is fully implemented.
 
 ## Namespaces
 
-Namespaces store functions, structs, records, variables, etc.
-
-To declare functions accessible in the global scope you must use the `public` keyword, everything is private by default, you may still add the `private` keyword for fun
-Example
-```text
-namespace math
-    public let PI = 3.14159265358979
-    public let E = 2.718281828459045
-    public 
-
+Namespaces group functions, structs, records, and variables. Members are
+private by default; use `public` to expose a member through the namespace:
 
+```chemql
+namespace geometry
+    public let PI = 3.141592653589793
+    public func circle_area
+        return [PI * \1 * \1]
+    endfunc
+endnamespace
+
+geometry::circle_area{2}
 ```
 
 ## Standard library
 
-ChemQL loads reusable `.cql` packages with `load`. The loader searches the current
-directory and then the interpreter's adjacent `stdlib/` directory. Preserve the
-folder structure when extracting `chemql_stdlib.zip`.
+ChemQL loads reusable `.cql` packages with `load`. The loader searches the
+current directory first and then ChemQL's bundled `stdlib/` directory.
 
 | Package | Purpose |
 | --- | --- |
@@ -707,6 +713,10 @@ folder structure when extracting `chemql_stdlib.zip`.
 | `collections` | `unique`, `flatten`, `zip`, `pairwise`, frequency counts, product |
 | `datetime` | Current date/time, ISO dates, timestamps, weekday and date arithmetic |
 | `json` | JSON serialization, pretty serialization, parsing and type inspection |
+| `random` | Pseudo-random numbers and sequence sampling |
+| `decimal` | Base-10 decimal arithmetic and quantization |
+| `fractions` | Exact rational numbers and fraction arithmetic |
+| `pathlib` | Path inspection and UTF-8 text file operations |
 
 ```chemql
 load math
@@ -731,9 +741,30 @@ datetime::date_add_days{"2026-10-20", 7}
 
 load json
 json::loads{"{\"formula\": \"H2O\"}"}
+
+load random
+random::seed{42}
+random::randint{1, 6}
+
+load decimal
+decimal::add{"0.1", "0.2"}
+decimal::quantize{"3.14159", "0.01"}
+
+load fractions
+fractions::create{1, 3}
+fractions::add{"1/3", "1/6"}
+
+load pathlib
+pathlib::name{"data/results.csv"}
+pathlib::join{"data", "results.csv"}
 ```
 
 These packages use Python's standard library only; they add no third-party dependencies.
+Use `help{stdlib}` for the package index, `help{math}` for a module
+overview, and `help{math::sqrt}` for function help. These help pages are
+available before loading the package. `pathlib::read_text` and
+`pathlib::write_text` access files with the permissions of the ChemQL
+process.
 
 ## Built-in help
 
@@ -747,10 +778,14 @@ help{syntax}
 help{errors}
 help{files}
 help{chemistry}
+help{stdlib}
+help{math}
+help{math::sqrt}
 ```
 
-Use `help{function_name}` for built-in documentation. The ANSI-colored help screen
-also includes a quick reference to the standard-library packages.
+Use `help{function_name}` for built-in documentation and
+`help{module::function}` for standard-library function documentation. The
+help index also lists the available standard-library packages.
 
 ## Shell integration and scripting
 

{chemql_python-1.4.0.dist-info → chemql_python-1.4.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-chemql/__init__.py,sha256=-ukYmQV6XaXjHOP9lcC5CHiBsaW0kxTIW5E_sBY-DWs,263372
+chemql/__init__.py,sha256=INIV28S5-HJkfc32Fpql9Cbn7tENAuHiPmmj69Zx6V0,272034
 chemql/__main__.py,sha256=5eIIUjMeE90JcHhOamg7KczBDQVHjMHNNCSshBQ6buw,32
 chemql/data/BondEnergies.json,sha256=QZN3iWZrD8125jV41EG1GiRohBtP0CzAP_EDQTfaEKc,8269
 chemql/data/MoleculeBonds.json,sha256=Iw2shYxJScH_tI80IytBYoqVDSbgT7OSqPJUIgKZme4,84262
@@ -8,16 +8,20 @@ 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/stdlib/README.md,sha256=54ECAxQeOcSzUmoGMAPRvjFZL3NIyhrlS5yqHVdbNP4,1111
+chemql/stdlib/README.md,sha256=mv-oXxTcFl1i-PiZehx9wDzY4zFwwg2UxdjPtWv14GI,2045
 chemql/stdlib/collections.cql,sha256=MEiD1BJ11tW9Y7Fbo58xVn6VW_PmCZOZ8IZAICqPml0,804
 chemql/stdlib/datetime.cql,sha256=_EOg9M6Gq8E8fCWrNVZZ50v5nMkOIB5_HqcLKo0Dl-Q,1252
+chemql/stdlib/decimal.cql,sha256=m9gJdNe-D4C2qiPGzsazulPU1tc17JRFl5O7QhW5BI4,882
+chemql/stdlib/fractions.cql,sha256=FzonkrbtCNhy2QT8wEVCyEiOh0pkIOGZNYpfHZZFrYs,1039
 chemql/stdlib/json.cql,sha256=D-l8teKi-9F3Rk3z61WlOB4MWid7BAeR0FEMxDfH2Cs,397
 chemql/stdlib/math.cql,sha256=2RjuZlkrgIaN74G5OkcNmtrosNI9s-eZANDjuGvPzCA,2036
+chemql/stdlib/pathlib.cql,sha256=XkgWoPCtxW7tJKJokx52byb2RiWBKnVzG7X5uPfBFNQ,1332
+chemql/stdlib/random.cql,sha256=Rvxbs-XP_gHUh0AmYmYl9WZXpJJJY3JpNNPn2HUobZU,742
 chemql/stdlib/text.cql,sha256=vBHE9b5SUxTQutaqViMteZeAC580Wg39J1eExkIx4yw,2038
 chemql/stdlib/math/statistics.cql,sha256=TVfazUbGGabUgAkLsg4LtPD8CaqZaj8mPnHbSuAmi40,1083
-chemql_python-1.4.0.dist-info/licenses/LICENSE,sha256=o4ywHC0EwRy2zgIASiRD2sK3Vcsf7LBcTHjDvoJgRE0,1079
-chemql_python-1.4.0.dist-info/METADATA,sha256=yu7GA3fgn3ftUDN0DgB4dRTjdKvRtGGQBY4j84l1GjE,27173
-chemql_python-1.4.0.dist-info/WHEEL,sha256=a-udL2m4V_6Yn8b-uKzWb12RjRxwwMo6ohYFM24tpaY,91
-chemql_python-1.4.0.dist-info/entry_points.txt,sha256=j98ObVWR743an524z24AiWeRsppag-py5cc7l0D0HkI,39
-chemql_python-1.4.0.dist-info/top_level.txt,sha256=9UzHwnk_F6W19Q9nayaFgVyAELQXXwoYjeBgB6MWNr8,7
-chemql_python-1.4.0.dist-info/RECORD,,
+chemql_python-1.4.2.dist-info/licenses/LICENSE,sha256=o4ywHC0EwRy2zgIASiRD2sK3Vcsf7LBcTHjDvoJgRE0,1079
+chemql_python-1.4.2.dist-info/METADATA,sha256=QeC1TFVbuH7-d6PHoSlXPvi52nLyza64rShUECCPjZc,27679
+chemql_python-1.4.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+chemql_python-1.4.2.dist-info/entry_points.txt,sha256=j98ObVWR743an524z24AiWeRsppag-py5cc7l0D0HkI,39
+chemql_python-1.4.2.dist-info/top_level.txt,sha256=9UzHwnk_F6W19Q9nayaFgVyAELQXXwoYjeBgB6MWNr8,7
+chemql_python-1.4.2.dist-info/RECORD,,

{chemql_python-1.4.0.dist-info → chemql_python-1.4.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.2.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any