pamda.pamda

   1from functools import reduce
   2from pamda.pamda_utils import pamda_utils
   3from pamda.pamda_fast import (
   4    __getForceDict__,
   5    __assocPath__,
   6    __groupByHashable__,
   7    __mergeDeep__,
   8    __pathOr__,
   9    __getKeyValues__,
  10)
  11from pamda.pamda_curry import curry_obj
  12from pamda import pamda_wrappers
  13from typing import Any
  14
  15
  16@pamda_wrappers.typed_curry_wrap
  17@pamda_wrappers.classmethod_wrap
  18class pamda(pamda_utils):
  19    def accumulate(self, fn, initial_accumulator, data: list):
  20        """
  21        Function:
  22
  23        - Returns an accumulated list of items by iterating a function starting with an accumulator over a list
  24
  25        Requires:
  26
  27        - `fn`:
  28            - Type: function | method
  29            - What: The function or method to reduce
  30            - Note: This function should have an arity of 2 (take two inputs)
  31            - Note: The first input should take the accumulator value
  32            - Note: The second input should take the data value
  33        -`initial_accumulator`:
  34            - Type: any
  35            - What: The initial item to pass into the function when starting the accumulation process
  36        - `data`:
  37            - Type: list
  38            - What: The list of items to iterate over
  39
  40        Example:
  41
  42        ```
  43        data=[1,2,3,4]
  44        pamda.accumulate(
  45            fn=pamda.add,
  46            initial_accumulator=0,
  47            data=data
  48        )
  49        #=> [1,3,6,10]
  50
  51        ```
  52        """
  53        fn = self.curry(fn)
  54        if fn.__arity__ != 2:
  55            raise Exception("`fn` must have an arity of 2 (take two inputs)")
  56        if not len(data) > 0:
  57            raise Exception(
  58                "`data` has a length of 0, however it must have a length of at least 1"
  59            )
  60        acc = initial_accumulator
  61        out = []
  62        for i in data:
  63            acc = fn(acc, i)
  64            out.append(acc)
  65        return out
  66
  67    def add(self, a: int | float, b: int | float):
  68        """
  69        Function:
  70
  71        - Adds two numbers
  72
  73        Requires:
  74
  75        - `a`:
  76            - Type: int | float
  77            - What: The first number to add
  78        - `b`:
  79            - Type: int | float
  80            - What: The second number to add
  81
  82        Example:
  83
  84        ```
  85        pamda.add(1, 2) #=> 3
  86        ```
  87        """
  88        return a + b
  89
  90    def adjust(self, index: int, fn, data: list):
  91        """
  92        Function:
  93
  94        - Adjusts an item in a list by applying a function to it
  95
  96        Requires:
  97
  98        - `index`:
  99            - Type: int
 100            - What: The 0 based index of the item in the list to adjust
 101            - Note: Indicies are accepted
 102            - Note: If the index is out of range, picks the (-)first / (+)last item
 103        - `fn`:
 104            - Type: function | method
 105            - What: The function to apply the index item to
 106            - Note: This is automatically curried
 107        - `data`:
 108            - Type: list
 109            - What: The list to adjust
 110
 111        Example:
 112
 113        ```
 114        data=[1,5,9]
 115        pamda.adjust(
 116            index=1,
 117            fn=pamda.inc,
 118            data=data
 119        ) #=> [1,6,9]
 120        ```
 121        """
 122        fn = self.curry(fn)
 123        index = self.clamp(-len(data), len(data) - 1, index)
 124        data[index] = fn(data[index])
 125        return data
 126
 127    def assocPath(self, path: list | str | int | tuple, value, data: dict):
 128        """
 129        Function:
 130
 131        - Ensures a path exists within a nested dictionary
 132        - Note: This updates the object in place, but also returns the object
 133
 134        Requires:
 135
 136        - `path`:
 137            - Type: list[str | int | tuple] | str | int | tuple
 138            - What: The path to check
 139            - Note: If a string is passed, assumes a single item path list with that string
 140        - `value`:
 141            - Type: any
 142            - What: The value to appropriate to the end of the path
 143        - `data`:
 144            - Type: dict
 145            - What: A dictionary in which to associate the given value to the given path
 146
 147        Example:
 148
 149        ```
 150        data={'a':{'b':1}}
 151        pamda.assocPath(path=['a','c'], value=3, data=data) #=> {'a':{'b':1, 'c':3}}
 152        ```
 153        """
 154        if not isinstance(path, list):
 155            path = [path]
 156        reduce(__getForceDict__, path[:-1], data).__setitem__(path[-1], value)
 157        return data
 158
 159    def assocPathComplex(
 160        self, default, default_fn, path: list | int | float | tuple, data: dict
 161    ):
 162        """
 163        Function:
 164
 165        - Ensures a path exists within a nested dictionary
 166        - Note: This updates the object in place, but also returns the object
 167
 168        Requires:
 169
 170        - `default`:
 171            - Type: any
 172            - What: The default item to add to a path that does not yet exist
 173        - `default_fn`:
 174            - Type: function | method
 175            - What: A unary (single input) function that takes in the current path item (or default) and adjusts it
 176            - Example: `lambda x: x` # Returns the value in the dict or the default value if none was present
 177        - `path`:
 178            - Type: list[str | int | tuple] | str | int | tuple
 179            - What: The path to check
 180        - `data`:
 181            - Type: dict
 182            - What: A dictionary to check if the path exists
 183
 184        Example:
 185
 186        ```
 187        data={'a':{'b':1}}
 188        pamda.assocPathComplex(default=[2], default_fn=lambda x:x+[1], path=['a','c'], data=data) #=> {'a':{'b':1,'c':[2,1]}}
 189        ```
 190        """
 191        if self.getArity(default_fn) != 1:
 192            raise Exception(
 193                "`assocPathComplex` `default_fn` must be an unary (single input) function."
 194            )
 195        if not isinstance(path, list):
 196            path = [path]
 197        path_object = reduce(__getForceDict__, path[:-1], data)
 198        path_object.__setitem__(
 199            path[-1], default_fn(path_object.get(path[-1], default))
 200        )
 201        return data
 202
 203    def asyncKill(self, fn: curry_obj):
 204        """
 205        Function:
 206
 207        - Kills an asynchronous function that is currently running
 208        - Returns:
 209            - `None` if the function has not yet finished running
 210            - The result of the function if it has finished running
 211
 212        Requires:
 213
 214        - `fn`:
 215            - Type: thunkified function | thunkified method
 216            - What: The function or method to run asychronously
 217            - Note: The supplied `fn` must already be asynchronously running
 218
 219        Notes:
 220
 221        - See also `asyncRun` and `asyncWait`
 222        - A thunkified function currently running asynchronously can call `asyncKill` on itself
 223        - If a function has already finished running, calling `asyncKill` on it will have no effect
 224        - `asyncKill` does not kill threads that are sleeping (EG: `time.sleep`), but will kill the thread once the sleep is finished
 225
 226        Example:
 227
 228        ```
 229        import time
 230        from pamda import pamda
 231
 232        @pamda.thunkify
 233        def test(name, wait):
 234            waited = 0
 235            while waited < wait:
 236                time.sleep(1)
 237                waited += 1
 238                print(f'{name} has waited {waited} seconds')
 239
 240        async_test = pamda.asyncRun(test('a',3))
 241        time.sleep(1)
 242        pamda.asyncKill(async_test)
 243        # Alternatively:
 244        # async_test.asyncKill()
 245        ```
 246        """
 247        return fn.asyncKill()
 248
 249    def asyncRun(self, fn: curry_obj):
 250        """
 251        Function:
 252
 253        - Runs the supplied function asychronously
 254
 255        Requires:
 256
 257        - `fn`:
 258            - Type: thunkified function | thunkified method
 259            - What: The function or method to run asychronously
 260            - Note: The supplied `fn` must have an arity of 0
 261
 262        Notes:
 263
 264        - To pass inputs to a function in asyncRun, first thunkify the function and pass all arguments before calling `asyncRun` on it
 265        - To get the results of an `asyncRun` call `asyncWait`
 266        - To kill an `asyncRun` mid process call `asyncKill`
 267        - A thunkified function with arity of 0 can call `asyncRun` on itself
 268
 269        Examples:
 270
 271        Input:
 272        ```
 273        import time
 274
 275        @pamda.thunkify
 276        def test(name, wait):
 277            print(f'{name} start')
 278            time.sleep(wait)
 279            print(f'{name} end')
 280
 281        async_test = pamda.asyncRun(test('a',2))
 282        sync_test = test('b',1)()
 283        ```
 284        Output:
 285        ```
 286        a start
 287        b start
 288        b end
 289        a end
 290        ```
 291
 292
 293        Input:
 294        ```
 295        import time
 296
 297        @pamda.thunkify
 298        def test(name, wait):
 299            time.sleep(wait)
 300            return f"{name}: {wait}"
 301
 302        async_test = pamda.asyncRun(test('a',2))
 303        print(async_test.asyncWait()) #=> a: 2
 304        ```
 305
 306
 307        Input:
 308        ```
 309        import time
 310
 311        @pamda.thunkify
 312        def test(name, wait):
 313            time.sleep(wait)
 314            return f"{name}: {wait}"
 315
 316        async_test = test('a',2).asyncRun()
 317        print(async_test.asyncWait()) #=> a: 2
 318        ```
 319        """
 320        return fn.asyncRun()
 321
 322    def asyncWait(self, fn: curry_obj):
 323        """
 324        Function:
 325
 326        - Waits for a supplied function (if needed) and returns the results
 327
 328        Requires:
 329
 330        - `fn`:
 331            - Type: function | method
 332            - What: The function or method for which to wait
 333            - Note: The supplied `fn` must have previously called `asyncRun`
 334
 335        Notes:
 336
 337        - A thunkified function that has called `asyncRun` can call `asyncWait` on itself
 338
 339        Examples:
 340
 341        ```
 342        import time
 343
 344        @pamda.thunkify
 345        def test(name, wait):
 346            time.sleep(wait)
 347            return f"{name}: {wait}"
 348
 349        async_test = pamda.asyncRun(test('a',2))
 350        print(pamda.asyncWait(async_test)) #=> a: 2
 351        ```
 352
 353
 354        ```
 355        import time
 356
 357        @pamda.thunkify
 358        def test(name, wait):
 359            time.sleep(wait)
 360            return f"{name}: {wait}"
 361
 362        async_test = pamda.asyncRun(test('a',2))
 363        print(async_test.asyncWait()) #=> a: 2
 364        ```
 365        """
 366        return fn.asyncWait()
 367
 368    def clamp(self, minimum: int | float, maximum: int | float, a: int | float):
 369        """
 370        Function:
 371
 372        - Forces data to be within minimum and maximum
 373
 374        Requires:
 375
 376        - `minimum`:
 377            - Type: int | float
 378            - What: The minimum number
 379        - `maximum`:
 380            - Type: int | float
 381            - What: The maximum number
 382        - `a`:
 383            - Type: int | float
 384            - What: The number to clamp
 385
 386        Example:
 387
 388        ```
 389        pamda.clamp(1, 3, 2) #=> 2
 390        pamda.clamp(1, 3, 5) #=> 3
 391        ```
 392        """
 393        return min(max(a, minimum), maximum)
 394
 395    def curry(self, fn):
 396        """
 397        Function:
 398
 399        - Curries a function such that inputs can be added interatively
 400
 401        Requires:
 402
 403        - `fn`:
 404            - Type: function | method
 405            - What: The function or method to curry
 406            - Note: Class methods auto apply self during curry
 407
 408        Notes:
 409
 410        - Once curried, the function | method becomes a curry_obj object
 411        - The initial function is only called once all inputs are passed
 412
 413
 414        Examples:
 415
 416        ```
 417        curriedZip=pamda.curry(pamda.zip)
 418        curriedZip(['a','b'])([1,2]) #=> [['a',1],['b',2]]
 419
 420        # Curried functions can be thunkified at any time
 421        # See also thunkify
 422        zipThunk=curriedZip.thunkify()(['a','b'])([1,2])
 423        zipThunk() #=> [['a',1],['b',2]]
 424        ```
 425
 426        ```
 427        def myFunction(a,b,c):
 428            return [a,b,c]
 429
 430        curriedMyFn=pamda.curry(myFunction)
 431
 432        curriedMyFn(1,2,3) #=> [1,2,3]
 433        curriedMyFn(1)(2,3) #=> [1,2,3]
 434
 435        x=curriedMyFn(1)(2)
 436        x(3) #=> [1,2,3]
 437        x(4) #=> [1,2,4]
 438
 439
 440        ```
 441        """
 442        if fn.__dict__.get("__isCurried__"):
 443            return fn()
 444        return curry_obj(fn)
 445
 446    def curryTyped(self, fn):
 447        """
 448        Function:
 449
 450        - Curries a function such that inputs can be added interatively and function annotations are type checked at runtime
 451
 452        Requires:
 453
 454        - `fn`:
 455            - Type: function | method
 456            - What: The function or method to curry
 457            - Note: Class methods auto apply self during curry
 458
 459        Notes:
 460
 461        - Once curried, the function | method becomes a curry_obj object
 462        - The initial function is only called once all inputs are passed
 463
 464
 465        Examples:
 466
 467        ```
 468        @pamda.curryTyped
 469        def add(a:int,b:int):
 470            return a+b
 471
 472        add(1)(1) #=> 2
 473        add(1)(1.5) #=> Raises type exception
 474        ```
 475        """
 476        if fn.__dict__.get("__isCurried__"):
 477            return fn().typeEnforce()
 478        return curry_obj(fn).typeEnforce()
 479
 480    def dec(self, a: int | float):
 481        """
 482        Function:
 483
 484        - Decrements a number by one
 485
 486        Requires:
 487
 488        - `a`:
 489            - Type: int | float
 490            - What: The number to decrement
 491
 492        Example:
 493
 494        ```
 495        pamda.dec(42) #=> 41
 496        ```
 497        """
 498        if not isinstance(a, (int, float)):
 499            raise Exception("`a` must be an `int` or a `float`")
 500        return a - 1
 501
 502    def difference(self, a: list, b: list):
 503        """
 504        Function:
 505
 506        - Combines two lists into a list of no duplicate items present in the first list but not the second
 507
 508        Requires:
 509
 510        - `a`:
 511            - Type: list
 512            - What: List of items in which to look for a difference
 513        - `b`:
 514            - Type: list
 515            - What: List of items in which to compare when looking for the difference
 516
 517        Example:
 518
 519        ```
 520        a=['a','b']
 521        b=['b','c']
 522        pamda.difference(a=a, b=b) #=> ['a']
 523        pamda.difference(a=b, b=a) #=> ['c']
 524        ```
 525        """
 526        return list(set(a).difference(set(b)))
 527
 528    def dissocPath(self, path: list | str | int | tuple, data: dict):
 529        """
 530        Function:
 531
 532        - Removes the value at the end of a path within a nested dictionary
 533        - Note: This updates the object in place, but also returns the object
 534
 535        Requires:
 536
 537        - `path`:
 538            - Type: list of strs | str
 539            - What: The path to remove from the dictionary
 540            - Note: If a string is passed, assumes a single item path list with that string
 541        - `data`:
 542            - Type: dict
 543            - What: A dictionary with a path to be removed
 544
 545        Example:
 546
 547        ```
 548        data={'a':{'b':{'c':0,'d':1}}}
 549        pamda.dissocPath(path=['a','b','c'], data=data) #=> {'a':{'b':{'d':1}}}
 550        ```
 551        """
 552        if not isinstance(path, list):
 553            path = [path]
 554        if not self.hasPath(path=path, data=data):
 555            raise Exception("Path does not exist")
 556        else:
 557            reduce(__getForceDict__, path[:-1], data).pop(path[-1])
 558        return data
 559
 560    def flatten(self, data: list):
 561        """
 562        Function:
 563
 564        - Flattens a list of lists of lists ... into a single list depth first
 565
 566        Requires:
 567
 568        - `data`:
 569            - Type: list of lists
 570            - What: The list of lists to reduce to a single list
 571        Example:
 572
 573        ```
 574        data=[['a','b'],[1,[2]]]
 575        pamda.flatten(data=data) #=> ['a','b',1,2]
 576        ```
 577        """
 578
 579        def iter_flatten(data):
 580            out = []
 581            for i in data:
 582                if isinstance(i, list):
 583                    out.extend(iter_flatten(i))
 584                else:
 585                    out.append(i)
 586            return out
 587
 588        return iter_flatten(data)
 589
 590    def flip(self, fn):
 591        """
 592        Function:
 593
 594        - Returns a new function equivalent to the supplied function except that the first two inputs are flipped
 595
 596        Requires:
 597
 598        - `fn`:
 599            - Type: function | method
 600            - What: The function or method to flip
 601            - Note: This function must have an arity of at least 2 (take two inputs)
 602            - Note: Only args are flipped, kwargs are passed as normal
 603
 604        Notes:
 605
 606        - Input functions are not flipped in place
 607        - The returned function is a flipped version of the input function
 608        - A curried function can be flipped in place by calling fn.flip()
 609        - A function can be flipped multiple times:
 610            - At each flip, the first and second inputs for the function as it is currently curried are switched
 611            - Flipping a function two times before adding an input will return the initial value
 612
 613        Examples:
 614
 615        ```
 616        def concat(a,b,c,d):
 617            return str(a)+str(b)+str(c)+str(d)
 618
 619        flip_concat=pamda.flip(concat)
 620
 621        concat('fe-','fi-','fo-','fum') #=> 'fe-fi-fo-fum'
 622        flip_concat('fe-','fi-','fo-','fum') #=> 'fi-fe-fo-fum'
 623        ```
 624
 625        ```
 626        @pamda.curry
 627        def concat(a,b,c,d):
 628            return str(a)+str(b)+str(c)+str(d)
 629
 630        concat('fe-','fi-','fo-','fum') #=> 'fe-fi-fo-fum'
 631
 632        concat.flip()
 633
 634        concat('fe-','fi-','fo-','fum') #=> 'fi-fe-fo-fum'
 635        ```
 636
 637        ```
 638        @pamda.curry
 639        def concat(a,b,c,d):
 640            return str(a)+str(b)+str(c)+str(d)
 641
 642        a=pamda.flip(concat)('fi-')
 643        b=pamda.flip(a)('fo-')
 644        c=pamda.flip(b)('fum')
 645        c('fe-') #=> 'fe-fi-fo-fum'
 646        ```
 647
 648        ```
 649        def concat(a,b,c,d):
 650            return str(a)+str(b)+str(c)+str(d)
 651
 652        a=pamda.flip(concat)('fi-').flip()('fo-').flip()('fum')
 653        a('fe-') #=> 'fe-fi-fo-fum'
 654        ```
 655        """
 656        fn = self.curry(fn)
 657        return fn.flip()
 658
 659    def getArity(self, fn):
 660        """
 661        Function:
 662
 663        - Gets the arity (number of inputs left to be specified) of a function or method (curried or uncurried)
 664
 665        Requires:
 666
 667        - `fn`:
 668            - Type: function | method
 669            - What: The function or method to get the arity of
 670            - Note: Class methods remove one arity to account for self
 671
 672        Examples:
 673
 674        ```
 675        pamda.getArity(pamda.zip) #=> 2
 676        curriedZip=pamda.curry(pamda.zip)
 677        ABCuriedZip=curriedZip(['a','b'])
 678        pamda.getArity(ABCuriedZip) #=> 1
 679        ```
 680        """
 681        fn = self.curry(fn)
 682        return fn.__arity__
 683
 684    def groupBy(self, fn, data: list):
 685        """
 686        Function:
 687
 688        - Splits a list into a dictionary of sublists keyed by the return string of a provided function
 689
 690        Requires:
 691
 692        - `fn`:
 693            - Type: function | method
 694            - What: The function or method to group by
 695            - Note: Must return a string (or other hashable object)
 696            - Note: This function must be unary (take one input)
 697            - Note: This function is applied to each item in the list recursively
 698        - `data`:
 699            - Type: list
 700            - What: List of items to apply the function to and then group by the results
 701
 702        Examples:
 703
 704        ```
 705        def getGrade(item):
 706            score=item['score']
 707            if score>90:
 708                return 'A'
 709            elif score>80:
 710                return 'B'
 711            elif score>70:
 712                return 'C'
 713            elif score>60:
 714                return 'D'
 715            else:
 716                return 'F'
 717
 718        data=[
 719            {'name':'Connor', 'score':75},
 720            {'name':'Fred', 'score':79},
 721            {'name':'Joe', 'score':84},
 722        ]
 723        pamda.groupBy(getGrade,data)
 724        #=>{
 725        #=>    'B':[{'name':'Joe', 'score':84}]
 726        #=>    'C':[{'name':'Connor', 'score':75},{'name':'Fred', 'score':79}]
 727        #=>}
 728        ```
 729        """
 730        curried_fn = self.curry(fn)
 731        if curried_fn.__arity__ != 1:
 732            raise Exception(
 733                "groupBy `fn` must only take one parameter as its input"
 734            )
 735        return __groupByHashable__(fn=fn, data=data)
 736
 737    def groupKeys(self, keys: list, data: list):
 738        """
 739        Function:
 740
 741        - Splits a list of dicts into a list of sublists of dicts separated by values with equal keys
 742
 743        Requires:
 744
 745        - `keys`:
 746            - Type: list of strs
 747            - What: The keys to group by
 748        - `data`:
 749            - Type: list of dicts
 750            - What: List of dictionaries with which to match keys
 751
 752        Examples:
 753
 754        ```
 755        data=[
 756            {'color':'red', 'size':9, 'shape':'ball'},
 757            {'color':'red', 'size':10, 'shape':'ball'},
 758            {'color':'green', 'size':11, 'shape':'ball'},
 759            {'color':'green', 'size':12, 'shape':'square'}
 760        ]
 761        pamda.groupKeys(['color','shape'],data)
 762        #=> [
 763        #=>     [{'color': 'red', 'size': 9, 'shape': 'ball'}, {'color': 'red', 'size': 10, 'shape': 'ball'}],
 764        #=>     [{'color': 'green', 'size': 11, 'shape': 'ball'}],
 765        #=>     [{'color': 'green', 'size': 12, 'shape': 'square'}]
 766        #=> ]
 767        ```
 768        """
 769
 770        def key_fn(item):
 771            return tuple([item[key] for key in keys])
 772
 773        return list(__groupByHashable__(key_fn, data).values())
 774
 775    def groupWith(self, fn, data: list):
 776        """
 777        Function:
 778
 779        - Splits a list into a list of sublists where each sublist is determined by adjacent pairwise comparisons from a provided function
 780
 781        Requires:
 782
 783        - `fn`:
 784            - Type: function | method
 785            - What: The function or method to groub with
 786            - Note: Must return a boolean value
 787            - Note: This function must have an arity of two (take two inputs)
 788            - Note: This function is applied to each item plus the next adjacent item in the list recursively
 789        - `data`:
 790            - Type: list
 791            - What: List of items to apply the function to and then group the results
 792
 793        Examples:
 794
 795        ```
 796        def areEqual(a,b):
 797            return a==b
 798
 799        data=[1,2,3,1,1,2,2,3,3,3]
 800        pamda.groupWith(areEqual,data) #=> [[1], [2], [3], [1, 1], [2, 2], [3, 3, 3]]
 801        ```
 802        """
 803        curried_fn = self.curry(fn)
 804        if curried_fn.__arity__ != 2:
 805            raise Exception("groupWith `fn` must take exactly two parameters")
 806        previous = data[0]
 807        output = []
 808        sublist = [previous]
 809        for i in data[1:]:
 810            if fn(i, previous):
 811                sublist.append(i)
 812            else:
 813                output.append(sublist)
 814                sublist = [i]
 815            previous = i
 816        output.append(sublist)
 817        return output
 818
 819    def hasPath(self, path: list | str, data: dict):
 820        """
 821        Function:
 822
 823        - Checks if a path exists within a nested dictionary
 824
 825        Requires:
 826
 827        - `path`:
 828            - Type: list of strs | str
 829            - What: The path to check
 830            - Note: If a string is passed, assumes a single item path list with that string
 831        - `data`:
 832            - Type: dict
 833            - What: A dictionary to check if the path exists
 834
 835        Example:
 836
 837        ```
 838        data={'a':{'b':1}}
 839        pamda.hasPath(path=['a','b'], data=data) #=> True
 840        pamda.hasPath(path=['a','d'], data=data) #=> False
 841        ```
 842        """
 843        if isinstance(path, str):
 844            path = [path]
 845        return path[-1] in reduce(lambda x, y: x.get(y, {}), path[:-1], data)
 846
 847    def hardRound(self, decimal_places: int, a: int | float):
 848        """
 849        Function:
 850
 851        - Rounds to a set number of decimal places regardless of floating point math in python
 852
 853        Requires:
 854
 855        - `decimal_places`:
 856            - Type: int
 857            - What: The number of decimal places to round to
 858            - Default: 0
 859            - Notes: Negative numbers accepted (EG -1 rounds to the nearest 10)
 860        - `a`:
 861            - Type: int | float
 862            - What: The number to round
 863
 864        Example:
 865
 866        ```
 867        a=12.345
 868        pamda.hardRound(1,a) #=> 12.3
 869        pamda.hardRound(-1,a) #=> 10
 870        ```
 871        """
 872        return int(a * (10**decimal_places) + 0.5) / (10**decimal_places)
 873
 874    def head(self, data: list | str):
 875        """
 876        Function:
 877
 878        - Picks the first item out of a list or string
 879
 880        Requires:
 881
 882        - `data`:
 883            - Type: list | str
 884            - What: A list or string
 885
 886        Example:
 887
 888        ```
 889        data=['fe','fi','fo','fum']
 890        pamda.first(
 891            data=data
 892        ) #=> fe
 893        ```
 894        """
 895        if not isinstance(data, (list, str)):
 896            raise Exception("`head` can only be called on a `str` or a `list`")
 897        if not len(data) > 0:
 898            raise Exception("Attempting to call `head` on an empty list or str")
 899        return data[0]
 900
 901    def inc(self, a: int | float):
 902        """
 903        Function:
 904
 905        - Increments a number by one
 906
 907        Requires:
 908
 909        - `a`:
 910            - Type: int | float
 911            - What: The number to increment
 912
 913        Example:
 914
 915        ```
 916        pamda.inc(42) #=> 43
 917        ```
 918        """
 919        if not isinstance(a, (int, float)):
 920            raise Exception("`a` must be an `int` or a `float`")
 921        return a + 1
 922
 923    def intersection(self, a: list, b: list):
 924        """
 925        Function:
 926
 927        - Combines two lists into a list of no duplicates composed of those elements common to both lists
 928
 929        Requires:
 930
 931        - `a`:
 932            - Type: list
 933            - What: List of items in which to look for an intersection
 934        - `b`:
 935            - Type: list
 936            - What: List of items in which to look for an intersection
 937
 938        Example:
 939
 940        ```
 941        a=['a','b']
 942        b=['b','c']
 943        pamda.intersection(a=a, b=b) #=> ['b']
 944        ```
 945        """
 946        return list(set(a).intersection(set(b)))
 947
 948    def map(self, fn, data: list | dict):
 949        """
 950        Function:
 951
 952        - Maps a function over a list or a dictionary
 953
 954        Requires:
 955
 956        - `fn`:
 957            - Type: function | method
 958            - What: The function or method to map over the list or dictionary
 959            - Note: This function should have an arity of 1
 960        - `data`:
 961            - Type: list | dict
 962            - What: The list or dict of items to map the function over
 963
 964        Examples:
 965
 966        ```
 967        data=[1,2,3]
 968        pamda.map(
 969            fn=pamda.inc,
 970            data=data
 971        )
 972        #=> [2,3,4]
 973        ```
 974
 975        ```
 976        data={'a':1,'b':2,'c':3}
 977        pamda.map(
 978            fn=pamda.inc,
 979            data=data
 980        )
 981        #=> {'a':2,'b':3,'c':4}
 982        ```
 983
 984        """
 985        # TODO: Check for efficiency gains
 986        fn = self.curry(fn)
 987        if fn.__arity__ != 1:
 988            raise Exception("`map` `fn` must be unary (take one input)")
 989        if not len(data) > 0:
 990            raise Exception(
 991                "`map` `data` has a length of 0 or is an empty dictionary, however it must have at least one element in it"
 992            )
 993        if isinstance(data, dict):
 994            return {key: fn(value) for key, value in data.items()}
 995        else:
 996            return [fn(i) for i in data]
 997
 998    def mean(self, data: list):
 999        """
1000        Function:
1001
1002        - Calculates the mean of a given list
1003
1004        Requires:
1005
1006        - `data`:
1007            - Type: list of (floats | ints)
1008            - What: The list with wich to calculate the mean
1009            - Note: If the length of this list is 0, returns None
1010
1011        Example:
1012
1013        ```
1014        data=[1,2,3]
1015        pamda.mean(data=data)
1016        #=> 2
1017        ```
1018
1019        ```
1020        data=[]
1021        pamda.mean(data=data)
1022        #=> None
1023        ```
1024        """
1025        if len(data) == 0:
1026            return None
1027        return sum(data) / len(data)
1028
1029    def median(self, data: list):
1030        """
1031        Function:
1032
1033        - Calculates the median of a given list
1034        - If the length of the list is even, calculates the mean of the two central values
1035
1036        Requires:
1037
1038        - `data`:
1039            - Type: list of (floats | ints)
1040            - What: The list with wich to calculate the mean
1041            - Note: If the length of this list is 0, returns None
1042
1043        Examples:
1044
1045        ```
1046        data=[7,2,8,9]
1047        pamda.median(data=data)
1048        #=> 7.5
1049        ```
1050
1051        ```
1052        data=[7,8,9]
1053        pamda.median(data=data)
1054        #=> 8
1055        ```
1056
1057        ```
1058        data=[]
1059        pamda.median(data=data)
1060        #=> None
1061        ```
1062        """
1063        if not isinstance(data, (list)):
1064            raise Exception("`median` `data` must be a list")
1065        length = len(data)
1066        if length == 0:
1067            return None
1068        data = sorted(data)
1069        if length % 2 == 0:
1070            return (data[int(length / 2)] + data[int(length / 2) - 1]) / 2
1071        return data[int(length / 2)]
1072
1073    def mergeDeep(self, update_data, data):
1074        """
1075        Function:
1076
1077        - Recursively merges two nested dictionaries keeping all keys at each layer
1078        - Values from `update_data` are used when keys are present in both dictionaries
1079
1080        Requires:
1081
1082        - `update_data`:
1083            - Type: any
1084            - What: The new data that will take precedence during merging
1085        - `data`:
1086            - Type: any
1087            - What: The original data that will be merged into
1088
1089        Example:
1090
1091        ```
1092        data={'a':{'b':{'c':'d'},'e':'f'}}
1093        update_data={'a':{'b':{'h':'i'},'e':'g'}}
1094        pamda.mergeDeep(
1095            update_data=update_data,
1096            data=data
1097        ) #=> {'a':{'b':{'c':'d','h':'i'},'e':'g'}}
1098        ```
1099        """
1100        return __mergeDeep__(update_data, data)
1101
1102    def nest(self, path_keys: list, value_key: str, data: list):
1103        """
1104        Function:
1105
1106        - Nests a list of dictionaries into a nested dictionary
1107        - Similar items are appended to a list in the end of the nested dictionary
1108
1109        Requires:
1110
1111        - `path_keys`:
1112            - Type: list of strs
1113            - What: The variables to pull from each item in data
1114            - Note: Used to build out the nested dicitonary
1115            - Note: Order matters as the nesting occurs in order of variable
1116        - `value_key`:
1117            - Type: str
1118            - What: The variable to add to the list at the end of the nested dictionary path
1119        - `data`:
1120            - Type: list of dicts
1121            - What: A list of dictionaries to use for nesting purposes
1122
1123        Example:
1124
1125        ```
1126        data=[
1127            {'x_1':'a','x_2':'b', 'output':'c'},
1128            {'x_1':'a','x_2':'b', 'output':'d'},
1129            {'x_1':'a','x_2':'e', 'output':'f'}
1130        ]
1131        pamda.nest(
1132            path_keys=['x_1','x_2'],
1133            value_key='output',
1134            data=data
1135        ) #=> {'a':{'b':['c','d'], 'e':['f']}}
1136        ```
1137        """
1138        if not isinstance(data, list):
1139            raise Exception("Attempting to `nest` an object that is not a list")
1140        if len(data) == 0:
1141            raise Exception("Attempting to `nest` from an empty list")
1142        nested_output = {}
1143        for item in self.groupKeys(keys=path_keys, data=data):
1144            nested_output = __assocPath__(
1145                path=__getKeyValues__(path_keys, item[0]),
1146                value=[i.get(value_key) for i in item],
1147                data=nested_output,
1148            )
1149        return nested_output
1150
1151    def nestItem(self, path_keys: list, data: list):
1152        """
1153        Function:
1154
1155        - Nests a list of dictionaries into a nested dictionary
1156        - Similar items are appended to a list in the end of the nested dictionary
1157        - Similar to `nest`, except no values are plucked for the aggregated list
1158
1159        Requires:
1160
1161        - `path_keys`:
1162            - Type: list of strs
1163            - What: The variables to pull from each item in data
1164            - Note: Used to build out the nested dicitonary
1165            - Note: Order matters as the nesting occurs in order of variable
1166        - `data`:
1167            - Type: list of dicts
1168            - What: A list of dictionaries to use for nesting purposes
1169
1170        Example:
1171
1172        ```
1173        data=[
1174            {'x_1':'a','x_2':'b'},
1175            {'x_1':'a','x_2':'b'},
1176            {'x_1':'a','x_2':'e'}
1177        ]
1178        pamda.nestItem
1179            path_keys=['x_1','x_2'],
1180            data=data
1181        )
1182        #=> {'a': {'b': [{'x_1': 'a', 'x_2': 'b'}, {'x_1': 'a', 'x_2': 'b'}], 'e': [{'x_1': 'a', 'x_2': 'e'}]}}
1183
1184        ```
1185        """
1186        if not isinstance(data, list):
1187            raise Exception("Attempting to `nest` an object that is not a list")
1188        if len(data) == 0:
1189            raise Exception("Attempting to `nest` from an empty list")
1190        nested_output = {}
1191        for item in self.groupKeys(keys=path_keys, data=data):
1192            nested_output = __assocPath__(
1193                path=__getKeyValues__(path_keys, item[0]),
1194                value=item,
1195                data=nested_output,
1196            )
1197        return nested_output
1198
1199    def path(self, path: list | str, data: dict):
1200        """
1201        Function:
1202
1203        - Returns the value of a path within a nested dictionary or None if the path does not exist
1204
1205        Requires:
1206
1207        - `path`:
1208            - Type: list of strs | str
1209            - What: The path to pull given the data
1210            - Note: If a string is passed, assumes a single item path list with that string
1211        - `data`:
1212            - Type: dict
1213            - What: A dictionary to get the path from
1214
1215        Example:
1216
1217        ```
1218        data={'a':{'b':1}}
1219        pamda.path(path=['a','b'], data=data) #=> 1
1220        ```
1221        """
1222        if isinstance(path, str):
1223            path = [path]
1224        return __pathOr__(None, path, data)
1225
1226    def pathOr(self, default, path: list | str, data: dict):
1227        """
1228        Function:
1229
1230        - Returns the value of a path within a nested dictionary or a default value if that path does not exist
1231
1232        Requires:
1233
1234        - `default`:
1235            - Type: any
1236            - What: The object to return if the path does not exist
1237        - `path`:
1238            - Type: list of strs | str
1239            - What: The path to pull given the data
1240            - Note: If a string is passed, assumes a single item path list with that string
1241        - `data`:
1242            - Type: dict
1243            - What: A dictionary to get the path from
1244
1245        Example:
1246
1247        ```
1248        data={'a':{'b':1}}
1249        pamda.path(default=2, path=['a','c'], data=data) #=> 2
1250        ```
1251        """
1252        if isinstance(path, str):
1253            path = [path]
1254        return reduce(lambda x, y: x.get(y, {}), path[:-1], data).get(
1255            path[-1], default
1256        )
1257
1258    def pipe(self, fns: list, args: tuple, kwargs: dict):
1259        """
1260        Function:
1261
1262        - Pipes data through n functions in order (left to right composition) and returns the output
1263
1264        Requires:
1265
1266        - `fns`:
1267            - Type: list of (functions | methods)
1268            - What: The list of functions and methods to pipe the data through
1269            - Notes: The first function in the list can be any arity (accepting any number of inputs)
1270            - Notes: Any further function in the list can only be unary (single input)
1271            - Notes: A function can be curried, but is not required to be
1272            - Notes: You may opt to curry functions and add inputs to make them unary
1273        - `args`:
1274            - Type: tuple
1275            - What: a tuple of positional arguments to pass to the first function in `fns`
1276        - `kwargs`:
1277            - Type: dict
1278            - What: a dictionary of keyword arguments to pass to the first function in `fns`
1279
1280        Examples:
1281
1282        ```
1283        data=['abc','def']
1284        pamda.pipe(fns=[pamda.head, pamda.tail], args=(data), kwargs={}) #=> 'c'
1285        pamda.pipe(fns=[pamda.head, pamda.tail], args=(), kwargs={'data':data}) #=> 'c'
1286        ```
1287
1288        ```
1289        data={'a':{'b':'c'}}
1290        curriedPath=pamda.curry(pamda.path)
1291        pamda.pipe(fns=[curriedPath('a'), curriedPath('b')], args=(), kwargs={'data':data}) #=> 'c'
1292        ```
1293        """
1294        if len(fns) == 0:
1295            raise Exception("`fns` must be a list with at least one function")
1296        if self.getArity(fns[0]) == 0:
1297            raise Exception(
1298                "The first function in `fns` can have n arity (accepting n args), but this must be greater than 0."
1299            )
1300        if not all([(self.getArity(fn) == 1) for fn in fns[1:]]):
1301            raise Exception(
1302                "Only the first function in `fns` can have n arity (accept n args). All other functions must have an arity of one (accepting one argument)."
1303            )
1304        out = fns[0](*args, **kwargs)
1305        for fn in fns[1:]:
1306            out = fn(out)
1307        return out
1308
1309    def pivot(self, data: list[dict] | dict[Any, list]):
1310        """
1311        Function:
1312
1313        - Pivots a list of dictionaries into a dictionary of lists
1314        - Pivots a dictionary of lists into a list of dictionaries
1315
1316        Requires:
1317
1318        - `data`:
1319            - Type: list of dicts | dict of lists
1320            - What: The data to pivot
1321            - Note: If a list of dictionaries is passed, all dictionaries must have the same keys
1322            - Note: If a dictionary of lists is passed, all lists must have the same length
1323
1324        Example:
1325
1326        ```
1327        data=[
1328            {'a':1,'b':2},
1329            {'a':3,'b':4}
1330        ]
1331        pamda.pivot(data=data) #=> {'a':[1,3],'b':[2,4]}
1332
1333        data={'a':[1,3],'b':[2,4]}
1334        pamda.pivot(data=data)
1335        #=> [
1336        #=>     {'a':1,'b':2},
1337        #=>     {'a':3,'b':4}
1338        #=> ]
1339        ```
1340        """
1341        if isinstance(data, list):
1342            return {
1343                key: [record[key] for record in data] for key in data[0].keys()
1344            }
1345        else:
1346            return [
1347                {key: data[key][i] for key in data.keys()}
1348                for i in range(len(data[list(data.keys())[0]]))
1349            ]
1350
1351    def pluck(self, path: list | str, data: list):
1352        """
1353        Function:
1354
1355        - Returns the values of a path within a list of nested dictionaries
1356
1357        Requires:
1358
1359        - `path`:
1360            - Type: list of strs
1361            - What: The path to pull given the data
1362            - Note: If a string is passed, assumes a single item path list with that string
1363        - `data`:
1364            - Type: list of dicts
1365            - What: A list of dictionaries to get the path from
1366
1367        Example:
1368
1369        ```
1370        data=[{'a':{'b':1, 'c':'d'}},{'a':{'b':2, 'c':'e'}}]
1371        pamda.pluck(path=['a','b'], data=data) #=> [1,2]
1372        ```
1373        """
1374        if len(data) == 0:
1375            raise Exception("Attempting to pluck from an empty list")
1376        if isinstance(path, str):
1377            path = [path]
1378        return [__pathOr__(default=None, path=path, data=i) for i in data]
1379
1380    def pluckIf(self, fn, path: list | str, data: list):
1381        """
1382        Function:
1383
1384        - Returns the values of a path within a list of nested dictionaries if a path in those same dictionaries matches a value
1385
1386        Requires:
1387
1388        - `fn`:
1389            - Type: function
1390            - What: A function to take in each item in data and return a boolean
1391            - Note: Only items that return true are plucked
1392            - Note: Should be a unary function (take one input)
1393        - `path`:
1394            - Type: list of strs
1395            - What: The path to pull given the data
1396            - Note: If a string is passed, assumes a single item path list with that string
1397        - `data`:
1398            - Type: list of dicts
1399            - What: A list of dictionary to get the path from
1400
1401        Example:
1402
1403        ```
1404
1405        data=[{'a':{'b':1, 'c':'d'}},{'a':{'b':2, 'c':'e'}}]
1406        pamda.pluck(fn:lambda x: x['a']['b']==1, path=['a','c'], data=data) #=> ['d']
1407        ```
1408        """
1409        if len(data) == 0:
1410            raise Exception("Attempting to pluck from an empty list")
1411        curried_fn = self.curry(fn)
1412        if curried_fn.__arity__ != 1:
1413            raise Exception(
1414                "`pluckIf` `fn` must have an arity of 1 (take one input)"
1415            )
1416        if isinstance(path, str):
1417            path = [path]
1418        return [
1419            __pathOr__(default=None, path=path, data=i) for i in data if fn(i)
1420        ]
1421
1422    def project(self, keys: list[str], data: list[dict]):
1423        """
1424        Function:
1425
1426        - Returns a list of dictionaries with only the keys provided
1427        - Analogous to SQL's `SELECT` statement
1428
1429        Requires:
1430
1431        - `keys`:
1432            - Type: list of strs
1433            - What: The keys to select from each dictionary in the data list
1434        - `data`:
1435            - Type: list of dicts
1436            - What: The list of dictionaries to select from
1437
1438        Example:
1439
1440        ```
1441        data=[
1442            {'a':1,'b':2,'c':3},
1443            {'a':4,'b':5,'c':6}
1444        ]
1445        pamda.project(keys=['a','c'], data=data)
1446        #=> [
1447        #=>     {'a':1,'c':3},
1448        #=>     {'a':4,'c':6}
1449        #=> ]
1450        ```
1451        """
1452        return [{key: record[key] for key in keys} for record in data]
1453
1454    def props(self, keys: list[str], data: dict):
1455        """
1456        Function:
1457
1458        - Returns the values of a list of keys within a dictionary
1459
1460        Requires:
1461
1462        - `keys`:
1463            - Type: list of strs
1464            - What: The keys to pull given the data
1465        - `data`:
1466            - Type: dict
1467            - What: A dictionary to get the keys from
1468
1469        Example:
1470        ```
1471        data={'a':1,'b':2,'c':3}
1472        pamda.props(keys=['a','c'], data=data)
1473        #=> [1,3]
1474        ```
1475        """
1476        return [data[key] for key in keys]
1477
1478    def reduce(self, fn, initial_accumulator, data: list):
1479        """
1480        Function:
1481
1482        - Returns a single item by iterating a function starting with an accumulator over a list
1483
1484        Requires:
1485
1486        - `fn`:
1487            - Type: function | method
1488            - What: The function or method to reduce
1489            - Note: This function should have an arity of 2 (take two inputs)
1490            - Note: The first input should take the accumulator value
1491            - Note: The second input should take the data value
1492        -`initial_accumulator`:
1493            - Type: any
1494            - What: The initial item to pass into the function when starting the accumulation process
1495        - `data`:
1496            - Type: list
1497            - What: The list of items to iterate over
1498
1499        Example:
1500
1501        ```
1502        data=[1,2,3,4]
1503        pamda.reduce(
1504            fn=pamda.add,
1505            initial_accumulator=0,
1506            data=data
1507        )
1508        #=> 10
1509
1510        ```
1511        """
1512        fn = self.curry(fn)
1513        if fn.__arity__ != 2:
1514            raise Exception(
1515                "`reduce` `fn` must have an arity of 2 (take two inputs)"
1516            )
1517        if not isinstance(data, (list)):
1518            raise Exception("`reduce` `data` must be a list")
1519        if not len(data) > 0:
1520            raise Exception(
1521                "`reduce` `data` has a length of 0, however it must have a length of at least 1"
1522            )
1523        acc = initial_accumulator
1524        for i in data:
1525            acc = fn(acc, i)
1526        return acc
1527
1528    def safeDivide(self, denominator: int | float, a: int | float):
1529        """
1530        Function:
1531
1532        - Forces division to work by enforcing a denominator of 1 if the provided denominator is zero
1533
1534        Requires:
1535
1536        - `denominator`:
1537            - Type: int | float
1538            - What: The denominator
1539
1540        - `a`:
1541            - Type: int | float
1542            - What: The numerator
1543
1544        Example:
1545
1546        ```
1547        pamda.safeDivide(2,10) #=> 5
1548        pamda.safeDivide(0,10) #=> 10
1549        ```
1550        """
1551        return a / denominator if denominator != 0 else a
1552
1553    def safeDivideDefault(
1554        self,
1555        default_denominator: int | float,
1556        denominator: int | float,
1557        a: int | float,
1558    ):
1559        """
1560        Function:
1561
1562        - Forces division to work by enforcing a non zero default denominator if the provided denominator is zero
1563
1564        Requires:
1565
1566        - `default_denominator`:
1567            - Type: int | float
1568            - What: A non zero denominator to use if denominator is zero
1569            - Default: 1
1570        - `denominator`:
1571            - Type: int | float
1572            - What: The denominator
1573        - `a`:
1574            - Type: int | float
1575            - What: The numerator
1576
1577        Example:
1578
1579        ```
1580        pamda.safeDivideDefault(2,5,10) #=> 2
1581        pamda.safeDivideDefault(2,0,10) #=> 5
1582        ```
1583        """
1584        if default_denominator == 0:
1585            raise Exception(
1586                "`safeDivideDefault` `default_denominator` can not be 0"
1587            )
1588        return a / denominator if denominator != 0 else a / default_denominator
1589
1590    def symmetricDifference(self, a: list, b: list):
1591        """
1592        Function:
1593
1594        - Combines two lists into a list of no duplicates items present in one list but not the other
1595
1596        Requires:
1597
1598        - `a`:
1599            - Type: list
1600            - What: List of items in which to look for a difference
1601        - `b`:
1602            - Type: list
1603            - What: List of items in which to look for a difference
1604
1605        Example:
1606
1607        ```
1608        a=['a','b']
1609        b=['b','c']
1610        pamda.symmetricDifference(a=a, b=b) #=> ['a','c']
1611        ```
1612        """
1613        return list(set(a).difference(set(b))) + list(set(b).difference(set(a)))
1614
1615    def tail(self, data: list | str):
1616        """
1617        Function:
1618
1619        - Picks the last item out of a list or string
1620
1621        Requires:
1622
1623        - `data`:
1624            - Type: list | str
1625            - What: A list or string
1626
1627        Example:
1628
1629        ```
1630        data=['fe','fi','fo','fum']
1631        pamda.tail(
1632            data=data
1633        ) #=> fum
1634        ```
1635        """
1636        if not len(data) > 0:
1637            raise Exception("Attempting to call `tail` on an empty list or str")
1638        return data[-1]
1639
1640    def thunkify(self, fn):
1641        """
1642        Function:
1643
1644        - Creates a curried thunk out of a function
1645        - Evaluation of the thunk lazy and is delayed until called
1646
1647        Requires:
1648
1649        - `fn`:
1650            - Type: function | method
1651            - What: The function or method to thunkify
1652            - Note: Thunkified functions are automatically curried
1653            - Note: Class methods auto apply self during thunkify
1654
1655        Notes:
1656
1657        - Input functions are not thunkified in place
1658        - The returned function is a thunkified version of the input function
1659        - A curried function can be thunkified in place by calling fn.thunkify()
1660
1661        Examples:
1662
1663        ```
1664        def add(a,b):
1665            return a+b
1666
1667        addThunk=pamda.thunkify(add)
1668
1669        add(1,2) #=> 3
1670        addThunk(1,2)
1671        addThunk(1,2)() #=> 3
1672
1673        x=addThunk(1,2)
1674        x() #=> 3
1675        ```
1676
1677        ```
1678        @pamda.curry
1679        def add(a,b):
1680            return a+b
1681
1682        add(1,2) #=> 3
1683
1684        add.thunkify()
1685
1686        add(1,2)
1687        add(1,2)() #=> 3
1688        ```
1689        """
1690        fn = self.curry(fn)
1691        return fn.thunkify()
1692
1693    def unnest(self, data: list):
1694        """
1695        Function:
1696
1697        - Removes one level of depth for all items in a list
1698
1699        Requires:
1700
1701        - `data`:
1702            - Type: list
1703            - What: A list of items to unnest by one level
1704
1705        Examples:
1706
1707        ```
1708        data=['fe','fi',['fo',['fum']]]
1709        pamda.unnest(
1710            data=data
1711        ) #=> ['fe','fi','fo',['fum']]
1712        ```
1713        """
1714        if not len(data) > 0:
1715            raise Exception("Attempting to call `unnest` on an empty list")
1716        output = []
1717        for i in data:
1718            if isinstance(i, list):
1719                output += i
1720            else:
1721                output.append(i)
1722        return output
1723
1724    def zip(self, a: list, b: list):
1725        """
1726        Function:
1727
1728        - Creates a new list out of the two supplied by pairing up equally-positioned items from both lists
1729
1730        Requires:
1731
1732        - `a`:
1733            - Type: list
1734            - What: List of items to appear in new list first
1735        - `b`:
1736            - Type: list
1737            - What: List of items to appear in new list second
1738
1739        Example:
1740
1741        ```
1742        a=['a','b']
1743        b=[1,2]
1744        pamda.zip(a=a, b=b) #=> [['a',1],['b',2]]
1745        ```
1746        """
1747        return list(map(list, zip(a, b)))
1748
1749    def zipObj(self, a: list, b: list):
1750        """
1751        Function:
1752
1753        - Creates a new dict out of two supplied lists by pairing up equally-positioned items from both lists
1754        - The first list represents keys and the second values
1755
1756        Requires:
1757
1758        - `a`:
1759            - Type: list
1760            - What: List of items to appear in new list first
1761        - `b`:
1762            - Type: list
1763            - What: List of items to appear in new list second
1764
1765        Example:
1766
1767        ```
1768        a=['a','b']
1769        b=[1,2]
1770        pamda.zipObj(a=a, b=b) #=> {'a':1, 'b':2}
1771        ```
1772        """
1773        return dict(zip(a, b))