npdict 0.0.1__tar.gz

npdict-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI/CD Pipeline
+
+on:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[test]
+
+    - name: Test with pytest
+      run: |
+        pytest

npdict-0.0.1/.gitignore

@@ -0,0 +1,486 @@
+### JetBrains+all template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### VisualStudioCode template
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### VirtualEnv template
+# Virtualenv
+# http://iamzed.com/2009/05/07/a-primer-on-virtualenv/
+.Python
+[Bb]in
+[Ii]nclude
+[Ll]ib
+[Ll]ib64
+[Ll]ocal
+[Ss]cripts
+pyvenv.cfg
+.venv
+pip-selfcheck.json
+
+### Linux template
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### JupyterNotebooks template
+# gitignore template for Jupyter Notebooks
+# website: http://jupyter.org/
+
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# IPython
+profile_default/
+ipython_config.py
+
+# Remove previous ipynb_checkpoints
+#   git rm -r .ipynb_checkpoints/
+
+### JetBrains+iml template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### macOS template
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+

npdict-0.0.1/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include pyproject.toml
+include LICENSE

npdict-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,142 @@
+
+[![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/npdict/__init__.py

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

npdict-0.0.1/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-0.0.1/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/npdict.egg-info/PKG-INFO

@@ -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/npdict.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+.gitignore
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+.github/workflows/ci.yml
+npdict/__init__.py
+npdict/utils.py
+npdict/wrap.py
+npdict.egg-info/PKG-INFO
+npdict.egg-info/SOURCES.txt
+npdict.egg-info/dependency_links.txt
+npdict.egg-info/not-zip-safe
+npdict.egg-info/requires.txt
+npdict.egg-info/top_level.txt
+test/__init__.py
+test/test_wrap.py

npdict-0.0.1/npdict.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

npdict-0.0.1/npdict.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

npdict-0.0.1/npdict.egg-info/requires.txt

@@ -0,0 +1,5 @@
+numpy
+typing-extensions
+
+[test]
+pytest

npdict-0.0.1/npdict.egg-info/top_level.txt

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

npdict-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools", "setuptools-scm", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "npdict"
+version = "0.0.1"
+authors = [
+    {name = "Kwan Yuet Stephen Ho", email = "stephenhky@yahoo.com.hk"}
+]
+description = "A Python dictionary wrapper for numpy arrays"
+readme = {file = "README.md", content-type = "text/markdown"}
+license = {text = "MIT"}
+keywords = ["dictionary", "numpy"]
+requires-python = ">=3.9"
+classifiers = [
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+]
+dependencies = ["numpy", "typing-extensions"]
+
+[project.urls]
+Repository = "https://github.com/stephenhky/npdict"
+Issues = "https://github.com/stephenhky/npdict/issues"
+
+[tool.setuptools]
+packages = ["npdict"]
+zip-safe = false
+
+[project.optional-dependencies]
+test = ["pytest"]

npdict-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

npdict-0.0.1/test/test_wrap.py

@@ -0,0 +1,110 @@
+import unittest
+import numpy as np
+
+from npdict import NumpyNDArrayWrappedDict
+from npdict.utils import DuplicatedKeyError, WrongArrayDimensionException, WrongArrayShapeException
+
+
+class TestNumpyNDArrayWrappedDict(unittest.TestCase):
+
+    def setUp(self):
+        self.lists_keystrings = [
+            ['a', 'b', 'c'],
+            ['d', 'e']
+        ]
+        self.wrapped_dict = NumpyNDArrayWrappedDict(self.lists_keystrings, default_initial_value=1.0)
+
+    def test_initialization(self):
+        self.assertEqual(self.wrapped_dict.tensor_dimensions, 2)
+        self.assertEqual(self.wrapped_dict.dimension_sizes, [3, 2])
+        self.assertEqual(len(self.wrapped_dict), 6)
+        np.testing.assert_array_equal(self.wrapped_dict.to_numpy(), np.ones((3, 2)))
+
+    def test_initialization_with_duplicated_keys(self):
+        with self.assertRaises(DuplicatedKeyError):
+            NumpyNDArrayWrappedDict([['a', 'a'], ['b', 'c']])
+
+    def test_getitem(self):
+        self.wrapped_dict[('a', 'd')] = 2.0
+        self.assertEqual(self.wrapped_dict[('a', 'd')], 2.0)
+
+    def test_getitem_wrong_dimension(self):
+        with self.assertRaises(WrongArrayDimensionException):
+            _ = self.wrapped_dict[('a',)]
+
+    def test_setitem(self):
+        self.wrapped_dict[('b', 'e')] = 3.0
+        self.assertEqual(self.wrapped_dict.to_numpy()[1, 1], 3.0)
+
+    def test_setitem_wrong_dimension(self):
+        with self.assertRaises(WrongArrayDimensionException):
+            self.wrapped_dict[('a', 'b', 'c')] = 1.0
+
+    def test_iteration(self):
+        keys = list(self.wrapped_dict)
+        self.assertEqual(len(keys), 6)
+        self.assertIn(('a', 'd'), keys)
+        self.assertIn(('c', 'e'), keys)
+
+    def test_keys(self):
+        keys = self.wrapped_dict.keys()
+        self.assertEqual(len(keys), 6)
+        self.assertIn(('a', 'd'), keys)
+
+    def test_values(self):
+        self.wrapped_dict[('a', 'd')] = 5.0
+        self.wrapped_dict[('c', 'e')] = 6.0
+        values = self.wrapped_dict.values()
+        self.assertIn(1.0, values)
+        self.assertIn(5.0, values)
+        self.assertIn(6.0, values)
+
+    def test_items(self):
+        self.wrapped_dict[('a', 'd')] = 7.0
+        items = self.wrapped_dict.items()
+        self.assertIn((('a', 'd'), 7.0), items)
+        self.assertIn((('b', 'd'), 1.0), items)
+
+    def test_to_dict(self):
+        self.wrapped_dict[('a', 'd')] = 8.0
+        d = self.wrapped_dict.to_dict()
+        self.assertEqual(d[('a', 'd')], 8.0)
+        self.assertEqual(d[('b', 'e')], 1.0)
+
+    def test_from_dict(self):
+        d = {('a', 'x'): 1, ('b', 'y'): 2}
+        wrapped = NumpyNDArrayWrappedDict.from_dict(d)
+        self.assertEqual(wrapped[('a', 'x')], 1)
+        self.assertEqual(wrapped[('b', 'y')], 2)
+        self.assertEqual(wrapped[('a', 'y')], 0.0)
+        self.assertEqual(wrapped[('b', 'x')], 0.0)
+
+    def test_from_dict_given_keywords(self):
+        d = {('a', 'x'): 1}
+        keywords = [['a', 'b'], ['x', 'y']]
+        wrapped = NumpyNDArrayWrappedDict.from_dict_given_keywords(keywords, d, default_initial_value=-1)
+        self.assertEqual(wrapped[('a', 'x')], 1)
+        self.assertEqual(wrapped[('b', 'y')], -1)
+
+    def test_repr_str(self):
+        self.assertEqual(repr(self.wrapped_dict), f"<NumpyNDArrayWrappedDict: dimensions ({', '.join(map(str, self.wrapped_dict.dimension_sizes))})>")
+        self.assertEqual(str(self.wrapped_dict), repr(self.wrapped_dict))
+
+    def test_update(self):
+        with self.assertRaises(TypeError):
+            self.wrapped_dict.update({('a', 'd'): 1})
+
+    def test_generate_dict(self):
+        new_array = np.zeros((3, 2))
+        new_wrapped_dict = self.wrapped_dict.generate_dict(new_array)
+        np.testing.assert_array_equal(new_wrapped_dict.to_numpy(), new_array)
+        self.assertEqual(new_wrapped_dict.dimension_sizes, self.wrapped_dict.dimension_sizes)
+
+    def test_generate_dict_wrong_shape(self):
+        new_array = np.zeros((2, 3))
+        with self.assertRaises(WrongArrayShapeException):
+            self.wrapped_dict.generate_dict(new_array)
+
+
+if __name__ == '__main__':
+    unittest.main()