purem 2.1.6__py3-none-any.whl → 3.0.1__py3-none-any.whl

purem/core.py

@@ -2,7 +2,7 @@
 Business Source License 1.1
 
 Copyright (C) 2025 Raman Marozau, raman@worktif.com
-Use of this software is governed by the Business Source License included in the LICENSE.TXT file and at www.mariadb.com/bsl11.
+Use of this software is governed by the Business Source License included in the LICENSE file and at www.mariadb.com/bsl11.
 
 Change Date: Never
 On the date above, in accordance with the Business Source License, use of this software will be governed by the open source license specified in the LICENSE file.
@@ -34,46 +34,48 @@ from purem.utils import _compute_shifted_jit
 
 class Purem:
     """
-    Summary of what the class does.
+    Represents the functionality of the Purem system, including initialization, configuration,
+    and operations using a shared library binary. The class provides methods for setting up
+    license keys, managing binary paths, loading configurations from a Content Delivery Network (CDN),
+    and executing specific computations such as the softmax function. It handles both high-level
+    configuration details and low-level interactions with binary libraries.
 
-    The Purem class is used to manage and handle the initialization, configuration, and
-    operation of the Purem environment and its associated runtime, including license management,
-    binary handling, and API configuration. It centralizes the setup of the Purem runtime,
-    ensuring that all necessary binaries, license checks, and configurations are in place.
-
-    The class supports downloading and extracting binaries, setting up runtime libraries, and providing utility
-    methods such as softmax computation, license validation, and URL construction to interact with remote
-    and local systems.
-
-    :ivar _license_key: The license key used for Purem initialization and validation.
+    :ivar _license_key: The license key used to initialize the system.
     :type _license_key: Optional[str]
-    :ivar _lib: The dynamically loaded library object for the Purem binary.
-    :type _lib: ctypes.CDLL
-    :ivar _download_binary_url: The URL for downloading the Purem binary.
+    :ivar _lib: Represents the dynamically loaded shared library for performing operations.
+    :type _lib: Optional[ctypes.CDLL]
+    :ivar _download_binary_url: URL for downloading the binary configuration.
     :type _download_binary_url: Optional[str]
-    :ivar _ctx: SSL context used for secure connections, initialized using the system's certificates.
+    :ivar _ctx: SSL context for establishing secure connections.
     :type _ctx: ssl.SSLContext
-    :ivar _file_structure: Manages file paths and structures related to Purem binary and runtime.
+    :ivar _file_structure: The handler for managing binary-related paths and file structure.
     :type _file_structure: FileStructure
-    :ivar _binary_path: The path to the main Purem binary.
-    :type _binary_path: pathlib.Path
-    :ivar _binary_project_root_path: The path to the project root Purem binary.
-    :type _binary_project_root_path: pathlib.Path
-    :ivar _binary_archive_path: The path where the binary archive is stored.
-    :type _binary_archive_path: pathlib.Path
-    :ivar _binary_archive_path_tmp: The temporary path for binary archive operations.
-    :type _binary_archive_path_tmp: pathlib.Path
-    :ivar _env: Environment configuration used in Purem operations, including URLs.
+    :ivar _binary_path: Absolute path of the binary file used for execution.
+    :type _binary_path: str
+    :ivar _binary_project_root_path: Path to the binary located in the project root.
+    :type _binary_project_root_path: str
+    :ivar _binary_archive_path: Path where binary archives are stored.
+    :type _binary_archive_path: str
+    :ivar _binary_archive_path_tmp: Temporary path for binary archive operations.
+    :type _binary_archive_path_tmp: str
+    :ivar _env: Object holding environment configurations and variables.
     :type _env: Any
-    :ivar _config_url: URL for retrieving Purem configuration, either from an environment variable or a default.
+    :ivar _config_url: URL for retrieving Purem's configuration from a remote server.
     :type _config_url: str
-    :ivar _loader: Loader utility for displaying loading messages during lengthy operations.
+    :ivar _loader: Loader instance for displaying runtime messages during setup and initialization.
     :type _loader: Loader
-    :ivar _log: Logger utility for tracking and managing logging in the Purem operations.
+    :ivar _log: Logger instance for recording system messages and error details.
     :type _log: Logger
     """
 
     def __init__(self, licenced_key: Optional[str] = None):
