chemql-python 1.4.1__tar.gz → 1.4.2__tar.gz

{chemql_python-1.4.1/src/chemql_python.egg-info → chemql_python-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chemql-python
-Version: 1.4.1
+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.1 → chemql_python-1.4.2}/README.md

@@ -6,7 +6,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
@@ -509,49 +509,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
@@ -559,19 +565,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
 
@@ -634,7 +639,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
@@ -648,8 +654,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!
@@ -667,24 +673,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 |
 | --- | --- |
@@ -694,6 +700,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
@@ -718,9 +728,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
 
@@ -734,10 +765,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.1 → chemql_python-1.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "chemql-python"
-version = "1.4.1"
+version = "1.4.2"
 authors = [
     { name = "Mohammad Rakibul Islam", email = "rakibulofficial1017@gmail.com" }
 ]