npdict 0.0.1__py3-none-any.whl

npdict/__init__.py

@@ -0,0 +1,2 @@
+
+from .wrap import NumpyNDArrayWrappedDict

npdict/utils.py

@@ -0,0 +1,18 @@
+
+
+from typing import Tuple
+
+
+class DuplicatedKeyError(Exception):
+    def __init__(self):
+        self.message = "Duplicated keys!"
+
+
+class WrongArrayDimensionException(Exception):
+    def __init__(self, expected_dimension: int, given_dimensions: int):
+        self.message = f"Expected dimension: {expected_dimension}, but {given_dimensions} dimensions are given!"
+
+
+class WrongArrayShapeException(Exception):
+    def __init__(self, expected_shape: Tuple[int, ...], given_shape: Tuple[int, ...]):
+        self.message = f"Expected shape: {', '.join(str(dim_len) for dim_len in expected_shape)}, but the given array shape is {', '.join(str(dim_len) for dim_len in given_shape)}!"

npdict/wrap.py

@@ -0,0 +1,143 @@
+
+from typing import Tuple, Generator
+import sys
+from itertools import product
+from functools import reduce
+
+import numpy as np
+
+if sys.version_info < (3, 11):
+    from typing_extensions import Self
+else:
+    from typing import Self
+
+from .utils import DuplicatedKeyError, WrongArrayDimensionException, WrongArrayShapeException
+
+
+class NumpyNDArrayWrappedDict(dict):
+    def __init__(
+            self,
+            lists_keystrings: list[list[str]],
+            default_initial_value: float=0.0
+    ):
+        super(dict, self).__init__()
+        for list_keystrings in lists_keystrings:
+            if (len(list_keystrings)) != len(set(list_keystrings)):
+                raise DuplicatedKeyError()
+        self._lists_keystrings = lists_keystrings
+        self._keystrings_to_indices = [
+            {
+                keyword: idx for idx, keyword in enumerate(list_keystrings)
+            }
+            for list_keystrings in self._lists_keystrings
+        ]
+
+        self._tensor_dimensions = len(self._lists_keystrings)
+        self._dimension_sizes = [len(l) for l in self._lists_keystrings]
+        self._total_size = reduce(lambda a, b: a*b, self._dimension_sizes)
+
+        self._numpyarray = np.empty(tuple(len(l) for l in self._lists_keystrings))
+        self._numpyarray.fill(default_initial_value)
+
+    def _get_indices(self, item: Tuple[str, ...]) -> list[int]:
+        return [
+            mapping[keyword]
+            for mapping, keyword in zip(self._keystrings_to_indices, item)
+        ]
+
+    def __getitem__(self, item: Tuple[str, ...]) -> float:
+        if len(item) != self.tensor_dimensions:
+            raise WrongArrayDimensionException(self.tensor_dimensions, len(item))
+        indices = self._get_indices(item)
+        return self._numpyarray[tuple(indices)]
+
+    def __setitem__(self, key: Tuple[str, ...], value: float) -> None:
+        if len(key) != self.tensor_dimensions:
+            raise WrongArrayDimensionException(self.tensor_dimensions, len(key))
+        indices = self._get_indices(key)
+        self._numpyarray[tuple(indices)] = value
+
+    def update(self, new_dict: dict):
+        raise TypeError("We cannot update this kind of dict this way!")
+
+    def __iter__(self) -> Generator[Tuple[str, ...], None, None]:
+        for keywords_tuple in product(*self._lists_keystrings):
+            yield keywords_tuple
+
+    def keys(self):
+        return list(self.__iter__())
+
+    def values(self):
+        return [self.__getitem__(keywords_tuple) for keywords_tuple in self.__iter__()]
+
+    def items(self):
+        return [
+            (keywords_tuple, self.__getitem__(keywords_tuple))
+            for keywords_tuple in self.__iter__()
+        ]
+
+    def to_numpy(self) -> np.ndarray:
+        return self._numpyarray
+
+    def generate_dict(self, nparray: np.ndarray) -> Self:
+        if len(nparray.shape) != self.tensor_dimensions:
+            raise WrongArrayDimensionException(self.tensor_dimensions, len(nparray.shape))
+        if nparray.shape != self._numpyarray.shape:
+            raise WrongArrayShapeException(self._numpyarray.shape, nparray.shape)
+        wrapped_dict = NumpyNDArrayWrappedDict(self._lists_keystrings)
+        wrapped_dict._numpyarray = nparray
+        return wrapped_dict
+
+    def __repr__(self) -> str:
+        return f"<NumpyNDArrayWrappedDict: dimensions ({', '.join(map(str, self.dimension_sizes))})>"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __len__(self) -> int:
+        return self._total_size
+
+    def to_dict(self) -> dict[Tuple[str, ...], float]:
+        return {
+            keywords_tuple: value for keywords_tuple, value in self.items()
+        }
+
+    @classmethod
+    def from_dict_given_keywords(
+            cls,
+            lists_keywords: list[list[str]],
+            oridict: dict[Tuple[str, ...], float],
+            default_initial_value: float = 0.0
+    ) -> Self:
+        wrapped_dict = NumpyNDArrayWrappedDict(
+            lists_keywords,
+            default_initial_value=default_initial_value
+        )
+        for keywords_tuple in product(*lists_keywords):
+            wrapped_dict[keywords_tuple] = oridict.get(keywords_tuple, default_initial_value)
+        return wrapped_dict
+
+    @classmethod
+    def from_dict(
+            cls,
+            oridict: dict[Tuple[str, ...], float],
+            default_initial_value: float = 0.0
+    ) -> Self:
+        nbdims = len(next(iter(oridict)))
+        lists_keystrings = [
+            list(set(keystring[i] for keystring in oridict.keys()))
+            for i in range(nbdims)
+        ]
+        return cls.from_dict_given_keywords(
+            lists_keystrings,
+            oridict,
+            default_initial_value=default_initial_value
+        )
+
+    @property
+    def tensor_dimensions(self) -> int:
+        return self._tensor_dimensions
+
+    @property
+    def dimension_sizes(self) -> list[int]:
+        return self._dimension_sizes

