💰 LRU Cache (#45)

* 💰 LRU Cache

* update linter

* update linter

.github/labeler.yml

@@ -7,6 +7,9 @@ iot-edge-validator:
 iot-ftps-client:
   - iot-ftps-client/*
 
+iot-lru-cache:
+  - iot-lru-cache/*
+
 iot-samba-client:
   - iot-samba-client/*
 

.github/workflows/linter.yml

@@ -21,11 +21,16 @@ jobs:
         uses: github/super-linter/slim@v4
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEFAULT_BRANCH: develop
+          DEFAULT_BRANCH: master
           VALIDATE_ALL_CODEBASE: false
+          VALIDATE_GITHUB_ACTIONS: false
           VALIDATE_JSCPD: false
+          VALIDATE_JAVASCRIPT_STANDARD: false
+          VALIDATE_JAVASCRIPT_ES: false
+          VALIDATE_MARKDOWN: false
+          VALIDATE_PYTHON_FLAKE8: false
+          VALIDATE_NATURAL_LANGUAGE: false
           VALIDATE_PYTHON_MYPY: false
-          VALIDATE_GITHUB_ACTIONS: false
           VALIDATE_PYTHON_ISORT: false
           FILTER_REGEX_EXCLUDE: (.*tests/.*|*.md|.*assets/.*)
           IGNORE_GITIGNORED_FILES: true

.github/workflows/publisher.yml

@@ -48,6 +48,14 @@ jobs:
           twine upload dist/* -u ${{ env.PYPI_USER }} -p ${{ secrets.PYPI_API_TOKEN }}
           popd
 
+      - name: Build and Publish IoT LRU Cache to PyPI
+        if: contains(github.event.release.tag_name, 'iot-lru-cache')
+        run: |
+          pushd "./iot-lru-cache"
+          python3 -m build
+          twine upload dist/* -u ${{ env.PYPI_USER }} -p ${{ secrets.PYPI_API_TOKEN }}
+          popd
+
       - name: Build and Publish IoT Samba Client to PyPI
         if: contains(github.event.release.tag_name, 'iot-samba-client')
         run: |

.github/workflows/tester.yml

@@ -21,6 +21,8 @@ jobs:
               - 'iot-edge-validator/**'
             iot-ftps-client:
               - 'iot-ftps-client/**'
+            iot-lru-cache:
+              - 'iot-lru-cache/**'
             iot-samba-client:
               - 'iot-samba-client/**'
             iot-storage-client:
@@ -60,6 +62,14 @@ jobs:
           coverage report -m
           popd
 
+      - name: Test iot-lru-cache Package
+        if: steps.changes.outputs.iot-lru-cache == 'true'
+        run: |
+          pushd "./iot-lru-cache"
+          coverage run -m unittest discover tests -b
+          coverage report -m
+          popd
+
       - name: Test iot-samba-client Package
         if: steps.changes.outputs.iot-samba-client == 'true'
         run: |

README.md

@@ -20,7 +20,11 @@ As mentioned above, there are several PyPI packages contained within this reposi
 
 - [iot-ftps-client](https://github.com/dgonzo27/py-iot-utils/tree/master/iot-ftps-client)
 
-  This package is a wrapper around the [ftplib](https://docs.python.org/3/library/ftplib.html) protocol to provide a synchronous client for interacting with FTPS servers from IoT edge devices.
+  This package is a wrapper around the [ftplib](https://docs.python.org/3/library/ftplib.html) protocol to provide a synchronous client for interacting with FTPS servers from IoT edge devices. [View on PyPI](https://pypi.org/project/iot-ftps-client).
+
+- [iot-lru-cache](https://github.com/dgonzo27/py-iot-utils/tree/master/iot-lru-cache)
+
+  This package is an implementation of a Least Recently Used (LRU) caching algorithm for optimized caching on an IoT edge device. [View on PyPI](https://pypi.org/project/iot-lru-cache).
 
 - [iot-samba-client](https://github.com/dgonzo27/py-iot-utils/tree/master/iot-samba-client)
 

docs/public/static/changelog/iotLruCache.md

@@ -0,0 +1,13 @@
+---
+title: iot-lru-cache Changelog
+---
+
+# Release History for iot-lru-cache
+
+### 1.0.0 (12/13/2022)
+
+- Initial Release
+
+- Configured CHANGELOG, LICENSE and MANIFEST
+
+- Least Recently Used (LRU) cache

docs/public/static/changelog/iotStorageClient.md

@@ -4,6 +4,10 @@ title: iot-storage-client Changelog
 
 # Release History for iot-storage-client
 
+### 1.2.2 (12/13/2022)
+
+- Update `azure-storage-blob` package dependency to `v12.14.1`
+
 ### 1.2.1 (10/26/2022)
 
 - Default Azure Private Link/Endpoints to leverage DNS resolution

docs/public/static/packages/iotLruCache.md

@@ -0,0 +1,113 @@
+---
+title: iot-lru-cache
+---
+
+# iot-lru-cache
+
+[![python version](https://img.shields.io/badge/python_v3.9-blue?logo=python&logoColor=yellow)](https://www.python.org/) [![pre-commit](https://img.shields.io/badge/pre--commit-blue?logo=pre-commit&logoColor=FAB040)](https://pre-commit.com/) [![Keep a Changelog](https://img.shields.io/badge/keep_a_changelog-blue?logo=keepachangelog&logoColor=E05735)](https://keepachangelog.com/en/1.0.0/) [![CI_CD GitHub_Actions](https://img.shields.io/badge/GitHub_Actions-blue?logo=githubactions&logoColor=black)](https://github.com/features/actions) [![package PyPI](https://img.shields.io/badge/PyPI-blue?logo=PyPI&logoColor=yellow)](https://pypi.org/)
+
+This package is an implementation of a Least Recently Used (LRU) caching algorithm for optimized caching on an IoT edge device.
+
+[Source code](https://github.com/dgonzo27/py-iot-utils/tree/master/iot-lru-cache) | [Package PyPI](https://pypi.org/project/iot-lru-cache/)
+
+## Versioning
+
+This repository adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). It will be maintained through the `CHANGELOG.md` and in GitHub Releases. **It's important to note** that you must maintain the version with your releases in `iot/lru/cache/_version.py`, otherwise a new package version will fail to get published.
+
+## Getting Started
+
+This section provides basic examples with the `iot-lru-cache`.
+
+### Prerequisites
+
+- Python 3.7 or later is required to use this package.
+
+### Basic Examples
+
+1. Install via [pip](https://pypi.org/project/pip/):
+
+```sh
+pip install iot-lru-cache
+```
+
+2. Import and say hello:
+
+```python
+from iot.lru.cache import __version__
+
+print(f"hello world from iot-lru-cache version: {__version__}")
+```
+
+3. Basic usage:
+
+```python
+from iot.lru.cache import IoTLRUCache
+
+# instantiate cache
+cache = IoTLRUCache(capacity=100)
+
+# print info w/ repr
+print(f"{cache.__repr__()}")
+
+# add a key-value pair to the cache
+cache.put(key="my_key", value={"my": "value"})
+
+# retrieve the value for a given key (returns -1 if not found)
+val = cache.get(key="my_key")
+```
+
+## IoTLRUCache Class
+
+A Least Recently Used (LRU) caching algorithm for optimized caching on an IoT edge device.
+
+This class provides operations to get, and put key-value pairs of type `Any`.
+
+```python
+IoTLRUCache(capacity)
+```
+
+**Parameters**
+
+- `capacity` int
+
+  The number of key-value pairs to be stored in-memory before evicting on a LRU basis.
+
+### Get Method
+
+Retrieves the value of a key if it exists.
+
+```python
+cache.get(key)
+```
+
+**Parameters**
+
+- `key` Any
+
+  The key that should be used to retrieve its value.
+
+**Returns**
+
+Returns the key's value if it exists, -1 if it does not exist.
+
+### Put Method
+
+Update the value of a key if it exists, or simply adds the key-value pair to the cache.
+
+```python
+cache.put(key, value)
+```
+
+**Parameters**
+
+- `key` Any
+
+  The key in a key-value pair.
+
+- `value` Any
+
+  The value in a key-value pair.
+
+**Returns**
+
+Returns `None`.

docs/src/layout/sidebar.js

@@ -48,6 +48,10 @@ const sections = [
         title: "iot-ftps-client",
         path: "/packages/iotFtpsClient",
       },
+      {
+        title: "iot-lru-cache",
+        path: "/packages/iotLruCache",
+      },
       {
         title: "iot-samba-client",
         path: "/packages/iotSambaClient",

iot-lru-cache/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Release History
+
+## 1.0.0 (12/13/2022)
+
+- Initial Release
+
+- Configured CHANGELOG, LICENSE and MANIFEST
+
+- Least Recently Used (LRU) cache

iot-lru-cache/MANIFEST.in

@@ -0,0 +1,3 @@
+include *.md
+include iot/__init__.py
+include iot/lru/__init__.py

iot-lru-cache/README.md

@@ -0,0 +1,60 @@
+# iot-lru-cache
+
+[![python version](https://img.shields.io/badge/python_v3.9-blue?logo=python&logoColor=yellow)](https://www.python.org/) [![pre-commit](https://img.shields.io/badge/pre--commit-blue?logo=pre-commit&logoColor=FAB040)](https://pre-commit.com/) [![Keep a Changelog](https://img.shields.io/badge/keep_a_changelog-blue?logo=keepachangelog&logoColor=E05735)](https://keepachangelog.com/en/1.0.0/) [![CI_CD GitHub_Actions](https://img.shields.io/badge/GitHub_Actions-blue?logo=githubactions&logoColor=black)](https://github.com/features/actions) [![package PyPI](https://img.shields.io/badge/PyPI-blue?logo=PyPI&logoColor=yellow)](https://pypi.org/)
+
+This package is an implementation of a Least Recently Used (LRU) caching algorithm for optimized caching on an IoT edge device.
+
+[Official Documentation](https://py-iot-utils.com/packages/iotLruCache) | [Source code](https://github.com/dgonzo27/py-iot-utils/tree/master/iot-lru-cache) | [Package PyPI](https://pypi.org/project/iot-lru-cache/)
+
+## Table of Contents
+
+- [Versioning](#versioning)
+- [Getting Started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Basic Examples](#basic-examples)
+
+## Versioning
+
+This repository adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). It will be maintained through the `CHANGELOG.md` and in GitHub Releases. **It's important to note** that you must maintain the version with your releases in `iot/lru/cache/_version.py`, otherwise a new package version will fail to get published.
+
+## Getting Started
+
+This section provides basic examples with the `iot-lru-cache`.
+
+### Prerequisites
+
+- Python 3.7 or later is required to use this package.
+
+### Basic Examples
+
+1. Install via [pip](https://pypi.org/project/pip/):
+
+```sh
+pip install iot-lru-cache
+```
+
+2. Import and say hello:
+
+```python
+from iot.lru.cache import __version__
+
+print(f"hello world from iot-lru-cache version: {__version__}")
+```
+
+3. Basic usage:
+
+```python
+from iot.lru.cache import IoTLRUCache
+
+# instantiate cache
+cache = IoTLRUCache(capacity=100)
+
+# print info w/ repr
+print(f"{cache.__repr__()}")
+
+# add a key-value pair to the cache
+cache.put(key="my_key", value={"my": "value"})
+
+# retrieve the value for a given key (returns -1 if not found)
+val = cache.get(key="my_key")
+```

iot-lru-cache/iot/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

iot-lru-cache/iot/lru/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)

iot-lru-cache/iot/lru/cache/__init__.py

@@ -0,0 +1,2 @@
+from ._cache import IoTLRUCache
+from ._version import __version__

iot-lru-cache/iot/lru/cache/_cache.py

@@ -0,0 +1,39 @@
+"""least recently used (LRU) cache"""
+
+from collections import OrderedDict
+from typing import Any
+
+
+class IoTLRUCache:
+    """iot lru cache"""
+
+    cache: OrderedDict
+    capacity: int
+
+    def __init__(self, capacity: int) -> None:
+        self.capacity = capacity
+        self.cache = OrderedDict()
+
+    def __repr__(self) -> str:
+        return (
+            "IoT LRU Cache\n"
+            "-----------------\n"
+            f"capacity: {self.capacity}\n"
+            f"remaining capacity: {self.capacity - len(self.cache)}"
+        )
+
+    def get(self, key: Any) -> Any:
+        """retrieve the value of a key if it exists, default returns -1"""
+        if key not in self.cache:
+            return -1
+        self.cache.move_to_end(key, last=True)
+        return self.cache[key]
+
+    def put(self, key: Any, value: Any) -> None:
+        """update the value of a key if it exists, or add the key-value pair to the cache"""
+        if len(self.cache) == self.capacity and key not in self.cache:
+            # evict the LRU key if the cache has reached its capacity
+            self.cache.pop(next(iter(self.cache.items()))[0])
+        if key in self.cache:
+            self.cache.pop(key)
+        self.cache[key] = value

iot-lru-cache/iot/lru/cache/_version.py

@@ -0,0 +1,3 @@
+VERSION = "1.0.0"
+
+__version__ = VERSION

iot-lru-cache/setup.cfg

@@ -0,0 +1,2 @@
+[metadata]
+version = attr: iot.lru.cache._version.__version__