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

purem/__init__.py

@@ -2,5 +2,4 @@ from purem.env_config import load_env_config
 
 from purem.core import Purem
 
-
-purem = Purem(licenced_key=load_env_config().PUREM_LICENSE_KEY)
+purem = Purem()

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.
@@ -11,7 +11,6 @@ Additional Use Grant: Free for personal and non-commercial research use only.
 SPDX-License-Identifier: BUSL-1.1
 """
 
-import base64
 import ctypes
 import json
 import os
@@ -19,83 +18,102 @@ import shutil
 import ssl
 import urllib.request
 import zipfile
-from typing import List, Optional, Dict
+from pathlib import Path
+from typing import Optional, Dict
 
 import certifi as certifi
-import numpy as np
 from numpy import ndarray
 
-from purem.env_config import load_env_config
+from purem.env_config import load_env_config, EnvConfig
 from purem.file_structure import FileStructure
 from purem.loader import Loader
 from purem.logger import Logger
-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):
-        self._license_key = licenced_key or None
-        self._lib = None
-        self._download_binary_url = None
+    def __init__(self):
+        """
+        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._lib: Optional[ctypes.CDLL] = None
+        self._download_binary_url: Optional[str] = None
         self._ctx = ssl.create_default_context(cafile=certifi.where())
         self._file_structure = FileStructure()
-        self._binary_path = self._file_structure.get_binary_path()
-        self._binary_project_root_path = (
+        self._binary_path: Path = self._file_structure.get_binary_path()
+        self._binary_project_root_path: Path = (
             self._file_structure.get_binary_project_root_path()
         )
-        self._binary_archive_path = self._file_structure.get_binary_archive_path()
-        self._binary_archive_path_tmp = (
+        self._binary_archive_path: Path = self._file_structure.get_binary_archive_path()
+        self._binary_archive_path_tmp: Path = (
             self._file_structure.get_binary_archive_path_tmp()
         )
-        self._env = load_env_config()
-        self._config_url = (
+        self._env: EnvConfig = load_env_config()
+        self._license_key: Optional[str] = self._env.PUREM_LICENSE_KEY or None
+        self._config_url: str = (
                 self._env.PUREM_CONFIG_URL
                 or "https://api.worktif.com/v2/portal/products/purem/config"
         )
-        self._loader = Loader()
-        self._log = Logger()
+        self._loader: Loader = Loader()
+        self._log: Logger = Logger()
+        print('self._license_key: ', self._license_key)
+
+        if self._license_key is not None:
+            self.configure(license_key=self._license_key)
 
     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 +127,50 @@ 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))
-        self._lib.purem(ptr, array.size)
-        return shifted_arr
+        try:
+            ptr = array.ctypes.data_as(ctypes.POINTER(ctypes.c_float))
+            self._lib.purem(ptr, array.size)
+            return array
+        except Exception as e:
+            raise ValueError(
+                self._log.info(
+                    "Purem requires a valid license key to initialize.\n"
+                    "You can obtain your key at https://worktif.com or through your enterprise deployment.",
+                    verbose=True
+                )
+            )
 
-    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("/")
@@ -141,17 +179,52 @@ class Purem:
         binary_url = f"{protocol}://{base}/{path}{self._license_key}"
         return binary_url
 
-    def _tune_binary(self):
+    def _tune_binary(self) -> None:
+        """
+        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):
+    def _tune_project_root_binary(self) -> None:
+        """
+        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(
@@ -166,7 +239,22 @@ class Purem:
         except Exception:
             return None
 
-    def _set_binary(self):
+    def _set_binary(self) -> None:
+        """
+        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):
@@ -211,10 +299,20 @@ class Purem:
                     )
                 )
 
-    def _download_and_extract_binary(self):
+    def _download_and_extract_binary(self) -> None:
+        """
+        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:
@@ -250,3 +348,16 @@ class Purem:
             )
 
         self._binary_archive_path.unlink()
+
+    def has_license_key(self) -> bool:
+        """
+        Checks if an object has a valid license key.
+
+        This method evaluates whether the `_license_key` attribute of
+        the object is not `None`, implying the presence of a license key.
+
+        :return: Returns `True` if the `_license_key` attribute is not
+            `None`, otherwise returns `False`.
+        :rtype: bool
+        """
+        return self._license_key is not None

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.
@@ -19,8 +19,8 @@ class Logger:
         self._env = load_env_config()
         self._default_info_message = f"Something went wrong"
 
-    def info(self, message: str) -> str:
-        if self._env.PUREM_VERBOSE is True:
+    def info(self, message: str, verbose: bool = False) -> str:
+        if self._env.PUREM_VERBOSE is True or verbose is True:
             return f"[purem]: {message}\n"
         else:
             return f"[purem]: {self._default_info_message}\n"

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.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: purem
-Version: 2.1.6
+Version: 3.0.2
 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
@@ -25,7 +25,6 @@ Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: numpy~=2.1.3
-Requires-Dist: pytest~=8.3.5
 Requires-Dist: numba~=0.61.0
 Requires-Dist: certifi~=2025.1.31
 Requires-Dist: pydantic~=2.10.6
@@ -33,6 +32,8 @@ Requires-Dist: dotenv~=0.9.9
 Requires-Dist: python-dotenv~=1.1.0
 Requires-Dist: setuptools~=65.5.1
 Requires-Dist: requests~=2.32.3
+Requires-Dist: pytest~=8.3.5
+Requires-Dist: pytest-env~=1.1.5
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: flake8; extra == "dev"

purem-3.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+purem/__init__.py,sha256=of-z4lRvk7cmLLsCbiXHIPXVjP0FHBCByndtPgINfT0,92
+purem/core.py,sha256=kGhCPlSwyTlmjsv970H_DSCBrvMCL6TA2-EHmwsgQ3c,15830
+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=vZHUGwL-MXJPNBoHIxqLf26KOF9qk4xj2qdgUhRas8c,1281
+purem/utils.py,sha256=wjLHukHROX3GKJoEwXCR9X6CfqT70M1Mj6FcLtFUxJ8,923
+purem-3.0.2.dist-info/licenses/LICENSE,sha256=5WFXHK6Xc_wj2EtvzVtd9TIC4cWEZJS8ECNTuvutsiE,1636
+purem-3.0.2.dist-info/METADATA,sha256=fuDQr3LQrympk6wCLUqEbqb-Raxb5qxrAmrnH1BQZJg,5677
+purem-3.0.2.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+purem-3.0.2.dist-info/top_level.txt,sha256=EjS75KEpZUEKSV2TFGW6w5aLqY9nUyO6Gq2ATz-KeZM,6
+purem-3.0.2.dist-info/RECORD,,

{purem-2.1.6.dist-info → purem-3.0.2.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,,