+        """
+        Represents the initialization and configuration of an environment, license key,
+        and file structure required for the system's binary operations.
+
+        :param licenced_key: Optional license key string for initializing the system.
+        :type licenced_key: Optional[str]
+        """
         self._license_key = licenced_key or None
         self._lib = None
         self._download_binary_url = None
@@ -89,13 +91,27 @@ class Purem:
         )
         self._env = load_env_config()
         self._config_url = (
-                self._env.PUREM_CONFIG_URL
-                or "https://api.worktif.com/v2/portal/products/purem/config"
+            self._env.PUREM_CONFIG_URL
+            or "https://api.worktif.com/v2/portal/products/purem/config"
         )
         self._loader = Loader()
         self._log = Logger()
 
     def configure(self, license_key: Optional[str] = None) -> None:
+        """
+        Configures the system with a given license key.
+
+        This method sets up the license key required for initializing the system. If no
+        license key is provided during configuration, the method checks if it was
+        already initialized. If the license key remains unset, it raises a ValueError
+        to indicate that a valid license key is mandatory for the setup.
+
+        :raises ValueError: Raised when no valid license key is provided during
+            configuration.
+
+        :param license_key: An optional string representing the license key.
+        :return: None
+        """
         if self._license_key is None and license_key is not None:
             self._license_key = license_key
         if self._license_key is None:
@@ -109,30 +125,41 @@ class Purem:
         self._set_binary()
 
     def softmax(self, array: ndarray) -> ndarray:
-        shifted_arr = np.empty(array.size, dtype=np.float32)
-        _compute_shifted_jit(array, shifted_arr)
-        ptr = shifted_arr.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
+        ptr = array.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
         self._lib.purem(ptr, array.size)
-        return shifted_arr
+        return array
 
-    def softmax_pure(self, arr, size) -> List[any]:
+    def softmax_pure(self, ptr, size) -> None:
         """
-        Compute the softmax of an array using a pure implementation.
+        Computes the softmax function on the provided array using pure library implementation.
 
-        The softmax function is used to normalize an input array into a probability
-        distribution. It is often used in machine learning for classification tasks
-        where the output represents probabilities of different classes. This method
-        employs a pure implementation by calling a pre-defined library function.
+        This function applies the softmax transformation to the data pointed to by the
+        pointer and modifies it in-place. The underlying implementation is handled
+        by a pure library function call.
 
-        :param arr: The input array containing numeric values to be transformed
-            into a probability distribution.
-        :param size: The size of the input array `arr`.
-        :return: A list representing the normalized probability distribution obtained
-            by applying the softmax function.
+        :param ptr: Pointer to the data array that the softmax is to be applied on.
+        :type ptr: Any
+        :param size: The number of elements in the data array to be processed.
+        :type size: int
+        :return: None
         """
-        return self._lib.purem(arr, size)
+        self._lib.purem(ptr, size)
 
     def _build_url(self, config: dict) -> Optional[str]:
+        """
+        Constructs a URL based on the provided configuration dictionary. The method
+        combines protocol, base URL, path, and appends a license key to generate
+        a complete binary URL. If the provided configuration is None, the method
+        returns None immediately.
+
+        :param config: A dictionary containing the parts needed to construct the
+            URL. The keys usually include:
+            - `base_url`: The base of the URL (e.g., domain).
+            - `protocol`: The URL protocol (e.g., "http" or "https").
+            - `pathname`: The path to append to the base URL.
+        :return: Returns the complete binary URL as a string if the configuration
+            is valid. If the given configuration is None, it returns None.
+        """
         if config is None:
             return None
         base = config.get("base_url", "").rstrip("/")
@@ -142,16 +169,51 @@ class Purem:
         return binary_url
 
     def _tune_binary(self):
+        """
+        Tunes the binary by loading the specified binary file as a shared library
+        and setting up its function signatures for further use.
+
+        This method initializes the shared library from the specified `_binary_path`
+        and configures the expected argument types and return type for the `purem` function
+        provided by the library.
+
+        :raises OSError: If the library at `_binary_path` cannot be loaded by `ctypes.CDLL`.
+
+        :rtype: None
+        """
         self._lib = ctypes.CDLL(str(self._binary_path))
         self._lib.purem.argtypes = [ctypes.POINTER(ctypes.c_float), ctypes.c_size_t]
         self._lib.purem.restype = None
 
     def _tune_project_root_binary(self):
