pamda.pamda

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