npdict-0.0.1.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: npdict
+Version: 0.0.1
+Summary: A Python dictionary wrapper for numpy arrays
+Author-email: Kwan Yuet Stephen Ho <stephenhky@yahoo.com.hk>
+License: MIT
+Project-URL: Repository, https://github.com/stephenhky/npdict
+Project-URL: Issues, https://github.com/stephenhky/npdict/issues
+Keywords: dictionary,numpy
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: typing-extensions
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+
+[![GitHub release](https://img.shields.io/github/release/stephenhky/npdict.svg?maxAge=3600)](https://github.com/stephenhky/npdict/releases)
+[![pypi](https://img.shields.io/pypi/v/npdict.svg?maxAge=3600)](https://pypi.org/project/npdict/)
+[![download](https://img.shields.io/pypi/dm/npdict.svg?maxAge=2592000&label=installs&color=%2327B1FF)](https://pypi.org/project/npdict/)
+
+# `npdict`: Python Package for Dictionary Wrappers for Numpy Arrays
+
+This Python package, `npdict`, aims at facilitating holding numerical
+values in a Python dictionary, but at the same time retaining the
+ultra-high performance supported by NumPy. It supports an object
+which is a Python dictionary on the surface, but numpy behind the
+back, facilitating fast assignment and retrieval of values
+and fast computation of numpy arrays.
+
+## Installation
+
+To install, in your terminal, simply enter:
+
+```
+pip install npdict
+```
+
+## Quickstart
+
+### Instantiation
+
+Suppose you are doing a similarity dictionary between two sets of words.
+And each of these sets have words:
+
+```
+document1 = ['president', 'computer', 'tree']
+document2 = ['chairman', 'abacus', 'trees']
+```
+
+And you can build a dictionary like this:
+
+```
+import numpy as np
+from npdict import NumpyNDArrayWrappedDict
+
+similarity_dict = NumpyNDArrayWrappedDict([document1, document2])
+```
+
+An `npdict.NumpyNDArrayWrappedDict` instance is instantiated. It is 
+a Python dict:
+
+```
+isinstance(similarity_dict, dict)  # which gives `True`
+```
+
+It has a matrix inside with default value 0.0 (and the initial default value can
+be changed to other values when the instance is instantiated.)
+
+```
+similarity_dict.to_numpy()
+```
+giving
+```
+array([[0., 0., 0.],
+       [0., 0., 0.],
+       [0., 0., 0.]])
+```
+
+### Value Assignments
+
+Now you can assign values just like what you do to a Python dictionary:
+
+```
+similarity_dict['president', 'chairman'] = 0.9
+similarity_dict['computer', 'abacus'] = 0.7
+similarity_dict['tree', 'trees'] = 0.95
+```
+
+And it has changed the inside numpy array to be:
+
+```
+array([[0.9  , 0.  , 0.  ],
+       [0.  , 0.7 , 0.  ],
+       [0.  , 0.  , 0.95]])
+```
+
+### Generation of New Object from the Old One
+
+If you want to create another dict using the same words, but 
+a manipulation of the original value, 25 percent discount
+of the original one for example, you can do something like this:
+
+```
+new_similarity_dict = similarity_dict.generate_dict(similarity_dict.to_numpy()*0.75)
+```
+
+And you got a new dictionary with numpy array to be:
+
+```
+new_similarity_dict.to_numpy()
+```
+giving
+```
+array([[0.675 , 0.    , 0.    ],
+       [0.    , 0.525 , 0.    ],
+       [0.    , 0.    , 0.7125]])
+```
+
+This is a simple operation. But the design of this wrapped Python
+dictionary is that you can perform any fast or optimized operation
+on your numpy array (using numba or Cython, for examples),
+while retaining the keywords as your dictionary.
+
+### Retrieval of Values
+
+At the same time, you can set new values just like above, or retrieve
+values as if it is a Python dictionary:
+
+```
+similarity_dict['president', 'chairman']
+```
+
+### Conversion to a Python Dictionary
+
+You can also convert this to an ordinary Python dictionary:
+
+```
+raw_similarity_dict = similarity_dict.to_dict()
+```
+
+### Instantiation from a Python Dictionary
+
+And you can convert a Python dictionary of this type back to 
+`npdict.NumpyNDArrayWrappedDict` by (recommended)
+
+```
+new_similarity_dict_2 = NumpyNDArrayWrappedDict.from_dict_given_keywords([document1, document2], raw_similarity_dict)
+```
+
+Or you can even do this (not recommended):
+
+```
+new_similarity_dict_3 = NumpyNDArrayWrappedDict.from_dict(raw_similarity_dict)
+```
+
+It is not recommended because the order of the keys are not retained in this way.
+Use it with caution.

npdict-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+npdict/__init__.py,sha256=ux0JiBWDLIy_L-ecnTyQggbvqyDWGnA8ugoaux-ToG8,43
+npdict/utils.py,sha256=qKyXJuO3Nm1oLjX4tSbvWzqMkCieDH6sIC-ZO_CD0E4,680
+npdict/wrap.py,sha256=74seK4p5VDl73N3wG_6fqEd6BQO86eB4tQZWPw7m9rM,4902
+npdict-0.0.1.dist-info/licenses/LICENSE,sha256=ufwgIO2ky6BJ35g3fjy2fgU7-tkFlYu9C5K3WaYaPaA,1063
+npdict-0.0.1.dist-info/METADATA,sha256=lWFxoUEdOnZbYPaDI2wsLyLOm0EHcyzp_cSLgEb_7cg,4905
+npdict-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+npdict-0.0.1.dist-info/top_level.txt,sha256=6UZJ6RoYitrWz9KNuPH5SwIKL83tz5A0AluK29GoOD8,7
+npdict-0.0.1.dist-info/RECORD,,

npdict-0.0.1.dist-info/WHEEL

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

npdict-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025 Kwan Yuet Stephen Ho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npdict-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+npdict