+        """
+        Tuning the project root binary configuration.
+
+        This private method initializes a connection to the binary library
+        located at the project's root path. It achieves this by loading the
+        binary through the use of the `ctypes.CDLL` method. The method also
+        sets expected argument types and a return type for a specific function
+        available in the shared library.
+
+        :return: None
+        """
         self._lib = ctypes.CDLL(str(self._binary_project_root_path))
         self._lib.purem.argtypes = [ctypes.POINTER(ctypes.c_float), ctypes.c_size_t]
         self._lib.purem.restype = None
 
     def _load_from_latest_cdn_index(self) -> Optional[Dict]:
+        """
+        Attempts to load the latest configuration from a CDN index, if a config URL is provided.
+        The method sends a request to the configured URL, reads its response, and parses it into
+        a dictionary. If there is no configured URL or an exception occurs during the process, it
+        returns None.
+
+        :raises Exception: If an error occurs during the request or while reading the response.
+
+        :return: A dictionary containing the parsed configuration data if the operation is
+            successful, or None if no config URL is provided or an error occurs.
+        :rtype: Optional[Dict]
+        """
         try:
             if self._config_url is not None:
                 req = urllib.request.Request(
@@ -167,6 +229,21 @@ class Purem:
             return None
 
     def _set_binary(self):
+        """
+        Sets and initializes the binary for the Purem runtime environment. The method ensures that a valid binary
+        is available and properly configured. If a valid license key or binary is not found, the method will attempt
+        to download, validate, and extract the required binary files. If initialization fails at any stage,
+        appropriate errors are raised with detailed logging for debugging and support purposes.
+
+        :param self: Represents the instance of the class.
+        :type self: PuremRuntime
+
+        :raises ValueError: Raised if a valid license key is missing and cannot proceed with initialization.
+        :raises RuntimeError: Raised if the purem binary fails to load or cannot be initialized due to local issues,
+            license mismatch, or any other unexpected errors.
+
+        :return: None
+        """
         if os.path.exists(self._binary_path):
             self._tune_binary()
         elif os.path.exists(self._binary_project_root_path):
@@ -185,8 +262,8 @@ class Purem:
                 )
                 self._loader.start()
                 self._download_binary_url = (
-                        self._build_url(self._load_from_latest_cdn_index())
-                        or f"{self._env.PUREM_DOWNLOAD_BINARY_URL}{self._license_key}"
+                    self._build_url(self._load_from_latest_cdn_index())
+                    or f"{self._env.PUREM_DOWNLOAD_BINARY_URL}{self._license_key}"
                 )
                 self._download_and_extract_binary()
                 self._loader.stop()
@@ -212,9 +289,19 @@ class Purem:
                 )
 
     def _download_and_extract_binary(self):
+        """
+        Downloads a binary file from a given URL, saves it temporarily, and extracts its
+        contents to a specific directory. Handles errors related to incomplete or
+        corrupted downloads and archives.
+
+        Raises runtime errors with detailed context if an issue occurs during download
+        or extraction. Ensures successful extraction and logs the output location.
+
+        :raises RuntimeError: If the download or extraction process fails due to
+            corrupted archive or any other unexpected issue.
+        """
         req = urllib.request.Request(
-            self._download_binary_url,
-            headers={"User-Agent": "Mozilla/5.0"}
+            self._download_binary_url, headers={"User-Agent": "Mozilla/5.0"}
         )
 
         try:

purem/env_config.py

@@ -2,7 +2,7 @@
 Business Source License 1.1
 
 Copyright (C) 2025 Raman Marozau, raman@worktif.com
-Use of this software is governed by the Business Source License included in the LICENSE.TXT file and at www.mariadb.com/bsl11.
+Use of this software is governed by the Business Source License included in the LICENSE file and at www.mariadb.com/bsl11.
 
 Change Date: Never
 On the date above, in accordance with the Business Source License, use of this software will be governed by the open source license specified in the LICENSE file.

