A Smuggle is a key/value pair where ONLY the key (which is read-only) is used to hash and compare. The smuggledvalue rides along without being part of the value of the object. Originally concocted as a hack for working with lru_cache

smuggle.py

# The MIT License (MIT)
#
# Copyright (c) 2022 Neil Webber
#
# 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.


# A 'Smuggle' is a key/value pair, but the value ("smuggledvalue")
# is ignored for equality and hash. So, for example:
#    s1 = Smuggle('somekey')
#    s2 = Smuggle('somekey')
#
#    s1 == s2 --> True
#
#    s1.smuggledvalue = 17
#    s2.smuggledvalue = 42
#
#    s1 == s2 --> True   # despite different smuggled values
#
# The key is immutable (can only be set at instantiation time)
# In some uses the key is irrelevant; it defaults to None:
#    s1 = Smuggle()
#    s1.key is None --> True
#
# Originally concocted as a hack to allow use of @lru_cache on a function
# while ignoring (for cache purposes) some of the arguments. Thus, a
# caller and the target function can "smuggle in" values that will all
# look the same to @lru_cache (and so will not prevent cache lookup match).
#
# (Contrived) Example:
#   @lru_cache
#   def plus1(x, g):
#       time.sleep(g.smuggledvalue)
#       return x + 1
#
#   s = Smuggle()
#   s.smuggledvalue = 5; plus1(1, s)
#      ... delays 5 seconds, returns 2
#   plus1(1, s)
#      ... returns 2 instantly, because cached by lru_cache
#   s.smuggledvalue = 8 ; plus1(1, s)
#      ... also returns 2 instantly, because still matches lru_cache
#

class Smuggle:
    __slots__ = ['__key', 'smuggledvalue']

    def __init__(self, key=None, /):
        self.__key = key

    @property
    def key(self):
        return self.__key
    # No .setter - 'key' is immutable

    # Note that this ignores any smuggled value
    def __hash__(self):
        return hash(self.key)

    # Note that this ignores any smuggled value
    def __eq__(self, other):
        return self.key == other.key

    # Didn't *have to* provide this, but may as well
    def __ne__(self, other):
        return self.key != other.key

    def __repr__(self):
        return f"{self.__class__.__name__}({self.key})"

if __name__ == "__main__":
    import unittest
    import time
    from functools import lru_cache

    class TestMethods(unittest.TestCase):
        def test1(self):
            self.assertEqual(Smuggle(), Smuggle())

        def test2(self):
            s1 = Smuggle()
            s2 = Smuggle()
            self.assertTrue(s1 == s2)
            self.assertEqual(hash(s1), hash(s2))

        def test3(self):
            s1 = Smuggle('somekey')
            s2 = Smuggle('somekey')
            s1.smuggledvalue = 17
            s2.smuggledvalue = 42
            self.assertTrue(s1 == s2)
            self.assertEqual(hash(s1), hash(s2))

        def test4(self):
            s1 = Smuggle('somekey')
            s2 = Smuggle('otherkey')
            self.assertFalse(s1 == s2)
            self.assertTrue(s1 != s2)

        def test5(self):
            s1 = Smuggle('foo')
            with self.assertRaises(AttributeError):
                s1.key = 88

        def test6(self):
            # test that the value can be updated
            s1 = Smuggle('bozo')
            s1.smuggledvalue = 17
            self.assertEqual(s1.smuggledvalue, 17)
            s1.smuggledvalue += 1
            self.assertEqual(s1.smuggledvalue, 18)
            
        # this tests the example from the comments
        def test7(self):
            @lru_cache
            def plus1(x, g):
                time.sleep(g.smuggledvalue)
                return x + 1

            s = Smuggle()
            delaytime = 5
            s.smuggledvalue = delaytime

            t0 = time.time()
            x = plus1(1, s)
            t1 = time.time()
            self.assertEqual(x, 2)

            # allow for sloppiness in delay time...
            self.assertTrue(t1 - t0 > delaytime * 0.9)

            # second invocation is (should be) cached and cause "no" delay
            t0 = time.time()
            x = plus1(1, s)
            t1 = time.time()

            self.assertEqual(x, 2)
            self.assertTrue(t1 - t0 < delaytime * 0.25)  # accept up to 25%

            # changing the smuggled value should have no effect
            s.smuggledvalue = delaytime + 1
            t0 = time.time()
            x = plus1(1, s)
            t1 = time.time()
            self.assertEqual(x, 2)
            self.assertTrue(t1 - t0 < delaytime * 0.25)

    unittest.main()