purem/file_structure.py

@@ -2,7 +2,7 @@
 Business Source License 1.1
 
 Copyright (C) 2025 Raman Marozau, raman@worktif.com
-Use of this software is governed by the Business Source License included in the LICENSE.TXT file and at www.mariadb.com/bsl11.
+Use of this software is governed by the Business Source License included in the LICENSE file and at www.mariadb.com/bsl11.
 
 Change Date: Never
 On the date above, in accordance with the Business Source License, use of this software will be governed by the open source license specified in the LICENSE file.

purem/loader.py

@@ -2,7 +2,7 @@
 Business Source License 1.1
 
 Copyright (C) 2025 Raman Marozau, raman@worktif.com
-Use of this software is governed by the Business Source License included in the LICENSE.TXT file and at www.mariadb.com/bsl11.
+Use of this software is governed by the Business Source License included in the LICENSE file and at www.mariadb.com/bsl11.
 
 Change Date: Never
 On the date above, in accordance with the Business Source License, use of this software will be governed by the open source license specified in the LICENSE file.
@@ -18,21 +18,80 @@ import time
 
 class Loader:
     def __init__(self, message="Downloading"):
+        """
+        Represents a CLI-based animation that indicates a background task.
+
+        This class is designed to show a simple animation in the terminal
+        to convey the progress of an ongoing background task. The animation
+        runs in a separate thread to ensure that it does not block the main
+        thread's operations.
+
+        Attributes
+        ----------
+        _message : str
+            The text message displayed along with the animation.
+        _thread : threading.Thread
+            The thread responsible for running the animation in the background.
+        done : bool
+            A control flag to stop the animation when set to True.
+
+        :param message: The message to display alongside the animation. Defaults to
+            "Downloading".
+        """
         self._message = message
         self._thread = threading.Thread(target=self._animate, daemon=True)
         self.done = False
 
     def set_message(self, message: str):
+        """
+        Sets the message attribute of the instance.
+
+        :param message: A string representing the message to be assigned.
+        :type message: str
+        """
         self._message = message
 
     def start(self):
+        """
+        Starts the thread associated with this instance.
+
+        This method initiates the thread's execution by invoking the `start`
+        method on the `self._thread` object. It assumes that the `self._thread`
+        attribute has been properly initialized and is a valid thread instance.
+
+        :return: None
+        """
         self._thread.start()
 
     def stop(self):
+        """
+        Represents a mechanism to stop a thread execution gracefully.
+
+        This class or function provides a controlled way to stop a running thread
+        by marking it as done and waiting for the thread to conclude its execution.
+        It ensures the thread completes its ongoing tasks correctly before stopping.
+
+        :attributes:
+            done: Indicates whether the thread execution is flagged to stop.
+            _thread: The thread instance being managed.
+
+        :return: None
+        """
         self.done = True
         self._thread.join()
 
     def _animate(self):
+        """
+        Handles the animation of a loading spinner for a CLI-based task. The animation
+        displays a series of symbols in rotation while the task is ongoing. It
+        continues until the flag `self.done` is set to True. Once the task is complete,
+        a "done" message is displayed.
+
+        This method is designed to provide a simple user feedback mechanism during
+        long-running or background operations in command-line applications.
+
+        :return: None
+        """
         symbols = ["|", "/", "-", "\\"]
         i = 0
         while not self.done:

purem/logger.py

@@ -2,7 +2,7 @@
 Business Source License 1.1
 
 Copyright (C) 2025 Raman Marozau, raman@worktif.com
-Use of this software is governed by the Business Source License included in the LICENSE.TXT file and at www.mariadb.com/bsl11.
+Use of this software is governed by the Business Source License included in the LICENSE file and at www.mariadb.com/bsl11.
 
 Change Date: Never
 On the date above, in accordance with the Business Source License, use of this software will be governed by the open source license specified in the LICENSE file.

purem/utils.py

@@ -2,7 +2,7 @@
 Business Source License 1.1
 
 Copyright (C) 2025 Raman Marozau, raman@worktif.com
-Use of this software is governed by the Business Source License included in the LICENSE.TXT file and at www.mariadb.com/bsl11.
+Use of this software is governed by the Business Source License included in the LICENSE file and at www.mariadb.com/bsl11.
 
 Change Date: Never
 On the date above, in accordance with the Business Source License, use of this software will be governed by the open source license specified in the LICENSE file.

{purem-2.1.6.dist-info → purem-3.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: purem
-Version: 2.1.6
+Version: 3.0.1
 Summary: The official high-performance mapping function for mixed-type arrays powered by Work TIF Ltd.
 Author-email: Raman Marozau <raman@worktif.com>
 License-Expression: BUSL-1.1

purem-3.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+purem/__init__.py,sha256=zF_hOKYn8X3jeoBxQ9X1irDi6HCPQ-HRcMP5fcocaNw,141
+purem/core.py,sha256=fAWRKSzPp4x0YNKm_HrHWV9j38gISl2fLU6XyYIK33U,14772
+purem/env_config.py,sha256=o1VujOYEH0XXVHbM0j84BEbO2FqlWVQ088DxlSfsvRU,2663
+purem/file_structure.py,sha256=nYTSj74gDsnVAYAwkb5NGE1QHXvlkaYuaafB_FIAMaI,3337
+purem/loader.py,sha256=GDeuiqZcKvZQEDaUg2TO5rC-WwVcjIgKqNEpF602mmg,3610
+purem/logger.py,sha256=56pSIjyQal4IvaFzRpKBaQ8oMAdt-u638QK6uex-cRQ,1239
+purem/utils.py,sha256=wjLHukHROX3GKJoEwXCR9X6CfqT70M1Mj6FcLtFUxJ8,923
+purem-3.0.1.dist-info/licenses/LICENSE,sha256=5WFXHK6Xc_wj2EtvzVtd9TIC4cWEZJS8ECNTuvutsiE,1636
+purem-3.0.1.dist-info/METADATA,sha256=qe1GhJoHEKQyjhJH7NR4c4XVhNlPhifKA-H_bY8HITg,5644
+purem-3.0.1.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+purem-3.0.1.dist-info/top_level.txt,sha256=EjS75KEpZUEKSV2TFGW6w5aLqY9nUyO6Gq2ATz-KeZM,6
+purem-3.0.1.dist-info/RECORD,,

{purem-2.1.6.dist-info → purem-3.0.1.dist-info}/WHEEL

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

purem-2.1.6.dist-info/RECORD

@@ -1,12 +0,0 @@
-purem/__init__.py,sha256=zF_hOKYn8X3jeoBxQ9X1irDi6HCPQ-HRcMP5fcocaNw,141
-purem/core.py,sha256=urg3JSdg2A-iVjYHJYPLnvNDPwUP5PElECAtSK1HRQY,10677
-purem/env_config.py,sha256=q1zOaiQLgqACfpU9d21kh004RSLjomORC8ZIvqFdnZE,2667
-purem/file_structure.py,sha256=8PRP9uk6PApOHwKF5Pfyg7CbZfgqTVwzV4NrYLJkTjY,3341
-purem/loader.py,sha256=F-4dFzBtmxnB8r4Y620WJhJ6-yAiBjmvZYCi8Z1ykkU,1274
-purem/logger.py,sha256=bs7jtx1cHmyuM6Irdcq60gTMURCai2pi5MIUB3TQcSQ,1243
-purem/utils.py,sha256=Kv0DPvt8SpSfKp4ar03ZP26Aj60dxW5Gf8B9FKKUrDc,927
-purem-2.1.6.dist-info/licenses/LICENSE,sha256=5WFXHK6Xc_wj2EtvzVtd9TIC4cWEZJS8ECNTuvutsiE,1636
-purem-2.1.6.dist-info/METADATA,sha256=wLqdwfxAnJi0FLLocMn7zFf4ayKwUpvA2OMjN6E1Y78,5644
-purem-2.1.6.dist-info/WHEEL,sha256=ck4Vq1_RXyvS4Jt6SI0Vz6fyVs4GWg7AINwpsaGEgPE,91
-purem-2.1.6.dist-info/top_level.txt,sha256=EjS75KEpZUEKSV2TFGW6w5aLqY9nUyO6Gq2ATz-KeZM,6
-purem-2.1.6.dist-info/RECORD,,