gfgNdZddlmZmZmZmZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddl Z ddl!Z!ddl"Z"ddl#Z#ddl$Z$ddl%m&Z&m'Z'ddl%m(Z(m)Z)m*Z*ddl%m+Z+m,Z,m-Z-ddl%m.Z.m/Z/m0Z0m1Z1m2Z2ddl%m3Z3dd l%m4Z4m5Z5dd l%m6Z6m7Z7m8Z8d Z9d Z:d ddddddZ;dZdDcic] \}}||dz c}}e>dDcic] \}}||dz c}}ddiddidddddddZ?e?dje?d e?dje?d!e?d"je?d jDcic] \}}||e=z c}}e?d#je?d!jDcic] \}}||e=z c}}e?d$je?d"e?d$je?d#eje?ZCeje?ZDd%D]2ZEe?eEd&eDeEd'<e?eEd&eDeEd(<e?eEd&eCeEd'<eCeEd&=4eFjd)d*ZHeFjd)d+ZId,ZJeJDcic]}||c}ZKeKjeLd-eMd.eNd/eFd0ieKjd-d1d2d3d4d.d5d6d7d8d9d/d:d0d;dd?d@ZPhdAZQejeFjdZTdBZUdCZVdrdDZWdEZXeX dsdGZYeX dtdHZZGdIdJe[Z\dKZ]dLZ^ dudNZSdOZ_dPZ`dQe"jdRdfdSZb dvdTZc dudUZddVZedWZf drdXZgdYZh dwdZZi dud[Zje\ dxd\Zk dyd]ZleFemenffd^ZodeFemenffd_ZpdeFemenffd`Zq dzdaZrejdMfdbZtejfdcZuddZvdMdeweFemenffdeZxdMdewdMeFemenffdfZy d{dgZz drdhZ{deFemenffdiZ| d|djZ} d}dkZ~dlZ drdmZddeFemenffdnZ d~doZdeFemenffdpZdddddeFemenffdqZde j fdrZ dwdsZdddefdtZ dwduZddedFfdvZ dwdwZ dwdxZ ddyZddedFfdzZ dwd{Z dwd|Zd}Z dwd~ZdZewdfdZ d}dZ ddZ ddZ d|dZ d}dZ ddZ ddZ drdZ drdZ dxdZ drdZ drdZ dxdZ dxdZ dudZ drdZddddZ drdZ ddZ drdZ ddZddMfdZdZ dwdZ ddZ ddZdZdZdZdZdZdZdZdZdZdZ ddZ ddZ d}dZ d}dZdZdZdZdZdZdZdZdZdZ ddZdZdZdZ ddZ ddZ ddZ ddZddefdZdZdededddDzZeeeҫfd„Z drdÄZddedfdĄZddedfdńZ drdƄZedfdDŽZdȄZ ddʄZd˄Z dd̄Z dd̈́Zdd΄dFfdτZdЄZdфZd҄ZdӄZdԄZ dudՄZddքZ ddׄZd؄Z dudلZ dudڄZdۄZd܄Zd݄ZdބZd߄ZdZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZdZdZ dudZ dudZ dudZ ddZ ddZdedMfdZddddMedfdZddMedfdZdZ dudZ dudZdZdZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ ddZ dd Z dd Z dd Zd Zd Z ddZdZdZ drdZ drdZ dZ!dZ"dZ#dFddZ$ ddZ% ddZ&dZ'dddejPfdZ)dejPfdZ* ddZ+e jXe!jZdɐdfd Z.d!e jXe!jZdfd"Z/ddd#e"j`e"jbdFfd$Z2 dd%Z3 dd&Z4 dd'Z5d(Z6dd)dd*ddFe)fd+Z7dd,ddde)fd-Z8 dud.Z9ddMdMe)fd/Z: dd0Z; dd1ZZJ dd?ZK dd@ZL ddAZM ddBZNddeMeNeOeNffdCZPdDZQ ddFZRepeDd$fdGZSepe?d$fdHZT ddIZU ddJZVepeDd$dEfdKZWepe?d$dEfdLZX ddMZY ddNZZ ddOZ[ ddPZ\ ddQZ] drdRZ^dSZ_drdTZ` ddUZa ddVZb ddWZc ddXZd ddYZedZZfdFe)dFdFfd[Zg dud\Zh dud]Zid^Zjd_Zkd`ZlefdaZm ddbZn ddcZo dddZpeXdedfdgddhdeee jdMdMdidMe)fdjZrddeΐdkeѐdEDdldmddFdndodMe)f dpZse+ejzjeteudqk(r e-eyycc}}wcc}}wcc}}wcc}}wcc}w(z% flyingcircus.base: Base subpackage. )divisionabsolute_importprint_functionunicode_literalsN)INFOPATH)VERB_LVL D_VERB_LVLVERB_LVL_NAMES)elapsedreport run_doctests)msgdbgfmtfmtmsafe_format_map)do_nothing_decorator)HAS_JITjit) valid_indexfind_allnested_delimiters #gzbz2lzmaxzlz)gzipbzipbzip2rrlzip)kMGTPEZY)mμnpfazy)dah)dc) base1000+ base1000-base1000base10base10+base10-rBr@rArDrErC)rArErBrCr1uµz0123456789.e+-=()nu2⁰¹²³⁴⁵⁶⁷⁸⁹·ᵉ⁺⁻⁼⁽⁾ⁿu4₀₁₂₃₄₅₆₇₈₉.ₑ₊₋₌₍₎ₙ)xr?bB?r;HiIlLqQr4r>sr3r+rKrMr4rSrIrJr;rLrNrOrPrQrRr>)boolcharucharshortushortintuintlongulongllongullongfloatdoublestr)crc32adler32) shake_128 shake_256>b16b32b64b85 urlsafe_b64c^tjj|jdS)a Heuristic to determine hidden files. Args: filepath (str): the input filepath. Returns: is_hidden (bool): True if is hidden, False otherwise. Notes: Only works with UNIX-like files, relying on prepended '.'. .)ospathbasename startswith)filepaths i/var/dept/share/cheung/public_html/OutSchool/python/env/lib/python3.12/site-packages/flyingcircus/base.py _is_hiddenrvs$ 77  H % 0 0 55ctj| xr.tj| xrtj| }|S)a Heuristic to determine non-standard files. Args: stats_mode (mode): A mode as specified by the `stat` module. Returns: is_special (bool): True if is hidden, False otherwise. Notes: Its working relies on Python stat module implementation. )statS_ISREGS_ISDIRS_ISLNK) stats_mode is_specials ru _is_specialrsH LL $$ % LL $$ % LL $$ rwc| t|}t|st}n#|turt}n|t t fvrt } ||dd|S#t$r t}Y|SwxYw)aT Guess container for combinatorial computations. Args: seq (Sequence): The input items. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Returns: container (callable): The container function. r)typecallabletuplera _str_joinbytes bytearray TypeError)seq containers ru_guess_containerrsvI I  c  ui( ( #a(   s AA$#A$cBtjfd}|S)a Create a decorator-factory from a decorator. This is for creating decorators with parameters. Note: contrarily to function parameters, decorator parameter's names should never be reassigned. Args: decorator (callable): The input decorator. Returns: decorator_factory (callable): The decorated decorator-factory. Examples: >>> def multiply(func): ... @functools.wraps(func) ... def wrapper(*args, **kws): ... return 10 * func(*args, **kws) ... return wrapper >>> @multiply ... def my_sum(values): ... return sum(values) >>> my_sum(range(10)) 450 >>> @parametric ... def multiply(func, factor=1): ... @functools.wraps(func) ... def wrapper(*args, **kws): ... return factor * func(*args, **kws) ... return wrapper >>> @multiply() ... def my_sum(values): ... return sum(values) >>> my_sum(range(10)) 45 >>> @multiply(10) ... def my_sum(values): ... return sum(values) >>> my_sum(range(10)) 450 cfd}|S)Nc|giSN)func_args_kws decorators ru_wrapperz0parametric.._decorator.._wrapper'sT2E2T2 2rwr)rrrrs`` ru _decoratorzparametric.._decorator%s 3rw functoolswraps)rrs` ru parametricrs)Z__Y  rwFcJtjfd}|S)a~ Decorate a function to accept starred arguments instead of an iterable. Args: func (callable): The input function. mode (str): The auto-star detection mode. This determines on what condition `func` is decorated. Allowed modes: - 'type': if the first parameter is iterable. - 'nargs': if `func` accepts a single parameter. allow_empty (bool): Allow `func` to be called without parameters. This is effective only if the first parameter of `func` does not have a default value. Returns: wrapper (callable): The decorated function. Raises: TypeError: If `allow_empty` is False, `func`'s first parameter does not have a default value and no value is specified when calling the decorated function. Examples: >>> @auto_star_magic('type', True) ... def my_prod(items, start=1): ... for item in items: ... start *= item ... return start >>> print(my_prod(1, 2, 3)) 6 >>> print(my_prod(range(1, 4))) 6 >>> print(my_prod()) 1 >>> @auto_star_magic('type', False) ... def my_prod(items, start=1): ... for item in items: ... start *= item ... return start >>> print(my_prod(1, 2, 3)) 6 >>> print(my_prod(range(1, 4))) 6 >>> print(my_prod()) Traceback (most recent call last): ... TypeError: my_prod() missing 1 required positional argument: 'items' >>> @auto_star_magic('nargs', True) ... def my_prod(items): ... start = 1 ... for item in items: ... start *= item ... return start >>> print(my_prod(1, 2, 3)) 6 >>> print(my_prod(range(1, 4))) 6 >>> print(my_prod()) 1 >>> @auto_star_magic('nargs', False) ... def my_prod(items): ... start = 1 ... for item in items: ... start *= item ... return start >>> print(my_prod(1, 2, 3)) 6 >>> print(my_prod(range(1, 4))) 6 >>> print(my_prod()) Traceback (most recent call last): ... TypeError: my_prod() missing 1 required positional argument: 'items' ctj}tt|j}t dr j nd}|j|jtjjk7}s$|s"t|dk(rttd dk(r t|dd}n dk(rt|d k(}nd}|r|i|S|fi|S#ttf$rd}Y&wxYw) N__name__z rzJ{func_name}() missing 1 required positional argument: '{first_param_name}'rTFnargsr/)inspect signaturenextiter parametershasattrrdefault Parameteremptylenrr IndexError) argskwssigfirst_param_name func_name has_defaultuse_star allow_emptyrmodes ruwrapperz auto_star_magic..wrappers%S^^ 45%,T:%>DMMK NN+ , 4 48I8I8O8O O ;3t9>,-. . v~$aM $Ht9> )14%% HtD7HC7H H":.%$H%s/C))C=<C=r)rrrrs``` ruauto_star_magicr0s*f__TII2 NrwcJtjfd}|S)a Decorator for iterize a function in its positional arguments. Furthermore, it adds support for an additional `fill` parameter (the exact parameter name can be changed). This parameter controls how shorter iterables are extented. If `fill` is None, the iterable is extended using an infinite loop. Otherwise, uses the `fill` value specified. Args: func (callable): The input function. container (callable|None): The container for the result. If callable, must accept a `map` object, otherwise the `map` object itself will be used. fill_param (str): The name of the extra parameter used for filling. Returns: wrapper (callable): The iterized function. Examples: >>> @iterize(list) ... def isum(*x): ... return sum(x) >>> isum(range(10), 100) [100, 101, 102, 103, 104, 105, 106, 107, 108, 109] >>> isum(range(10), 100, fill=0) [100, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> isum(range(10), range(5)) [0, 2, 4, 6, 8, 5, 7, 9, 11, 13] >>> isum(range(10), range(3)) [0, 2, 4, 3, 5, 7, 6, 8, 10, 9] >>> isum(range(10), range(3), fill=0) [0, 2, 4, 3, 4, 5, 6, 7, 8, 9] >>> isum(range(4), range(8), range(12), fill=0) [0, 3, 6, 9, 8, 10, 12, 14, 8, 9, 10, 11] >>> isum(range(4), range(8), range(12)) [0, 3, 6, 9, 8, 11, 14, 17, 8, 11, 14, 17] c |vr|j ndfdntjdg}|D]5} t| t t ||j|7fd|D}t g|i|}tr|}|S#t $rYNwxYw#t $r|g}Y`wxYw)Nc3.K|D]}| wrr)itemsitemfills ruextendz(iterize..wrapper..extends(!DJJrc3NK|]}t|k(r|n|ywrr).0iargrmax_lens ru z+iterize..wrapper..s,N?CCI(DfTl :Ns"%) pop itertoolscyclermaxrrappendmapr) rriargsargresultrrrr fill_paramrs @@@rurziterize..wrappers&0C&7swwz"T    __F C S !'3s84G LL  NGLNT)E)S) I v&F !  e s# B1 B"" B.-B.1 C?Cr)rrrrs``` ruiterizers)Z__T@ NrwceZdZdZdZGddZGddZdZdZd Z exZ xZ xZ xZ xZxZxZxZxZxZxZxZZexZxZxZxZxZxZxZxZxZxZ xZ!xZ"Z#y ) Infixa+ Emulate an infix operator using an arbitrary variable. This can also be used as a decorator. Examples: >>> to = Infix(range) >>> to(1, 10) range(1, 10) >>> 1 | to | 10 range(1, 10) >>> [x for x in 1 | to | 15] [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14] >>> @Infix ... def till(a, b): ... return range(a, b) >>> (1 | to | 10) == (1 | till | 10) True >>> ((1 + to + 9) == (1 - to - 9) == (1 * to * 9) == (1 / to / 9) ... == (1 // to // 9) == (1 % to % 9) == (1 ** to ** 9) ... == (1 >> to >> 9) == (1 << to << 9) ... == (1 | to | 9) == (1 & to & 9) == (1 ^ to ^ 9) ... == (1 << to >> 9) == (1 + to ^ 9)) # etc. (all combos work) True c||_y)z Args: func (callable): The function to emulate the binary operator. The function must support two positional arguments. Nr)selfrs ru__init__zInfix.__init__s  rwcLeZdZdZdZexZxZxZxZxZ xZ xZ xZ xZ xZxZxZZy) Infix.RBindc ||_||_yrrbindedrrrs rurzInfix.RBind.__init__DI DKrwc:|j||jSrrrothers ru__call__zInfix.RBind.__call__!s99UDKK0 0rwN)r __module__ __qualname__rr__radd____rsub____rmul__ __rtruediv__ __rfloordiv____rmod____rpow__ __rmatmul__ __rlshift__ __rrshift____ror____rand____rxor__rrwruRBindrsn !  1 -5 5 58 5h 5 5  5  5 5"- 50; 5>I 5  5rwrcLeZdZdZdZexZxZxZxZxZ xZ xZ xZ xZ xZxZxZZy) Infix.LBindc ||_||_yrrrs rurzInfix.LBind.__init__,rrwc:|j|j|Srrrs rurzInfix.LBind.__call__1s99T[[%0 0rwN)rrrrr__add____sub____mul__ __truediv__ __floordiv____mod____pow__ __matmul__ __lshift__ __rshift____or____and____xor__rrwruLBindr*sn !  1 *2 2 2' 2G 2k 2L 2  2 2 * 2-7 2:D 2  2wrwrc:|j|j|Sr)rrrs rurbindz Infix.rbind:zz$))U++rwc:|j|j|Sr)rrrs rulbindz Infix.lbind>rrwc&|j||Srr)rvalue1value2s rurzInfix.__call__Bsyy((rwN)$rrr__doc__rrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrwrurrs: 5 5 2 2 ,,) &++G+g++++ +++&+)3+6@++7)..H.x.(.\.M...).,7.:E..XrwrcF tj}||}t t t |jt |j}i}|jD]}||vr ||||<||vs||||<|S#t$rtj}YwxYw)a Set keyword parameters of a function to specific or default values. Args: func (callable): The function to be inspected. func_kws (Mappable|None): The (key, value) pairs to set. If a value is None, it will be replaced by the default value. To use the names defined locally, use: `locals()`. Results: result (dict): A dictionary of the keyword parameters to set. See Also: inspect, locals, globals. ) rgetfullargspecAttributeError getargspecdictzipreversedrdefaults)rfunc_kws get_argspec inspectedrrkeys ru set_func_kwsrOs$),, D!I HY^^ $hy/A/A&BCEH F~~( (?"3-F3K H_"3-F3K ( M )(( )sBB B c tj}||}i}i}|j D]\}}||j vr|||<|||< ||fS#t$rtj}Y\wxYw)a Split a set of keywords into accepted and not accepted by some function. Args: func (callable): The function to be inspected. func_kws (Mappable|None): The (key, value) pairs to split. Results: result (tuple): The tuple contains: - in_func (dict): The keywords NOT accepted by `func`. - not_in_func (Mappable|None): The keywords accepted by `func`. See Also: inspect, locals, globals. )rr r r rr)rrrrin_func not_in_funcr'vs rusplit_func_kwsrrs&),, D!IGK 1  GAJKN  K  )(( )sAA/.A/Tct|}t|}t|}|tk(rb|rJ|D]C}t |t r|j }nt |ts t|}||z }E|S|dj|z }|S|t tfvrh|rP|D]I}t |tr|j}n!t |t tfs t |}||z }K|S|dj|z }|St|dr2|r"|D]}|t ||r|n||z }|S|D]}||z } |St|dr2|r"|D]}|t ||r|n||z}|S|D]}||z} |St|drJ|r.|D]'}|jt ||r|n||)|S|D]}|j||Sttd)ae Join together multiple containers. Args: operands (Iterable): The operands to join. coerce (bool): Cast all operands into the type of the first. Returns: result: The joined object. Examples: >>> join(([1], [2], [3])) [1, 2, 3] >>> join(((1, 2), (3, 4))) (1, 2, 3, 4) >>> join(({1: 2}, {2: 3}, {3: 4})) {1: 2, 2: 3, 3: 4} >>> join(({1}, {2, 3}, {3, 4})) {1, 2, 3, 4} >>> join(([1], [2], (3, 4))) [1, 2, 3, 4] >>> join(((1,), [2], (3, 4))) (1, 2, 3, 4) >>> join(((1, 2), (3, 4)), coerce=False) (1, 2, 3, 4) >>> join(((1,), [2], (3, 4)), coerce=False) Traceback (most recent call last): ... TypeError: can only concatenate tuple (not "list") to tuple # These are side effect of duck-typing: >>> join([1, 2.5, 3]) 6 >>> join([1.0, 2.5, 3]) 6.5 >>> join([[1], 2, 3.0]) Traceback (most recent call last): ... TypeError: 'int' object is not iterable >>> join([1, [2], 3.0]) Traceback (most recent call last): ... TypeError: int() argument must be a string, a bytes-like object or a number, not 'list' >>> join(['aaa', 'bbb', 'ccc']) 'aaabbbccc' >>> join([b'aaa', b'bbb', b'ccc']) b'aaabbbccc' >>> join(x for x in string.ascii_lowercase) 'abcdefghijklmnopqrstuvwxyz' >>> join(x.encode() for x in string.ascii_lowercase) b'abcdefghijklmnopqrstuvwxyz' >>> join(['aaa', b'bbb', 'ccc']) 'aaabbbccc' >>> join([b'aaa', 'bbb', b'ccc']) b'aaabbbccc' >>> join(['aaa', b'bbb', 'ccc'], False) Traceback (most recent call last): ... TypeError: sequence item 0: expected str instance, bytes found >>> join([b'aaa', 'bbb', b'ccc'], False) Traceback (most recent call last): ... TypeError: sequence item 0: expected a bytes-like object, str found See Also: - flyingcircus.join_() r8rw__iadd__rupdatez%Cannot apply `join()` on `{operands}`)rrrra isinstancerdecodejoinrencoderr ValueErrorr)operandscoerce iter_operandsr type_resultrHs rur r sQRNM - Fv,Kc " a' A#As+AA!   V MI bggm, ,FH MG  * * " a% A#Ay'9:aA!   B M5 chh}- -F4 M3  $ " Nz![9!{1~M N. M)# !  ( M%  # " I#A{3AQI I M# $! $ M  " " I #A{3AQI I M # ! a  ! MEFGGrwct|fi|S)a Star magic version of `flyingcircus.join()`. Examples: >>> join_([1], [2], [3]) [1, 2, 3] >>> join_((1, 2), (3, 4)) (1, 2, 3, 4) >>> join_({1: 2}, {2: 3}, {3: 4}) {1: 2, 2: 3, 3: 4} >>> join_({1}, {2, 3}, {3, 4}) {1, 2, 3, 4} >>> join_([1], [2], (3, 4)) [1, 2, 3, 4] >>> join_((1,), [2], (3, 4)) (1, 2, 3, 4) >>> join_((1, 2), (3, 4), coerce=False) (1, 2, 3, 4) >>> join_((1,), [2], (3, 4), coerce=False) Traceback (most recent call last): ... TypeError: can only concatenate tuple (not "list") to tuple See Also: - flyingcircus.join() )r )r#rs rujoin_r(s6  !D !!rwc,|D]}t||}|S)aF Get the nested attributes of an object. Args: obj (Any): The input object. *names (tuple[str]): The attributes to get. Returns: Any: The specified attribute. Examples: >>> print(get_nested_attr(1, 'real')) 1 >>> print(get_nested_attr(1, 'real', 'imag')) 0 >>> print(get_nested_attr(1, '__class__')) >>> print(get_nested_attr(1, '__class__', '__name__')) int >>> print(get_nested_attr(1, '__class__', '__name__', '__class__')) )getattr)objnamesnames ruget_nested_attrr.1s$2!c4 ! Jrwsha256hexct|r||}t|tr|tjvr\|t vr/t |}t t||j|}nt t||j}nz|tvrTt|}t t||j|d}tj|jd}ntdt|r||}t|trH|dk(rtj|}n@|tvrt t |d|}ntdt|r||}t|t"r |jd}||d|}|S#t$$r'tj|jd}Y8wxYw)aCompute a checksum of an object. Args: obj (Any): The input object. chksum_func (callable|str): The checksum computing function. If str, must be in `hashlib.algorithm_available` or one of {"crc32", "adler32"}. ser_func (callable|str|None): The serialization function. to_str_func (callable|str|None): The checksum-to-string conversion function. If str, must be one of: - "hex": uses `binascii.b2a_hex()` - "b16": uses `base64.b16encode()` - "b32": uses `base64.b32encode()` - "b64": uses `base64.b64encode()` - "b85": uses `base64.b85encode()` - "urlsafe_b64": uses `base64.urlsafe_b64encode()` max_len: Max length of the checksum. If the checksum exceed this value, it is coerced to the specific length. If None, uses the default length. Returns: The computed checksum as string. Examples: >>> chksum(1) '018f5c4626b56e8489da7abb6c8b62331933c42c35d1342037a5242b8ed148f6' >>> chksum("This is some text") '388ef7c8f5cb46a241f12dbb7eefb5bde22b4cf1db539a03a71cb00b94b790e1' >>> chksum(None) '9c298d589a2158eb513cb52191144518a2acab2cb0c04f1df14fca0f712fa4a1' >>> chksum({1: {2: 3, 4: {5: [6, {7: 8}], 9: 0}}}) 'c6e3c985351ce6e394d77f931ae65fe8c78beb1c7f3521affa46c00cdd997557' littleasciizUnsupported checksum method.r0r!zUnsupported conversion method.N)rrrahashlibalgorithms_available_VAR_LENGTH_HASHLIB_ALGORITHMSr*digest_ZLIB_CHECKSUMSzlibto_bytesbinasciib2a_hexrr"_BASE64_ENCODINGSbase64rUnicodeDecodeError)r+ chksum_funcser_func to_str_funcrlength chksum_sizes ruchecksumrEPsRsm+s# '66 6<<7 D3gg{3C8??G3gg{3C8??A O +)+6K,'$ ,S1::;QC""3'..w7C;< < + #+s# % ""3'C - -9'&[M"89#>C=> > + ##u 8**W%C(7m J " 8""3'..w7C 8sF""-GGc#Kt|s|fd}|s|syt|D]6}||r t||}t|}|r|s|s*|r-|r||fn|8yw)a Iteratively (and selectively) list the attributes of an object. Args: obj (Any): The input object. skip (str|callable): The skip criterion. If str, names starting with the specified string are skipped. If callable, skips when `skip(name)` evaluates to True. methods (bool): Include methods. If False, the callable attributes are excluded. attributes (bool): Include non-callable attributes. If False, the non-callable attributes are excluded. yield_attr (bool): Yield both the name and the attribute. If False, only the name is yielded (same behavior as `dir()`). Yields: str|tuple[str, Any]: The name or the name/attribute pair. The return type/mode depends on the value of `yield_attr`. Examples: >>> list(idir(1, '_', True, True)) # doctest:+ELLIPSIS [..., 'from_bytes', 'imag', 'numerator', 'real', 'to_bytes'] >>> list(idir(1, '_', False, True)) ['denominator', 'imag', 'numerator', 'real'] >>> list(idir(1, '_', True, False)) ['bit_length', 'conjugate', 'from_bytes', 'to_bytes'] >>> list(idir(1, '_', False, False)) [] >>> list(idir(1, '_', False, True, True)) [('denominator', 1), ('imag', 0), ('numerator', 1), ('real', 1)] >>> list(idir(1, '_', True, False, True)) # doctest:+ELLIPSIS [('bit_length', ), ('conjugate', ), ('from_bytes', ), ('to_bytes', )] c$|j|Srrs)trSs ruskipzidir..skips<<? "rwN)rdirr*)r+rJmethods attributes yield_attrr-attr is_callables ruidirrQshV D> # :C;Dz3%D"4.KKZ &0tTld: ;s,AA A Ac|jDcic]\}}|| }}}|r"t|t|k7r td|Scc}}w)at Reverse the (key, value) relationship of a mapping. Given a (key, value) sequence, returns a (value, key) sequence. The values in the input mapping must be allowed to be used as `dict` keys. Args: mapping (Mapping): The input mapping check (bool): Perform a validity check. The check succeeds if all values in the original mapping are unique. Returns: result (dict): The reversed mapping. Raises: KeyError: if `check == True` and a duplicate key is detected. Examples: >>> mapping = {i: str(i) for i in range(5)} >>> print(sorted(mapping.items())) [(0, '0'), (1, '1'), (2, '2'), (3, '3'), (4, '4')] >>> print(sorted(reverse_mapping(mapping).items())) [('0', 0), ('1', 1), ('2', 2), ('3', 3), ('4', 4)] >>> reverse_mapping({1: 2, 2: 2}) Traceback (most recent call last): ... KeyError: 'Reversing a mapping detected duplicate key in the result!' >>> reverse_mapping({1: 2, 2: 2}, False) {2: 2} See Also: - flyingcircus.reverse_mapping_iter() z9Reversing a mapping detected duplicate key in the result!)rrKeyError)mappingcheckr'rrs rureverse_mappingrVsVJ '}} /tq!ad /F / WV, GI I 0s A c< t|S#t$ricYSwxYw)aTransparently convert any object to dict. If the object cannot be converted to `dict`, returns an empty `dict`. Args: obj: The input object. Returns: The object converted to a dict. Examples: >>> as_dict({1: 2, 3: 4}) {1: 2, 3: 4} >>> as_dict(((1, 2), (3, 4))) {1: 2, 3: 4} >>> as_dict([[1, 2], [3, 4]]) {1: 2, 3: 4} >>> as_dict(()) {} >>> as_dict(None) {} )r r)r+s ruas_dictrXs%.Cy  s ci}|jD]+\}}|D]!}||vr||j||g||<#-|S)a7 Reverse the (key, values) relationship of a mapping. Given a (key, values) sequence, returns a reversed (value, keys) sequence. The input values need to be iterable and their items need to be hashable. Each of the values either generates a new key or gets appended to the new values in the result. Args: mapping (Mapping): The input mapping with iterable values. Returns: result (dict): The reversed mapping. Examples: >>> mapping = {i: [str(i)] for i in range(5)} >>> print(sorted(mapping.items())) [(0, ['0']), (1, ['1']), (2, ['2']), (3, ['3']), (4, ['4'])] >>> print(sorted(reverse_mapping_iter(mapping).items())) [('0', [0]), ('1', [1]), ('2', [2]), ('3', [3]), ('4', [4])] >>> reverse_mapping_iter({1: [2], 2: [2]}) {2: [1, 2]} >>> reverse_mapping_iter({1: [1, 2], 2: [2]}) {1: [1], 2: [1, 2]} >>> reverse_mapping_iter({1: [1, 2, 1], 2: [2, 1]}) {1: [1, 1, 2], 2: [1, 2]} See Also: - flyingcircus.reverse_mapping() )rr)rTrrvaluesvalues rureverse_mapping_iterr\$s\>F}}& V &Eu $$S)!$u  && Mrwc t|| t|}t|st}t j ||}|tk(r|S||S#t $r||cYSwxYw)a+ Extract selected items according to the specified indexes. Note that this is mostly equivalent to (but faster than) `flyingcircus.iter_at()`. Args: seq (Sequence): The input items. indexes (Iterable[int|slice]): The items to select. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Returns: result: The selected items. Examples: >>> items = [x ** 2 for x in range(20)] >>> print(multi_at(items, (0, 6, 7, 0, 1, 3))) [0, 36, 49, 0, 1, 9] >>> indexes = (0, 6, 7, slice(1, 3)) >>> print(multi_at(items, (12, 4, 11, slice(1, 3)))) [144, 16, 121, [1, 4]] >>> print(multi_at(items, 19)) 361 >>> print(multi_at(items, slice(3, 9, 2))) [9, 25, 49] >>> items = string.ascii_letters >>> print(multi_at(items, (0, 6, 7, 0, 1, 3))) ('a', 'g', 'h', 'a', 'b', 'd') >>> indexes = (0, 6, 7, slice(1, 3)) >>> print(multi_at(items, (12, 4, 11, slice(1, 3)))) ('m', 'e', 'l', 'bc') >>> print(multi_at(items, 19)) t >>> print(multi_at(items, slice(3, 9, 2))) dfh See Also: - flyingcircus.iter_at() )rrrroperator itemgetterr)rindexesrrs rumulti_atraNsw\ C W   S I "I.$$g.s3"e+vB61BB 7|s AA'&A'c#K t||D] }|| y#t$r7 t||||D]}|Yy#t$r ||YYywxYwwxYww)a3 Iterate over selected items according to the specified indexes. Note that this is mostly equivalent to `flyingcircus.multi_at()` except that this yields a generator. Args: seq (Sequence): The input items. indexes (Iterable[int|slice]): The items to select. Yields: item: The selected item. Examples: >>> items = [x ** 2 for x in range(20)] >>> print(list(iter_at(items, (0, 6, 7, 0, 1, 3)))) [0, 36, 49, 0, 1, 9] >>> indexes = (0, 6, 7, slice(1, 3)) >>> print(list(iter_at(items, (12, 4, 11, slice(1, 3))))) [144, 16, 121, [1, 4]] >>> print(list(iter_at(items, 19))) [361] >>> print(list(iter_at(items, slice(3, 9, 2)))) [9, 25, 49] See Also: - flyingcircus.multi_at() N)rr)rr`indexrs ruiter_atrds>  W  Ee*     W G     g,  sGA! A! AAAA!AAA!AAA!c#Kt|}|dkDr?t||}t||}|} |j||}||kr ||dz }ny#y#t$rYywxYww)aV Find all occurrences of an item in an sequence. For dense inputs (item is present in more than ~20% of the sequence), a looping comprehension may be faster. For string, bytes or bytearray inputs, `flyingcircus.find_all()` is typically faster. Args: seq (Sequence): The input sequence. item (Any): The item to find. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. Yields: position (int): The position of the next finding. Examples: >>> list(index_all([1, 2, 3, 5, 3, 4, 5, 7, 8], 3)) [2, 4] >>> list(index_all((1, 2, 3, 5, 3, 4, 5, 7, 8), 3)) [2, 4] >>> list(index_all((1, 2, 3, 5, 3, 4, 5, 7, 8), 0)) [] >>> list(index_all((1, 2, 3, 5, 3, 4, 5, 7, 8), [3, 5])) [] >>> list(index_all((1, 2, 3, 5, 3, 4, 5, 7, None), None)) [8] >>> list(index_all((1, 2, 3, 5, 3, 4, 5, 7, 8), ())) [] >>> list(index_all('0010120123012340123450123456', '0')) [0, 1, 3, 6, 10, 15, 21] >>> list(index_all(' 1 12 123 1234 12345 123456', '0')) [] >>> list(index_all(' 1 12 123 1234 12345 123456', '12')) [4, 7, 11, 16, 22] >>> list(index_all(b' 1 12 123 1234 12345 123456', b'12')) [4, 7, 11, 16, 22] >>> list(index_all('0123456789', '')) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(index_all('', '')) [] >>> list(index_all('', '0123456789')) [] >>> list(index_all(b'0123456789', b'')) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(index_all(b'', b'')) [] >>> list(index_all(b'', b'0123456789')) [] See Also: - flyingcircus.find_all() rr/N)rrrcr")rrfirstlastr2rMs ru index_allrhs| CA1uE1%4#  IIdA&9GFA     s4+A""AA"AA" AA"AA"c #RKt|x}}g}tt||}tt||}|j|} t | D]} | |vr|j | dz| |vs!t |dkDr'|j} | |z | |zt |fVttdt |t |z || t |dkDr=ttdt |t |z ||jdz yw)a$ Find matching delimiters in a sequence. The delimiters are matched according to nesting level. For string, bytes or bytearray inputs, `flyingcircus.find_nested_delims()` is a better option, because it supports multi-char delimiters and it is typically faster. Args: seq (Sequence): The input sequence. l_item (Any): The left delimiter item. r_item (Any): The right delimiter item. including (bool): Include delimiters. yields: result (tuple[int]): The matching delimiters. Examples: >>> s = '{a} {b:{c}}' >>> list(nested_pairs(s, '{', '}')) [(0, 3, 0), (7, 10, 1), (4, 11, 0)] >>> [s[i:j] for i, j, depth in nested_pairs(s, '{', '}')] ['{a}', '{c}', '{b:{c}}'] >>> [s[i:j] for i, j, d in nested_pairs(s, '{', '}') if d == 0] ['{a}', '{b:{c}}'] >>> list(nested_pairs('{a} {b:{c}', '{', '}')) Traceback (most recent call last): ... ValueError: Found `1` unmatched left token(s) `{` (position: 4). >>> list(nested_pairs('{a}} {b:{c}}', '{', '}')) Traceback (most recent call last): ... ValueError: Found `1` unmatched right token(s) `}` (position: 3). See Also: - flyingcircus.nested_delimiters() r/rz8Found `{}` unmatched right token(s) `{}` (position: {}).z7Found `{}` unmatched left token(s) `{}` (position: {}).N) rYsetrhunionsortedrrrr"r) rl_itemr_item includingl_offsetr_offsetstackl_itemsr_items positionsposprevs ru nested_pairsrx s&Ti.(Hx E)C()G)C()G g&Ii ? '> LLq ! G^5zA~yy{hhE CC 'L3w</">?? ? 5zA~  L3w< 'qBC Cs A6D'9B.D'cf|d|}}n||}}|s ||krdnd}|||z |zs|ndz}t|||S)ap Span consecutive numbers in a range. This is useful to produce 1-based ranges, which first from 1 (if `start` is not specified) and include the `stop` element (if the `step` parameter allows). Args: first (int): The first value of the span. If `second` is None, the `start` value is 1, and this is the `stop` value. It is included if `step` is a multiple of the sequence length. Otherwise, this is the `start` value and it is always included. second (int|None): The second value of the span. If None, the start value is 1 and this parameter is ignored. Otherwise, this is the `stop` value of the range. It is included if `step` is a multiple of the sequence length. If `first < second` the sequence is yielded backwards. step (int): The step of the rows range. If `start > stop`, the step parameter should be negative in order to obtain a non-empty range. If None, this is computed automatically based on `first` and `second`, such that a non-empty sequence is avoided, if possible, i.e. `step == 1` if `start <= stop` else `step == -1`. Returns: result (range): The spanned range. Examples: >>> print(list(span(10))) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> print(list(span(-10))) [1, 0, -1, -2, -3, -4, -5, -6, -7, -8, -9, -10] >>> print(list(span(1))) [1] >>> print(list(span(1, 10))) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> print(list(span(-1, 10))) [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> print(list(span(-1, 9, 2))) [-1, 1, 3, 5, 7, 9] >>> print(list(span(-1, 10, 2))) [-1, 1, 3, 5, 7, 9] >>> print(list(span(10, 1))) [10, 9, 8, 7, 6, 5, 4, 3, 2, 1] >>> print(list(span(10, 1, -2))) [10, 8, 6, 4, 2] >>> print(list(span(-1, -10, -2))) [-1, -3, -5, -7, -9] >>> print(list(span(-1, -11, -2))) [-1, -3, -5, -7, -9, -11] >>> 1 - span - 10 == span(1, 10) r/r<rrange)rfsecondstepstartstops ruspanrOsRv~tVt TMqr  54A >D d ##rwc#K|r||kr||ks ||kDr||kDr| }||kDrtj}n||krtj}nt|}|||r|||z }|||ryyw)aG Generate a range of objects. It is a generalization of `range()` built-in to non-integer arguments. The objects must be ordered and support addition and subtraction. Args: start (Any): The initial value (included). stop (Any): The final value (excluded). step (Any): The step value. zero (Any): The "zero" value (used to determine the sign of `step`). adapt_step_sign (bool): Swap the sign of `step`. This is used to ensure a non-empty range. Yields: The value(s) between `start` and `stop` (excluded) in `step` steps. Raises: ValueError: If the step is zero. Examples: >>> list(any_range(0, 4)) [0, 1, 2, 3] >>> list(any_range(4, 0)) [4, 3, 2, 1] >>> list(any_range(0, 4, 2)) [0, 2] >>> list(any_range(4, 0, 2)) [4, 2] >>> list(any_range(4, 0, adapt_step_sign=False)) [] >>> list(any_range(4, 0, -2)) [4, 2] >>> list(any_range(4, 0, -2, adapt_step_sign=False)) [4, 2] N)r^ltgtr")r~rr}zeroadapt_step_signcomparercurrs ru any_rangers|TdlD4Ku d{;; ;; D 4     4 s A)A.,A.c@t|dxr|xr t|| S)a Determine if an object is deep, i.e. it can be iterated through. Args: obj (Any): The object to test. skip (tuple|None): Types to skip descending into. Returns: result (bool): If the object is deep or not. Examples: >>> is_deep(1) False >>> is_deep(()) True >>> is_deep([1, 2, 3]) True >>> is_deep(range(4)) True >>> is_deep((i for i in range(4))) True >>> is_deep('ciao') False >>> is_deep('c') False >>> is_deep('') False >>> is_deep(1, skip=None) False >>> is_deep('c', skip=None) True >>> is_deep('', skip=None) True __iter__)rr)r+rJs ruis_deeprs&L 3 # LT-Kjd6K(LLrwcdk(rStdr$tfdjDSttrt nt}|fdDS)ag Recursively convert mutable containers to immutable counterparts. The following conversions are performed: - Iterable -> tuple - set -> frozenset - dict (any container with `items()` method) -> tuple This is useful to sanitize default parameters in functions. Args: items: The input items. max_depth (int): Maximum depth to reach. Negative for unlimited. skip (tuple|None): Types to skip descending into. Returns: result (tuple): The output items. Examples: >>> freeze([1, 2, 'ciao', [2, 3]]) (1, 2, 'ciao', (2, 3)) >>> freeze([1, 2, 'ciao', {2, 3}]) (1, 2, 'ciao', frozenset({2, 3})) >>> freeze([1, 2, 'ciao', {2: 3}]) (1, 2, 'ciao', ((2, 3),)) >>> freeze([1, 2, 'ciao', {2: 3}, {4: 5}]) (1, 2, 'ciao', ((2, 3),), ((4, 5),)) rrc3dK|]'}t|r|k7rt|dz n|)ywr/Nrfreezerrr max_depthrJs rurzfreeze..sC+4&45=tY]D1>BC+-0c3dK|]'}t|r|k7rt|dz n|)ywrrrs rurzfreeze..%sC#4&45=tY]D1>BC#r)rrrrrj frozensetrrrJrs``` rurrsl@A~ 5' "+"KKM++ + &0s%; I#"## #rwcdk(rS tfdDS#t$r2ttrtnt }|fdDcYSwxYw)a Recursively convert immutable containers to mutable counterparts. The following conversions are performed: - Iterable -> dict (if possible) or list - frozenset -> set Args: items: The input items. max_depth (int): Maximum depth to reach. Negative for unlimited. skip (tuple|None): Types to skip descending into. Returns: result (tuple): The output items. Examples: >>> unfreeze((1, 2, 'ciao', (2, 3))) [1, 2, 'ciao', [2, 3]] >>> unfreeze((1, 2, 'ciao', frozenset({2, 3}))) [1, 2, 'ciao', {2, 3}] >>> unfreeze((1, 2, 'ciao', ((2, 3),))) [1, 2, 'ciao', {2: 3}] >>> unfreeze((1, 2, 'ciao', ((2, 3),), ((4, 5),))) [1, 2, 'ciao', {2: 3}, {4: 5}] rc3dK|]'}t|r|k7rt|dz n|)ywrrunfreezers rurzunfreeze..MsC#4&45=y1}d3>BC#rc3dK|]'}t|r|k7rt|dz n|)ywrrrs rurzunfreeze..SsC#4&45=y1}d3>BC#r)r rrrrjlistrs``` rurr,so:A~  ##"## # #)%;I#"## # #s"8AActttttt t tf}t||ryt|ttttfr|dk7r|D]}t||dz syyyy)a Recursively determine if an object is mutable. This is useful to inspect whether it is safe to use an object as default parameter value. Args: obj (Any): The object to inspect. max_depth (int): Maximum depth to reach. Negative for unlimited. Returns: result (bool): The result of the mutability check. Examples: >>> is_mutable(1) False >>> is_mutable([1]) True >>> is_mutable((1, 2)) False >>> is_mutable((1, 2, [])) True >>> is_mutable((1, 2, []), max_depth=0) False >>> is_mutable(zip(([], []), ((), ()))) True >>> is_mutable(zip(((), ()), ((), ()))) False >>> is_mutable(map(lambda x: [], (1, 2))) True >>> is_mutable(map(lambda x: 'ciao', (1, 2))) False >>> is_mutable(filter(lambda x: len(x) >= 0, ((), (), []))) True >>> is_mutable(filter(lambda x: len(x) >= 0, ((), ()))) False Frr/T)rTrYr_rarslicer{rrrrrfilter is_mutable)r+rshallow_immutablesrs rurrZsqR c5#ueUI?#)* C%c62 3 > dIM2 rwc|rtj|dntj|d}|fd|DS)ah Compute multiple comparisons. Args: grouper (callable): Determine how to group multiple comparisons. Must accept the following signature: multi_comparison(*Iterable[bool]): bool Can be either `all` or `any`, or any callable with the supported signature. items (Iterable): The input items. comparison (callable): Compute pair-wise comparison. Must accept the following signature: comparison(Any, Any): bool symmetric (bool): Assume that the comparison is symmetric. A comparison is symmetric if: comparison(a, b) == comparison(b, a). Returns: result (bool): The result of the multiple comparisons. Examples: >>> multi_compare(all, [1, 1, 1, 1, 1, 1, 1, 1, 1]) True >>> multi_compare(any, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0]) True >>> multi_compare(all, 'xxxxx') True >>> multi_compare(all, 'yxxxy') False >>> multi_compare(any, 'xxxxxyxxxy') True >>> all_equal({0, 1}) False r9c36K|]\}}||ywrr)rr5rI comparisons rurz multi_compare..s91:a#9)r combinations permutations)grouperrr symmetricpairwises ` ru multi_comparersAP %%eQ/#00: 99 99rwc(|D] }|||s yy)a Check if an object is equal to any of the items. This is useful if any among the object or the items does not implement `__eq__` to return a `bool` for any given input. Note that this operation is always of O(N) complexity (N being the `items` size). Args: obj (Any): The object to check. items (Iterable): The container to check. eq (callable): The function to check for equality. Must have the following signature: eq(Any, Any): bool Returns: bool: The result of the check. Examples: >>> in_(1, [1, 2, 3]) True >>> in_(0, [1, 2, 3]) False >>> in_(1, {1, 2, 3}) True >>> in_(0, {1, 2, 3}) False TFr)r+reqrs ruin_rs$> c4= rwct|tjjr |dd|ddk(St |} t |}|D] }||k7s yy#t $rYywxYw)a( Check if all items are equal. Args: items (Iterable): The input items. Returns: result (bool): The result of the equality test. Examples: >>> all_equal([1, 1, 1, 1, 1, 1, 1, 1, 1]) True >>> all_equal([1, 1, 1, 1, 0, 1, 1, 1, 1]) False >>> all_equal('xxxxx') True >>> all_equal('xxxxy') False >>> all_equal({0}) True >>> all_equal({0, 1}) False >>> all(all_equal(x) for x in ((), [], {}, set())) True r/Nr<TF)r collectionsabcSequencerr StopIterationr iter_itemsrfrs ru all_equalrs{4%112QRyE#2J&&%[  $E  D}   s A A"!A"ct|syt|dk(rydk(ryrfd|D}d|zSt|ddz }d|zS)a Compute the nesting level of nested iterables. Args: obj (Any): The object to test. deep (bool): Evaluate all item. If True, all elements within `obj` are evaluated. If False, only the first element of each deep object is evaluated. An object is considered deep using `is_deep()`. max_depth (int): Maximum depth to reach. Negative for unlimited. combine (callable): Combine multiple depth at the same level. If `deep` is False, this parameter is ignored. skip (tuple|None): Types to skip descending into. Returns: result (int): The nesting level. Examples: >>> nesting_level([]) 1 >>> nesting_level([], True) 1 >>> nesting_level([[]], False) 2 >>> nesting_level( ... [[(1, 2, 3), (4, 5)], [(1, 2), (3,)], ['1,2', [6, 7]]], True) 3 >>> nesting_level( ... [[1, (2, 3), (4, 5)], [(1, 2), (3,)], ['1,2', [6, 7]]], False) 2 >>> nesting_level( ... [1, [[[[[[[[[[[[[[[[[[[[[5]]]]]]]]]]]]]]]]]]]]]], True) 22 >>> nesting_level( ... [1, [[[[[[[[[[[[[[[[[[[[[5]]]]]]]]]]]]]]]]]]]]]], False) 1 >>> nesting_level(((1, 2), 1, (1, (2, 3))), True) 3 >>> nesting_level(((1, 2), 1, (1, (2, 3))), True, combine=min) 1 rr/c3BK|]}t|dz ywr) nesting_level)rrHcombinedeeprrJs rurz nesting_level..Is*!ay1}gtD!)rrr)r+rrrrJ next_levels ```` rurrsz^ 3  SQ a  !!J :~'Ai!mWd>> nested_len(((1, 1), (1, 1), (1, 1))) (3, 2) >>> nested_len(((1, 2), (1,), (1, (2, 3))), check_same=True) Traceback (most recent call last): ... ValueError: Same nesting level items with different length. >>> nested_len(((1, 2), (1,), (1, (2, 3))), check_same=False) (3, 2, 2) >>> nested_len(((1, 2), (1, 2), (1, 2)), check_same=False) (3, 2) >>> nested_len(((1,), (1,), (1,))) (3, 1) >>> nested_len((1, 2, 3)) (3,) >>> nested_len( ... ((1, 2), (1,), (1, (2, 3))), combine=None, check_same=False) (3, (2,), (1,), (2, (2,))) >>> nested_len( ... ((1, 2), (1,), ((1,), (2, 3))), combine=None, check_same=False) (3, (2,), (1,), (2, (1,), (2,))) >>> nested_len( ... ((1, 2), (1,), ((1, (2, 3)),)), combine=None, check_same=False) (3, (2,), (1,), (1, (2, (2,)))) rc 3DK|]}t|dz ywr) nested_len)rrH check_samerrrrJs rurznested_len..s2tY]GZGs z/Same nesting level items with different length.r/c3&K|] }|s| ywrrrrHs rurznested_len..s">A1">) rrrr"rrrrr)r+rrrrrJrs ````` rurrSsp 3  J)J"7 EGGG$ ,J#T#Yy1}gD"JC{U">j">>>>rwcp|xs t|d }|}t|tr%|r|f|z}|rt||k7r t d|St |d|k7s|r,t ||d||}|dddD]}t ||d|}|r-t |d||r t |dndzk7r t d|S) ac Automatically repeat the specified object n times. If the object is not Iterable, a tuple with the specified size is returned. If the object is Iterable, the object is repeated only if `n` is Iterable, in which case it is repeated accordingly. The resulting length depends on the value of `force`. Args: obj: The object to operate with. n (int|Sequence[int]): The length(s) of the output object. If Sequence, multiple nested tuples will be generated. force (bool): Force the repetition, even if the object is Iterable. If True, the nested length of the result is equal to `n` plus the length of the input, otherwise it is equal to `n` (but the last value) plus the length of the input. check (bool): Ensure that the object has length n. More precisely the `n` and the initial part of `nested_len(check_same=True)` must be identical. Returns: result (tuple): Returns obj repeated n times. Raises: AssertionError: If force is True and the object does not have length n. Examples: >>> auto_repeat(1, 3) (1, 1, 1) >>> auto_repeat([1], 3) [1] >>> auto_repeat([1, 3], 2) [1, 3] >>> auto_repeat([1, 3], 2, True) ([1, 3], [1, 3]) >>> auto_repeat([1, 2, 3], 2, True, True) ([1, 2, 3], [1, 2, 3]) >>> auto_repeat([1, 2, 3], 2, False, True) Traceback (most recent call last): ... ValueError: Incompatible input value length. >>> auto_repeat(1, (3,)) (1, 1, 1) >>> auto_repeat(1, (3, 2)) ((1, 1), (1, 1), (1, 1)) >>> auto_repeat(1, (2, 3)) ((1, 1, 1), (1, 1, 1)) >>> auto_repeat([1], (3, 1), False, True) ([1], [1], [1]) >>> auto_repeat([1], (3, 1), True, True) (([1],), ([1],), ([1],)) >>> auto_repeat([1], (3, 1), False, False) ([1], [1], [1]) >>> auto_repeat([1], (3, 1), True, False) (([1],), ([1],), ([1],)) >>> auto_repeat([1], (3, 3), False, False) ([1], [1], [1]) >>> auto_repeat([1], (3, 3), True, False) (([1], [1], [1]), ([1], [1], [1]), ([1], [1], [1])) >>> auto_repeat([1], (3, 3), True, True) (([1], [1], [1]), ([1], [1], [1]), ([1], [1], [1])) >>> auto_repeat([1], (3, 3), False, True) Traceback (most recent call last): ... ValueError: Incompatible input value length. >>> auto_repeat(((1, 1), (1, 1), (1, 1)), (3, 2), False, True) ((1, 1), (1, 1), (1, 1)) >>> auto_repeat((1, 1), (3, 2), False, True) ((1, 1), (1, 1), (1, 1)) >>> auto_repeat((1, 1, 1), (3, 2), False, True) Traceback (most recent call last): ... ValueError: Incompatible input value length. >>> auto_repeat((1, 1, 1), (3, 2), False, False) ((1, 1, 1), (1, 1, 1), (1, 1, 1)) >>> auto_repeat((1, 1), (3, 2), True, True) (((1, 1), (1, 1)), ((1, 1), (1, 1)), ((1, 1), (1, 1))) See Also: - flyingcircus.stretch() rz Incompatible input value length.Trr<r=Nr)rrrYrr"r auto_repeat)r+r2forcerUrrMs rurrsl  1j11E F!S VaZF S[A%?@ @ M cd +q 0E aeUE:Frv2vY =$VQe< = 6d3E 348rJK?@ @ Mrwct|st|}|St|d}t|dk(r/tdkDr!d|dk(rt fd|D}|S|ddk(rt fd|Ddz}|S|k(r t|d|}|S|ddk(rt fd |D}|St d j |#t $rt fd|D}Y|SwxYw) a Automatically stretch the values to the target shape. This is similar to `flyingcircus.auto_repeat()`, except that it can flexibly repeat values only when needed. This is similar to shape broadcasting of multi-dimensional arrays. Args: items (Any|Iterable): The input items. shape (Sequence[int]): The target shape (nested lengths). skip (tuple|None): Types to skip descending into. Returns: result (tuple): The values stretched to match the target shape. Raises: ValueError: If `items` and `shape` are incompatible. Examples: >>> stretch(1, 10) (1, 1, 1, 1, 1, 1, 1, 1, 1, 1) >>> stretch(1, (2, 3)) ((1, 1, 1), (1, 1, 1)) >>> stretch(1, (2, 3, 2)) (((1, 1), (1, 1), (1, 1)), ((1, 1), (1, 1), (1, 1))) >>> stretch((1, (2, 3)), (2, 2)) ((1, 1), (2, 3)) >>> stretch((1, (2, 3, 4)), (2, 3)) ((1, 1, 1), (2, 3, 4)) >>> stretch((1, (2, 3,)), (2, 3)) Traceback (most recent call last): ... ValueError: Cannot stretch `(2, 3)` to `(3,)`. >>> stretch((1, (2, 3, 4, 5)), (2, 3)) Traceback (most recent call last): ... ValueError: Cannot stretch `(2, 3, 4, 5)` to `(3,)`. >>> stretch(((1, 2),), (4, 2)) ((1, 2), (1, 2), (1, 2), (1, 2)) >>> stretch((1, 2, 3, 4), (4, 2)) ((1, 1), (2, 2), (3, 3), (4, 4)) >>> items = [[[[1], [2], [3]]], [[[4], [5], [6]]]] >>> print(nested_len(items)) (2, 1, 3, 1) >>> stretch(items, (2, 4, 3, 4)) ((((1, 1, 1, 1), (2, 2, 2, 2), (3, 3, 3, 3)), ((1, 1, 1, 1), (2, 2, 2, 2), (3, 3, 3, 3)), ((1, 1, 1, 1), (2, 2, 2, 2), (3, 3, 3, 3)), ((1, 1, 1, 1), (2, 2, 2, 2), (3, 3, 3, 3))), (((4, 4, 4, 4), (5, 5, 5, 5), (6, 6, 6, 6)), ((4, 4, 4, 4), (5, 5, 5, 5), (6, 6, 6, 6)), ((4, 4, 4, 4), (5, 5, 5, 5), (6, 6, 6, 6)), ((4, 4, 4, 4), (5, 5, 5, 5), (6, 6, 6, 6)))) See Also: - flyingcircus.auto_repeat() Frr/rc3@K|]}t|ddddyw)r/NT)rrrshapes rurzstretch..Ms*#D%)T48#sc3JK|]}ddrt|ddn|ywr)stretchrs rurzstretch..Qs3#-2!"IeABi(4?# #Tc3rK|].}t|rt|ddnt|dd0ywrrrrrrrrJs rurzstretch..XsI'tT*D%),$T5956'47c3rK|].}t|rt|ddnt|dd0ywrrrs rurzstretch..`sI#4&eABi( uQRy12#rzCannot stretch `{}` to `{}`.)rrrrrr"format)rrrJr old_shapes `` rurr sWz 5$ UE*> M;u7 y>Q 3u:>eAh)A,6N#!##F6 M1q\Q #!##%*1X.F. M)%  5T2 Mq\U1X %#" ##F M.55eUCE E ''!& '' M# 's CDDc#K|D]9}|r t||s ||k(s|dk(r| t||dz |D]}|;y#t$r|YLwxYww)a Recursively flattens nested Iterables. The maximum depth is limited by Python's recursion limit. Args: items (Iterable): The input items. max_depth (int): Maximum depth to reach. Negative for unlimited. shallow (tuple|None): Data types to always consider shallow. Note that recursive and self-slicing objects are handled separately. Yields: item (any): The next non-Iterable item of the flattened items. Examples: >>> ll = [[1, 2, 3], [4, 5, 6], [7], [8, 9]] >>> list(flatten(ll)) [1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(flatten(ll)) == list(itertools.chain.from_iterable(ll)) True >>> ll = [ll, ll] >>> list(flatten(ll)) [1, 2, 3, 4, 5, 6, 7, 8, 9, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(itertools.chain.from_iterable(ll)) [[1, 2, 3], [4, 5, 6], [7], [8, 9], [1, 2, 3], [4, 5, 6], [7], [8, 9]] >>> list(flatten([1, 2, 3])) [1, 2, 3] >>> list(flatten(['best', ['function', 'ever']])) ['best', 'function', 'ever'] >>> ll2 = [[(1, 2, 3), (4, 5)], [(1, 2), (3, 4, 5)], ['1, 2', [6, 7]]] >>> list(flatten(ll2)) [1, 2, 3, 4, 5, 1, 2, 3, 4, 5, '1, 2', 6, 7] >>> list(flatten(ll2, shallow=(tuple, str))) [(1, 2, 3), (4, 5), (1, 2), (3, 4, 5), '1, 2', 6, 7] >>> list(flatten(ll2, max_depth=1)) [(1, 2, 3), (4, 5), (1, 2), (3, 4, 5), '1, 2', [6, 7]] >>> list(flatten(ll2, shallow=None)) [1, 2, 3, 4, 5, 1, 2, 3, 4, 5, '1', ',', ' ', '2', 6, 7] >>> list( ... flatten([['best', 'func'], 'ever'], 1, ... shallow=None)) ['best', 'func', 'e', 'v', 'e', 'r'] >>> list( ... flatten([['best', 'func'], 'ever'], ... shallow=None)) ['b', 'e', 's', 't', 'f', 'u', 'n', 'c', 'e', 'v', 'e', 'r'] >>> list(flatten(list(range(10)))) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(flatten(range(10))) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> list(flatten([[0, 1], range(2, 5), (i for i in range(5, 10))])) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] rr/N)rflattenr)rrshallowrsubitems rurrlsqt  z$0 aJ &tY]GD"G!M"    s'#AAA AAAAc@|rtj|d|iSt|S)a. Transpose an iterable of iterables. Args: items (Iterable[Iterable]): The input items. longest (bool): Align to longest inner iterable. If True, aligns to the longest inner iterable from the input. If False, cuts the inner iterables to the shortest. fill (Any): Fill value to use for aligning to longest. If `longest` is False, this parameter has no effect. Returns: result (zip|itertools.zip_longest): The transposed items. Examples: >>> tuple(transpose(((1, 2), (3, 4), (5, 6)))) ((1, 3, 5), (2, 4, 6)) >>> tuple(transpose(((1, 2), (3, 4), (5, 6, 7)))) ((1, 3, 5), (2, 4, 6)) >>> tuple(transpose(((1, 2), (3, 4), (5, 6, 7)), True)) ((1, 3, 5), (2, 4, 6), (None, None, 7)) fillvalue)r zip_longestr)rlongestrs ru transposers'4$$e>> flip_slice(slice(10, 20)) slice(20, 10, None) >>> flip_slice(slice(10, 20, 2)) slice(20, 10, -2) >>> flip_slice(slice(20, 10, -2)) slice(10, 20, 2) >>> flip_slice(slice(10, 20), True) slice(20, 10, -1) >>> flip_slice(slice(20, 10)) slice(10, 20, None) >>> flip_slice(slice(20, 10), True) slice(10, 20, 1) >>> flip_slice(slice(None, 10)) slice(10, None, None) >>> flip_slice(slice(None, 10), True) slice(10, None, 1) >>> flip_slice(slice(20, None)) slice(None, 20, None) >>> flip_slice(slice(20, None), True) slice(None, 20, 1) >>> flip_slice(slice(None, None)) slice(None, None, None) >>> flip_slice(slice(None, None), True) slice(None, None, 1) >>> flip_slice(range(10, 20)) range(20, 10, -1) >>> flip_slice(range(10, 20, 2)) range(20, 10, -2) >>> flip_slice(range(20, 10, -2)) range(10, 20, 2) >>> flip_slice(range(10, 20), True) range(20, 10, -1) >>> flip_slice(range(20, 10)) range(10, 20, -1) >>> flip_slice(range(20, 10), True) range(10, 20, -1) r}c3$K|]}|du ywrrrs rurzflip_slice.. s@Q1D=@r<r/c3$K|]}|du ywrrrs rurzflip_slice.. sBq}Br)rr}allr~rr)r+ force_stepr}s ru flip_slicerstsF 88  @399chh*?@@ CHH,88D Bsyy#((D&AB B5DtCy399d33tCy399--rwc#0Kttt||}|jr |jnd}|dkDrt |D]\}}||vs |yt|}t t |D]\}}||z dz |vs|yw)a Extract the elements not matching a given slice. Args: seq (Sequence): The input items. slice_ (slice): The slice to be complemented. Yields: item (Any): The next item not matching the slice pattern. Examples: >>> items = tuple(range(10)) >>> s = slice(None) >>> print(items[s], tuple(complement(items, s))) (0, 1, 2, 3, 4, 5, 6, 7, 8, 9) () >>> s = slice(None, None, 2) >>> print(items[s], tuple(complement(items, s))) (0, 2, 4, 6, 8) (1, 3, 5, 7, 9) >>> s = slice(None, None, 3) >>> print(items[s], tuple(complement(items, s))) (0, 3, 6, 9) (1, 2, 4, 5, 7, 8) >>> s = slice(2, None, None) >>> print(items[s], tuple(complement(items, s))) (2, 3, 4, 5, 6, 7, 8, 9) (0, 1) >>> s = slice(None, 7, None) >>> print(items[s], tuple(complement(items, s))) (0, 1, 2, 3, 4, 5, 6) (7, 8, 9) >>> s = slice(2, None, 3) >>> print(items[s], tuple(complement(items, s))) (2, 5, 8) (0, 1, 3, 4, 6, 7, 9) >>> s = slice(None, 7, 3) >>> print(items[s], tuple(complement(items, s))) (0, 3, 6) (1, 2, 4, 5, 7, 8, 9) >>> s = slice(2, 7, 3) >>> print(items[s], tuple(complement(items, s))) (2, 5) (0, 1, 3, 4, 6, 7, 8, 9) >>> s = slice(None, None, -3) >>> print(items[s], tuple(complement(items, s))) (9, 6, 3, 0) (8, 7, 5, 4, 2, 1) >>> s = slice(2, None, -3) >>> print(items[s], tuple(complement(items, s))) (2,) (9, 8, 7, 6, 5, 4, 3, 1, 0) >>> s = slice(None, 7, -3) >>> print(items[s], tuple(complement(items, s))) (9,) (8, 7, 6, 5, 4, 3, 2, 1, 0) >>> s = slice(2, 7, -3) >>> print(items[s], tuple(complement(items, s))) () (9, 8, 7, 6, 5, 4, 3, 2, 1, 0) >>> s = slice(7, 2, -3) >>> print(items[s], tuple(complement(items, s))) (7, 4) (9, 8, 6, 5, 3, 2, 1, 0) >>> items = tuple(1 for i in range(10)) >>> s = slice(None, None, 3) >>> print(items[s], tuple(complement(items, s))) (1, 1, 1, 1) (1, 1, 1, 1, 1, 1) >>> items = tuple(i % 2 for i in range(10)) >>> s = slice(None, None, 3) >>> print(items[s], tuple(complement(items, s))) (0, 1, 0, 1) (1, 0, 0, 1, 1, 0) >>> ll = list(range(1000)) >>> vals = (3, 5, 7, 17, 101) >>> vals += tuple(-x for x in vals) + (None,) >>> print(vals) (3, 5, 7, 17, 101, -3, -5, -7, -17, -101, None) >>> sls = [slice(*x) for x in itertools.product(vals, vals, vals)] >>> all( ... set(complement(ll, sl)).intersection(ll[sl]) == set() ... for sl in sls) True r/rN)rjr{rr} enumerater)rslice_ to_excluder}rMr num_itemss ru complementr srU3s8_V,-J ++6;;1D ax ~ GAt "  H  #/ GAtA !*4  sAB6BBc,trfdSS)a Modify a function so that it is applied only if a condition is satisfied. Args: func (callable): A function to apply to an object. Must have the following signature: func(Any): Any condition (callable|None): The condition function. If not None, the function `func` is applied to an object only if the condition on the object evaluates to True. Must have the following signature: condition(Any): bool Returns: result (callable): The conditional function. Examples: >>> conditional_apply(str)(1) '1' >>> list(map(conditional_apply(str), range(10))) ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] >>> [conditional_apply(str, lambda x: x > 5)(i) for i in range(10)] [0, 1, 2, 3, 4, 5, '6', '7', '8', '9'] >>> list(map(conditional_apply(str, lambda x: x > 5), range(10))) [0, 1, 2, 3, 4, 5, '6', '7', '8', '9'] >>> print(conditional_apply(str) == str) True c(|r|S|Srr)rH conditionrs ruz#conditional_apply.. sIaLaarw)r)rrs``ruconditional_applyr s: 77 rwc | t|n|}t|st}g}|D]G}t||r"|j t ||||dz |1|j ||I||S)aw Compute a function on each element of a nested structure of iterables. The result preserves the nested structure of the input. Args: func (callable): The function to apply to the individual item. Must have the following signature: func(Any): Any. items (Iterable): The input items. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. max_depth (int): Maximum depth to reach. Negative for unlimited. skip (tuple|None): Types to skip descending into. Returns: new_items (Iterable): The mapped items. Examples: >>> items = [1, 2, [3, 4, 5], 2, (3, [4, 5])] >>> print(deep_map(str, items)) ['1', '2', ['3', '4', '5'], '2', ('3', ['4', '5'])] >>> print(deep_map(float, items)) [1.0, 2.0, [3.0, 4.0, 5.0], 2.0, (3.0, [4.0, 5.0])] >>> print(deep_map(lambda x: x, items)) [1, 2, [3, 4, 5], 2, (3, [4, 5])] >>> print(deep_map(lambda x: x, items, tuple)) (1, 2, (3, 4, 5), 2, (3, (4, 5))) r/)rrrrrdeep_map)rrrrrJfinal_container new_itemsrs rurr sF&/%6d5kIO O $$I) 4    tY A tD F   T$Z ( ) 9 %%rwc |in t|}| t|n|}t|st}g}|D]J}t |fi|r"|j t ||||dz |1||s:|j |L||S)aN Filter the elements from a nested structure of iterables. The result preserves the nested structure of the input. Args: func (callable): The condition function to include the individual item. Must have the following signature: func(Any): bool items (Iterable): The input items. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. max_depth (int): Maximum depth to reach. Negative for unlimited. is_deep_kws (Mapping|None): Keyword parameters for `is_deep()`. These are passed to `flyingcircus.is_deep()`. Returns: new_items (Iterable): The filtered items. Examples: >>> items = [1, 2, [3, 4, 5], 2, (3, [4, 5])] >>> print(deep_filter(lambda x: x > 1, items)) [2, [3, 4, 5], 2, (3, [4, 5])] >>> print(deep_filter(lambda x: x > 2, items)) [[3, 4, 5], (3, [4, 5])] >>> print(deep_filter(lambda _: True, items)) [1, 2, [3, 4, 5], 2, (3, [4, 5])] r/)r rrrrr deep_filter)rrrr is_deep_kwsrrrs rurr sD$+"k1BK%.%6d5kIO O $&I' 4 '; '   D$ 9q=+N PDz  & ' 9 %%rwc |Yg}|D]J}|dk(st||r||k(r|j|+|jt|||dz |L||S|S)a/ Convert the containers from a nested structure of iterables. Args: container (callable|None): The container to apply. Must have the following signature: Must have the following signature: container(Iterable): container. If None, no conversion is performed. items (Iterable): The input items. max_depth (int): Maximum depth to reach. Negative for unlimited. skip (tuple|None): Types to skip descending into. Returns: new_items (container): The converted nested structure of iterables. Examples: >>> items = [1, 2, [3, 4, 5], 2, (3, [4, 5], 'ciao')] >>> deep_convert(list, items) [1, 2, [3, 4, 5], 2, [3, [4, 5], 'ciao']] >>> deep_convert(tuple, items) (1, 2, (3, 4, 5), 2, (3, (4, 5), 'ciao')) >>> deep_convert(tuple, items, skip=None) (1, 2, (3, 4, 5), 2, (3, (4, 5), (('c',), ('i',), ('a',), ('o',)))) >>> deep_convert(None, items) [1, 2, [3, 4, 5], 2, (3, [4, 5], 'ciao')] >>> print( ... deep_map(lambda x: x, items, tuple) ... == deep_convert(tuple, items)) True >>> print( ... deep_filter(lambda x: True, items, tuple) ... == deep_convert(tuple, items)) True rr/)rr deep_convert)rrrrJrrs rurr0 sxR  HDA~WT4%8DEM  &   D)a-FH  H ## rwc J| t|n|}t|st}|d}|d}|d}g}|D]f} |dk(st| |r| |k(r+|| s"|j || r|| n| D|j t | |||||dz |h||S)a Apply conditional mapping, filtering and conversion on nested structures. The behavior of this function can be obtained by combining the following: - flyingcircus.conditional_apply() - flyingcircus.deep_map() - flyingcircus.deep_filter() - flyingcircus.deep_convert() In particular: deep_filter_map( items, func, map_condition, filter_condition, container, avoid, max_depth) is equivalent to: deep_convert( container, deep_map( conditional_apply(func, map_condition), deep_filter(filter_condition, items, avoid, max_depth), avoid, max_depth), avoid, max_depth) If some of the parameters of `deep_filter_map()` can be set to None, the equivalent expression can be simplified. However, if the call to `deep_filter_map()` would require both `deep_map()` and `deep_filter()`, then `deep_filter_map()` is generally (and typically also substantially) more performing. Args: items (Iterable): The input items. func (callable): The function to apply to the individual item. Must have the following signature: func(Any): Any. map_condition (callable|None): The map condition function. Only items matching the condition are mapped. Must have the following signature: map_condition(Any): bool. filter_condition (callable|None): The filter condition function. Only items matching the condition are included. Must have the following signature: filter_condition(Any): bool. container (callable|None): The container to apply. Must have the following signature: container(Iterable): container. If None, the original container is retained. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. max_depth (int): Maximum depth to reach. Negative for unlimited. skip (tuple|None): Types to skip descending into. Returns: new_items (Iterable): The mapped and filtered items. Examples: >>> items = [1, 2, [3, 4, 5], 2, (3, [4, 5])] >>> print( ... deep_filter_map(items, str, lambda x: x > 2, lambda x: x > 1)) [2, ['3', '4', '5'], 2, ('3', ['4', '5'])] >>> print(deep_map( ... conditional_apply(str, lambda x: x > 2), ... deep_filter(lambda x: x > 1, items))) [2, ['3', '4', '5'], 2, ('3', ['4', '5'])] >>> print(deep_filter_map(items, str, None, lambda x: x > 1)) ['2', ['3', '4', '5'], '2', ('3', ['4', '5'])] >>> print(deep_filter_map(items, str, lambda x: x > 2, None)) [1, 2, ['3', '4', '5'], 2, ('3', ['4', '5'])] >>> print(deep_filter_map(items, None, None, lambda x: x > 1)) [2, [3, 4, 5], 2, (3, [4, 5])] >>> deep_filter_map(items, str, None, None) ['1', '2', ['3', '4', '5'], '2', ('3', ['4', '5'])] >>> deep_filter_map(items, str, None, None, tuple) ('1', '2', ('3', '4', '5'), '2', ('3', ('4', '5'))) >>> def c1(x): return x > 1 >>> def c2(x): return x > 2 >>> print( ... deep_filter_map(items, str, c2, c1, tuple) ... == deep_convert(tuple, deep_map(conditional_apply(str, c2), ... deep_filter(c1, items)))) True >>> print( ... deep_filter_map(items, str, c2, c1) ... == deep_map(conditional_apply(str, c2), ... deep_filter(c1, items))) True >>> print( ... deep_filter_map(items, str, None, c1) ... == deep_map(str, deep_filter(c1, items))) True >>> print( ... deep_filter_map(items, str, c2, None) ... == deep_map(conditional_apply(str, c2), items)) True >>> print( ... deep_filter_map(items, None, None, c1) ... == deep_filter(c1, items)) True >>> print( ... deep_filter_map(items, str, None, None) ... == deep_map(str, items)) True >>> print( ... deep_filter_map(items, None, None, None, tuple) ... == deep_convert(tuple, items)) True c|SrrrHs rurzdeep_filter_map..func sAXrwcyNTr_s ru map_conditionz&deep_filter_map..map_condition sTrwcyrrrs rufilter_conditionz)deep_filter_map..filter_condition srwrr/)rrrrrdeep_filter_map) rrrrrrrJrrrs rurrg sf&/%6d5kIO O $ |),I* >t!4 %  }T/BdM   $ /?M4) * * 9 %%rwc||d}}n||z |}}|dkDr7|r||j|z|zS||j|zS|dk(r|Std)a Pick a random integer in the specified range. Note that this is roughly equivalent to (but faster than) `random.randrange()` or `random.randint()`. Args: first (int): The first value of the range. If `second` is None, the `start` value is 0 and this is the `stop` value (not included in the range). Otherwise, this is the `start` value and it is always included. second (int|None): The second value of the range. If None, the start value is 1 and the stop value is `first`. Otherwise, this is the stop value and it is not included. rand_bits (callable): Function to generate random bits as int. Must accept the following signature: rand_bits(n: int): int The `n` parameter is the number of `bits`. Returns: result (int): The random value within the specified range. Raises: ValueError: if `first` and `second` would produce an empty range. This happens if `second` is None and `first` is not positive, or if `second <= first`. Examples: >>> random.seed(0); n = 16; [random_int(n) for _ in range(n)] [11, 12, 8, 12, 13, 1, 8, 14, 0, 15, 12, 13, 9, 10, 9, 14] >>> random.seed(0); n = 16; [random_int(10, 20) for _ in range(n)] [13, 16, 12, 14, 16, 10, 14, 15, 18, 17, 16, 14, 12, 13, 14, 15] >>> random.seed(0); n = 16; [random_int(-10, 10) for _ in range(n)] [-3, 2, -6, -2, 3, -9, -2, 0, 6, 5, 2, -1, -5, -4, -1, 0] >>> random.seed(0); n = 16; [random_int(-10, -5) for _ in range(n)] [-9, -7, -9, -8, -7, -10, -8, -8, -6, -7, -7, -8, -9, -9, -8, -8] >>> random_int(0) 0 >>> random_int(10, 10) 10 >>> random_int(10, 5) Traceback (most recent call last): ... ValueError: The range size must be greater than 0 rz%The range size must be greater than 0) bit_lengthr")rfr| rand_bitssizeoffsets ru random_intr  su`~af~uf ax T__./$6? ?T__./$6 6  @AArwct|}t||}t||}|dk(r&||dz k(rt|dr|j|S||z}t ||dzdzD]}||z }||||c||<||<|S)a Reverse or flip in-place a sequence. Warning! This function modifies its `seq` parameter. This supports also partial reversing / flipping. Note that this is roughly equivalent to: seq[first:last + 1] = reversed(seq[first:last + 1]) but it does not require additional memory. Args: seq (MutableSequence): The input sequence. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. Returns: result (int): The reversed sequence. Examples: >>> seq = list(range(10)) >>> print(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> print(flip(seq)) [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> print(seq) [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> print(flip(seq, 3, 7)) [9, 8, 7, 2, 3, 4, 5, 6, 1, 0] >>> print(flip(seq, 3, 7)) [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> print(flip(seq, 3, 6)) [9, 8, 7, 3, 4, 5, 6, 2, 1, 0] >>> print(flip(seq, 3, 6)) [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] rr/reverser9)rrrr r{)rrfrgr2r0rMjs ruflipr3 s\ CA q !E tQ D zda!emY(?  J 5Luq1ul+ ,AAA VSVNCFCF , Jrwct|}t||}t||}|dkrd}|dkDr1t|||D]}|||dz}||||c||<||<!|St||| D]}||}||||c||<||<|S)a Shuffle in-place a sequence. Warning! This function modifies its `seq` parameter. This use Fisher-Yates shuffle (Durstenfeld method). Args: seq (MutableSequence): The input sequence. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. k (int): Swap reduction factor. Larger values result in more speed and less randomness. Must be 1 or more, otherwise it is ignored rand_int (callable): The random integer generator. Must accept the signature: rand_int(a: int, b: int|None): int If `b` is None, must produce a random value in the [0, a) range (0 is included, `a` is excluded), otherwise must produce a random value in the [a, b) range (`a` is included, `b` is excluded) Returns: result (int): The shuffled sequence. Examples: >>> seq = list(range(16)) >>> print(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] >>> seq = list(range(16)); random.seed(0) >>> print(shuffle(seq)) [15, 8, 1, 10, 5, 11, 3, 9, 7, 4, 0, 14, 2, 12, 6, 13] >>> seq = list(range(16)); random.seed(0) >>> print(shuffle(seq, k=2)) [7, 9, 2, 11, 4, 0, 15, 3, 8, 5, 10, 1, 12, 6, 14, 13] >>> seq = list(range(16)); random.seed(0) >>> print(shuffle(seq, 6)) [0, 1, 2, 3, 4, 5, 9, 13, 12, 6, 7, 11, 14, 10, 8, 15] >>> seq = list(range(16)); random.seed(0) >>> print(shuffle(seq, 3, 13)) [0, 1, 2, 5, 10, 8, 12, 4, 3, 11, 13, 7, 9, 6, 14, 15] >>> seq = list(range(16)); random.seed(0) >>> print(shuffle(seq, 0, 13)) [7, 8, 5, 9, 3, 10, 11, 2, 13, 12, 4, 1, 6, 0, 14, 15] See Also: - random.shuffle() - random.randrange() - flyingcircus.random_int() - https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle r/rrrr{)rrfrgr'rand_intr2rMrs rushufflerx s| CA q !E tQ D1u  qyudA& ,AD1H%A VSVNCFCF , JtUQB' ,A A VSVNCFCF , Jrwct|}t||}t||}||krdnd}t|||z|D]$}|||s||||c||<||<||z }&|dkDr|S|dzS)a Partition in-place a sequence according to a specified condition. Warning! This function modifies its `seq` parameter. Args: seq (MutableSequence): The input sequence. condition (callable): The partitioning condition. Must have the following signature: condition(Any): bool. If the condition is met, first (int): The first index. The index is forced within boundaries. If first < last, the partitioning is performed forward, otherwise the partitioning is performed backward. last (int): The last index (included). The index is forced within boundaries. If first < last, the partitioning is performed forward, otherwise the partitioning is performed backward. Returns: result (int): The index that delimits the partitioning. Examples: >>> seq = list(range(10)) >>> k = partition(seq, lambda x: x % 2 == 0) >>> print(seq[:k], seq[k:]) [0, 2, 4, 6, 8] [5, 3, 7, 1, 9] >>> k = partition(seq, lambda x: x >= 5) >>> print(seq[:k], seq[k:]) [6, 8, 5, 7, 9] [4, 3, 0, 1, 2] >>> k = partition(seq, lambda x: x < 5) >>> print(seq[:k], seq[k:]) [4, 3, 0, 1, 2] [6, 8, 5, 7, 9] >>> seq = list(range(10)) >>> k = partition(seq, lambda x: x % 5, 2, 8) >>> print(seq[2:k], seq[k:9]) [2, 3, 4, 6, 7, 8] [5] >>> seq = list(range(10)) >>> k = partition(seq, lambda x: x % 2 == 0, -1, 0) >>> print(seq[:k], seq[k:]) [5, 1, 9, 3, 7] [0, 2, 4, 6, 8] See Also: - flyingcircus.selection() - flyingcircus.quick_sort() r/r<rr)rrrfrgr2r}rMs ru partitionr sn CA q !E tQ D 1"D 5$+t , SV !$QU CJA TME ax qyrwc~t|}t||}t||}t||}|rt||||||krw|||dz}||}|} |} || |kr| dz } || |kr|| |kDr| dz} || |kDr| | k\rn|| || c|| <|| <| dz } | dz} N|| kr| }n| dz}||krw|S)a Rearrange in-place a sequence so that the k-th element is at position k. Warning! This function modifies its `seq` parameter. This implements quick-select using an iterative approach with Hoare partitioning scheme. Essentially, this ensures that `seq[k]` is the k-th largest element. The order of the elements below or above `k` is ignored. The problem is also known as selection or k-th statistics. Args: seq (MutableSequence): The input sequence. k (int): The input index. This is 0-based and supports negative indexing. The index is forced within boundaries. If k is not in the (first, last) interval, the result is undefined. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. pivot (callable): The function for choosing the pivot index. Must accept the following signature: pivot(first: int, last: int): int The arguments are the first and last indices of the subsequence to be partitioned. randomize (bool|int): Pre-shuffle the input. If int, this is passed as `k` parameter (shuffling reduction factor) to `flyingcircus.shuffle()`. This render the worst case **very** unlikely. This is useful for deterministic pivoting. Returns: seq (MutableSequence): The partially sorted sequence. Examples: >>> seq = [2 * x for x in range(10)] >>> print(seq) [0, 2, 4, 6, 8, 10, 12, 14, 16, 18] >>> random.seed(0); seq.sort(); print(shuffle(seq)) [4, 18, 10, 14, 0, 6, 2, 16, 12, 8] >>> k = 2 >>> print(selection(seq, k)[k]) 4 >>> random.seed(0); seq.sort(); print(shuffle(seq)) [4, 18, 10, 14, 0, 6, 2, 16, 12, 8] >>> k = 5 >>> print(selection(seq, k)[k]) 10 >>> random.seed(0); seq.sort(); print(shuffle(seq)) [4, 18, 10, 14, 0, 6, 2, 16, 12, 8] >>> k = -1 >>> print(selection(seq, k)[k]) 18 >>> random.seed(0); seq.sort(); print(shuffle(seq)) [4, 18, 10, 14, 0, 6, 2, 16, 12, 8] >>> k = 7 >>> print(selection(seq, k, 1, 7)[k]) 18 See Also: - flyingcircus.partition() - flyingcircus.quick_sort() )r'r/)rrr) rr'rfrgpivot randomizer2r3rHrMrs ru selectionr sX CAAqA q !E tQ DUDI. $,& % " F  a&1*Qa&1*a&1*Qa&1*Av!$QQAAQQ 6DEEK $,L Jrwc t|}t||}t||}t|dz|dzD]J}|}||kDs ||dz ||kDs||dz ||c||<||dz <|dz}||kDs<||dz ||kDr1L|S)u Sort in-place a sequence using insertion sort. Warning! This function modifies its `seq` parameter. This is slower than `sorted()` or `list.sort()`, but uses less memory. The algorithm is: - best-case: O(n) - average-case: O(n²) - worst-case: O(n²) - memory: O(1) - stable Args: seq (MutableSequence): The input sequence. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. Returns: seq (MutableSequence): The sorted sequence. Examples: >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> insertion_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> insertion_sort(seq, 3, 7) [1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> seq = [9, 0, 2, 6, 3, 5, 1, 7, 8, 4, 1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> insertion_sort(seq) [0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9] >>> seq = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> insertion_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] >>> insertion_sort(seq) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] See Also: - flyingcircus.selection_sort() - flyingcircus.step_sort() - flyingcircus.quick_sort() - flyingcircus.merge_sort() - flyingcirucs.nat_merge_sort() r/r)rrfrgr2rMrs ruinsertion_sortr sr CA q !E tQ D 519dQh ' %iCAJQ/!$QUSV CFCAJ FA%iCAJQ/ JrwcRt|}t||}t||}||kr~||}|}||}|}t||dzD]}||} | |kr| }|}| |kDs| }|}||k7r||||c||<||<||k(r|}||k7r||||c||<||<|dz }|dz}||kr~|S)u Sort in-place using (double-edged) selection sort. Warning! This function modifies its `seq` parameter. This is slower than `sorted()` or `list.sort()`, but uses less memory. The algorithm is: - best-case: O(n²) - average-case: O(n²) - worst-case: O(n²) - memory: O(1) - stable Args: seq (MutableSequence): The input sequence. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. Returns: seq (MutableSequence): The sorted sequence. Examples: >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> selection_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> selection_sort(seq, 3, 7) [1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> seq = [9, 0, 2, 6, 3, 5, 1, 7, 8, 4, 1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> selection_sort(seq) [0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9] >>> seq = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> selection_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] >>> selection_sort(seq) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] See Also: - flyingcircus.insertion_sort() - flyingcircus.step_sort() - flyingcircus.quick_sort() - flyingcircus.merge_sort() - flyingcirucs.nat_merge_sort() r/r) rrfrgr2min_valrMmax_valrr'rHs ruselection_sortr sp CA q !E tQ D $,e* d) udQh' AAA7{W  A:!$QU CJA A:A 19 #AD CIs1v    7 $,8 Jrwct|}t||}t||}|>dg}d\}}}||kr|j|||z|z}||kr|jnt |rt ||d}|dz}|D]Y} t || z|D]E} || } | } | || zk\r/|| | z | kDr$|| | z || <| | z} | || zk\r || | z | kDr$| || <G[|S)u Sort in-place a sequence using step insertion (Shell) sort. Warning! This function modifies its `seq` parameter. This is slower than `sorted()` or `list.sort()`, but uses less memory. The algorithm is: - best-case: O(n log n) - average-case: O(n log n) to O(n √n) -- depending on the steps - worst-case: O(n log² n) to O(n²) -- depending on the steps - memory: O(1) - unstable Args: seq (MutableSequence): The input sequence. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. steps (Iterable[int]|None): The steps to use. If None, uses pseudo-optimal values following the sequence: x(k) = 9 * x(k-1) // 4; with x(0) = 1, x(1) = 4 in decreasing order not exceeding the sequence length. This is empirically fast, but theoretical performance is unknown. Returns: seq (MutableSequence): The sorted sequence. Examples: >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> step_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> step_sort(seq, 3, 7) [1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> seq = [9, 0, 2, 6, 3, 5, 1, 7, 8, 4, 1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> step_sort(seq) [0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9] >>> seq = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> step_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] >>> step_sort(seq) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] See Also: - flyingcircus.insertion_sort() - flyingcircus.selection_sort() - flyingcircus.quick_sort() - flyingcircus.merge_sort() - flyingcirucs.nat_merge_sort() r/)rb rbTr )rrrr rrlr{) rrfrgstepsr2rHr0r>rr}rMtemprs ru step_sortr%* s+~ CA q !E tQ D }1a!e LLOA A!e   %uQx. !8Dut|T* Aq6DAut|#AH (<QXAT ut|#AH (<CF   Jrwct|}t||}t||}|rt||||||fg}|r|j\}}|||dz}||}|} |} || |kr| dz } || |kr|| |kDr| dz} || |kDr| | k\rn|| || c|| <|| <| dz } | dz} N| |kDr| |z dkDr|j || g|| dzkDr|| z dkDr|j | dz|g|r|S)u Sort in-place a sequence using quick (partition-exchange) sort. Warning! This function modifies its `seq` parameter. This is slower than `sorted()` or `list.sort()`, but uses less memory. Uses an iterative approach with Hoare partitioning scheme. The algorithm is: - best-case: O(n log n) - average-case: O(n log n) - worst-case: O(n²) - memory: O(log n) to O(n) - unstable Args: seq (MutableSequence): The input sequence. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. pivot (callable): The function for choosing the pivot index. Must accept the following signature: pivot(first: int, last: int): int The arguments are the first and last indices of the subsequence to be partitioned. randomize (bool): Pre-shuffle the input. If int, this is passed as `k` parameter (shuffling reduction factor) to `flyingcircus.shuffle()`. This render the worst case **very** unlikely. This is useful for deterministic pivoting. Returns: seq (MutableSequence): The sorted sequence. Examples: >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> quick_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> quick_sort(seq, 3, 7) [1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> seq = [9, 0, 2, 6, 3, 5, 1, 7, 8, 4, 1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> quick_sort(seq) [0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9] >>> seq = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> quick_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] >>> quick_sort(seq) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] See Also: - flyingcircus.partition() - flyingcircus.selection() - flyingcircus.insertion_sort() - flyingcircus.selection_sort() - flyingcircus.step_sort() - flyingcircus.merge_sort() - flyingcirucs.nat_merge_sort() r/r)rrrrr) rrfrgrrr2indicesr3rHrMrs ru quick_sortr( sRP CA q !E tQ DUD),t}oG* kkm t % " F  a&1*Qa&1*a&1*Qa&1*Av!$QQAAQQ u9UQ NNE1: & !a%>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> merge_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> merge_sort(seq, 3, 7) [1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> seq = [9, 0, 2, 6, 3, 5, 1, 7, 8, 4, 1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> merge_sort(seq) [0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9] >>> seq = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> merge_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] >>> merge_sort(seq) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] See Also: - flyingcircus.insertion_sort() - flyingcircus.selection_sort() - flyingcircus.step_sort() - flyingcircus.quick_sort() - flyingcirucs.nat_merge_sort() r/Nr9r)rrfrgr2r rr$widthrOr0r;rMrr's ru merge_sortr+ s3x CA q !E tQ D %>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> nat_merge_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [1, 0, 3, 5, 7, 9, 2, 4, 6, 8] >>> nat_merge_sort(seq, 3, 7) [1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> seq = [9, 0, 2, 6, 3, 5, 1, 7, 8, 4, 1, 0, 3, 2, 4, 5, 7, 9, 6, 8] >>> nat_merge_sort(seq) [0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9] >>> seq = [9, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> nat_merge_sort(seq) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> seq = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] >>> nat_merge_sort(seq) [0, 0, 0, 0, 0, 0, 0, 0, 0, 0] See Also: - flyingcircus.insertion_sort() - flyingcircus.selection_sort() - flyingcircus.step_sort() - flyingcircus.quick_sort() - flyingcirucs.merge_sort() r/N)rrrr{) rrfrgr2r r$rOr;r0rMrr's runat_merge_sortr-Ysz CA q !E tQ D %>> x = 'flyingcircus' >>> i = argsort(x) >>> print(list(iter_at(x, i))) ['c', 'c', 'f', 'g', 'i', 'i', 'l', 'n', 'r', 's', 'u', 'y'] >>> j = argsort(i) >>> print(list(iter_at(list(iter_at(x, i)), j))) ['f', 'l', 'y', 'i', 'n', 'g', 'c', 'i', 'r', 'c', 'u', 's'] >>> y = 'abracadabras' >>> print(list(iter_at(y, i))) ['d', 'r', 'a', 'a', 'a', 'a', 'b', 'c', 'b', 's', 'a', 'r'] >>> print(list(iter_at(list(iter_at(y, i)), j))) ['a', 'b', 'r', 'a', 'c', 'a', 'd', 'a', 'b', 'r', 'a', 's'] >>> print(sorted(x) == list(iter_at(x, i))) True >>> print(list(x) == list(iter_at(list(iter_at(x, i)), j))) True >>> print(list(y) == list(iter_at(list(iter_at(y, i)), j))) True r)rlr{r __getitem__rs ruargsortr2sD %C/s 77rwclt|}| |cxkr|krnytt|||||Sy)aB Find the smallest k-th element in a sequence. This is roughly equivalent to, but asymptotically more efficient than: `sorted(seq)[k]`. The problem is also known as selection or k-th statistics. This is the not-in-place version of `flyingcircus.selection()`. This is similar to `flyingcircus.medoid()` and `flyingcircus.quantiloid()`, except that the arguments are different and they are potentially faster. Args: seq (Sequence): The input sequence. k (int): The input index. This is 0-based and supports negative indexing. If k > len(seq) or k < -len(seq), None is returned. If k is not in the (first, last) interval, the result is undefined. first (int): The first index. The index is forced within boundaries. last (int): The last index (included). The index is forced within boundaries. Returns: result: The smallest k-th element. Examples: >>> seq = [2 * x for x in range(10)] >>> print(seq) [0, 2, 4, 6, 8, 10, 12, 14, 16, 18] >>> random.seed(0); print(shuffle(seq)) [4, 18, 10, 14, 0, 6, 2, 16, 12, 8] >>> seq = tuple(seq) # seq is now immutable >>> print(select_ordinal(seq, 0)) 0 >>> print(select_ordinal(seq, 9)) 18 >>> print(select_ordinal(seq, 4)) 8 >>> print(select_ordinal(seq, -10)) 0 >>> print(select_ordinal(seq, -1)) 18 >>> print(select_ordinal(seq, -6)) 8 >>> print(select_ordinal(seq, 10)) None >>> print(select_ordinal(seq, -11)) None >>> print(select_ordinal(seq, 7, 1, 7)) 18 See Also: - flyingcircus.partition() - flyingcircus.medoid() - flyingcircus.quantiloid() N)rrr)rr'rfrgr2s ruselect_ordinalr4s?x CA rQ{{cAud3A66rwc#dKt}|D]}||vs|j|r|yw)a* Get unique items (keeping order of appearance). If the order of appearance is not important, use `set()`. Args: items (Iterable): The input items. Yields: item: Unique items. Examples: >>> items = (5, 4, 3, 2, 1, 1, 2, 3, 4, 5, 3, 2, 4, 2, 4, 1, 1) >>> tuple(uniques(items)) (5, 4, 3, 2, 1) >>> tuple(set(items)) (1, 2, 3, 4, 5) >>> sorted(set(items)) == sorted(uniques(items)) True >>> tuple(uniques('abcde')) ('a', 'b', 'c', 'd', 'e') N)rjadd)rseenrs ruuniquesr8:s5. 5D t DHHTNJs 000cd}|D]}|} t|}||}|||} |S#t$rYwxYw#||}w|||}wxYw)a Combine the length of each item within items. For each item within items, determine if the item has a length and then use a given combination function to combine the multiple extracted length. If an item is not a sequence, its length is assumed to be 0. A useful application is to determine the longest item. Args: items (Iterable): The collection of items to inspect. combine (callable): The combination method. Must have the following signature: combine(int, int): int. The lengths are combined incrementally. non_seq_len (int): The length of non-sequence items. Typical choices are `0` or `1` depending on the application. Returns: num (int): The combined length of the collection. Examples: >>> a = list(range(10)) >>> b = tuple(range(5)) >>> c = set(range(20)) >>> combine_iter_len((a, b, c)) 20 >>> combine_iter_len((a, b, c), min) 5 >>> combine_iter_len((1, a)) 10 N)rr)rr non_seq_lennumvalnew_nums rucombine_iter_lenr>XsxF C , ,#hG{gs+ , J   {gs+s ( 4747Ac#Kt|} t|}|r|D]}||||}y|D]}||||}y#t$rYywxYww)a Apply a binary function to consecutive elements in an iterable. The same can be obtained combining `map()` and `flyingcircus.slide()`, but this is faster. Args: func (callable): The pairwise operator to apply. items (Iterable): The input items. reverse (bool): Reverse the order of the arguments in `func()`. Yields: value: The result of func applied to the next pair. Examples: >>> list(pairwise_map(lambda x, y: (x, y), range(8))) [(0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7)] >>> list(pairwise_map(lambda x, y: (x, y), range(8), True)) [(1, 0), (2, 1), (3, 2), (4, 3), (5, 4), (6, 5), (7, 6)] >>> list(pairwise_map(lambda x, y: x < y, range(10))) [True, True, True, True, True, True, True, True, True] >>> list(pairwise_map(lambda x, y: x < y, [])) [] >>> def sub_args(x): return x[0] - x[1] >>> items = range(1000) >>> all(x == y for x, y in zip( ... pairwise_map(operator.sub, items), ... map(sub_args, slide(items, 2)))) True See Also: - flyingcircus.slide() Nrrr)rrr r last_itemrs ru pairwise_maprBs}LeJ !$ " !4++  !# !9d++  !    s' A A,A AAAAc ptjt||}|dkDr4t|Dcgc]\}}tj||d|}}}n'd} t|Dcgc]\}}| ||}}}|r t |}|rt |Stj|d|iScc}}wcc}}w)a Generate a sliding grouping / window across the items. The number of elements for each yield is fixed. This can be used to compute sliding/running/moving/rolling statistics for the general case, but rolling computations that can be expressed in terms of the previous iteration may be computed more efficiently with `flyingcircus.rolling()`. Args: items (Iterable): The input items. size (int): The windowing size. step (int|None): The windowing step. If int, must be larger than 0. truncate (bool): Determine how to handle uneven splits. If True, last groups are skipped if smaller than `size`. fill (Any): Value to use for filling the last group. This is only used when `truncate` is False. reverse (bool): Reverse the order within the window. Returns: result (zip|itertools.zip_longest): Iterable of items within window. Examples: >>> tuple(slide(range(8), 2)) ((0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7)) >>> tuple(slide(range(8), 3)) ((0, 1, 2), (1, 2, 3), (2, 3, 4), (3, 4, 5), (4, 5, 6), (5, 6, 7)) >>> tuple(slide(range(8), 3, 2)) ((0, 1, 2), (2, 3, 4), (4, 5, 6)) >>> tuple(slide(range(8), 3, 2, False)) ((0, 1, 2), (2, 3, 4), (4, 5, 6), (6, 7, None)) >>> tuple(slide(range(8), 3, 2, False, -1)) ((0, 1, 2), (2, 3, 4), (4, 5, 6), (6, 7, -1)) >>> tuple(slide(range(5), 3, 1)) ((0, 1, 2), (1, 2, 3), (2, 3, 4)) >>> tuple(slide(range(5), 3, 1, False)) ((0, 1, 2), (1, 2, 3), (2, 3, 4), (3, 4, None), (4, None, None)) >>> tuple(slide(range(8), 2, 1)) ((0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7)) >>> tuple(slide(range(8), 1, 1)) ((0,), (1,), (2,), (3,), (4,), (5,), (6,), (7,)) >>> tuple(slide(range(8), 1, 2)) ((0,), (2,), (4,), (6,)) >>> tuple(slide(range(8), 2, 2)) ((0, 1), (2, 3), (4, 5), (6, 7)) >>> tuple(slide(range(8), 2, reverse=True)) ((1, 0), (2, 1), (3, 2), (4, 3), (5, 4), (6, 5), (7, 6)) >>> def irange(*args): ... for x in range(*args): ... yield x >>> tuple(slide(irange(8), 2)) ((0, 1), (1, 2), (2, 3), (3, 4), (4, 5), (5, 6), (6, 7)) See Also: - flyingcircus.sliding() - flyingcircus.separate() - flyingcircus.split() - flyingcircus.chunks() - flyingcircus.rolling() r/NcHttj|||d|Sr)rrislice)iteratorr2s ruconsumedzslide..consumeds !!(Aq14 8Orwr)rteerrrErrr) rr r}truncaterr itersrMiteringrGs rusliderLsT MM$u+t ,E ax(.07   Wat 400   4=U3CE%/QHWa EEE{$$e>> items = list(range(10)) >>> print(items) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> print(list(sliding(sum, items, 2))) [1, 3, 5, 7, 9, 11, 13, 15, 17] >>> print(list(sliding(sum, items, 3))) [3, 6, 9, 12, 15, 18, 21, 24] >>> print(list(sliding(sum, items, 3, 2))) [3, 9, 15, 21] >>> print(list(sliding(sum, items, 3, 2, False, 0))) [3, 9, 15, 21, 17] >>> print(list(sliding(sum, items, 3, 2, False))) Traceback (most recent call last): ... TypeError: unsupported operand type(s) for +: 'int' and 'NoneType' >>> print(list(sliding(operator.add, items, 2, star=True))) [1, 3, 5, 7, 9, 11, 13, 15, 17] >>> print(list(sliding(operator.add, items, 2))) Traceback (most recent call last): ... TypeError: add expected 2 arguments, got 1 See Also: - flyingcircus.slide() - flyingcircus.separate() - flyingcircus.split() - flyingcircus.chunks() - flyingcircus.rolling() N)rL)rrr r}rIrstarbatchs ruslidingrP#sZt 5$h= E,  5$h= Eu+  s>Ac^t|g|z}|rt|Stj|d|iS)af Separate items into groups with fixed size. The number of elements for each yield is fixed. For different handling of the last group for uneven splits, and for splitting into groups of varying size, see `flyingcircus.split()`. Args: items (Iterable): The input items. size (int): Number of elements to group together. truncate (bool): Determine how to handle uneven splits. If True, last group is skipped if smaller than `size`. fill (Any): Value to use for filling the last group. This is only used when `truncate` is False. Returns: result (zip|itertools.zip_longest): Iterable of grouped items. Each group is a tuple regardless of the original container. Examples: >>> l = list(range(10)) >>> tuple(separate(l, 4)) ((0, 1, 2, 3), (4, 5, 6, 7), (8, 9, None, None)) >>> tuple(separate(tuple(l), 2)) ((0, 1), (2, 3), (4, 5), (6, 7), (8, 9)) >>> tuple(separate(l, 4, True)) ((0, 1, 2, 3), (4, 5, 6, 7)) >>> tuple(separate(l, 4, False, 0)) ((0, 1, 2, 3), (4, 5, 6, 7), (8, 9, 0, 0)) >>> tuple(separate(l, 2)) == tuple(slide(l, 2, 2)) True See Also: - flyingcircus.slide() - flyingcircus.sliding() - flyingcircus.split() - flyingcircus.chunks() r)rrrr)rr rIr iteratorss ruseparaterSfs8`e $II$$i@4@@rwc#Kt|trt|t||z}t|}t ||k\r|dd}dt t j|z|fz}t|dz }|r(t|D]}t||||dzyt|D]}|||||dzyw)a Split items into groups according to size(s). The number of elements for each group can vary. Note that if the values in `sizes` are the same, `separate()` can be a faster alternative. All and only the elements in `items` are ever yielded. Args: seq (Sequence): The input items. sizes (int|Sequence[int]): The size(s) of each group. If Sequence, each group has the number of elements specified. If int, all groups have the same number of elements. The last group will have the remaining items (if any). slices (bool): Yield the slices. If True, yield the slices that would split the input. Otherwise, yield the splitted input. Yields: Sequence: The items/slices from the grouping. Its container matches the one of `items`. Examples: >>> l = list(range(10)) >>> tuple(split(l, 4)) ([0, 1, 2, 3], [4, 5, 6, 7], [8, 9]) >>> tuple(split(l, (2, 3))) ([0, 1], [2, 3, 4], [5, 6, 7, 8, 9]) >>> tuple(split(l, (2, 4, 1))) ([0, 1], [2, 3, 4, 5], [6], [7, 8, 9]) >>> tuple(split(l, (2, 4, 1, 20))) ([0, 1], [2, 3, 4, 5], [6], [7, 8, 9]) >>> tuple(split(tuple(l), 4)) ((0, 1, 2, 3), (4, 5, 6, 7), (8, 9)) >>> tuple(split(tuple(l), 4, True)) (slice(0, 4, None), slice(4, 8, None), slice(8, 10, None)) >>> tuple(split(tuple(l), 2)) == tuple(separate(l, 2)) True See Also: - flyingcircus.slide() - flyingcircus.sliding() - flyingcircus.separate() - flyingcircus.chunks() - flyingcircus.split_by() - flyingcircus.group_by() - flyingcircus.regroup_by() Nr<rr/) rrYrrsumrr accumulater{r)rsizesslicesrrcr;rMs rusplitrZsh%E3s8u#45CI 5zYcr  5--e45 5 DE e*q.C s 0Aa%A,/ / 0s -AeAhuQU|, , -sCCc#Ktjgdtjgdtgdi}t |}||vr ||d}nt dj |td|}t|t||z }|rPdt||zcxkr|dzkr6nn3t||zdz} t| |z} |f| | z z|dz f| zz}t|||D]} | y w) a^ Split items into groups according to the number desired. If the number of items does not allow groups (chunks) of the same size, the chunks are determined depending on the values of `balanced`. All and only the elements in `items` are ever yielded. Args: seq (Sequence): The input items. n (int): Approximate number of chunks. The exact number depends on the value of `mode`. mode (str|int): Determine which approximation to use. If str, valid inputs are: - 'upper', '+': at most `n` chunks are generated. - 'lower', '-': at least `n` chunks are generated. - 'closest', '~': the number of chunks is `n` or `n + 1` depending on which gives the most evenly distributed chunks sizes. If int, valid inputs are `+1`, `0` and `-1`, mapping to 'upper', 'closest' and 'lower' respectively. balanced (bool): Produce balanced chunks. If True, the size of any two chunks is not larger than one. Otherwise, the first chunks except the last have the same size. This has no effect if the number of items is a multiple of `n`. slices (bool): Yield the slices. If True, yield the slices that would split the input. Otherwise, yield the splitted input. Yields: Sequence: The items/slices from the grouping. Its container matches the one of `items`. Examples: >>> l = list(range(10)) >>> tuple(chunks(l, 5)) ([0, 1], [2, 3], [4, 5], [6, 7], [8, 9]) >>> tuple(chunks(l, 2)) ([0, 1, 2, 3, 4], [5, 6, 7, 8, 9]) >>> tuple(chunks(l, 3)) ([0, 1, 2, 3], [4, 5, 6], [7, 8, 9]) >>> tuple(chunks(l, 4)) ([0, 1, 2], [3, 4, 5], [6, 7], [8, 9]) >>> tuple(chunks(l, -1)) ([0, 1, 2, 3, 4, 5, 6, 7, 8, 9],) >>> tuple(chunks(l, 3, balanced=False)) ([0, 1, 2, 3], [4, 5, 6, 7], [8, 9]) >>> tuple(chunks(l, 3, '-')) ([0, 1, 2], [3, 4, 5], [6, 7], [8, 9]) >>> tuple(chunks(l, 3, '-', False)) ([0, 1, 2], [3, 4, 5], [6, 7, 8], [9]) >>> tuple(chunks(list(range(10)), 3, '~')) ([0, 1, 2], [3, 4, 5], [6, 7], [8, 9]) >>> tuple(chunks(list(range(10)), 3, '~', False)) ([0, 1, 2], [3, 4, 5], [6, 7, 8], [9]) See Also: - flyingcircus.slide() - flyingcircus.sliding() - flyingcircus.separate() - flyingcircus.split() - flyingcircus.split_by() - flyingcircus.group_by() - flyingcircus.regroup_by() )upper+r/)lower-r<)closest~rrInvalid mode `{mode}`rr/r9N) mathceilfloorroundr\r"rrrYrrZ) rr2rbalancedrYreversed_modesmodesapproxr r'rQgroups ruchunksrmsN $ & "$N ! 0E u}tQ077T7BCC Aq A vc#hl# $DAC444194 H q  XI w!a% D1H;?2sD&) sC4C6c#NKt|} t|}t|}|r||n|}dx}}t|dD]0\}}|r||n|} || k7s|r t ||n|||| }|}2||k\r|rt ||dzn|||dzyy#t $rYywxYww)a Split consecutive items into groups by some criterion. Args: seq (Sequence): The input items. key (callable|None): Splitting criterion. Must have the following signature: key(Any): Any Each element of the sequence is given as input. If None, the element itself is used. slices (bool): Yield the slices. If True, yield the slices that would split the input. Otherwise, yield the splitted input. Yields: Sequence: The items/slices from the grouping. Its container matches the one of `items`. Examples: >>> items = [1, 1, 1, 2, 2, 2, 3, 3, 3] >>> print(list(split_by(items))) [[1, 1, 1], [2, 2, 2], [3, 3, 3]] >>> items = [0, 0, 2, 2, 2, 1, 1, 3, 3, 3] >>> print(list(split_by(items))) [[0, 0], [2, 2, 2], [1, 1], [3, 3, 3]] >>> items = [0, 0, 2, 2, 2, 1, 1, 3, 3, 3] >>> print(list(split_by(items, lambda x: x % 2))) [[0, 0, 2, 2, 2], [1, 1, 3, 3, 3]] See Also: - flyingcircus.split() - flyingcircus.chunks() - flyingcircus.group_by() - flyingcircus.regroup_by() rr/N)rrrrrr) rrrYrr callable_keyrgrMrcurrents rusplit_byrq=sP IE>E{ } (s4yd A * GAt#/c$iTGw%+eAqkQq9   6%+%1q5/Qq1u =  s- B% B>B%=B% B"B%!B""B%c#Kt|} t|}t|}|r||n|}|g}|D]0}|r||n|}||k(r|j|&||f|}|g}2|r||fyy#t$rYywxYww)a- Split consecutive items into groups by some criterion. This similar to `flyingcircus.split_by()` except that it also yields the value that determines the splitting. Args: items (Iterable): The input items. key (callable|None): Splitting criterion. Must have the following signature: key(Any): Any Each element of the sequence is given as input. If None, the element itself is used. Yields: tuple[Any, list]: The grouping item and the groups. Examples: >>> items = [1, 1, 1, 2, 2, 2, 3, 3, 3] >>> print(list(group_by(items))) [(1, [1, 1, 1]), (2, [2, 2, 2]), (3, [3, 3, 3])] >>> items = [0, 0, 2, 2, 2, 1, 1, 3, 3, 3] >>> print(list(group_by(items))) [(0, [0, 0]), (2, [2, 2, 2]), (1, [1, 1]), (3, [3, 3, 3])] >>> items = [0, 0, 2, 2, 2, 1, 1, 3, 3, 3] >>> print(list(group_by(items, lambda x: x % 2))) [(0, [0, 0, 2, 2, 2]), (1, [1, 1, 3, 3, 3])] >>> items = (0, 0, 2, 2, 2, 1, 1, 3, 3, 3) >>> print(list(group_by(items, lambda x: x % 2))) [(0, [0, 0, 2, 2, 2]), (1, [1, 1, 3, 3, 3])] See Also: - flyingcircus.split() - flyingcircus.chunks() - flyingcircus.split_by() - flyingcircus.regroup_by() N)rrrrr)rrrrorgrlrps rugroup_byrs~sT KEE{ } (s4yd D#/c$iTGw T"Ek!  +   s( B A3AB3 A?<B>A??Bci}t|}|D]+}|r||n|}||vrg||<||j|-|S)a Split items into groups by some criterion. The items are not required to be consecutive. For splitting consecutive items use `flyingcircus.split_by()` or `flyingcircus.group_by()`. Args: items (Iterable): The input items. key (callable|None): Splitting criterion. Must have the following signature: key(Any): Any Each element of the sequence is given as input. If None, the element itself is used. Returns: dict: Contains the criterion and a list of the grouped items. Examples: >>> items = [1, 2, 3, 2, 1, 3, 2, 1, 3, 2, 1, 3] >>> print(regroup_by(items)) {1: [1, 1, 1, 1], 2: [2, 2, 2, 2], 3: [3, 3, 3, 3]} >>> items = [1, 2, 3, 0, 3, 1, 2, 0, 0, 2, 1, 3] >>> print(regroup_by(items, lambda x: x % 2)) {1: [1, 3, 3, 1, 1, 3], 0: [2, 0, 2, 0, 0, 2]} >>> items = range(16) >>> print(regroup_by(items, lambda x: x % 2)) {0: [0, 2, 4, 6, 8, 10, 12, 14], 1: [1, 3, 5, 7, 9, 11, 13, 15]} See Also: - flyingcircus.split() - flyingcircus.chunks() - flyingcircus.split_by() - flyingcircus.group_by() )rr)rrrror key_values ru regroup_byrvs[lFC=L'!-CI4 F " "F9 y  & ' Mrwc#Kt|}||kry||4||g|z}|t|dz D]}|||||}|||d|}|td||z dzD] }|||||zdz ||dz |}|"|)t||z |D]}|||||dz }|yy|8t||g|z}t|D]}|||d|d|zt||z dzD]}|||||z|.td|dzD]}||||z |zdd|zyyw)a Compute a rolling function on a sequence. The function is expressed in terms of an initialization and an update. The following pairs can be used for notable rolling computations: - rolling mean - func: mean - update: lambda x, a, b, n: x + a / n - b / n Args: seq (Sequence[Any]): The input sequence. size (int): The rolling window. func (callable): The function to compute. Must have the following signature: func(Sequence): Any If `update` is a callable provided, this serves as initialization. update (callable|None): The updating function. Must have the following signature: func(last_value, new_item, old_item, size): Any fill (Any|None): The filling value. If None, the rolling starts and stops at the edges of the sequence. Otherwise, the fill value is used to compute partial windows at the edges. Yields: value: The next rolling value. Examples: >>> print(list(rolling(range(16), 2, sum))) [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29] >>> print(list(rolling(range(16), 3, sum))) [3, 6, 9, 12, 15, 18, 21, 24, 27, 30, 33, 36, 39, 42] >>> print(list(rolling(range(16), 4, sum))) [6, 10, 14, 18, 22, 26, 30, 34, 38, 42, 46, 50, 54] >>> print(list(rolling([1] * 16, 4, sum))) [4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4] >>> print(list(rolling([1] * 16, 4, sum, fill=0))) [0, 1, 2, 3, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 3, 2, 1, 0] >>> print(list(rolling([1] * 16, 4, sum, fill=1))) [4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4, 4] >>> print(list(rolling([1] * 8, 8, sum, fill=0))) [0, 1, 2, 3, 4, 5, 6, 7, 8, 7, 6, 5, 4, 3, 2, 1, 0] >>> print(list(rolling([1] * 8, 8, sum, fill=1))) [8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8] >>> print(list(rolling([1] * 8, 8, sum))) [8] >>> print(list(rolling([1] * 8, 9, sum))) [] >>> print(list(rolling([1] * 8, 9, sum, fill=0))) [] >>> def sum_update(x, a, b, n): return x + a - b >>> print(list(rolling(range(16), 2, sum))) [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29] >>> print(list(rolling(range(16), 2, sum, sum_update))) [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25, 27, 29] >>> def mean_update(x, a, b, n): return x + a / n - b / n >>> print(list(rolling(range(12), 2, mean))) [0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5] >>> print(list(rolling(range(12), 2, mean, mean_update))) [0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5] >>> def prod_update(x, a, b, n): return x * a / b >>> print(list(rolling(range(1, 13), 3, prod))) [6, 24, 60, 120, 210, 336, 504, 720, 990, 1320] >>> print(list(rolling(range(1, 13), 3, prod, prod_update))) [6, 24.0, 60.0, 120.0, 210.0, 336.0, 504.0, 720.0, 990.0, 1320.0] >>> def hash_func(seq): return sum(hash(x) for x in seq) >>> def hash_update(x, a, b, n): return x + hash(a) - hash(b) >>> print(list(rolling(range(12), 3, hash_func))) [3, 6, 9, 12, 15, 18, 21, 24, 27, 30] >>> print(list(rolling(range(12), 3, hash_func, hash_update))) [3, 6, 9, 12, 15, 18, 21, 24, 27, 30] See Also: - flyingcircus.slide() - flyingcircus.sliding() Nr/)rr{r) rr rrrr2r[rMbuffers rurollingrysp CA4x   $$'EK4!8_ uc!fd3  S$Z  q!d(Q,' A5#a$hl"3SQZFEK   1t8Q' udCAJ7     T#Yv}-F4[ 16!":BQ/00 1q4x!|$ (As1QX' ' (  1dQh' <3q4x!|}-r :;; < sE E c#vKt|}t}|r ||kDs|dkrytt|}|fd|D t|dz ddD]}||||z|z k7sny||xxdz cc<t|dz|D]}||dz dz||<|fd|Diw)a Generate all possible k-combinations of given items. This is similar to `itertools.combinations()`. The `itertools` version should be preferred to this function. Args: seq (Sequence): The input items. k (int): The number of items to select. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: result (Sequence): The next output elements. Examples: >>> list(combinations(range(3), 2)) [(0, 1), (0, 2), (1, 2)] >>> list(combinations(range(4), 0)) [] >>> list(combinations(range(4), 1)) [(0,), (1,), (2,), (3,)] >>> list(combinations(range(4), 2)) [(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)] >>> list(combinations(range(4), 3)) [(0, 1, 2), (0, 1, 3), (0, 2, 3), (1, 2, 3)] >>> list(combinations(range(4), 4)) [(0, 1, 2, 3)] >>> list(combinations(range(4), 5)) [] >>> list(combinations([], 0)) [] >>> list(combinations([], 1)) [] >>> list(combinations(range(2), 2)) [(0, 1)] >>> list(combinations(tuple(range(3)), 2)) [(0, 1), (0, 2), (1, 2)] >>> list(combinations(list(range(3)), 2)) [[0, 1], [0, 2], [1, 2]] >>> list(combinations(range(3), 2)) [(0, 1), (0, 2), (1, 2)] >>> list(combinations('abc', 2)) ['ab', 'ac', 'bc'] >>> list(combinations(b'abc', 2)) [b'ab', b'ac', b'bc'] >>> p1 = sorted(combinations(range(10), 3)) >>> p2 = sorted(itertools.combinations(range(10), 3)) >>> p1 == p2 True See Also: - flyingcircus.multi_combinations() - flyingcircus.permutations() - flyingcircus.multi_permutations() - flyingcircus.cyclic_permutations() - flyingcircus.unique_permutations() - flyingcircus.cartesian_product() r/Nc3(K|] }| ywrrrrMrs rurzcombinations..,qCF,r<c3(K|] }| ywrrr|s rurzcombinations..01A0r~rrrr{rr'rr;r'rMrs` rurrwsJ!i0I c(C !c'QU58nG ,G, ,, q1ub"% AqzQWq[(   a q1ua ,A Q!+GAJ ,0000 s A.B92AB9c# Kt|}t}|r|sydg|z}|fd|D t|dz ddD]}|||dz k7sny||dzg||z z||d|fd|DIw)aQ Generate all possible k-multi-combinations of given items. These are also called combinations with repetitions. This is similar to `itertools.combinations_with_replacement()`. The `itertools` version should be preferred to this function. Args: seq (Sequence): The input items. k (int): The number of items to select. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: result (Sequence): The next output elements. Examples: >>> list(multi_combinations(range(2), 0)) [] >>> list(multi_combinations(range(2), 1)) [(0,), (1,)] >>> list(multi_combinations(range(2), 2)) [(0, 0), (0, 1), (1, 1)] >>> list(multi_combinations(range(2), 3)) [(0, 0, 0), (0, 0, 1), (0, 1, 1), (1, 1, 1)] >>> list(multi_combinations(range(2), 4)) [(0, 0, 0, 0), (0, 0, 0, 1), (0, 0, 1, 1), (0, 1, 1, 1), (1, 1, 1, 1)] >>> list(multi_combinations([], 0)) [] >>> list(multi_combinations([], 1)) [] >>> list(multi_combinations(tuple(range(3)), 2)) [(0, 0), (0, 1), (0, 2), (1, 1), (1, 2), (2, 2)] >>> list(multi_combinations(list(range(3)), 2)) [[0, 0], [0, 1], [0, 2], [1, 1], [1, 2], [2, 2]] >>> list(multi_combinations(range(3), 2)) [(0, 0), (0, 1), (0, 2), (1, 1), (1, 2), (2, 2)] >>> list(multi_combinations('abc', 2)) ['aa', 'ab', 'ac', 'bb', 'bc', 'cc'] >>> list(multi_combinations(b'abc', 2)) [b'aa', b'ab', b'ac', b'bb', b'bc', b'cc'] >>> p1 = sorted(multi_combinations(range(10), 3)) >>> p2 = sorted(itertools.combinations_with_replacement(range(10), 3)) >>> p1 == p2 True See Also: - flyingcircus.combinations() - flyingcircus.permutations() - flyingcircus.multi_permutations() - flyingcircus.cyclic_permutations() - flyingcircus.unique_permutations() - flyingcircus.cartesian_product() Nrc3(K|] }| ywrrr|s rurz%multi_combinations..r}r~r/r<c3(K|] }| ywrrr|s rurz%multi_combinations..rr~rrr{)rr'rr;r'rMs` rumulti_combinationsrs~!i0I c(C acAgG ,G, ,, q1ub"% AqzS1W$  qzA~&!a%0 0000 s AB*Bc#Kt|}t}||n|}||kDs |dks|dkrytt|}tt|||z d}|fd|d|D|r{t|dz ddD]c}||xxdzcc<||dk(r||dzd|||dzz||d||z ||<5||}|| ||c||<|| <|fd|d|Dny|rzyyw)a/ Generate all possible k-permutations of given items. If k is smaller than the number of input items, generates partial permutations. This is similar to `itertools.permutations()`. The `itertools` version should be preferred to this function. Args: seq (Sequence): The input items. k (int|None): The number of items to select. If k is None, all permutations are generated. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: result (Sequence): The next output elements. Examples: >>> list(permutations(range(3), 0)) [] >>> list(permutations(range(3), 1)) [(0,), (1,), (2,)] >>> list(permutations(range(3), 2)) [(0, 1), (0, 2), (1, 0), (1, 2), (2, 0), (2, 1)] >>> list(permutations(range(3), 3)) [(0, 1, 2), (0, 2, 1), (1, 0, 2), (1, 2, 0), (2, 0, 1), (2, 1, 0)] >>> list(permutations(range(3), 4)) [] >>> list(permutations([], 0)) [] >>> list(permutations([], 1)) [] >>> list(permutations(tuple(range(3)), 2)) [(0, 1), (0, 2), (1, 0), (1, 2), (2, 0), (2, 1)] >>> list(permutations(list(range(3)), 2)) [[0, 1], [0, 2], [1, 0], [1, 2], [2, 0], [2, 1]] >>> list(permutations(range(3), 2)) [(0, 1), (0, 2), (1, 0), (1, 2), (2, 0), (2, 1)] >>> list(permutations('abc', 2)) ['ab', 'ac', 'ba', 'bc', 'ca', 'cb'] >>> list(permutations(b'abc', 2)) [b'ab', b'ac', b'ba', b'bc', b'ca', b'cb'] >>> p1 = sorted(permutations(range(10), 3)) >>> p2 = sorted(itertools.permutations(range(10), 3)) >>> p1 == p2 True See Also: - flyingcircus.combinations() - flyingcircus.multi_combinations() - flyingcircus.multi_permutations() - flyingcircus.cyclic_permutations() - flyingcircus.unique_permutations() - flyingcircus.cartesian_product() Nr/r<c3(K|] }| ywrrr|s rurzpermutations..gs0qCF0r~rc3(K|] }| ywrrr|s rurzpermutations..qs<1A>> list(multi_permutations(range(2), 0)) [] >>> list(multi_permutations(range(2), 1)) [(0,), (1,)] >>> list(multi_permutations(range(2), 2)) [(0, 0), (0, 1), (1, 0), (1, 1)] >>> list(multi_permutations(range(2), 3)) [(0, 0, 0), (0, 0, 1), (0, 1, 0), (0, 1, 1), (1, 0, 0), (1, 0, 1), (1, 1, 0), (1, 1, 1)] >>> list(multi_permutations([], 0)) [] >>> list(multi_permutations([], 1)) [] >>> list(multi_permutations(tuple(range(3)), 2)) [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2), (2, 0), (2, 1), (2, 2)] >>> list(multi_permutations(list(range(3)), 2)) [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]] >>> list(multi_permutations(range(4), 1)) [(0,), (1,), (2,), (3,)] >>> list(multi_permutations('abc', 2)) ['aa', 'ab', 'ac', 'ba', 'bb', 'bc', 'ca', 'cb', 'cc'] >>> list(multi_permutations(b'abc', 2)) [b'aa', b'ab', b'ac', b'ba', b'bb', b'bc', b'ca', b'cb', b'cc'] >>> p1 = sorted(multi_permutations(range(10), 3)) >>> p2 = sorted(itertools.product(range(10), repeat=3)) >>> p1 == p2 True See Also: - flyingcircus.combinations() - flyingcircus.multi_combinations() - flyingcircus.permutations() - flyingcircus.cyclic_permutations() - flyingcircus.unique_permutations() - flyingcircus.cartesian_product() r/Nrc3(K|] }| ywrrr|s rurz%multi_permutations..r}r~r<c3(K|] }| ywrrr|s rurz%multi_permutations..rr~rrs` rumulti_permutationsrxsB!i0I c(C !a%cAgG ,G, ,, q1ub"% AqzS1W$q!#A!"GAJ#    a 0000 sBBc#pK|rdnd}tt|D]}|||zd|d||zzyw)a Generate cyclic permutations of given items. Args: seq (Sequence): The input items. forward (bool): Determine how to advance through permutations. Yields: result (Sequence): The next output elements. See Also: - flyingcircus.combinations() - flyingcircus.multi_combinations() - flyingcircus.permutations() - flyingcircus.multi_permutations() - flyingcircus.unique_permutations() - flyingcircus.cartesian_product() Examples: >>> list(cyclic_permutations(tuple(range(4)))) [(0, 1, 2, 3), (1, 2, 3, 0), (2, 3, 0, 1), (3, 0, 1, 2)] >>> list(cyclic_permutations(list(range(4)))) [[0, 1, 2, 3], [1, 2, 3, 0], [2, 3, 0, 1], [3, 0, 1, 2]] >>> list(cyclic_permutations(list(range(3)), True)) [[0, 1, 2], [1, 2, 0], [2, 0, 1]] >>> list(cyclic_permutations(list(range(3)), False)) [[0, 1, 2], [2, 0, 1], [1, 2, 0]] >>> list(cyclic_permutations('abcdef', True)) ['abcdef', 'bcdefa', 'cdefab', 'defabc', 'efabcd', 'fabcde'] >>> list(cyclic_permutations('abcdef', False)) ['abcdef', 'fabcde', 'efabcd', 'defabc', 'cdefab', 'bcdefa'] >>> list(cyclic_permutations(b'abcdef', True)) [b'abcdef', b'bcdefa', b'cdefab', b'defabc', b'efabcd', b'fabcde'] >>> list(cyclic_permutations(b'abcdef', False)) [b'abcdef', b'fabcde', b'efabcd', b'defabc', b'cdefab', b'bcdefa'] r/r<N)r{r)rforwardsignrMs rucyclic_permutationsrsHR1RD 3s8_.$()ns9D1H~--.s46c#&Kt||}tt|dz dd}t|} |||ddD]}||||dzksny||}|D] }|||ks nd}||||c||<||<|d|d||dzd]w)a* Generate unique permutations of items in an efficient way. If items does not contain repeating elements, this is equivalent to `flyingcircus.permutations()`. Args: seq (Sequence): The input items. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: result (Sequence): The next output elements. Examples: >>> list(unique_permutations([0, 0, 0])) [[0, 0, 0]] >>> list(itertools.permutations([0, 0, 0])) [(0, 0, 0), (0, 0, 0), (0, 0, 0), (0, 0, 0), (0, 0, 0), (0, 0, 0)] >>> list(unique_permutations([0, 0, 2])) [[0, 0, 2], [0, 2, 0], [2, 0, 0]] >>> list(itertools.permutations([0, 0, 2])) [(0, 0, 2), (0, 2, 0), (0, 0, 2), (0, 2, 0), (2, 0, 0), (2, 0, 0)] >>> list(unique_permutations([0, 1, 2])) [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]] >>> list(permutations([0, 1, 2])) [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]] >>> list(itertools.permutations([0, 1, 2])) [(0, 1, 2), (0, 2, 1), (1, 0, 2), (1, 2, 0), (2, 0, 1), (2, 1, 0)] >>> list(unique_permutations([])) [[]] >>> list(unique_permutations('aabb')) ['aabb', 'abab', 'abba', 'baab', 'baba', 'bbaa'] >>> list(unique_permutations(b'aabb')) [b'aabb', b'abab', b'abba', b'baab', b'baba', b'bbaa'] >>> p1 = sorted(unique_permutations(tuple(range(8)))) >>> p2 = sorted(itertools.permutations(tuple(range(8)))) >>> p1 == p2 True References: - Donald Knuth, The Art of Computer Programming, Volume 4, Fascicle 2: Generating All Permutations. See Also: - flyingcircus.combinations() - flyingcircus.multi_combinations() - flyingcircus.permutations() - flyingcircus.multi_permutations() - flyingcircus.cyclic_permutations() - flyingcircus.cartesian_product() r/r<Nr)rr{rrl)rrr`r'k_valrMs ruunique_permutationsrsz!i0ICHqL"b)G +C n A1vAE "  A As1v~ AQQAA"Qr'lAEF  sABB,%B)r'rc 'K|Dcgc]}t||}}t|stn|d}|dkDr||z}t|}t t |}t t |t tt|}d}dg|z} |}t|D]\} \}} ||| z||| z dz <|| z} |dkDry|||dz }Dcc}ww)a! Generate the cartesian product of the input sequences. This is similar to `itertools.product()`. The `itertools` version should be preferred to this function. Args: *seqs (Sequence[Sequence]): The input sequences. k (int): Repetition factor for the input sequences. The input sequences are repeated `k` times. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: result (Sequence): The next output elements. Examples: >>> sorted(cartesian_product([1, 2], [3, 4, 5])) [[1, 3], [1, 4], [1, 5], [2, 3], [2, 4], [2, 5]] >>> sorted(cartesian_product((1, 2), (3, 4, 5))) [(1, 3), (1, 4), (1, 5), (2, 3), (2, 4), (2, 5)] >>> sorted(cartesian_product(range(2), range(3))) [(0, 0), (0, 1), (0, 2), (1, 0), (1, 1), (1, 2)] >>> sorted(cartesian_product('abc', 'ABC')) ['aA', 'aB', 'aC', 'bA', 'bB', 'bC', 'cA', 'cB', 'cC'] >>> sorted(cartesian_product([1, 2], k=2)) [[1, 1], [1, 2], [2, 1], [2, 2]] >>> sorted(cartesian_product('ab', k=3)) ['aaa', 'aab', 'aba', 'abb', 'baa', 'bab', 'bba', 'bbb'] >>> sorted(cartesian_product('ab', 'c', k=2)) ['acac', 'acbc', 'bcac', 'bcbc'] >>> sorted(cartesian_product('ab', 'cd', k=2)) ['acac', 'acad', 'acbc', 'acbd', 'adac', 'adad', 'adbc', 'adbd', 'bcac', 'bcad', 'bcbc', 'bcbd', 'bdac', 'bdad', 'bdbc', 'bdbd'] See Also: - flyingcircus.combinations() - flyingcircus.multi_combinations() - flyingcircus.permutations() - flyingcircus.multi_permutations() - flyingcircus.cyclic_permutations() - flyingcircus.unique_permutations() rr/N) rrrrrrrrr) r'rseqsr containersr2r_seqsrMrrr0s rucartesian_productrNs`?CCs"3 2CJC&z2 1 I1uax` D A (4. !F FDS&!123 4D AVaZF  $T? KAxQ #AE F1q519  !GA  q5 F# # FA qDsCCB?Cc #xK| t}t|r|tttfvrt } |tt fdtjtd|dz D}|D]|fdt|D!y#t $r t }YvwxYww)aH Generate all k-partitions for the items. Args: seq (Sequence): The input items. k (int): The number of splitting partitions. Each group has exactly `k` elements. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: partition (Sequence[Sequence]]): The grouped items. Each partition contains `k` grouped items from the source. Examples: >>> items = tuple(range(3)) >>> tuple(partitions(items, 2)) (((0,), (1, 2)), ((0, 1), (2,))) >>> tuple(partitions(items, 3)) (((0,), (1,), (2,)),) >>> items = 'abc' >>> tuple(partitions(items, 2)) (('a', 'bc'), ('ab', 'c')) >>> tuple(partitions(items, 3)) (('a', 'b', 'c'),) >>> items = range(3) >>> tuple(partitions(items, 2)) ((range(0, 1), range(1, 3)), (range(0, 2), range(2, 3))) >>> tuple(partitions(items, 3)) ((range(0, 1), range(1, 2), range(2, 3)),) >>> tuple(partitions(tuple(range(4)), 3)) (((0,), (1,), (2, 3)), ((0,), (1, 2), (3,)), ((0, 1), (2,), (3,))) >>> tuple(partitions(list(range(4)), 3)) ([[0], [1], [2, 3]], [[0], [1, 2], [3]], [[0, 1], [2], [3]]) Nc3BK|]}dt|zfzyw)rUNr)rrcr;s rurzpartitions..s+C  uU|sf$Crr/c3:K|]}||dzywrr)rrMrcrs rurzpartitions..s$EqE!HU1q5\2E) rrrarrrrrrrr{)rr'rr`rcr;s` @@ru partitionsrsVI I )UI/F"F # c(CC++E!SM1q5ACCGFEE!HEEEF  s)2B:B%A%B:%B74B:6B77B:c #K| t|}t|st}|rt|}t |D]\}}t t||tt jt j||}t |t j||D] }||y|D cgc]} tt| } } t| } tjt| t|| D]?}g} | D]} | j|| z|| z}|dt!| |DAycc} w#t"$rt%}t|t|| kr:|j'td| Dt|t|| kr:t|}t |t j||D]}|dt!||DYywxYww)a Obtain a number of random unique combinations of a sequence of sequences. Args: seq (Sequence[Sequence]): The input sequence of sequences. k (int): The number of random unique combinations to obtain. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. pseudo (bool): Generate random combinations somewhat less randomly. If True, the memory requirements for intermediate steps will be significantly lower (but still all `k` items are required to fit in memory). Yields: combination (Sequence): The next random unique combination. Examples: >>> import string >>> max_lens = list(range(2, 10)) >>> items = tuple( ... string.ascii_lowercase[:max_len] for max_len in max_lens) >>> random.seed(0) >>> num = 10 >>> for i in random_unique_combinations_k(items, num): ... print(i) ('b', 'a', 'd', 'a', 'd', 'a', 'a', 'f') ('a', 'a', 'c', 'c', 'b', 'f', 'd', 'f') ('b', 'b', 'b', 'e', 'c', 'b', 'e', 'a') ('a', 'b', 'a', 'b', 'd', 'g', 'c', 'd') ('b', 'c', 'd', 'd', 'b', 'b', 'f', 'g') ('a', 'a', 'b', 'a', 'f', 'd', 'c', 'g') ('a', 'c', 'd', 'a', 'f', 'a', 'c', 'f') ('b', 'c', 'd', 'a', 'f', 'd', 'h', 'd') ('a', 'c', 'b', 'b', 'a', 'e', 'b', 'g') ('a', 'c', 'c', 'b', 'e', 'b', 'f', 'e') >>> max_lens = list(range(2, 4)) >>> items = tuple( ... string.ascii_uppercase[:max_len] for max_len in max_lens) >>> random.seed(0) >>> num = 10 >>> for i in random_unique_combinations_k(items, num): ... print(i) ('B', 'B') ('B', 'C') ('A', 'A') ('B', 'A') ('A', 'B') ('A', 'C') Nc3,K|] \}}||ywrrrrMrs rurz/random_unique_combinations_k..MsIGAtQIc32K|]}t|ywr)r )rrs rurz/random_unique_combinations_k..VsF'*W-Fsc3,K|] \}}||ywrrrs rurz/random_unique_combinations_k..\sLGAtQLr)rrrrrrrrEproductrprodrandomsampler{minrr OverflowErrorrjr6)rr'rpseudo comb_gensr;comb_gencombs combinationrmax_lensmax_kr`r index_combs index_combs rurandom_unique_combinations_krsnI I   I &y1 *MC D3( ) *Y%%i&7&7&CQGH$++E15 )KK( ( )144CT O44X M}}U5\3q%=A J')GNN3=1.C) Is7C7HIII  J5 M%Kk"SE]2FXFFHk"SE]2 {+K K '..{A> M Ls:s7KLLL M Ms?B:H <E H %A+EH A$H ;A H H  H  H c#K| t|}t|st}t|D]}|t |||yw)a  Generate all k-partitions for all unique permutations of the items. Args: seq (Sequence): The input items. k (int): The number of splitting partitions. Each group has exactly `k` elements. container (callable|None): The container for the result. If None, this is inferred from `seq` if possible, otherwise uses `tuple`. Yields: partitions (Sequence[Sequence[Sequence]]]): The items partitions. More precisely, all partitions of size `num` for each unique permutations of `items`. Examples: >>> list(unique_partitions([0, 1], 2)) [[[[0], [1]]], [[[1], [0]]]] >>> tuple(unique_partitions((0, 1), 2)) ((((0,), (1,)),), (((1,), (0,)),)) N)rrrrr)rr'rpermss ruunique_partitionsr`sO4I I  $S)9 9U#3Q7889sA A cr|rtt||}ng}|stt|}t|D]f}d}t |D]@\}}|D cgc]} | | c} |gz} t t | t | ks>d}n|sV|j|h|r t||Scc} w)a Generate a latin square. Args: seq (Sequence): The input items. randomize (bool): Shuffle the output "rows". cyclic (bool): Generate cyclic permutations only. forward (bool): Determine how to advance through permutations. Note that for cyclic permutations (`cyclic == True`), this means that the cycling is moving forward (or not), whereas for non-cyclic permutations (`cyclic == False`), this is equivalent to reversing the items order prior to generating the permutations, i.e. `permutations(reversed(items)) == reversed(permutations(items))`. Returns: result (list[Sequence]): The latin square. Examples: >>> random.seed(0) >>> latin_square(list(range(4))) [[2, 3, 0, 1], [3, 0, 1, 2], [1, 2, 3, 0], [0, 1, 2, 3]] >>> latin_square(list(range(4)), False, False, False) [[3, 2, 1, 0], [2, 3, 0, 1], [1, 0, 3, 2], [0, 1, 2, 3]] >>> latin_square(list(range(4)), False, True, False) [[0, 1, 2, 3], [3, 0, 1, 2], [2, 3, 0, 1], [1, 2, 3, 0]] >>> latin_square(list(range(4)), False, False, True) [[0, 1, 2, 3], [1, 0, 3, 2], [2, 3, 0, 1], [3, 2, 1, 0]] >>> latin_square(list(range(4)), False, True, True) [[0, 1, 2, 3], [1, 2, 3, 0], [2, 3, 0, 1], [3, 0, 1, 2]] >>> random.seed(0) >>> latin_square(list(range(4)), True, False, False) [[1, 0, 3, 2], [0, 1, 2, 3], [2, 3, 0, 1], [3, 2, 1, 0]] >>> random.seed(0) >>> latin_square(list(range(4)), True, True, False) [[2, 3, 0, 1], [1, 2, 3, 0], [3, 0, 1, 2], [0, 1, 2, 3]] >>> random.seed(0) >>> latin_square(list(range(4)), True, False, True) [[2, 3, 0, 1], [3, 2, 1, 0], [1, 0, 3, 2], [0, 1, 2, 3]] >>> random.seed(0) >>> latin_square(list(range(4)), True, True, True) [[2, 3, 0, 1], [3, 0, 1, 2], [1, 2, 3, 0], [0, 1, 2, 3]] >>> random.seed(0) >>> latin_square(tuple(range(4))) [(2, 3, 0, 1), (3, 0, 1, 2), (1, 2, 3, 0), (0, 1, 2, 3)] >>> random.seed(0) >>> latin_square('abcde') ['eabcd', 'abcde', 'deabc', 'bcdea', 'cdeab'] >>> print('\n'.join(latin_square('0123456789'))) 7890123456 8901234567 5678901234 9012345678 3456789012 4567890123 1234567890 2345678901 0123456789 6789012345 TF) rrrrrrrjrr) rrcyclicrrelemsvalidrMelemrH orthogonalss ru latin_squarersJ)#w78x}%C!#& %EE$U+ 4-34qt4v= s;'(3{+;;!E    e$ % M5s B4c ||kSrrrHr7s rurrs Q!Vrwcjtt||d}|r|xstt||d}|S)a Determine if an iterable is sorted or not. Args: items (Iterable): The input items. compare (callable): The comparison function. Must have the signature: compare(Any, Any): bool. both (bool): Compare the items both forward and backward. Returns: result (bool): The result of the comparison for all consecutive pairs. Examples: >>> items = list(range(10)) >>> print(items) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> is_sorted(items) True >>> is_sorted(items[::-1]) True >>> is_sorted(items[::-1], both=False) False >>> is_sorted(items[::-1], lambda x, y: x > y, both=False) True >>> items = [1] * 10 >>> print(items) [1, 1, 1, 1, 1, 1, 1, 1, 1, 1] >>> is_sorted(items) True >>> is_sorted(items, lambda x, y: x < y) False >>> is_sorted([0, 1, 2, 4, 4, 5, 6, 7, 8, 9]) True >>> is_sorted([0, 1, 2, 5, 4, 5, 6, 7, 8, 9]) False >>> is_sorted([]) True >>> is_sorted(iter([0, 1, 2, 4, 4, 5, 6, 7, 8, 9])) True >>> is_sorted(iter([0, 1, 2, 5, 4, 5, 6, 7, 8, 9])) False See Also: - flyingcircus.pairwise_map() FT)rrB)rcomparebothrs ru is_sortedrs8fgue4 5F B3|GUDAB Mrwcd}t|dz }d}||kr2|s0||zdz}|||k(r|}d}n|||kr|dz }n|dz}||kr|s0|S)aY Search for an item in a sorted sequence. If the sequence is not sorted the results are unpredictable. Internally, it uses a binary search, which is the theoretical optimal algorithm for searching sorted sequences. Note that if the item is present in the sequence, for built-in sequences, the `.index()` method may be faster. Args: seq (Sequence): The input sequence. item (Any): The item to search for. Returns: result (int): The matching index. If `item` is in `seq`, this is the index at which `item` is found, i.e. `item == seq[result]` Otherwise, this is the index at which inserting `item` in `seq` would result in a sorted sequence. Examples: >>> search_sorted(list(range(1000)), 500) 500 >>> search_sorted([x ** 2 for x in range(100)], 500) 23 >>> items = [x ** 2 for x in range(10)] >>> print(items) [0, 1, 4, 9, 16, 25, 36, 49, 64, 81] >>> value = 9 >>> i = search_sorted(items, value) >>> print(items[i] == value) True >>> new_items = items[:i] + [value] + items[i:] >>> print(new_items) [0, 1, 4, 9, 9, 16, 25, 36, 49, 64, 81] >>> print(is_sorted(new_items)) True >>> value = 5 >>> i = search_sorted(items, value) >>> print(items[i] == value) False >>> new_items = items[:i] + [value] + items[i:] >>> print(new_items) [0, 1, 4, 5, 9, 16, 25, 36, 49, 64, 81] >>> print(is_sorted(new_items)) True >>> all(search_sorted(items, x) == items.index(x) for x in items) True >>> search_sorted([], 'ciao') 0 >>> search_sorted(string.ascii_lowercase, 'x') 23 These fails because the input is not sorted! >>> items = [1, 4, 6, 8, 2, 3, 5] >>> value = 5 >>> search_sorted(items, value) == items.index(value) False >>> search_sorted(string.ascii_letters, 'X') 0 See Also: - flyingcircus.is_sorted() rr/Fr9Tr)rrrfrgfoundmidpoints ru search_sortedrsyR E s8a>> list(find_subseq(list(range(10)), list(range(5, 7)))) [5] >>> list(find_subseq(list(range(10)), [])) [] >>> list(find_subseq([], list(range(5, 7)))) [] >>> list(find_subseq([], [])) [] >>> list(find_subseq(list(range(10)), list(range(5, 12)))) [] >>> list(find_subseq(list(range(10)), list(range(-2, 5)))) [] >>> list(find_subseq(list(range(10)), list(range(-5, -1)))) [] >>> list(find_subseq(list(range(10)), list(range(11, 12)))) [] >>> list(find_subseq(list(range(10)), list(range(3, 8)))) [3] >>> list(find_subseq(list(range(10)), list(range(5)))) [0] >>> list(find_subseq(list(range(10)), list(range(5, 10)))) [5] >>> list(find_subseq(list(range(10)) * 10, list(range(3, 8)))) [3, 13, 23, 33, 43, 53, 63, 73, 83, 93] >>> list(find_subseq(list(range(10)) * 10, list(range(3, 8)), 10, 90)) [13, 23, 33, 43, 53, 63, 73, 83] >>> seq = '12431243123431212' >>> list(find_subseq(seq, '1234')) [8] >>> list(find_subseq(seq, '12')) [0, 4, 8, 13, 15] >>> list(find_subseq(seq, '12')) == list(find_all(seq, '12')) True See Also: - flyingcircus.find_all() rr/N)rr) rsubseqrfrgr2r0offsetsrr'rMs ru find_subseqrrsKt CA F A1uQE1%4#.#'  !eayF1I%Q Q6AA!"GAJFA!e  4i1v"QQAv!e AENds1v26AAFA4i. sBC"AC"C"c b|ttt}t|st} ttst |sEt tjdDcgc]}t|jc}}|fd|DScc}w)a+ Convert tabular data from a Sequence of Mappings to a Mapping of Sequences. Args: data (Sequence[Mapping]): The input tabular data. labels (Sequence|None): The labels of the tabular data. If Sequence, all elements should be present as keys of the dicts. If the dicts contain keys not specified in `labels` they will be ignored. If None, the `labels` are guessed from the data. d_val (Any): The default value to use for incomplete dicts. This will be inserted in the lists to keep track of missing data. mapping_container (callable|None): The mapping container. If None, this is inferred from `data` if possible, otherwise uses `dict`. sequence_container (callable|None): The sequence container. If None, this is inferred from `data` if possible, otherwise uses `list`. Returns: result (Mapping[Sequence]): The output tabular data. All list will have the same size. Examples: >>> data = [{'a': 1, 'b': 2}, {'a': 3, 'b': 4}, {'a': 5, 'b': 6}] >>> tuple(seqmap2mapseq(data).items()) (('a', [1, 3, 5]), ('b', [2, 4, 6])) >>> data == mapseq2seqmap((seqmap2mapseq(data))) True >>> data = [{'a': 1}, {'b': 4}, {'b': 6}] >>> tuple(seqmap2mapseq(data).items()) (('a', [1, None, None]), ('b', [None, 4, 6])) >>> data == mapseq2seqmap((seqmap2mapseq(data))) True See Also: - flyingcircus.mapseq2seqmap() c$|j|Sr)rkrs rurzseqmap2mapseq..*srwc3HK|]fdDfyw)c34K|]}|vr|nywrr)rrd_vallabels rurz*seqmap2mapseq...-s'G9=ETMT%[u 4GsNr)rrrdatasequence_containers @rurz seqmap2mapseq..+s9   GAEG G Hs") rrrrr rrlrreducerjkeys)rlabelsrmapping_containerrrHs` ` ` ru seqmap2mapseqrsZ  d4j!12 % & !!$Z & '!  (( #T%Bc!&&(m%BDE   &Cs. B,c\ ttst| ttt }t|st }st jttt }|fdt|DS)a Convert tabular data from a Mapping of Sequences to a Sequence of Mappings. Args: data (Mapping[Sequence]): The input tabular data. All lists must have the same length. labels (Iterable|None): The labels of the tabular data. If None, the `labels` are guessed from the data. d_val (Any): The default value to be used for reducing dicts. The values matching `d_val` are not included in the dicts. mapping_container (callable|None): The mapping container. If None, this is inferred from `data` if possible, otherwise uses `dict`. sequence_container (callable|None): The sequence container. If None, this is inferred from `data` if possible, otherwise uses `list`. Returns: result (dict[Any:list]): The tabular data as a dict of lists. All list will have the same size. Examples: >>> data = {'a': [1, 3, 5], 'b': [2, 4, 6]} >>> [sorted(d.items()) for d in mapseq2seqmap(data)] [[('a', 1), ('b', 2)], [('a', 3), ('b', 4)], [('a', 5), ('b', 6)]] >>> data == seqmap2mapseq((mapseq2seqmap(data))) True >>> data = {'a': [1, None, None], 'b': [None, 4, 6]} >>> [sorted(d.items()) for d in mapseq2seqmap(data)] [[('a', 1)], [('b', 4)], [('b', 6)]] >>> data == seqmap2mapseq((mapseq2seqmap(data))) True See Also: - flyingcircus.seqmap2mapseq() c3FK|]fdDyw)c3FK|]}|ur ||fywrr)rrrrrMs rurz*mapseq2seqmap...ks6,(-E{1~U*DKN #,!Nr)rrMrrrrs @rurz mapseq2seqmap..js-#  ,17, ,#s!) rrr rrrrrrr{)rrrrr num_elemss```` ru mapseq2seqmapr3sV  J % & !!$tDJ'7"89 & '! tyy{#Dd6l+,-I #y! # ##rwc#0K|r|dz|dz}|ryyw)z Get the bit values for a number (lower to higher significance). Args: value (int): The input value. Yields: result (int): The bits. Examples: >>> list(bits(100)) [0, 0, 1, 0, 0, 1, 1] r/Nr)r[s rubitsrrs" ai !  sc#jK|j}t|dz ddD] }||z dzyw)z Get the reversed bit values for a number (higher to lower significance). Args: value (int): The input value. Yields: result (int): The bits. Examples: >>> list(bits(100)) [0, 0, 1, 0, 0, 1, 1] r/r<N)rr{)r[rIrMs rubits_rrsA A 1q5"b !zQs13c||z dzS)aQ Get the bit value for a number at a given position. Args: value (int): The input value. i (int): The bit position. Returns: result (int): The bit value. Examples: >>> get_bit(100, 2) 1 >>> [get_bit(100, i) for i in range(10)] [0, 0, 1, 0, 0, 1, 1, 0, 0, 0] r/rr[rMs ruget_bitrs& QJ! rwc(|r|d|zzS|d|zzS)a Put a bit value on a number at a given position. Args: value (int): The input value. i (int): The bit position. x (int|bool): The bit value. Returns: result (int): The output value. Examples: >>> put_bit(100, 2, 1) 100 >>> put_bit(100, 2, 0) 96 >>> put_bit(100, 3, 1) 108 >>> put_bit(100, 3, 0) 100 r/r)r[rMrHs ruput_bitrs'0 Qay  rwc|d|zzS)a% Set the bit value for a number at a given position. Args: value (int): The input value. i (int): The bit position. Returns: result (int): The output value. Examples: >>> set_bit(100, 2) 100 >>> set_bit(96, 2) 100 r/rrs ruset_bitrs" AF rwc|d|zzS)a) Unset the bit value for a number at a given position. Args: value (int): The input value. i (int): The bit position. Returns: result (int): The output value. Examples: >>> unset_bit(100, 2) 96 >>> unset_bit(96, 2) 96 r/rrs ru unset_bitrs" Q!V9 rwc|d|zz S)a Flip (toggle) the bit value for a number at a given position. Args: value (int): The input value. i (int): The bit position. Returns: result (int): The output value. Examples: >>> flip_bit(100, 2) 96 >>> flip_bit(96, 2) 100 >>> all( ... x == flip_bit(flip_bit(x, j), j) ... for x in range(1024) for j in range(10)) True r/rrs ruflip_bitrs, AF rwc#TKt|t|D] \}}|s |yw)aj Decode the bits for a number according to the specified tokens. Args: value (int): The input value. tokens (Sequence): The tokens for decoding. Yields: token (Any): The codified bit as token. Examples: >>> ''.join(decode_bits(5, 'abc')) 'ac' >>> ''.join(decode_bits(6, 'rwx')) 'wx' N)rr)r[tokenstokenbits ru decode_bitsrs."&$u+. s Ks((cNd}|D]}t||j|}|S)a Encode the items into a number according to the specified tokens. Args: items (Iterable): The input items. tokens (Sequence): The tokens for encoding. Returns: result (int): The encoded number. Examples: >>> encode_bits('abc', 'abc') 7 >>> encode_bits('ac', 'abc') 5 >>> encode_bits('rw', 'rwx') 3 >>> encode_bits('rx', 'rwx') 5 r)rrc)rrr[rs ru encode_bitsr/s2* E3v||D123 Lrwc#TKt|D]\}}||t||fyw)aG Unravel the bits for a number according to the specified tokens. This is similar to `decode_bits()` except that this yields additional info. Args: value (int): The input value. tokens (Sequence): The tokens for decoding. Yields: token (tuple): The position, token and bit value. N)rr)r[rrMrs ru unravel_bitsrKs4f%*5q)))*s&(c#.K|D] }||z| }yw)a Alternate the sign of arbitrary items. A similar result could be achieved with `itertools.cycle()` and `zip()`. Args: items (Iterable[Number]): The input items. start (Number): The initial value. In strict terms, this should be 1 or -1 but this is not enforced. Yields: item (Number): The item with alternating sign. Examples: >>> print(list(alternate_sign(range(16)))) [0, -1, 2, -3, 4, -5, 6, -7, 8, -9, 10, -11, 12, -13, 14, -15] >>> print(list(alternate_sign(range(16), -1))) [0, 1, -2, 3, -4, 5, -6, 7, -8, 9, -10, 11, -12, 13, -14, 15] >>> print(list(alternate_sign(range(16), 2))) [0, -2, 4, -6, 8, -10, 12, -14, 16, -18, 20, -22, 24, -26, 28, -30] >>> print(list(alternate_sign(itertools.repeat(1, 16)))) [1, -1, 1, -1, 1, -1, 1, -1, 1, -1, 1, -1, 1, -1, 1, -1] Nrrr~rs rualternate_signr]s(4dlsc|D]}||z} |S)a Compute the product of arbitrary items. This is similar to `sum`, but uses product instead of addition. Args: items (Iterable[Number]): The input items. start (Number): The initial value. Returns: result (Number): The cumulative product of `items`. Examples: >>> prod([2] * 10) 1024 >>> prod(range(1, 11)) 3628800 >>> all(prod(range(1, n + 1)) == math.factorial(n) for n in range(10)) True rrs rurr}s!0   Lrwc<ttj|| S)a Compute the pairwise difference of arbitrary items. This is similar to `flyingcircus.div()`, but uses subtraction instead of division. Args: items (Iterable[Number]): The input items. reverse (bool): Reverse the order of the operands. Yields: value (Number): The next pairwise difference. Examples: >>> list(diff(range(10))) [1, 1, 1, 1, 1, 1, 1, 1, 1] >>> list(diff(range(10), True)) [-1, -1, -1, -1, -1, -1, -1, -1, -1] r")rBr^subrr s rudiffrs2  e[ AArwc<ttj|| S)a Compute the pairwise division of arbitrary items. This is similar to `flyingcircus.diff()`, but uses division instead of subtraction. Args: items (Iterable[Number]): The input items. reverse (bool): Reverse the order of the operands. Yields: value (Number): The next pairwise division. Examples: >>> items = [2 ** x for x in range(10)] >>> items [1, 2, 4, 8, 16, 32, 64, 128, 256, 512] >>> list(div(items)) [2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0] >>> list(div(items, True)) [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] r")rBr^truedivrs rudivrs6 ((%W EErwcPt|}|dz}||dkDr |dkDrdzSdzSdzS)a Round to the largest close integer. To round down, just use `int()` Args: x (Number): The input number. Returns: x (int): The rounded-up integer. Examples: >>> round_up(10.4) 11 >>> round_up(10.9) 11 >>> round_up(11.0) 11 >>> round_up(-10.4) -11 >>> round_up(-10.9) -11 >>> round_up(-11.0) -11 r/rr<rY)rHint_xfrac_xs ruround_upr s=4 FE UF  %!)Q BB BB BBrwc2t||\}}|r|dz }|S)as Compute integer ceil division. This is such that: q = div_ceil(a, b) r = mod_ceil(a, b) q * b + r == a Args: a (int): The dividend. b (int): The divisor. Returns: q (int): The quotient. Examples: >>> div_ceil(6, 3) 2 >>> div_ceil(6, -3) -2 >>> div_ceil(-6, 3) -2 >>> div_ceil(-6, -3) 2 >>> div_ceil(7, 3) 3 >>> div_ceil(7, -3) -2 >>> div_ceil(-7, 3) -2 >>> div_ceil(-7, -3) 3 >>> div_ceil(3, 7) 1 >>> div_ceil(3, -7) 0 >>> div_ceil(-3, 7) 0 >>> div_ceil(-3, -7) 1 >>> div_ceil(1, 1) 1 >>> div_ceil(1, -1) -1 >>> div_ceil(-1, 1) -1 >>> div_ceil(-1, -1) 1 See Also: - operator.div() - operator.mod() - divmod() - flyingcircus.mod_ceil() - flyingcircus.divmod_ceil() - flyingcircus.div_round() - flyingcircus.mod_round() - flyingcircus.divmod_round() r/divmodr5rIrQrs rudiv_ceilrs%z !Qt||\}}|r|dz }|||zz S)aq Compute integer ceil modulus. This is such that: q = div_ceil(a, b) r = mod_ceil(a, b) q * b + r == a Args: a (int): The dividend. b (int): The divisor. Returns: r (int): The remainder. Examples: >>> mod_ceil(6, 3) 0 >>> mod_ceil(6, -3) 0 >>> mod_ceil(-6, 3) 0 >>> mod_ceil(-6, -3) 0 >>> mod_ceil(7, 3) -2 >>> mod_ceil(7, -3) 1 >>> mod_ceil(-7, 3) -1 >>> mod_ceil(-7, -3) 2 >>> mod_ceil(3, 7) -4 >>> mod_ceil(3, -7) 3 >>> mod_ceil(-3, 7) -3 >>> mod_ceil(-3, -7) 4 >>> mod_ceil(1, 1) 0 >>> mod_ceil(1, -1) 0 >>> mod_ceil(-1, 1) 0 >>> mod_ceil(-1, -1) 0 See Also: - operator.div() - operator.mod() - divmod() - flyingcircus.div_ceil() - flyingcircus.divmod_ceil() - flyingcircus.div_round() - flyingcircus.mod_round() - flyingcircus.divmod_round() r/r rs rumod_ceilr;s.z !Q>> n = 100 >>> l = list(range(-n, n + 1)) >>> ll = [(a, b) for a, b in itertools.product(l, repeat=2) if b] >>> result = True >>> for a, b in ll: ... q, r = divmod_ceil(a, b) ... result = result and (q == div_ceil(a, b)) ... result = result and (r == mod_ceil(a, b)) ... result = result and (q * b + r == a) >>> print(result) True See Also: - operator.div() - operator.mod() - divmod() - flyingcircus.div_ceil() - flyingcircus.mod_ceil() - flyingcircus.div_round() - flyingcircus.mod_round() - flyingcircus.divmod_round() r/r rs ru divmod_ceilrs2N !Q>> div_round(6, 3) 2 >>> div_round(6, -3) -2 >>> div_round(-6, 3) -2 >>> div_round(-6, -3) 2 >>> div_round(7, 3) 2 >>> div_round(7, -3) -2 >>> div_round(-7, 3) -2 >>> div_round(-7, -3) 2 >>> div_round(3, 7) 0 >>> div_round(3, -7) 0 >>> div_round(-3, 7) 0 >>> div_round(-3, -7) 0 >>> div_round(1, 1) 1 >>> div_round(1, -1) -1 >>> div_round(-1, 1) -1 >>> div_round(-1, -1) 1 See Also: - operator.div() - operator.mod() - divmod() - flyingcircus.div_ceil() - flyingcircus.mod_ceil() - flyingcircus.divmod_ceil() - flyingcircus.mod_round() - flyingcircus.divmod_round() rr/rr5rIs ru div_roundrs2~ QAFAAvzAv rwcN|dk\r|dk\r||zS|| zS|dk\r| |z S||zS)a Compute integer round modulus. This behaves the same as C `%` operator on integers. This is such that: q = div_round(a, b) r = mod_round(a, b) q * b + r == a Args: a (int): The dividend. b (int): The divisor. Returns: r (int): The remainder. Examples: >>> mod_round(6, 3) 0 >>> mod_round(6, -3) 0 >>> mod_round(-6, 3) 0 >>> mod_round(-6, -3) 0 >>> mod_round(7, 3) 1 >>> mod_round(7, -3) 1 >>> mod_round(-7, 3) -1 >>> mod_round(-7, -3) -1 >>> mod_round(3, 7) 3 >>> mod_round(3, -7) 3 >>> mod_round(-3, 7) -3 >>> mod_round(-3, -7) -3 >>> mod_round(1, 1) 0 >>> mod_round(1, -1) 0 >>> mod_round(-1, 1) 0 >>> mod_round(-1, -1) 0 See Also: - operator.div() - operator.mod() - divmod() - flyingcircus.div_ceil() - flyingcircus.mod_ceil() - flyingcircus.divmod_ceil() - flyingcircus.div_round() - flyingcircus.divmod_round() rrrs ru mod_roundrsE~ Av 6q5Lr6M 6R!V9 q5Lrwch|dk\r|dk\r||z}n|| z}n|dk\r| |z }n||z}||z |z|fS)a Compute integer round division and modulus. This behaves the same as C `/` and `%` operators on integers. This is such that: q, r = divmod_round(a, b) q * b + r == a Args: a (int): The dividend. b (int): The divisor. Returns: r (int): The remainder. Examples: >>> n = 100 >>> l = list(range(-n, n + 1)) >>> ll = [(a, b) for a, b in itertools.product(l, repeat=2) if b] >>> result = True >>> for a, b in ll: ... q, r = divmod_round(a, b) ... result = result and (q == div_round(a, b)) ... result = result and (r == mod_round(a, b)) ... result = result and (q * b + r == a) >>> print(result) True See Also: - operator.div() - operator.mod() - divmod() - flyingcircus.div_ceil() - flyingcircus.mod_ceil() - flyingcircus.divmod_ceil() - flyingcircus.div_round() - flyingcircus.mod_round() rr)r5rIrs ru divmod_roundr?sVR Av 6AAQBA 6"q& AAA Ea<?rwc(|jdz S)a Compute the integer base-2 logarithm of a number. This is defined as the largest integer whose power-2 value is smaller than the number, i.e. floor(log2(n)) Args: num (int): The input number. Returns: result (int): The integer base-2 logarithm of the abs(num). If the input is zero, returns -1. Examples: >>> ilog2(1024) 10 >>> ilog2(1023) 9 >>> ilog2(1025) 10 >>> ilog2(2 ** 400) 400 >>> ilog2(-1024) 10 >>> ilog2(-1023) 9 >>> ilog2(-1025) 10 >>> ilog2(0) -1 >>> all(ilog2(2 ** i) == i for i in range(1000)) True >>> all(ilog2(-(2 ** i)) == i for i in range(1000)) True r/)rr;s ruilog2rvsX >> a rwc|dkr| }||jdzz dz}|||zzdz}t||z dkDr|}|||zzdz}t||z dkDr||z|kDr|dz}||z|kDr|S)ay Compute the integer square root of a number. This is defined as the largest integer whose square is smaller than the number, i.e. floor(sqrt(num)) Args: num (int): The input number. Returns: result (int): The integer square root of num. Examples: >>> isqrt(1024) 32 >>> isqrt(1023) 31 >>> isqrt(1025) 32 >>> isqrt(2 ** 400) 1606938044258990275541962092341162602522202993782792835301376 >>> isqrt(2 ** 400) == 2 ** 200 True >>> all(isqrt(2 ** (2 * i)) == 2 ** i for i in range(1000)) True rr9r/rabs)r;guessrs ruisqrtr#s6 Qwd CNN$) )Q .EcUl"q (F fun  !#,&1, fun  ! 6/C !  6/C  MrwcN|dkr| }|dkDrd|jdzz}|}||z}d|z}t||z |kDr6|dkDr1|dz}||kr||z }n||z}||z}t||z |kDr|dkDr1||z|kr|dz }||z|kr||z|kDr|dz}||z|kDr|S|S)a Compute the integer k-th root of a number. This is defined as the largest integer whose n-th power is smaller than the number, i.e. floor(num ** (1 / base)) Args: num (int): The input number. k (int): The order of the root. Must be k >= 1. When k == 1, the result is `num`. Returns: result (int): The integer k-th root of num. Examples: >>> iroot(64, 3) 4 >>> iroot(63, 3) 3 >>> iroot(65, 3) 4 >>> iroot(2 ** 300, 3) 1267650600228229401496703205376 >>> iroot(2 ** 300, 3) == 2 ** 100 True >>> all( ... iroot(2 ** (k * i), k) == 2 ** i ... for i in range(100) for k in range(2, 10)) True rr/r9r )r;r'rrr"limits ruirootr&sB Qwd1ucnn&!++! Q%#+&6A: qLFs{& & aKE %#+&6A:kC aKFkCkC aKFkC M rwcvd|cxkr|kstdtdttd|dzS)a Compute the number of ways to permuting n items into groups of size k. This is equivalent to the number of ways to choose k items from n items without repetition and with order. This is often indicated as `n_P_k` or `P(n, k)`. n! / (n - k)! Args: n (int): The number of items. Must be non-negative. k (int): The group size. Must be non-negative and smaller than or equal to `n`. Returns: result (int): The number of k-permutation of n items. Raises: ValueError: if the inputs are invalid. Examples: >>> perm(10, 5) 30240 >>> [perm(8, i) for i in range(8 + 1)] [1, 8, 56, 336, 1680, 6720, 20160, 40320, 40320] >>> [perm(9, i) for i in range(9 + 1)] [1, 9, 72, 504, 3024, 15120, 60480, 181440, 362880, 362880] >>> perm(0, 0) 1 >>> perm(1, 0) 1 >>> perm(0, 1) Traceback (most recent call last): ... ValueError: Values must be non-negative and n >= k in perm(n, k) >>> all(perm(n, n) == math.factorial(n) for n in range(20)) True References: - https://en.wikipedia.org/wiki/Permutation rz4Values must be non-negative and n >= k in perm(n, k)r/r"rr{r2r's rupermr*sPX ;Q; BD D  BD DE!QUO$$rwcR|dkr tdttd|dzS)a6 Compute the factorial of a number `n!`. n! = n * (n - 1) * ... * 1 Args: n (int): The input number. Must be non-negative. Returns: result (int): The number of k-permutation of n items. Raises: ValueError: if the inputs are invalid. Examples: >>> factorial(5) 120 >>> [factorial(i) for i in range(12)] [1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800, 39916800] >>> factorial(0) 1 >>> factorial(1) 1 >>> factorial(-1) Traceback (most recent call last): ... ValueError: Value must be non-negative >>> all(factorial(n) == math.factorial(n) for n in range(20)) True References: - https://en.wikipedia.org/wiki/Factorial rzValue must be non-negativer/r()r2s ru factorialr,<s-F 1u566E!QUO$$rwcd|cxkr|ksnttd|||z kr|n||z }tt||z dz|dzt j |zS)a Compute the number of ways to combining n items into groups of size k. This is essentially binomial coefficient of order n and position k. This is equivalent to the number of ways to choose k items from n items without repetition and without order. This is often indicated as `(n k)`, `n_C_k` or `C(n, k)`. If more than one binomial coefficient of the same order are needed, then `flyingcircus.get_binomial_coeffs()` may be more efficient. Args: n (int): The number of items. Must be non-negative. k (int): The group size. Must be non-negative and smaller than or equal to `n`. Returns: result (int): The number of k-combinations of n items. Raises: ValueError: if the inputs are invalid. Examples: >>> comb(10, 5) 252 >>> [comb(10, i) for i in range(10 + 1)] [1, 10, 45, 120, 210, 252, 210, 120, 45, 10, 1] >>> [comb(11, i) for i in range(11 + 1)] [1, 11, 55, 165, 330, 462, 462, 330, 165, 55, 11, 1] >>> N = 10 >>> for n in range(N): ... print([comb(n, k) for k in range(n + 1)]) [1] [1, 1] [1, 2, 1] [1, 3, 3, 1] [1, 4, 6, 4, 1] [1, 5, 10, 10, 5, 1] [1, 6, 15, 20, 15, 6, 1] [1, 7, 21, 35, 35, 21, 7, 1] [1, 8, 28, 56, 70, 56, 28, 8, 1] [1, 9, 36, 84, 126, 126, 84, 36, 9, 1] >>> comb(0, 0) 1 >>> comb(1, 1) 1 >>> comb(1, 0) 1 >>> comb(0, 1) Traceback (most recent call last): ... ValueError: Values must be non-negative and n=0 >= k=1 >>> comb(1, 2) Traceback (most recent call last): ... ValueError: Values must be non-negative and n=1 >= k=2 >>> comb(2, 1) 2 >>> all(comb(n, k) * math.factorial(k) == perm(n, k) ... for n in range(20) for k in range(n)) True See Also: - flyingcircus.get_binomial_coeffs() - flyingcircus.binomial_triangle_range() References: - https://en.wikipedia.org/wiki/Combination - https://en.wikipedia.org/wiki/Binomial_coefficient - https://en.wikipedia.org/wiki/Binomial_triangle rz.Values must be non-negative and n={n} >= k={k}r/)r"rrr{rdr,r)s rucombr.fsmX ;Q; A BD DQUAAE!a%!)QU+,q0AAArwc#Kd}|r|s|dzn|dzdz}|r=|r;tt|dd}|D]}|||dzrdndddD]}|yt|D]}||||z z|dzz}yw)a- Generate the numbers of a given row of the binomial triangle. This is also known as Pascal's triangle. These are the numbers in the `num`-th row (order) of the binomial triangle. If only a specific binomial coefficient is required, use `flyingcircus.comb()`. Args: num (int): The row index of the triangle. Indexing starts from 0. full (bool): Compute all numbers of the row. If True, all numbers are yielded. Otherwise, it only yields non-repeated numbers (exploiting the fact that they are palindromes). cached (bool): Cache the non-repeated numbers. If True and `full == True`, the non-repeated numbers are cached (thus allocating some additional temporary memory). Otherwise, if False or `full == False` this has no effect, i.e. the numbers are computed directly. Yields: value (int): The next binomial coefficient of a given order / row. Examples: >>> list(get_binomial_coeffs(12)) [1, 12, 66, 220, 495, 792, 924, 792, 495, 220, 66, 12, 1] >>> list(get_binomial_coeffs(13)) [1, 13, 78, 286, 715, 1287, 1716, 1716, 1287, 715, 286, 78, 13, 1] >>> list(get_binomial_coeffs(12, cached=True)) [1, 12, 66, 220, 495, 792, 924, 792, 495, 220, 66, 12, 1] >>> list(get_binomial_coeffs(13, cached=True)) [1, 13, 78, 286, 715, 1287, 1716, 1716, 1287, 715, 286, 78, 13, 1] >>> list(get_binomial_coeffs(12, full=False)) [1, 12, 66, 220, 495, 792, 924] >>> list(get_binomial_coeffs(13, full=False)) [1, 13, 78, 286, 715, 1287, 1716] >>> num = 10 >>> for n in range(num): ... print(list(get_binomial_coeffs(n))) [1] [1, 1] [1, 2, 1] [1, 3, 3, 1] [1, 4, 6, 4, 1] [1, 5, 10, 10, 5, 1] [1, 6, 15, 20, 15, 6, 1] [1, 7, 21, 35, 35, 21, 7, 1] [1, 8, 28, 56, 70, 56, 28, 8, 1] [1, 9, 36, 84, 126, 126, 84, 36, 9, 1] >>> all(list(get_binomial_coeffs(n)) ... == list(get_binomial_coeffs(n, cached=True)) ... for n in range(10)) True >>> all(list(get_binomial_coeffs(n)) ... == [comb(n, k) for k in range(n + 1)] ... for n in range(10)) True See Also: - flyingcircus.comb() - flyingcircus.binomial_triangle_range() References: - https://en.wikipedia.org/wiki/Binomial_coefficient - https://en.wikipedia.org/wiki/Binomial_triangle r/r9F)fullcachedr<r=N)rget_binomial_coeffsr{)r;r0r1r[rcacherMs rur2r2sP EVC!G#(Q,D (5GH EK #'Br6B67 EK t 1AKS1W%!a%0E 1sA6A8c#HKd}||k7r||||z}}|dz }||k7ryyw)aQ Generate the first Fibonacci-like numbers. The next number is computed by adding the last two. This is useful for generating a sequence of Fibonacci numbers. To generate a specific Fibonacci number, use `flyingcircus.fibonacci()`. Args: max_count (int): The maximum number of values to yield. If `max_count == -1`, the generation proceeds indefinitely. first (int): The first number of the sequence. second (int): The second number of the sequence. Yields: value (int): The next Fibonacci number. Examples: >>> [x for x in get_fibonacci(16)] [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610] >>> [x for x in get_fibonacci(16, 0, 2)] [0, 2, 2, 4, 6, 10, 16, 26, 42, 68, 110, 178, 288, 466, 754, 1220] >>> [x for x in get_fibonacci(16, 3, 1)] [3, 1, 4, 5, 9, 14, 23, 37, 60, 97, 157, 254, 411, 665, 1076, 1741] See Also: - flyingcircus.get_gen_fibonacci() - flyingcircus.fibonacci() - https://en.wikipedia.org/wiki/Fibonacci_number rr/Nr) max_countrfr|rMs ru get_fibonaccir6!s9F A y. v Q y.s""rr/c#Kt||f}t||d}t||d}d}||k7r6|d|ddtdt||Dfz}|dz }||k7r5yyw)a Generate the first generalized Fibonacci-like numbers. The next number is computed as a linear combination of the last values multiplied by their respective weights. These can be used to compute n-step Fibonacci, Lucas numbers, Pell numbers, Perrin numbers, etc. Args: max_count (int): The maximum number of values to yield. If `max_count == -1`, the generation proceeds indefinitely. values (int|Sequence[int]): The initial numbers of the sequence. If int, the value is repeated for the number of `weights`, and `weights` must be a sequence. weights (int|Sequence[int]): The weights for the linear combination. If int, the value is repeated for the number of `values`, and `values` must be a sequence. Yields: value (int): The next number of the sequence. Examples: >>> [x for x in get_gen_fibonacci(16)] [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610] >>> [x for x in get_gen_fibonacci(16, (1, 1, 1))] [1, 1, 1, 3, 5, 9, 17, 31, 57, 105, 193, 355, 653, 1201, 2209, 4063] >>> [x for x in get_gen_fibonacci(16, (1, 0, 1))] [1, 0, 1, 2, 3, 6, 11, 20, 37, 68, 125, 230, 423, 778, 1431, 2632] >>> [x for x in get_gen_fibonacci(13, (0, 1), 2)] [0, 1, 2, 6, 16, 44, 120, 328, 896, 2448, 6688, 18272, 49920] >>> [x for x in get_gen_fibonacci(16, (1, 0, 1), (1, 2, 1))] [1, 0, 1, 2, 4, 9, 19, 41, 88, 189, 406, 872, 1873, 4023, 8641, 18560] See Also: - flyingcircus.get_fibonacci() - flyingcircus.fibonacci() - https://en.wikipedia.org/wiki/Fibonacci_number T)rUrr/Nc3,K|] \}}||zywrr)rwrHs rurz$get_gen_fibonacci..}s"JTQ1q5"Jr)r>rrVr)r5rZweightsr;rMs ruget_gen_fibonaccir<LsV FG, -C D 1F'3d3G A y.Qis"JS&5I"JJLL Q y.s A%A*(A*c4t|D] }|||z}} |S)a] Generate the n-th Fibonacci number. This is useful for generating a specific Fibonacci number. For generating a sequence of Fibonacci numbers, use `flyingcircus.get_fibonacci()`. Args: num (int): The ordinal to generate. Starts counting from 0. If `num < 0`, the first number is returned. first (int): The first number of the sequence. second (int): The second number of the sequence. Returns: value (int): The Fibonacci number. Examples: >>> fibonacci(10) 55 >>> fibonacci(100) 354224848179261915075 >>> fibonacci(200) 280571172992510140037611932413038677189525 >>> fibonacci(300) 222232244629420445529739893461909967206666939096499764990979600 >>> fibonacci(0) 0 >>> fibonacci(1) 1 >>> fibonacci(15, 0, 2) 1220 >>> fibonacci(15, 3, 1) 1741 See Also: - flyingcircus.get_fibonacci() - flyingcircus.get_gen_fibonacci() - https://en.wikipedia.org/wiki/Fibonacci_number rz)r;rfr|rs ru fibonaccir>s*X3Z/v/ Lrwc#K|d|}}n||}}|s ||krdnd}t|||D]}|t|yw)aU Generate the binomial triangle rows in a given range. This is also known as Pascal's triangle. See `flyingcircus.get_binomial_coeffs()` for generating any given row of the triangle. Args: first (int): The first value of the range. Must be non-negative. If `second == None` this is the `stop` value, and is not included. Otherwise, this is the `start` value and is included. If `first < second` the sequence is yielded backwards. second (int|None): The second value of the range. If None, the start value is 0. Otherwise, this is the `stop` value and is not included. Must be non-negative. If `first < second` the sequence is yielded backwards. step (int): The step of the rows range. If the sequence is yielded backward, the step should be negative, otherwise an empty sequence is yielded. If None, this is computed automatically based on `first` and `second`, such that a non-empty sequence is avoided, if possible. container (callable): The row container. This should be a Sequence constructor. Yields: row (Sequence[int]): The rows of the binomial triangle. Examples: >>> tuple(binomial_triangle(5)) ((1,), (1, 1), (1, 2, 1), (1, 3, 3, 1), (1, 4, 6, 4, 1)) >>> tuple(binomial_triangle(5, 7)) ((1, 5, 10, 10, 5, 1), (1, 6, 15, 20, 15, 6, 1)) >>> tuple(binomial_triangle(7, 9)) ((1, 7, 21, 35, 35, 21, 7, 1), (1, 8, 28, 56, 70, 56, 28, 8, 1)) >>> tuple(binomial_triangle(5, 2)) ((1, 5, 10, 10, 5, 1), (1, 4, 6, 4, 1), (1, 3, 3, 1)) >>> tuple(binomial_triangle(0, 7, 2)) ((1,), (1, 2, 1), (1, 4, 6, 4, 1), (1, 6, 15, 20, 15, 6, 1)) >>> tuple(binomial_triangle(0, 6, 2)) ((1,), (1, 2, 1), (1, 4, 6, 4, 1)) >>> tuple(binomial_triangle(7, 1, -2)) ((1, 7, 21, 35, 35, 21, 7, 1), (1, 5, 10, 10, 5, 1), (1, 3, 3, 1)) >>> tuple(binomial_triangle(7, 1, 2)) # empty range! () >>> list(binomial_triangle(3)) [(1,), (1, 1), (1, 2, 1)] >>> list(binomial_triangle(5, container=list)) [[1], [1, 1], [1, 2, 1], [1, 3, 3, 1], [1, 4, 6, 4, 1]] >>> for row in binomial_triangle(10): ... print(row) (1,) (1, 1) (1, 2, 1) (1, 3, 3, 1) (1, 4, 6, 4, 1) (1, 5, 10, 10, 5, 1) (1, 6, 15, 20, 15, 6, 1) (1, 7, 21, 35, 35, 21, 7, 1) (1, 8, 28, 56, 70, 56, 28, 8, 1) (1, 9, 36, 84, 126, 126, 84, 36, 9, 1) See Also: - flyingcircus.comb() - flyingcircus.get_binomial_coeffs() References - https://en.wikipedia.org/wiki/Binomial_coefficient - https://en.wikipedia.org/wiki/Binomial_triangle Nrr/r<)r{r2)rfr|r}rr~rrMs rubinomial_triangler@sYZ~tVt DLqb 5$ %0+A.//0s=?cz|dzs|dkDs |dzs|dkDryd}||z|kr||zr||dzzsy|dz }||z|kry)a Determine if a number is prime. A prime number is only divisible by 1 and itself. 0 and 1 are considered special cases; in this implementations they are considered primes. It is implemented by testing for possible factors using wheel increment. Args: num (int): The number to check for primality. Must be greater than 1. Returns: result (bool): The result of the primality. Examples: >>> _is_prime(100) False >>> _is_prime(101) True >>> _is_prime(0) True >>> all(is_prime(n) for n in (-2, -1, 0, 1, 2)) True See Also: - flyingcircus.is_prime() - flyingcircus.primes_range() References: - https://en.wikipedia.org/wiki/Prime_number - https://en.wikipedia.org/wiki/Trial_division - https://en.wikipedia.org/wiki/Wheel_factorization r9r&FTr)r;rMs ru _is_primerD s`J1W#'C!Gq A a%3,aC1q5M FA a%3, rw)r9c#8K|]}t|s|ywr)rDrr2s rurr=s9 9Q 2 ** 81. Args: num (int): The number to test for primality. Only works for numbers larger than 1. small_primes (Sequence|None): The first prime numbers (sorted). Must contain prime starting from 2 (included). Must be in increasing order. If None, uses a hard-coded sequence and skip fast hashed checks. hashed_small_primes (Container|None): The first prime numbers. Must contain prime starting from 2 (included). Should use a high performance container like `set` or `frozenset`. Must contain the same numbers included in `small_primes`. If None, skip fast hashed checks. Returns: result (bool): The result of the primality test. Examples: >>> is_prime(100) False >>> is_prime(101) True >>> is_prime(-100) False >>> is_prime(-101) True >>> is_prime(2 ** 17) False >>> is_prime(17 * 19) False >>> is_prime(2 ** 17 - 1) True >>> is_prime(2 ** 31 - 1) True >>> is_prime(2 ** 17 - 1, (2,)) True >>> is_prime(2 ** 17 - 1, (2, 3)) True >>> is_prime(2 ** 17 - 1, (2, 3, 5)) True >>> all(is_prime(n) for n in (-2, -1, 0, 1, 2)) True See Also: - flyingcircus.is_prime() - flyingcircus.is_pseudo_prime() - flyingcircus.primes_range() References: - https://en.wikipedia.org/wiki/Prime_number - https://en.wikipedia.org/wiki/Trial_division - https://en.wikipedia.org/wiki/Wheel_factorization - https://en.wikipedia.org/wiki/Miller–Rabin_primality_test r) r9r&rB %+NTr<FrBr/rCr9) iql}Bl;n>lp lHe%Z Nly5D(NNl7 y_@I7l%!Hn fWr&)rrr get_primesis_pseudo_prime) r; small_primeshashed_small_primesprimerMlimits num_basesr%basess ruis_primer\Bs;N Qwd E " \!_ R %8))) ! E;$   b!A%!+a/ /!esl7#Q-Q !esl ANN$) !&) HAuuE  j+,sE**rwc|dkr| }|dkry|dzsy|s*tdt|dz |jdz}|dz |dz zjdz }||z }|D]f}||k\r||z}|dk\st|||}|dk7s&||dz k7s/d}td|D]#}t|d|}||dz k(rd}n |dk(s"y|rfyy)u Determine if a number is pseudo-prime (using the Miller-Rabin test). Args: num (int): The number to test for primality. bases (Iterable[int]|None): The bases for the test. If None, uses the theoretical values for which the test is proven to be deterministic, if the extended Riemann hypothesis is True: bases = range(2, min(n-2, log2(n) ** 2) Returns: result (bool): The result of the pseudo-primality test. Examples: >>> is_pseudo_prime(100, (2,)) False >>> is_pseudo_prime(101, (2,)) True >>> is_pseudo_prime(-100, (2,)) False >>> is_pseudo_prime(-101, (2,)) True >>> is_pseudo_prime(2 ** 17, (2,)) False >>> is_pseudo_prime(17 * 19, (2,)) False >>> is_pseudo_prime(2 ** 17 - 1, (2,)) True >>> is_pseudo_prime(2 ** 31 - 1, (2,)) True >>> is_pseudo_prime(2 ** 17 - 1, (2,)) True >>> is_pseudo_prime(2 ** 17 - 1, (2, 3)) True >>> is_pseudo_prime(2 ** 17 - 1, (2, 3, 5)) True >>> all(is_pseudo_prime(n) for n in (-2, -1, 0, 1, 2)) True >>> is_pseudo_prime(2047, (2,)) True >>> is_prime(2047) False See Also: - flyingcircus.is_prime() - flyingcircus.is_pseudo_prime() - flyingcircus.primes_range() References: - https://en.wikipedia.org/wiki/Prime_number - https://en.wikipedia.org/wiki/Trial_division - https://en.wikipedia.org/wiki/Wheel_factorization - https://en.wikipedia.org/wiki/Miller–Rabin_primality_test rr&Tr9Fr/)r{rrpow)r;r[rr>baserHrJrs rurUrUsr Qwd Qw 1W aS1Wcnn&6!&;<= 'sQwZ ++-1A qA! 3; CKD 19D!S!AAv!sQw,q!%AAq#AC!G|#Av$% #!$ rwc#Kd}|dkrttd|sd}||dkr|D]}||k\s ||dz }||k(ry|}dkrOd|dz d zd zz} t|r||dz }||k(ryt|dzr|dz|dz }||k(ry|d z }@t|kDrt t dn|dt }t fd td|dzD}t t||d|zfz} t| } |d|dz |z|zz}d} ||k7r2||k\rt|r ||dz }|| | z }| dz } | | z} ||k7r1yyw) aH Generate the next prime numbers. New possible primes are obtained using a hard-coded (2, 3) wheel. Args: max_count (int): The maximum number of values to yield. If `max_count == -1`, the generation proceeds indefinitely. start (int): The initial value. This must be positive. small_primes (Sequence|None): The first prime numbers (sorted). Must contains prime starting from 2 (included). Must be in increasing order. If None, uses a hard-coded sequence. wheel (int): The number of primes to use as wheel. Must be > 1. The wheel is generated using `flyingcircus.get_primes()`. Yields: num (int): The next prime number. Examples: >>> n = 15 >>> primes = get_primes() >>> [next(primes) for i in range(n)] [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47] >>> list(get_primes(n)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47] >>> list(get_primes(10, 101)) [101, 103, 107, 109, 113, 127, 131, 137, 139, 149] >>> list(get_primes(10, 1000)) [1009, 1013, 1019, 1021, 1031, 1033, 1039, 1049, 1051, 1061] >>> list(get_primes(n, 2, None)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47] >>> list(get_primes(10, 101, None)) [101, 103, 107, 109, 113, 127, 131, 137, 139, 149] >>> list(get_primes(10, 1000, None)) [1009, 1013, 1019, 1021, 1031, 1033, 1039, 1049, 1051, 1061] >>> list(get_primes(n, 2, None, 3)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47] >>> list(get_primes(10, 101, None, 3)) [101, 103, 107, 109, 113, 127, 131, 137, 139, 149] >>> list(get_primes(10, 1000, None, 3)) [1009, 1013, 1019, 1021, 1031, 1033, 1039, 1049, 1051, 1061] See Also: - flyingcircus.is_prime() - flyingcircus.primes_range() References: - https://en.wikipedia.org/wiki/Prime_number - https://en.wikipedia.org/wiki/Wheel_factorization r:`get_primes()` must start at a positive value, not `{num}`r9r&rBrIrJrKrLrMrNrOrPrQ)rR/r<r/Nr9rBrCc3LK|]tfdDryw)c3PK|]}tj|dk(ywrrdgcdrr'r2s rurz'get_primes...i 61488Aq>Q&6#&Nrrr2wheels @rurzget_primes..g'8666 8 $) r"rr\rrrTrr{r) r5r~rVrnrMrXr; prod_wheelcoprimesdeltas len_deltasrs ` rurTrTsx A qy M NP P M  |B! "E~ Q >!E " z519"Q&&} Q >a Ag Q > 1HC 3|$ $*UA./E %(E%[ 8Q Q/88tH j(@'BBCD[ qkUQY:5 BB 9ne|  Q 6!9 C FA OA 9ns2E'D.E'%E'c#^Kd}|dkrttd|sd}dkr`d|dz dzdzz}||dkDr9t|r||dz }||k(ry t|d z r|d z |dz }||k(ry |dz}||dkDrHnt|kDrt t dn|d t }t fd t|dzddD}t t||d|z fz}t|} |d|dz |z|zz}d} ||kDr||| z }| dz } | | z} ||kDr||dkDr9||k7r4t|r ||dz }||| z }| dz } | | z} ||dkDr||k7r4||k7r/t|D] } | |ks | |ks| |dz }||k(ry | }"y y w) a Generate the previous prime numbers. New possible primes are obtained using a hard-coded (2, 3) wheel. Args: max_count (int): The maximum number of values to yield. If equal to -1 or larger than the number of primes smaller than or equal to `start`, the generation proceeds until the smallest proper prime number (2) is yielded. start (int): The initial value. This must be positive. small_primes (Sequence|None): The first prime numbers (sorted). Must contains prime starting from 2 (included). Must be in increasing order. If None, uses a hard-coded sequence. wheel (int): The number of primes to use as wheel. Must be > 1. The wheel is generated using `flyingcircus.get_primes()`. Yields: num (int): The next prime number. Examples: >>> n = 15 >>> primes = get_primes_r(-1, 47) >>> [next(primes) for i in range(n)] [47, 43, 41, 37, 31, 29, 23, 19, 17, 13, 11, 7, 5, 3, 2] >>> list(get_primes_r(n, 47)) [47, 43, 41, 37, 31, 29, 23, 19, 17, 13, 11, 7, 5, 3, 2] >>> list(get_primes_r(10, 150)) [149, 139, 137, 131, 127, 113, 109, 107, 103, 101] >>> list(get_primes_r(10, 1062)) [1061, 1051, 1049, 1039, 1033, 1031, 1021, 1019, 1013, 1009] >>> list(get_primes_r(10, 10)) [7, 5, 3, 2] >>> list(get_primes_r(n, 47, None)) [47, 43, 41, 37, 31, 29, 23, 19, 17, 13, 11, 7, 5, 3, 2] >>> list(get_primes_r(10, 150, None)) [149, 139, 137, 131, 127, 113, 109, 107, 103, 101] >>> list(get_primes_r(10, 1062, None)) [1061, 1051, 1049, 1039, 1033, 1031, 1021, 1019, 1013, 1009] >>> list(get_primes_r(10, 10, None)) [7, 5, 3, 2] >>> list(get_primes_r(n, 47, None, 3)) [47, 43, 41, 37, 31, 29, 23, 19, 17, 13, 11, 7, 5, 3, 2] >>> list(get_primes_r(10, 150, None, 3)) [149, 139, 137, 131, 127, 113, 109, 107, 103, 101] >>> list(get_primes_r(10, 1062, None, 3)) [1061, 1051, 1049, 1039, 1033, 1031, 1021, 1019, 1013, 1009] >>> list(get_primes_r(10, 10, None, 3)) [7, 5, 3, 2] See Also: - flyingcircus.is_prime() - flyingcircus.primes_range() References: - https://en.wikipedia.org/wiki/Prime_number - https://en.wikipedia.org/wiki/Wheel_factorization rrarbr9rBr/rCr<Nrbc3LK|]tfdDryw)c3PK|]}tj|dk(ywrrgris rurz)get_primes_r...rjrkNrlrms @rurzget_primes_r..rorp) r"rr\rrrTrr{rr) r5r~rVrnrMr;rqrrrsrtrrXs ` ru get_primes_rrxxsAH A qy M NP P M  z519"Q&&L$$} Q >a Ag Q > 1HCL$$ 3|$ $*UA./E %(E%[ 8Z!^Q388tH j(@'BBCD[ qkUQY:5 BB Ek 6!9 C FA OAEkL$$i} Q 6!9 C FA OA L$$i I~l+ "E~%3, Q >!E "s&BF-B/F-7AF-8F-F-F-c#K|d|}}n||}}||krtd|D] }||kr| yytd|D] }||kDr| yyw)a? Compute the prime numbers in the range. Args: first (int): The first value of the range. If `second == None` this is the `stop` value, and is not included. Otherwise, this is the start value and can be included (if it is a prime number). If `first < second` the sequence is yielded backwards. second (int|None): The second value of the range. If None, the start value is 2. If `first < second` the sequence is yielded backwards. Yields: num (int): The next prime number. Examples: >>> list(primes_range(50)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47] >>> list(primes_range(51, 100)) [53, 59, 61, 67, 71, 73, 79, 83, 89, 97] >>> list(primes_range(101, 150)) [101, 103, 107, 109, 113, 127, 131, 137, 139, 149] >>> list(primes_range(151, 200)) [151, 157, 163, 167, 173, 179, 181, 191, 193, 197, 199] >>> list(primes_range(1000, 1050)) [1009, 1013, 1019, 1021, 1031, 1033, 1039, 1049] >>> list(primes_range(1050, 1000)) [1049, 1039, 1033, 1031, 1021, 1019, 1013, 1009] >>> list(primes_range(1, 50)) [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47] >>> list(primes_range(50, 1)) [47, 43, 41, 37, 31, 29, 23, 19, 17, 13, 11, 7, 5, 3, 2] See Also: - flyingcircus.is_prime() - flyingcircus.get_primes() - https://en.wikipedia.org/wiki/Prime_number - https://en.wikipedia.org/wiki/Wheel_factorization Nr9r<)rTrx)rfr|r~rrXs ru primes_rangerzssV~tVt }E* Et|    ""e, Et|   sA A c#Kt|tstt|}|dk(rdy|dkrd| }n |dk(r||sd}|D]}||zr |||z}||zst|kDrt t dn|dD]}||zr |||z}||zst }t fdtd|dzD}t t||d|zfz}t|}d}|ddz |z|zz} | | z|kr/|| zs| || z}|| zs| ||z } |dz }||z}| | z|kr/|dkDr|yyw)a Find all factors of a number. It is implemented by testing for possible factors using wheel increment. This is not suitable for large numbers. Args: num (int|float): The number to factorize. If float, its nearest integer is factorized. small_primes (Sequence|None): The first prime numbers (sorted). Must contains prime starting from 2 (included). Must be in increasing order. If None, uses a hard-coded sequence. wheel (int): The number of primes to use as wheel. Must be > 1. The wheel is generated using `flyingcircus.get_primes()`. Yields: factor (int): The next factor of the number. Factors are yielded in increasing order. Examples: >>> list(get_factors(100)) [2, 2, 5, 5] >>> list(get_factors(1234567890)) [2, 3, 3, 5, 3607, 3803] >>> list(get_factors(-65536)) [-1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2] >>> list(get_factors(0)) [0] >>> list(get_factors(1)) [1] >>> list(get_factors(-1)) [-1] >>> list(get_factors(987654321.0)) [3, 3, 17, 17, 379721] >>> all(n == prod(get_factors(n)) for n in range(1000)) True See Also: - flyingcircus.is_prime() - flyingcircus.primes_range() - flyingcircus.get_primes() References: - https://en.wikipedia.org/wiki/Trial_division - https://en.wikipedia.org/wiki/Wheel_factorization rNr<r/rbr9c3LK|]tfdDryw)c3PK|]}tj|dk(ywrrgris rurz(get_factors...s 2qtxx1~"2rkNrlrms @rurzget_factors..s'4 2E2 2 4rp) rrYrgrrrTrr{r) r;rVrnrXrqrrrsrtrr's ` ru get_factorsr~2sl c3 %*o ax Qwd  M ;K EMC;  s<  j*+Ve$;K EMC;eJ4JN+44H4HQK*$<#>>? @FVJ A uqyZ/*<tjt|S)a Find all factors of a number and collect them in an ordered dict. Args: num (int): The number to factorize. Returns: factors (collections.Counter): The factors of the number. Examples: >>> sorted(get_factors_as_dict(100).items()) [(2, 2), (5, 2)] >>> sorted(get_factors_as_dict(1234567890).items()) [(2, 1), (3, 2), (5, 1), (3607, 1), (3803, 1)] >>> sorted(get_factors_as_dict(65536).items()) [(2, 16)] )rCounterr~rs ruget_factors_as_dictrs$   {3/ 00rwr3c t|tr<|j}|dk(rd\}}n&|dk(rd\}}n|dk(rd\}}n|dk(r d\}}n|\}}d }d }d }t|D]c}||k(r|d z }|d kDr5r||t|zz }n!|t|j t z }|d kDr|z }|t|z }|}d }e|d kDr6r||t|zz }|S|t|j t z }|S) u Find all factors of a number and output a human-readable text. Args: num (int): The number to factorize. mode (str|Iterable[str|None]): The formatting mode. If str, available options: - `ascii`: uses `^` for power, and ` * ` for multiplication. - `py`: uses ` ** ` for power, and ` * ` for multiplication. - `sup`: uses superscript for power, and ` ` for multiplication. - `utf8`: uses superscript for power, and `×` for multiplication. If Iterable of str or None, must have length 2: - the first is used as exponent symbol if str, otherwise if None, uses superscript notation. - the second is used as multiplication symbol (requires str). Returns: text (str): The factors of the number. Examples: >>> get_factors_as_str(100, 'ascii') '2^2 * 5^2' >>> get_factors_as_str(1234567890, 'ascii') '2 * 3^2 * 5 * 3607 * 3803' >>> get_factors_as_str(65536, 'ascii') '2^16' >>> get_factors_as_str(100, 'py') '2 ** 2 * 5 ** 2' >>> get_factors_as_str(1234567890, 'py') '2 * 3 ** 2 * 5 * 3607 * 3803' >>> get_factors_as_str(65536, 'py') '2 ** 16' >>> get_factors_as_str(100, 'utf8') '2²×5²' >>> get_factors_as_str(1234567890, 'utf8') '2×3²×5×3607×3803' >>> get_factors_as_str(65536, 'utf8') '2¹⁶' >>> get_factors_as_str(100, 'sup') '2² 5²' >>> get_factors_as_str(1234567890, 'sup') '2 3² 5 3607 3803' >>> get_factors_as_str(65536, 'sup') '2¹⁶' >>> get_factors_as_str(100, tuple('^*')) '2^2*5^2' >>> get_factors_as_str(1234567890, tuple('^*')) '2*3^2*5*3607*3803' >>> get_factors_as_str(65536, tuple('^*')) '2^16' r3)^ * py)z ** rsup)N utf8)N×r8r/r)rrar^r~ translateSUPERSCRIPT_MAP)r;rexp_sepfact_septext last_factorexpfactors ruget_factors_as_strrsAt$zz| 7? * GX T\ - GX U] ) GX V^ * GX  DK Cc"  [ 1HCQwGc#h..DCH..??DQ  CK D KC  Qw  Gc#h& &D K CH&&7 7D Krwc #.K|dvr|y|dkrd| }tttjt |j d\}}t jd|DD] }tdt||D"yw) a Find all divisors of a number. It is implemented by computing the possible unique combinations of the factors. This is not suitable for large numbers. Args: num (int|float): The number to factorize. If float, its nearest integer is factorized. Yields: factor (int): The next factor of the number. Factors are yielded in increasing order. Examples: >>> list(get_divisors(100)) [1, 2, 4, 5, 10, 20, 25, 50, 100] >>> list(get_divisors(-100)) [-1, 1, 2, 4, 5, 10, 20, 25, 50, 100] >>> list(get_divisors(2 ** 8)) [1, 2, 4, 8, 16, 32, 64, 128, 256] >>> list(get_divisors(12345)) [1, 3, 5, 15, 823, 2469, 4115, 12345] >>> list(get_divisors(0)) [0] >>> list(get_divisors(1)) [1] >>> list(get_divisors(2)) [1, 2] >>> list(get_divisors(101)) [1, 101] See Also: - flyingcircus.is_prime() - flyingcircus.primes_range() - flyingcircus.get_primes() - flyingcircus.get_factors() References: - https://en.wikipedia.org/wiki/Trial_division - https://en.wikipedia.org/wiki/Wheel_factorization r7Nrr<Tr"c38K|]}t|dzywrrzrFs rurzget_divisors..B s%JqeAEl%Jsc3,K|] \}}||zywrr)rrpowers rurzget_divisors..C sN -FeONr) rrlrrr~rrrr)r;unique_factors unique_powerspowerss ru get_divisorsr sZ f}  Qwd$'K,-335t*E%F!NM##%JM%JKNN14^V1LNN NNsBBcltt|}|d|t|z zz }t||Dcgc] }|D]}| }}}t t |}t t|D]}td||D||<ttt |||Scc}}w)a: Find all possible factorizations with k factors. Ones are not present, unless because there are not enough factors. Args: num (int): The number of elements to arrange. k (int): The number of factors. sort (callable): The sorting function. This is passed to the `key` arguments of `sorted()`. reverse (bool): The sorting direction. This is passed to the `reverse` arguments of `sorted()`. If False, sorting is ascending. Otherwise, sorting is descending. Returns: factorizations (tuple[tuple[int]]): The possible factorizations. Each factorization has exactly `k` items. Eventually, `1`s are used to ensure the number of items. Examples: >>> nums = (32, 41, 46, 60) >>> for i in nums: ... get_k_factors_all(i, 2) ((2, 16), (4, 8), (8, 4), (16, 2)) ((1, 41), (41, 1)) ((2, 23), (23, 2)) ((2, 30), (3, 20), (4, 15), (5, 12), (6, 10), (10, 6), (12, 5), (15, 4), (20, 3), (30, 2)) >>> for i in nums: ... get_k_factors_all(i, 3) ((2, 2, 8), (2, 4, 4), (2, 8, 2), (4, 2, 4), (4, 4, 2), (8, 2, 2)) ((1, 1, 41), (1, 41, 1), (41, 1, 1)) ((1, 2, 23), (1, 23, 2), (2, 1, 23), (2, 23, 1), (23, 1, 2), (23, 2, 1)) ((2, 2, 15), (2, 3, 10), (2, 5, 6), (2, 6, 5), (2, 10, 3), (2, 15, 2), (3, 2, 10), (3, 4, 5), (3, 5, 4), (3, 10, 2), (4, 3, 5), (4, 5, 3), (5, 2, 6), (5, 3, 4), (5, 4, 3), (5, 6, 2), (6, 2, 5), (6, 5, 2), (10, 2, 3), (10, 3, 2), (15, 2, 2)) r/c3JK|]}tjd|yw)c ||zSrrrs rurz-get_k_factors_all...~ !a%rwNrrrrs rurz$get_k_factors_all..} s%"P89I  / 3"P!#rr )rr~rrrrjr{rl) r;r'sortr factorssubitemsrfactorizationsrMs ruget_k_factors_allrH sZK$%G tq3w<'((G*'15    N#n-.N 3~& 'P!"P=KA=N"PPqP N+wG HHsB0c|dkDrtt|}t||kr!|jdg|t|z zd}|dvr t |}n(|dvrt |d}n|dk(r t |n|j dr8t|tdd}tj|t |n|j d r< t|td dt|dz z}||dd ddd ||dd <nm|d vritjd|Dcgc]}g}}t |dD]$} t |d}|d j| &t |td}|st!||d|}t#d|D} | S|f} | S#t$rd }YwxYwcc}w)a Generate a factorization of a number with k factors. Each factor contains (approximately) the same number of prime factors. Args: num (int): The number of elements to arrange. k (int): The number of factors. mode (str): The generation mode. This determines the factors order before splitting. The splitting itself is obtained with `chunks()`. Accepted values are: - 'increasing', 'ascending', '+': factors are sorted increasingly before splitting; - 'decreasing', 'descending', '-': factors are sorted decreasingly before splitting; - 'random': factors are shuffled before splitting; - 'seedX' where 'X' is an int, str or bytes: same as random, but 'X' is used to initialize the random seed; - 'altX' where 'X' is an int: starting from 'X', factors are alternated before splitting; - 'alt1': factors are alternated before splitting; - 'optimal', 'similar', '!', '=': factors have the similar sizes. balanced (bool): Balance the number of primes in each factor. See `flyingcircus.chunks()` for more info. Returns: tuple (int): A listing of `k` factors of `num`. Examples: >>> [get_k_factors(402653184, k) for k in range(3, 6)] [(1024, 768, 512), (192, 128, 128, 128), (64, 64, 64, 48, 32)] >>> [get_k_factors(402653184, k) for k in (2, 12)] [(24576, 16384), (8, 8, 8, 8, 6, 4, 4, 4, 4, 4, 4, 4)] >>> get_k_factors(6, 4) (3, 2, 1, 1) >>> get_k_factors(-12, 4) (3, 2, 2, -1) >>> get_k_factors(0, 4) (1, 1, 1, 0) >>> get_k_factors(720, 4) (6, 6, 5, 4) >>> get_k_factors(720, 4, '+') (4, 4, 9, 5) >>> get_k_factors(720, 3) (12, 10, 6) >>> get_k_factors(720, 3, '+') (8, 6, 15) >>> get_k_factors(720, 3, mode='-') (45, 4, 4) >>> get_k_factors(720, 3, mode='seed0') (18, 10, 4) >>> get_k_factors(720, 3, 'alt') (30, 4, 6) >>> get_k_factors(720, 3, 'alt1') (12, 6, 10) >>> get_k_factors(720, 3, '=') (12, 10, 6) r/N) increasing ascendingr]) decreasing descendingr_Tr"rseedaltrr9r<)optimalsimilar!=c8t|dkDr t|SdS)Nr)rrrs rurzget_k_factors.. sSVaZ$q'Qrwr/rr])rrhc3JK|]}tjd|yw)c ||zSrrrs rurz)get_k_factors... rrwNrrs rurz get_k_factors.. s%E89I  / 3Er)rr~rrrlrrs auto_convertrrrYr"rrepeatrrrmr) r;r'rrhrgroupsrrMrr factorizations ru get_k_factorsr s@ 1u{3'( w?$ADqDM$B$/GADqDM 5 5"+"2"24";>> n1, n2 = 40, 46 >>> [optimal_shape(i) for i in range(n1, n2)] [(8, 5), (41, 1), (7, 6), (43, 1), (11, 4), (9, 5)] >>> [optimal_shape(i, sort=max) for i in range(n1, n2)] [(5, 8), (1, 41), (6, 7), (1, 43), (4, 11), (5, 9)] >>> [optimal_shape(i, sort=min) for i in range(n1, n2)] [(2, 20), (1, 41), (2, 21), (1, 43), (2, 22), (3, 15)] >>> [optimal_shape(i, 3) for i in range(n1, n2)] [(5, 4, 2), (41, 1, 1), (7, 3, 2), (43, 1, 1), (11, 2, 2), (5, 3, 3)] rr)rrl)r;dimsrr rs ru optimal_shaper s%H'sD1N .dG >> _gcd(123, 45) 3 >>> _gcd(45, 123) 3 >>> _gcd(0, 1) 1 >>> _gcd(-3, 1) 1 >>> _gcd(211815584, 211815584) 211815584 Note: This should never be used as `math.gcd` offers identical functionality, but it is faster. rrs ru_gcdr!s. !a%1 Hrwc|t|}t|}|D] }tj||}|dk(s|S|S)a Find the greatest common divisor (GCD) of a list of numbers. Args: values (Iterable[int]): The input numbers. Returns: result (int): The value of the greatest common divisor (GCD). Examples: >>> gcd((12, 24, 18)) 6 >>> gcd((12, 24, 18, 42, 600, 66, 666, 768)) 6 >>> gcd((12, 24, 18, 42, 600, 66, 666, 768, 101)) 1 >>> gcd((12, 24, 18, 3)) 3 r/rrrdrh)rZ iter_valuesrr<s rurhrh1!sL(v,K + F&#& Q;  M  Mrwct|S)a Star magic version of `flyingcircus.gcd()`. Examples: >>> gcd_(12, 24, 18) 6 >>> gcd_(12, 24, 18, 42, 600, 66, 666, 768) 6 >>> gcd_(12, 24, 18, 42, 600, 66, 666, 768, 101) 1 >>> gcd_(12, 24, 18, 3) 3 )rhrZs rugcd_rO!s v;rwcxt|}t|}|D]}||tj||zz} |S)aa Find the least common multiple (LCM) of a list of numbers. Args: values (Iterable[int]): The input numbers. Returns: result (int): The value of the least common multiple (LCM). Examples: >>> lcm((2, 3, 4)) 12 >>> lcm((9, 8)) 72 >>> lcm((12, 23, 34, 45, 56)) 985320 r)rZrrr[s rulcmra!sE$v,K + F3%488FE2223 Mrwct|S)z Star magic version of `flyingcircus.lcm()`. Examples: >>> lcm_(2, 3, 4) 12 >>> lcm_(9, 8) 72 >>> lcm_(12, 23, 34, 45, 56) 985320 )r)rs rulcm_r{!s u:rwcrtj||}|r|s|dkr|r | |z| |zfS||z||zfSy)a" Simply a fraction. Args: a (int): The numerator. b (int): The denominator. sign (bool): Keep the sign in both the numerator and the denominator. If False, the sign is kept only in the numerator, unless the numerator is 0. Returns: result (tuple[int]): The tuple contains: - `a_n`: The simplified numerator. - `b_n`: The simplified denominator. Examples: >>> simplify_frac(12 * 7, 13 * 7) (12, 13) >>> simplify_frac(123, 321, True) (41, 107) >>> simplify_frac(123, -321, True) (41, -107) >>> simplify_frac(-123, 321, True) (-41, 107) >>> simplify_frac(-123, -321, True) (-41, -107) >>> simplify_frac(123, 321, False) (41, 107) >>> simplify_frac(123, -321, False) (-41, 107) >>> simplify_frac(-123, 321, False) (-41, 107) >>> simplify_frac(-123, -321, False) (41, 107) >>> simplify_frac(1234, 0) (1, 0) >>> simplify_frac(0, 1234) (0, 1) >>> simplify_frac(-1234, 0) (-1, 0) >>> simplify_frac(0, -1234) (0, -1) >>> simplify_frac(0, 0) (0, 0) >>> simplify_frac(-0, 0) (0, 0) r)rrrg)r5rIrrhs ru simplify_fracr!sOf ((1a.C Q129qbCi' '8Q#X% %rwc |P t|} t|}|dkr|dkr td|dkDr|dkDr t||}n t ||} |d|} |d|} t |} t |}d} d\} } t ||t|D]\} } }| | | zz| | z} } | | z} t| | S#t$rd}YwxYw#t$rd}YwxYw#t$rYwxYw#t$rYwxYw#t$rb t t |t|Dcgc]\}}| ncc}}wc}}}n%#t$rtj|g}YnwxYwYwxYw#t$rc t t |t|Dcgc]\}}| ncc}}wc}}}n%#t$rtj|g}YnwxYwY]wxYw)u Compute a fractional approximation of a continued fraction. The continued fraction is expressed in terms of the denominators and the numerators sequences: .. math:: \frac{a}{b} = b_0 + \frac{a_1}{b_1 +} \frac{a_2}{b_2 +} \ldots Args: b (int|Iterable[int]): Generalized continued fraction denominators. This should include also the first integer. The first `limit` values are used. All but the first value must be positive. a (int|Iterable[int]): Generalized continued fraction numerators. The first value does not contribute to `a_n / b_n` and can safely be set to 1. All values must be positive. limit (int|None): Maximum number of iterations to produce. Returns: result (tuple[int]): The tuple contains: - `a_n`: The numerator at the specified iteration level. - `b_n`: The denominator at the specified iteration level. Examples: >>> num, den = cont_frac([1, 2]) >>> print(num, den, round(num / den, 8)) 3 2 1.5 >>> num, den = cont_frac([0, 1, 5, 2, 2]) >>> print(num, den, round(num / den, 8)) 27 32 0.84375 >>> num, den = cont_frac([2, 2, 2], [1, 2, 2]) >>> print(num, den, round(num / den, 8)) 8 3 2.66666667 >>> num, den = cont_frac([2, 2, 2, 2], [1, 2, 2, 2]) >>> print(num, den, round(num / den, 8)) 11 4 2.75 >>> num, den = cont_frac([1, 2, 3, 4], [1, 2, 3, 4]) >>> print(num, den, round(num / den, 8)) 19 11 1.72727273 >>> num, den = cont_frac(range(1, 10), range(1, 20), 4) >>> print(num, den, round(num / den, 8)) 19 11 1.72727273 >>> num, den = cont_frac(2, 2, 3) >>> print(num, den, round(num / den, 8)) 8 3 2.66666667 >>> num, den = cont_frac([1, 2, 3, 4], 2) >>> print(num, den, round(num / den, 8)) 16 9 1.77777778 >>> num, den = cont_frac(2, [1, 2, 3, 4]) >>> print(num, den, round(num / den, 8)) 30 11 2.72727273 >>> num, den = cont_frac(2, [12, 2, 3, 4]) >>> print(num, den, round(num / den, 8)) 30 11 2.72727273 Computing √2 >>> n = 12 >>> b = [1] + [2] * (n - 1) >>> num, den = cont_frac(b) >>> print(num, den, round(num / den, 8)) 19601 13860 1.41421356 Computing Archimede's constant π >>> num, den = cont_frac([3, 7, 15, 1, 292, 1, 1, 1, 2, 1, 3, 1]) >>> print(num, den, round(num / den, 8)) 5419351 1725033 3.14159265 >>> n = 16 >>> b = [0] + [(2 * i + 1) for i in range(n - 1)] >>> a = [1, 4] + [(i + 1) ** 2 for i in range(n - 2)] >>> num, den = cont_frac(b, a) >>> print(num, den, round(num / den, 8)) 10392576224 3308059755 3.14159265 >>> n = 16 >>> b = [3] + [6] * (n - 1) >>> a = [1] + [(2 * i + 1) ** 2 for i in range(n - 1)] >>> num, den = cont_frac(b, a) >>> print(num, den, round(num / den, 8)) 226832956041173 72201776446800 3.14165339 >>> n = 16 >>> b = [0, 1] + [2] * (n - 2) >>> a = [1, 4] + [(2 * i + 1) ** 2 for i in range(n - 2)] >>> num, den = cont_frac(b, a) >>> print(num, den, round(num / den, 8)) 467009482388 145568097675 3.20818565 Computing Euler's Number e >>> n = 16 >>> b = [2] + [2 * i // 3 if not i % 3 else 1 for i in range(2, n + 1)] >>> num, den = cont_frac(b) >>> print(num, den, round(num / den, 8)) 566827 208524 2.71828183 Computing Golden ratio φ >>> n = 24 >>> num, den = cont_frac(1, 1, n) >>> print(num, den, round(num / den, 8)) 75025 46368 1.61803399 Nr<rz.Limit must be specified for given `a` and `b`.r/)r/r) rrr"rrrrr{rrr) rIr5r%len_blen_ar_iter_brHrr_iter_aa_ia_nb_nb_is ru cont_fracr!sf } FE FE 19MN N QY519u%Eu%E fuI fuI,A; ,A; CHC8XuU|<. S!s?C#IS.CKC c ""O E  E          , ,s1eEl/C Dtq! D DEH , s+H ,, , ,s1eEl/C Dtq! D DEH , s+H ,,s B; C CC, C;, E); C C  CC C)(C), C87C8; E&D>" D/ .D>=E&>E E&E  E&%E&) G3F, F F,+G,G G GGGc#K|j}t|s|f}|dk(r6t|dz |D]"tfdt |D$y|dk(r|D]d}|D] }|z|z} |yyw)u Yield the result of the polynomial evaluation at given points. y_i = sum(p_i * x_i ** i for i, p_i in enumerate(p[::-1])) Args: p (Sequence[Number]): The coefficients of the polynomial. Must be given in decreasing order. x (Number|Iterable[Number]): The evaluation point(s). method (str): Polynomial computation method. Accepted values are: - 'direct': use the direct computation (slower) - 'horner': use Horner's formula (faster, but less accurate) Yields: y_i (Number): The evaluated polynomial. Examples: >>> list(polynomial([1, 2, 3], range(16))) [3, 6, 11, 18, 27, 38, 51, 66, 83, 102, 123, 146, 171, 198, 227, 258] >>> list(polynomial([4, 0, 2, 1], range(10))) [1, 7, 37, 115, 265, 511, 877, 1387, 2065, 2935] >>> list(polynomial([1, -2], range(-8, 8))) [-10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5] >>> list(polynomial([1], range(-8, 8))) [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1] >>> list(polynomial([1, 0], range(-8, 8))) [-8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7] >>> list(polynomial([4, 0, 2, 1], 1)) [7] >>> list(polynomial([1, 2, 3], range(16), 'direct')) [3, 6, 11, 18, 27, 38, 51, 66, 83, 102, 123, 146, 171, 198, 227, 258] References: - Horner, W. G., and Davies Gilbert. “XXI. A New Method of Solving Numerical Equations of All Orders, by Continuous Approximation.” Philosophical Transactions of the Royal Society of London 109 ( January 1, 1819): 308–35. https://doi.org/10.1098/rstl.1819.0023. - https://en.wikipedia.org/wiki/Horner%27s_method directr/c3:K|]\}}||z zzywrr)rrMp_ir>x_is rurzpolynomial.."s"Fvq#cCAEN*FrhornerrN)r^rrrVr)r3rHmethody_irr>rs @@ru polynomialrj"sX\\^F 1: D  FQJ GCF1FF F G 8  CC &Ci#o &I   sA=Bc0t|t|z S)a Compute the arithmetic mean of a numeric sequence. For iterative computation see: - `flyingcircus.next_amean()` - `flyingcircus.i_amean()` - `flyingcircus.i_mean()` This is substantially faster than `statistics.mean()`. Args: seq (Sequence[Number]): The input items. Returns: result (Number): The arithmetic mean. Examples: >>> items = range(0, 52, 2) >>> mean(items) 25.0 >>> statistics.mean(items) == mean(items) True >>> [mean(range(n + 1)) for n in range(10)] [0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5] See Also: - flyingcircus.gmean() - flyingcircus.hmean() - flyingcircus.mean_and_soad() - flyingcircus.mean_and_sosd() - flyingcircus.mean_and_var() - flyingcircus.mean_and_stdev() - flyingcircus.mean_and_mean_abs_dev() - flyingcircus.median() - flyingcircus.next_amean() - flyingcircus.i_amean() - flyingcircus.i_mean() )rVrr1s rumeanr"sP s8c#h rwch|r|rtd|D}|syt|dt|z zS)a Compute the geometric mean of a numeric sequence. Args: seq (Sequence[Number]): The input items. valid (bool): Include only valid (non-zero) items. Returns: result (Number): The geometric mean. Examples: >>> items = range(0, 52, 2) >>> round(gmean(items), 3) 20.354 >>> gmean(items, False) 0.0 >>> [round(gmean(range(n + 1)), 3) for n in range(10)] [1.0, 1.0, 1.414, 1.817, 2.213, 2.605, 2.994, 3.38, 3.764, 4.147] See Also: - flyingcircus.mean() - flyingcircus.hmean() - flyingcircus.median() - flyingcircus.next_gmean() - flyingcircus.i_gmean() c3&K|] }|s| ywrrrrMs rurzgmean.."s(!aA(r?r/)rrrrrs rugmeanr"s6< (s(( 9SX &&rwcp|rtd|D}|sytd|D}dt|z S)aM Compute the harmonic mean of a numeric sequence. Args: seq (Sequence[Number]): The input items. The values within the sequence should be numeric. valid (bool): Include only valid (non-zero) items. Returns: result (Number): The harmonic mean. Examples: >>> items = range(0, 52, 2) >>> round(hmean(items), 3) 13.103 >>> hmean(items, False) Traceback (most recent call last): ... ZeroDivisionError: division by zero >>> [round(hmean(range(n + 1)), 3) for n in range(10)] [0.0, 1.0, 1.333, 1.636, 1.92, 2.19, 2.449, 2.7, 2.943, 3.181] See Also: - flyingcircus.mean() - flyingcircus.gmean() - flyingcircus.median() - flyingcircus.next_hmean() - flyingcircus.i_hmean() c3,K|] }|sd|z ywrrrs rurzhmean..#s.AQU.s c3&K|] }d|z  ywrrrs rurzhmean..#s)QU)sr/)rrrs ruhmeanr"s<B .S..)S)) tCy=rwc#:K|D]}t||z yw)a Yield the absolute deviations of the items from a value. Args: value (Number): The input value. seq (Sequence[Number]): The input items. Yields: result (Number): The next absolute deviation. Examples: >>> list(absolute_deviations(10, range(16))) [10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0, 1, 2, 3, 4, 5] See Also: - flyingcircus.squared_deviations() - flyingcircus.soad() - flyingcircus.mean_and_soad() - flyingcircus.mean_abs_dev() N)r!r[rrs ruabsolute_deviationsr##s&. %$, sc#4K|D]}||z ||z zyw)a  Yield the squared deviations of the items from a value. Args: value (Number): The input value. seq (Sequence[Number]): The input items. Yields: result (Number): The next squared deviation. Examples: >>> list(squared_deviations(10, range(16))) [100, 81, 64, 49, 36, 25, 16, 9, 4, 1, 0, 1, 4, 9, 16, 25] See Also: - flyingcircus.absolute_deviations() - flyingcircus.sosd() - flyingcircus.mean_and_sosd() - flyingcircus.var() Nrrs rusquared_deviationsr?#s*..t| --.scJt|}tt||}||fS)a Compute the mean and the sum-of-absolute-deviations of a numeric sequence. The sum-of-absolute-deviations (SoAD) is useful for computing the mean absolute deviation (MeanAD). Args: seq (Sequence[Number]): The input items. Returns: result (tuple): The tuple contains: - `mean_val` (Number): The mean of the items. - `soad_val` (Number): The SoAD of the items. Examples: >>> items = range(0, 52, 2) >>> mean_and_soad(items) (25.0, 338.0) >>> mean_and_soad(items) == (mean(items), soad(items)) True See Also: - flyingcircus.absolute_deviations() - flyingcircus.mean() - flyingcircus.soad() - flyingcircus.mean_and_sosd() - flyingcircus.mean_and_mean_abs_dev() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_mean_and_sosd() )rrVr)rmean_valsoad_vals ru mean_and_soadr[#s+@CyH&x56H X rwc>ttt||S)aL Compute the sum-of-absolute-deviations of a numeric sequence. The sum-of-absolute-deviations (SoAD) is useful for computing the mean absolute deviation (MeanAD). Args: seq (Sequence[Number]): The input items. Returns: result (Number): The sum-of-absolute-deviations (SoAD) of the items. Examples: >>> items = range(0, 52, 2) >>> soad(items) 338.0 See Also: - flyingcircus.absolute_deviations() - flyingcircus.mean_and_soad() - flyingcircus.sosd() - flyingcircus.mean_and_sosd() )rVrrr1s rusoadr#s0 "49c2 33rwcJt|}tt||}||fS)aA Compute the mean and the sum-of-squared-deviations of a numeric sequence. For iterative computation see: - `flyingcircus.next_mean_and_sosd()` - `flyingcircus.i_mean_and_sosd()` The sum-of-squared-deviations (SoSD) is useful for numerically stable computation of the variance and the standard deviation. Args: seq (Sequence[Number]): The input items. Returns: result (tuple): The tuple contains: - `mean_val` (Number): The mean of the items. - `sosd_val` (Number): The SoSD of the items. Examples: >>> items = range(0, 52, 2) >>> mean_and_sosd(items) (25.0, 5850.0) >>> mean_and_sosd(items) == (mean(items), sosd(items)) True See Also: - flyingcircus.squared_deviations() - flyingcircus.mean() - flyingcircus.sosd() - flyingcircus.mean_and_soad() - flyingcircus.mean_and_var() - flyingcircus.mean_and_stdev() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_mean_and_sosd() )rrVr)rrsosd_vals ru mean_and_sosdr#s+JCyH%h45H X rwc>ttt||S)a Compute the mean and the sum-of-squared-deviations of a numeric sequence. For iterative computation see: - `flyingcircus.next_mean_and_sosd()` - `flyingcircus.i_mean_and_sosd()` The sum-of-squared-deviations (SoSD) is useful for numerically stable computation of the variance and the standard deviation. Args: seq (Sequence[Number]): The input items. Returns: result (Number): The sum-of-squared-deviations (SoSD) of the items. Examples: >>> items = range(0, 52, 2) >>> sosd(items) 5850.0 See Also: - flyingcircus.squared_deviations() - flyingcircus.mean_and_sosd() - flyingcircus.soad() - flyingcircus.sosd2var() - flyingcircus.var2sosd() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_mean_and_sosd() )rVrrr1s rusosdr#sB !$s)S1 22rwc|||z z S)a Compute the variance from the sum-of-squared-deviations. Args: sosd_ (Number): The sum-of-squared-deviations value. num (int): The number of items. ddof (int): The number of degrees of freedom. Returns: result (Number): The variance value. Examples: >>> sosd2var(8, 3, 1) 4.0 >>> all([var2sosd(sosd2var(x, n, m), n, m) == x ... for x in range(9) for n in range(3, 9) for m in range(3)]) True See Also: - flyingcircus.sosd() - flyingcircus.var() - flyingcircus.var2sosd() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() rsosd_r;ddofs rusosd2varr#s< C$J rwc|||z zS)a Compute the sum-of-squared-deviations from the variance. Args: var_ (Number): The variance value. num (int): The number of items. ddof (int): The number of degrees of freedom. Returns: result (Number): The sum-of-squared-deviations value. Examples: >>> var2sosd(4, 3, 1) 8 >>> all([sosd2var(var2sosd(x, n, m), n, m) == x ... for x in range(9) for n in range(3, 9) for m in range(3)]) True See Also: - flyingcircus.sosd() - flyingcircus.var() - flyingcircus.sosd2var() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() r)var_r;rs ruvar2sosdr$s< 3: rwc|||z z dzS)a Compute the standard deviation from the sum-of-squared-deviations. Args: sosd_ (Number): The sum-of-squared-deviations value. num (int): The number of items. ddof (int): The number of degrees of freedom. Returns: result (Number): The standard deviation value. Examples: >>> sosd2stdev(8, 3, 1) 2.0 >>> all([sosd2stdev(stdev2sosd(x, n, m), n, m) == x ... for x in range(9) for n in range(3, 9) for m in range(3)]) True See Also: - flyingcircus.sosd() - flyingcircus.stdev() - flyingcircus.sosd2var() - flyingcircus.var2sosd() - flyingcircus.stdev2sosd() ?rrs ru sosd2stdevr1$s< S4Z S ((rwc||z||z zS)a Compute the sum-of-squared-deviations from the standard deviation. Args: stdev_ (Number): The variance value. num (int): The number of items. ddof (int): The number of degrees of freedom. Returns: sosd (Number): The sum-of-squared-deviations value. Examples: >>> stdev2sosd(2, 3, 1) 8 >>> all([abs(stdev2sosd(sosd2stdev(x, n, m), n, m) - x) < 1e-9 ... for x in range(9) for n in range(3, 9) for m in range(3)]) True See Also: - flyingcircus.sosd() - flyingcircus.stdev() - flyingcircus.sosd2var() - flyingcircus.var2sosd() - flyingcircus.sosd2stdev() r)stdev_r;rs ru stdev2sosdr S$s< VOd ++rwcJt|\}}t|t||S)a3 Compute the variance of a numeric sequence. For iterative computation see: - `flyingcircus.next_mean_and_var()` - `flyingcircus.next_mean_and_sosd()` and `.sosd2var()`. - `flyingcircus.i_var()` - `flyingcircus.i_mean_and_var()` This is substantially faster than `statistics.variance()`. Note that the variance is the mean of squared deviations. Args: seq (Sequence[Number]): The input items. ddof (int): The number of degrees of freedom. Returns: result (Number): The variance of the items. Examples: >>> items = range(0, 52, 2) >>> var(items) 225.0 >>> statistics.variance(items) == var(items, 1) True See Also: - flyingcircus.i_var() - flyingcircus.i_mean_and_var() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.mean_and_var() - flyingcircus.mean_and_sosd() - flyingcircus.stdev() - flyingcircus.sosd2var() - flyingcircus.var2sosd() rrrrrrrs ruvarru$s'R's+Hh Hc#h --rwcJt|\}}t|t||S)a Compute the standard deviation of a numeric sequence. For iterative computation see: - `flyingcircus.next_mean_and_stdev()` - `flyingcircus.next_mean_and_sosd()` and `.sosd2stdev()`. - `flyingcircus.i_stdev()` - `flyingcircus.i_mean_and_stdev()` This is substantially faster than `statistics.stdev()`. Note that the standard deviation is the square root of the variance, and hence it is also the square root of the mean of squared deviations. Args: seq (Sequence[Number]): The input items. The values within the sequence should be numeric. ddof (int): The number of degrees of freedom. Returns: result (Number): The standard deviation of the items. Examples: >>> items = range(0, 52, 2) >>> stdev(items) 15.0 >>> statistics.stdev(items) == stdev(items, 1) True See Also: - flyingcircus.i_stdev() - flyingcircus.i_mean_and_stdev() - flyingcircus.next_mean_and_stdev() - flyingcircus.next_mean_and_sosd() - flyingcircus.mean_and_stdev() - flyingcircus.mean_and_sosd() - flyingcircus.var() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() rrrrs rustdevr$s'V's+Hh hC$ //rwcNt|\}}|t|t||fS)a Compute the mean and variance of a numeric sequence. For iterative computation see: - `flyingcircus.next_amean()` - `flyingcircus.next_mean_and_var()` - `flyingcircus.next_mean_and_sosd()` and `.sosd2var()`. - `flyingcircus.i_mean()` - `flyingcircus.i_var()` - `flyingcircus.i_mean_and_var()` - `flyingcircus.i_mean_and_sosd()` and `.sosd2var()` This is faster than computing the two values separately. Args: seq (Sequence[Number]): The input items. The values within the sequence should be numeric. ddof (int): The number of degrees of freedom. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `var_` (Number): The variance of the items. Examples: >>> items = range(0, 52, 2) >>> mean_and_var(items) (25.0, 225.0) >>> mean_and_var(items) == (mean(items), var(items)) True See Also: - flyingcircus.mean() - flyingcircus.var() - flyingcircus.i_mean_and_var() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.mean_and_sosd() - flyingcircus.sosd2var() - flyingcircus.var2sosd() r rrmean_rs ru mean_and_varr$s+Z!%LE5 (5#c(D1 11rwcNt|\}}|t|t||fS)aL Compute the mean and the standard deviation of a numeric sequence. For iterative computation see: - `flyingcircus.next_amean()` - `flyingcircus.next_mean_and_stdev()` - `flyingcircus.next_mean_and_sosd()` and `.sosd2stdev()`. - `flyingcircus.i_mean()` - `flyingcircus.i_stdev()` - `flyingcircus.i_mean_and_stdev()` - `flyingcircus.i_mean_and_sosd()` and `.sosd2stdev()` This is faster than computing the two values separately. Args: seq (Sequence[Number]): The input items. The values within the sequence should be numeric. ddof (int): The number of degrees of freedom. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `stdev_` (Number): The standard deviation of the items. Examples: >>> items = range(0, 52, 2) >>> mean_and_stdev(items) (25.0, 15.0) >>> mean_and_stdev(items) == (mean(items), stdev(items)) True See Also: - flyingcircus.mean() - flyingcircus.stdev() - flyingcircus.i_mean_and_stdev() - flyingcircus.next_mean_and_stdev() - flyingcircus.next_mean_and_sosd() - flyingcircus.mean_and_sosd() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() rrs rumean_and_stdevr%s+Z!%LE5 *UCHd3 33rwcBt|\}}|t|z }||fS)a% Compute the mean and the mean absolute deviation of a numeric sequence. This is faster than computing the two values separately. Args: seq (Sequence[Number]): The input items. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `mean_abs_dev_` (Number): The mean abs. dev. of the items. Examples: >>> items = range(0, 52, 2) >>> mean_and_mean_abs_dev(items) (25.0, 13.0) >>> mean_and_mean_abs_dev(items) == (mean(items), mean_abs_dev(items)) True See Also: - flyingcircus.mean() - flyingcircus.mean_abs_dev() - flyingcircus.mean_and_soad() - flyingcircus.soad() - flyingcircus.absolute_deviations() )rr)rrsoad_ mean_abs_dev_s rumean_and_mean_abs_devr7%s+:!%LE5CH$M - rwc0t|t|z S)a Compute the mean absolute deviation of a numeric sequence. Args: seq (Sequence[Number]): The input items. Returns: result (Number): The mean absolute deviation of the items. Examples: >>> items = range(0, 52, 2) >>> mean_abs_dev(items) 13.0 See Also: - flyingcircus.mean() - flyingcircus.mean_abs_dev() - flyingcircus.mean_and_soad() - flyingcircus.soad() - flyingcircus.absolute_deviations() )rrr1s ru mean_abs_devrZ%s, 9s3x rwct|}|dz}|r t|n|}|dzs!||dz ||k7r||dz ||zdz }|S||}|S)a Compute the median of a numeric sequence. For iterative computation see: - `flyingcircus.next_median()` - `flyingcircus.next_medoid_and_median()` - `flyingcircus.i_median()` - `flyingcircus.i_medoid_and_median()` - `flyingcircus.i_median_and_median_abs_dev()` This is roughly comparable to `statistics.median()`. If more than one among median, medoid, quantile, quantiloid is needed, it is more efficient to sort the items prior to calling and then perform the multiple required calle with `force_sort` set to False. Args: seq (Sequence[Number]): The input items. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it should be set to True. Returns: result (Number): The median of the items. Examples: >>> items = range(0, 52, 2) >>> median(items) 25.0 >>> statistics.median(items) == median(items) True See Also: - flyingcircus.median_and_median_abs_dev() - flyingcircus.next_median() - flyingcircus.next_medoid_and_median() - flyingcircus.i_median() - flyingcircus.i_medoid_and_median() - flyingcircus.i_median_and_median_abs_dev() - flyingcircus.medoid() - flyingcircus.quantile() - flyingcircus.interquantilic_range() - flyingcircus.sym_interquantilic_range() - flyingcircus.median_abs_dev() r9r/)rrl)r force_sortr2rM sorted_itemsmedian_s rumedianr#t%sr` CA QA",6#;#L E|AE*l1o=A&a8A= Nq/ Nrwcdt||}tt||}|t||fS)a Compute the median and the median absolute deviation of a numeric sequence. Args: seq (Sequence[Number]): The input items. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it must be set to True. Returns: result (Number): The median deviation of the items. Examples: >>> items = range(0, 52, 2) >>> median_and_median_abs_dev(items) (25.0, 13.0) >>> (median_and_median_abs_dev(items) == ... (median(items), median_abs_dev(items))) True See Also: - flyingcircus.median() - flyingcircus.median_abs_dev() - flyingcircus.i_median() - flyingcircus.i_median_abs_dev() - flyingcircus.i_median_and_median_abs_dev() - flyingcircus.absolute_deviations() r r#rr)rr  median_val delta_itemss rumedian_and_median_abs_devr)%s5@ 3J+J<=K vkjA AArwc Xtttt||||S)a Compute the median absolute deviation of a numeric sequence. Args: seq (Sequence[Number]): The input items. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it must be set to True. Returns: result (Number): The median absolute deviation of the items. Examples: >>> items = range(0, 52, 2) >>> median_abs_dev(items) 13.0 See Also: - flyingcircus.median() - flyingcircus.median_and_median_abs_dev() - flyingcircus.i_median() - flyingcircus.i_median_abs_dev() - flyingcircus.i_median_and_median_abs_dev() - flyingcircus.absolute_deviations() r%r&)rr s rumedian_abs_devr+%s.8  sz BC H J rwdcxt|}t|ddd}t|}|j}|r t |n|} |dz |z } |dz |z} g} |D]M} | dkrt t dt| tr| |kDrt t dt| tr | r | | z}| |}nt| tr| |z } | dkDrt t d| |dz z}t|}|dz}t||kr| |}n|dk(r| tt|}nc|d k(r| |}nX|d k(r | |dz}nJ|d vr2| |}| |dz}||k(r| |}n.|d k(r |||z |zz}n||zd z }nt t d| j|P|r t| S| dS)as Compute the quantile of a numeric sequence. There is no efficient iterative version for any arbitrary factor. If more than one among median, medoid, quantile, quantiloid is needed, it is more efficient to sort the items prior to calling and then perform the multiple required calle with `force_sort` set to False. Args: seq (Sequence[Number]): The input items. factor (int|float|Iterable[int|float]): The quantile index. If float, must be a number in the [0, 1] range. If int, it is divided by `int_base` and its value must be in the [0, int_base] range. int_base (int|float): The denominator used to scale integer factors. interp (str): Interpolation for inexact quantiles. This determines tol (float): Tolerance for detecting exact indices. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it must be set to True. Returns: result (Number|tuple[Number]): The quantiles of the item(s). Returns the tuple if `factor` is a sequence (of any length), otherwise returns a Number. Examples: >>> items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> quantile(items, 0.25) 2.5 >>> quantile(items, range(0, 101, 10)) (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10) >>> ((min(items), median(items), max(items)) ... == quantile(items, (0.0, 0.5, 1.0))) True >>> interps = 'linear', 'lower', 'upper', 'midpoint', 'nearest' >>> [quantile([0, 1], 1, 2, interp) for interp in interps] [0.5, 0, 1, 0.5, 0] >>> [quantile([0, 1], 0.6, interp=interp) for interp in interps] [0.6, 0, 1, 0.5, 1] >>> [quantile([0, 1, 2], 1, 2, interp=interp) for interp in interps] [1, 1, 1, 1, 1] >>> [quantile([0, 1, 2], 0.5, interp=interp) for interp in interps] [1, 1, 1, 1, 1] >>> quantile([10, 11, 12], [0, 1, 2], 2) (10, 11, 12) >>> quantile([10, 11, 12], -1) Traceback (most recent call last): ... ValueError: Invalid factor `-1` (negative) >>> quantile([10, 11, 12], -0.1) Traceback (most recent call last): ... ValueError: Invalid factor `-0.1` (negative) >>> quantile([10, 11, 12], 101) Traceback (most recent call last): ... ValueError: Invalid integer factor `101` (larger than `int_base=100`) >>> quantile([10, 11, 12], 1.1) Traceback (most recent call last): ... ValueError: Invalid factor `1.1` (larger than 1.0) See Also: - flyingcircus.median() - flyingcircus.quantiloid() - flyingcircus.interquantilic_range() - flyingcircus.sym_interquantilic_range() r/FrzInvalid factor `{k}` (negative)z@Invalid integer factor `{k}` (larger than `int_base={int_base}`)rz&Invalid factor `{k}` (larger than 1.0)nearestr^r\)rlinearr/r9z!Invalid interpolation `{interp}`.) rrrr^rlr"rrrYr!rgrr)rrint_baseinterptolr  use_tuplekkr2r!is_exact exact_factorrr'rMrHint_ifrac_ir5rIs ruquantiler9%sjI VQu -B CA \\^F",6#;#LUh&'HEh&L F ) q5679 9 3 AL<=> > a (L AQA!S!L3w ABDDQU AFEUF6{S  'Y&$Sq]3Aw&$U+Aw&$UQY/A55$U+A$UQY/AAv(/!X- !QUf$4 4A!"Q! A$T*M%NOO aS)T&5=46!94rwct|}|rtt|dz dz n|dz}|r t|n|}||}|S)a Compute the medoid of an arbitrary sequence. For some inputs `select_ordinal()` may be faster. If more than one among median, medoid, quantile, quantiloid is needed, it is more efficient to sort the items prior to calling and then perform the multiple required calls with `force_sort` set to False. For iterative computation see: - `flyingcircus.next_medoid()` - `flyingcircus.i_medoid()` If the number of items is not odd, returns the medoid from the lower or upper half depending on the value of `lower` being True or False. Args: seq (Sequence[Number|Any]): The input items. The values within the sequence do not need to be numeric. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it should be set to True. lower (bool): Pick the lower medoid for even-sized items. Returns: result (Any): The medoid of the items. Examples: >>> items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> medoid(items) 5 >>> medoid(items, lower=False) 5 >>> items = range(0, 20, 2) >>> medoid(items) 8 >>> medoid(items, lower=False) 10 >>> items = string.ascii_lowercase >>> medoid(items) 'm' >>> medoid(items, lower=False) 'n' See Also: - flyingcirucs.select_ordinal() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() - flyingcircus.i_medoid() - flyingcircus.i_medoid_and_median() - flyingcircus.median() - flyingcircus.quantiloid() - flyingcircus.interquantilic_range() - flyingcircus.sym_interquantilic_range() r/r9)rrYrgrl)rr r^r2rMr!medoid_s rumedoidr<&sHz CA#(E1q5A+ a1fA",6#;#L1oG Nrwct|st|ddd}tfd|D}|r t|n|}t j ||}|S)a Compute the quantiloid of an arbitrary sequence. There is no efficient iterative version for any arbitrary factor. For some inputs `select_ordinal()` may be faster. If more than one among median, medoid, quantile, quantiloid is needed, it is more efficient to sort the items prior to calling and then perform the multiple required calle with `force_sort` set to False. Args: seq (Sequence[Number|Any]): The input items. The values within the sequence do not need to be numeric. factor (int|float|Iterable[int|float]): The quantile index. If float, must be a number in the [0, 1] range. If int, it is divided by `int_base` to get to the [0, 1] range. int_base (int|None): The denominator for scaling integer factors. If None (or zero), uses `len(items)`. rounding (callable): The rounding to use for determining the index. Use `round` to pick the closest index. Use `math.floor` to pick the lower index. Use `math.ceil` to pick the upper index. force_sort (bool): Force sorting of the input items. If the items are in the intended order, it should be set to False. Otherwise, it should be set to True. Returns: result (Any|tuple[Any]): The quantiloid of the item(s). Returns the tuple if `factor` is a sequence (of any length), otherwise returns an element of items. Examples: >>> items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> quantiloid(items, 0.25) 2 >>> quantiloid(items, range(0, 101, 10)) (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10) >>> ((min(items), medoid(items), max(items)) ... == quantiloid(items, (0.0, 0.5, 1.0))) True >>> items = string.ascii_lowercase >>> quantiloid(items, 0.25) 'g' >>> quantiloid(items, range(0, 101, 10)) ('a', 'c', 'f', 'i', 'k', 'm', 'p', 's', 'u', 'w', 'z') >>> ((min(items), medoid(items), max(items)) ... == quantiloid(items, (0.0, 0.5, 1.0))) True See Also: - flyingcircus.medoid() - flyingcircus.quantile() - flyingcircus.interquantilic_range() - flyingcircus.sym_interquantilic_range() r/Fc 3vK|]0}tt|tr|n|z dz z2ywr)rYrr_)rr'r0r2roundings rurzquantiloid.. 's;  H:a/aQ\a!eL MNs69)rrrrlr^r_) rrr0r?r r4r!rr2s `` @ru quantiloidr@&si| CA  VQu -B  B#-6#;#L %X " %l 3F Mrwg?g?cN| t|ni}||||f|fd|i|\}}||z S)a Compute the interquantilic range of a numeric sequence. If more than one among median, medoid, quantile, quantiloid is needed, it is more efficient to sort the items prior to calling and then perform the multiple required calle with `force_sort` set to False. Args: seq (Sequence[Number]): The input items. The values within the sequence may not need to be numeric, depending on the `quantilic_func` used. lower_factor (int|float): The lower quantilic index. If float, must be a number in the [0, 1] range. If int, it is divided by `int_base` to get to the [0, 1] range. upper_factor (int|float): The upper quantilic index. If float, must be a number in the [0, 1] range. If int, it is divided by `int_base` to get to the [0, 1] range. int_base (int|float): The denominator used to scale integer factors. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it must be set to True. quantilic_func (callable): The quantilic function. Must be either `flyingcircus.quantile()` or `flyingcircus.quantiloid()` (or any other callable implementing the same signature). quantilic_kws (Mapping|None): Keyword parameters for `quantilic_func`. Returns: result (Number): The inter-quantilic range. Examples: >>> items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> interquantilic_range(items) 5.0 See Also: - flyingcircus.quantile() - flyingcircus.quantiloid() - flyingcircus.sym_interquantilic_range() - flyingcircus.median_abs_dev() r )r ) r lower_factor upper_factorr0r quantilic_func quantilic_kwsq_aq_bs ruinterquantilic_rangerH'sLb,9+DD'"M lL )8@J HC 9rwc0t|d|z d|z|||S)ar Compute the symmetric interquantilic range of a numeric sequence. The quantilic range is defined as: [0.5 - sym_factor, 0.5 + sym_factor]. If more than one among median, medoid, quantile, quantiloid is needed, it is more efficient to sort the items prior to calling and then perform the multiple required calle with `force_sort` set to False. Args: seq (Sequence[Number]): The input items. sym_factor (float): The symmetric quantilic factor. Must be a number in the [0, 0.5] range. force_sort (bool): Force sorting of the input items. If the items are already sorted, this can be safely set to False. Otherwise, it must be set to True. quantilic_func (callable): The quantilic function. Must be either `flyingcircus.quantile()` or `flyingcircus.quantiloid()` (or any other callable implementing the same signature). quantilic_kws (Mapping|None): Keyword parameters for `quantilic_func`. Returns: result (Number): The inter-quantilic range. Examples: >>> items = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10] >>> sym_interquantilic_range(items) 5.0 See Also: - flyingcircus.quantile() - flyingcircus.quantiloid() - flyingcircus.interquantilic_range() - flyingcircus.median_abs_dev() r)r rDrE)rH)r sym_factorr rDrEs rusym_interquantilic_rangerKL's,T  S: sZ/J%] DDrwc(||z|z|dzz |dzfS)a Compute the arithmetic mean for (num + 1) items. This is useful for low memory footprint computation. Args: value (Number): The next value to consider. mean_ (Number): The aggregate mean of the previous n items. num (int): The number of items in the aggregate. Returns: result (tuple): The tuple contains: - mean_ (Number): The updated arithmetic mean. - num_ (int): The number of items included. Examples: >>> items = range(0, 52, 2) >>> mean_ = 0.0 >>> for i, val in enumerate(items): ... mean_, num_ = next_amean(val, mean_, i) >>> print((mean_, num_)) (25.0, 26) >>> mean_ == mean(items) True See Also: - flyingcircus.mean() - flyingcircus.i_amean() - flyingcircus.i_mean() - flyingcircus.i_mean_and_sosd() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() r/rr[rr;s ru next_ameanrN|'s&V %K% C!G ,cAg 55rwc`|s|s'|s||dzfS|||dzz z|d|dzz zz}||dzfS||fS)a Compute the geometric mean for (num + 1) items. This is useful for low memory footprint computation. Args: value (Number): The next value to consider. gmean_ (Number): The aggregate geometric mean of the previous n items. num (int): The number of items in the aggregate. valid (bool): Include only valid items. Valid items must be non-zero. Returns: result (tuple): The tuple contains: - gmean_ (Number): The updated geometric mean. - num_ (int): The number of items included. Examples: >>> items = range(0, 52, 2) >>> gmean_, num_ = 1.0, 0 >>> for i in items: ... gmean_, num_ = next_gmean(i, gmean_, num_) >>> print((round(gmean_, 3), num_)) (20.354, 25) >>> gmean_ == gmean(items) True See Also: - flyingcircus.mean() - flyingcircus.gmean() - flyingcircus.i_gmean() - flyingcircus.next_amean() - flyingcircus.next_hmean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() r/r)r[gmean_r;rs ru next_gmeanrQ'sYZ E#'> !sQw05Q#']3KKF37? "s{rwcT|s|s!|s||dzfS|dz||z d|z zz }||dzfS||fS)a Compute the harmonic mean for (num + 1) items. This is useful for low memory footprint computation. Args: value (Number): The next value to consider. hmean_ (Number): The aggregate harmonic mean of the previous n items. num (int): The number of items in the aggregate. valid (bool): Include only valid (non-zero) items. Returns: result (tuple): The tuple contains: - hmean_ (Number): The updated geometric mean. - num_ (int): The number of items included. Examples: >>> items = range(0, 52, 2) >>> hmean_, num_ = 0.0, 0 >>> for i in items: ... hmean_, num_ = next_hmean(i, hmean_, num_) >>> print((round(hmean_, 3), num_)) (13.103, 25) >>> abs(hmean_ - hmean(items)) < 1e-14 True See Also: - flyingcircus.mean() - flyingcircus.hmean() - flyingcircus.i_hmean() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_mean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() r/r)r[hmean_r;rs ru next_hmeanrT'sNZ E#'> !Ag#,U":;F37? "s{rwc||z|z|dzz S)am Compute the arithmetic mean for (num + 1) items. This is useful for low memory footprint computation. The difference between `flyingcircus.next_amean()` and `flyingcircus.next_mean()` is that the latter does return the number of items processed. Args: value (Number): The next value to consider. mean_ (Number): The aggregate mean of the previous n items. num (int): The number of items in the aggregate. Returns: result (tuple): The tuple contains: - mean_ (Number): The updated arithmetic mean. - num_ (int): The number of items included. Examples: >>> items = range(0, 52, 2) >>> mean_ = 0.0 >>> for i, val in enumerate(items): ... mean_, num_ = next_amean(val, mean_, i) >>> print((mean_, num_)) (25.0, 26) >>> mean_ == mean(items) True See Also: - flyingcircus.mean() - flyingcircus.i_amean() - flyingcircus.i_mean() - flyingcircus.i_mean_and_sosd() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() r/rrMs ru next_meanrV(s` %K% C!G ,,rwcX|}t|||\}}||z||z ||z zz|z }|||fS)a Compute the mean and variance for (num + 1) numeric items. This is useful for low memory footprint computation. Note that both mean and variance MUST be updated at each iteration, therefore a stand-alone `next_var()` is sub-optimal. Warning! This algorithm is not numerically stable. For better numerical stability use `next_mean_and_sosd()`. Args: value (Number): The next value to consider. mean_ (Number): The aggregate mean of the previous n items. var_ (Number): The aggregate variance of the previous n items. num (int): The number of items in the aggregate. Returns: result (tuple): The tuple contains: - mean (Number): The updated mean. - var (Number): The updated variance. - num_ (int): The number of items included. Examples: >>> items = range(0, 52, 2) >>> mean_, var_, num_ = 0.0, 0.0, 0 >>> for i in items: ... mean_, var_, num_ = next_mean_and_var(i, mean_, var_, num_) >>> print((mean_, var_)) (25.0, 225.0) >>> (mean_, var_) == mean_and_var(items) True See Also: - flyingcircus.mean() - flyingcircus.var() - flyingcircus.i_amean() - flyingcircus.i_var() - flyingcircus.i_mean_and_var() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() rN)r[rrr;rgnum_s runext_mean_and_varrZQ(sIl DUE3/KE4 CZEDLUU]; ;t CD $ rwcL|}t|||\}}|||z ||z zz }|||fS)u Compute the mean and sum-of-squared-deviations for (num + 1) numeric items. This is useful for low memory footprint computation. This algorithm is numerically stable. The sum-of-squared-deviations (SoSD) can be computed as below and it is equivalent to the variance multiplied by the number of items: sosd = sum((x_i - mu) ** 2) sosd = var * n Note that both mean and variance MUST be updated at each iteration, therefore a stand-alone `next_sosd()` is sub-optimal. Args: value (Number): The next value to consider. mean_ (Number): The aggregate mean of the previous n items. sosd_ (Number): The aggregate SoSD of the previous n items. num (int): The number of items in the aggregate value. Returns: result (tuple): The tuple contains: - mean_ (Number): The updated mean. - sosd_ (Number): The updated sum-of-squared-deviations. - num_ (int): The number of items included. Examples: >>> items = range(0, 52, 2) >>> mean_, sosd_, num_ = 0.0, 0.0, 0 >>> for i in items: ... mean_, sosd_, num_ = next_mean_and_sosd(i, mean_, sosd_, num_) >>> print((mean_, sosd_, num_)) (25.0, 5850.0, 26) >>> (mean_, sosd_) == mean_and_sosd(items) True References: - Welford, B.P. (1962). "Note on a method for calculating corrected sums of squares and products". Technometrics 4(3):419–420. doi:10.2307/1266577 See Also: - flyingcircus.squared_deviations() - flyingcircus.mean() - flyingcircus.sosd() - flyingcircus.mean_and_sosd() - flyingcircus.mean_and_var() - flyingcircus.mean_and_stdev() - flyingcircus.i_mean_and_sosd() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() rX)r[rrr;rgs runext_mean_and_sosdr\(s@D DE5#.JE3 edluu} --E % rwc|s|}|j||Stj||t|d}t ||kDr ||kDr|d=|S|d=|S)ax Compute the (approximate) median for (num + 1) items. This computes an approximate value. Relies on the robustness of the median. Requires the values to be shuffled (within at least half the buffer size), or that the buffer size is larger than the number of values. This is useful for low memory footprint approximate computation. Args: value (Number): The next value to consider. buffer (list): The buffer from previous iterations. max_buffer (int): The maximum size of the buffer. If `max_buffer >= len(items)` the result is exact. Returns: median_ (Number): The updated median. Examples: >>> items = range(0, 52, 2) >>> buffer = [] >>> for i in items: ... median_ = next_median(i, buffer) >>> print(median_) 25.0 >>> buffer = [] >>> for i in items: ... median_ = next_median(i, buffer, max_buffer=4) >>> print(median_) 46 >>> items = list(items) >>> random.seed(0) >>> items = shuffle(items) >>> buffer = [] >>> for i in items: ... median_ = next_median(i, buffer, max_buffer=4) >>> print(median_) 12 See Also: - flyingcircus.median() - flyingcircus.i_median() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() Frr<)rbisectinsortr#r)r[rx max_bufferr"s ru next_medianra(skt  e N  fe$' v; #w1I N2J Nrwc|s|}|j||Stj||t|d|}t ||kDr ||kDr|d=|S|d=|S)a Compute the (approximate) medoid for (num + 1) items. This computes an approximate value. Relies on the robustness of the medoid. Requires the values to be shuffled (within at least half the buffer size), or that the buffer size is larger than the number of values. This is useful for low memory footprint approximate computation. If the number of items is not odd, returns the medoid from the lower or upper half depending on the value of `lower` being True or False. Args: value (Any): The next value to consider. buffer (list): The buffer from previous iterations. lower (bool): Pick the lower medoid for even-sized buffer. max_buffer (int): The maximum size of the buffer. If `max_buffer >= len(items)` the result is exact. Returns: result (Any): The updated approximate medoid value. Examples: >>> items = range(0, 52, 2) >>> buffer = [] >>> for i in items: ... medoid_ = next_medoid(i, buffer) >>> print(medoid_) 24 >>> buffer = [] >>> for i in items: ... medoid_ = next_medoid(i, buffer, max_buffer=4) >>> print(medoid_) 46 >>> items = list(items) >>> random.seed(0) >>> items = shuffle(items) >>> buffer = [] >>> for i in items: ... medoid_ = next_medoid(i, buffer, max_buffer=4) >>> print(medoid_) 12 See Also: - flyingcircus.medoid() - flyingcircus.i_medoid() - flyingcircus.i_medoid_and_median() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() Frr<)rr^r_r<r)r[rxr^r`r;s ru next_medoidrc!)sm@  e N  fe$. v; #w1I N2J Nrwc|s|}|}|j|||fStj||t|d|}t |d}t ||kDr||kDr|d=||fS|d=||fS)a Compute the (approximate) medoid and median for (num + 1) items. This computes an approximate value. Relies on the robustness of the medoid and the median. Requires the values to be shuffled (within at least half the buffer size), or that the buffer size is larger than the number of values. This is used when both the medoid and the median are needed. In this case, a single buffer could be used. Note that calling both `next_medoid()` and `next_median()` consecutively over the same buffer MUST be avoided, because this introduces a bias, since the elements are inserted twice in buffer. This is useful for low memory footprint approximate computation. If the number of items is not odd, returns the medoid from the lower or upper half depending on the value of `lower` being True or False. Args: value (Any): The next value to consider. buffer (list): The buffer from previous iterations. lower (bool): Pick the lower medoid for even-sized buffer. max_buffer (int): The maximum size of the buffer. If `max_buffer >= len(items)` the result is exact. Returns: result (tuple): The tuple contains: - `medoid_` (Any): The updated approximate median value. - `median_` (Number): The updated medoid value. Examples: >>> items = range(0, 52, 2) >>> buffer = [] >>> for i in items: ... medoid_, median_ = next_medoid_and_median(i, buffer) >>> print((medoid_, median_)) (24, 25.0) >>> buffer = [] >>> for i in items: ... medoid_, median_ = next_medoid_and_median( ... i, buffer, max_buffer=4) >>> print((medoid_, median_)) (46, 46) >>> items = list(items) >>> random.seed(0) >>> items = shuffle(items) >>> buffer = [] >>> for i in items: ... medoid_, median_ = next_medoid_and_median( ... i, buffer, max_buffer=4) >>> print((medoid_, median_)) (12, 12) >>> buffer = [] >>> for i in items: ... medoid_, median_ = next_medoid_and_median( ... i, buffer, max_buffer=12) >>> print((medoid_, median_)) (24, 24) See Also: - flyingcircus.median() - flyingcircus.i_median() - flyingcircus.medoid() - flyingcircus.i_medoid() - flyingcircus.i_medoid_and_median() - flyingcircus.next_amean() - flyingcircus.next_gmean() - flyingcircus.next_hmean() - flyingcircus.next_mean() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.next_median() - flyingcircus.next_medoid() Frr<)rr^r_r<r#r)r[rxr^r`r;r"s runext_medoid_and_medianreq)sd  e G   fe$.' v; #w1I G 2J G rwc8|D]}t|||\}}||fS)a Compute the arithmetic mean a numeric iterable. Internally uses `flyingcircus.next_amean()`. This is substantially faster than `statistics.mean()`. The difference between `flyingcircus.i_amean()` and `flyingcircus.i_mean()` is that the latter does return the number of items processed. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. num (int): The number of items included in the start value. Returns: result (tuple): The tuple contains: - `mean_` (: The mean of the items. - `num`: The number of items. Examples: >>> items = range(0, 52, 2) >>> i_amean(items) (25.0, 26) >>> (mean(items), len(items)) == i_amean(items) True See Also: - flyingcircus.mean() - flyingcircus.next_amean() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean_and_sosd() - flyingcircus.i_var() - flyingcircus.i_stdev() - flyingcircus.i_mean_and_var() - flyingcircus.i_mean_and_stdev() rX)rrr;rs rui_ameanrg)s0Z2eS1 s2 #:rwc:|D]}t||||\}}||fS)a Compute the mean a numeric iterable. Internally uses `flyingcircus.next_gmean()`. This is substantially faster than `statistics.mean()`. Args: items (Iterable[Number]): The input items. gmean_ (Number): The start mean value. num (int): The number of items included in the start value. valid (bool): Include only valid (non-zero) items. Returns: result (tuple): The tuple contains: - `gmean_` (Number): The mean of the items. - `num` (int): The number of items. Examples: >>> items = range(0, 52, 2) >>> gmean_, num = i_gmean(items) >>> print((round(gmean_, 3), num)) (20.354, 25) >>> (gmean(items), len(items) - 1) == i_gmean(items) True )rQ)rrPr;rrs rui_gmeanri*s2@; vsE: ; 3;rwcRt|D]\}}t||||\}}||fS)a Compute the mean a numeric iterable. Internally uses `flyingcircus.next_hmean()`. This is substantially faster than `statistics.mean()`. Args: items (Iterable[Number]): The input items. hmean_ (Number): The start harmonic mean value. num (int): The number of items included in the start value. valid (bool): Include only valid (non-zero) items. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `num` (int): The number of items. Examples: >>> items = range(0, 52, 2) >>> hmean_, num = i_hmean(items) >>> print((round(hmean_, 3), num)) (13.103, 25) >>> abs(hmean_ - hmean(items)) < 1e-14 True )rrT)rrSr;rrMrs rui_hmeanrk.*s;@U#;4 vsE: ; 3;rwc&t|||\}}|S)a Compute the arithmetic mean a numeric iterable. Internally uses `flyingcircus.i_amean()`. This is substantially faster than `statistics.mean()`. The difference between `flyingcircus.i_amean()` and `flyingcircus.i_mean()` is that the latter does return the number of items processed. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. num (int): The number of items included in the start value. Returns: result (tuple): The tuple contains: - `mean_` (: The mean of the items. - `num`: The number of items. Examples: >>> items = range(0, 52, 2) >>> i_mean(items) 25.0 >>> mean(items) == i_mean(items) True See Also: - flyingcircus.mean() - flyingcircus.next_amean() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean_and_sosd() - flyingcircus.i_var() - flyingcircus.i_stdev() - flyingcircus.i_mean_and_var() - flyingcircus.i_mean_and_stdev() )rg)rrr;s rui_meanrmT*sZs+JE3 LrwcVt|D]\}}t||||\}}}|||fS)a# Compute the mean and the variance of a numeric iterable. Internally uses `flyingcircus.next_mean_and_sosd()`. This is useful for low memory footprint computation. This is substantially faster than computing the two values separately. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. sosd_ (Number): The start sum-of-squared-deviation value. num (int): The number of items included in the start mean value. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `var_` (Number): The variance of the items. - `num` (int): The number of items. Examples: >>> items = range(0, 52, 2) >>> i_mean_and_sosd(items) (25.0, 5850.0, 26) >>> mean_and_sosd(items) + (len(items),) == i_mean_and_sosd(items) True See Also: - flyingcircus.mean_and_sosd() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean() - flyingcircus.i_var() - flyingcircus.i_stdev() - flyingcircus.i_mean_and_var() - flyingcircus.i_mean_and_stdev() )rr\)rrrr;rMrs rui_mean_and_sosdro*sC\U#H4.tUE3GucH % rwcZt|||}t||||\}}}t|||S)aD Compute the variance of a numeric iterable. Internally uses `flyingcircus.next_mean_and_sosd()` and `flyingcircus.sosd2var()`. This is useful for low memory footprint computation. Note that both mean and variance MUST be updated at each iteration, therefore if both the mean and the variance are required use `flyingcircus.i_mean_var()`. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. var_ (Number): The start variance value. num (int): The number of items included in the start values. ddof (int): The number of degrees of freedom. Returns: result (Number): The variance of the items. Examples: >>> items = range(0, 52, 2) >>> i_var(items) 225.0 >>> var(items) == i_var(items) True See Also: - flyingcircus.var() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean() - flyingcircus.i_mean_and_sosd() - flyingcircus.i_stdev() - flyingcircus.i_mean_and_var() - flyingcircus.i_mean_and_stdev() - flyingcircus.sosd2var() - flyingcircus.var2sosd() rror)rrrr;rrrYs rui_varrr*s9d T3 %E(ucBE5$ E4 &&rwcZt|||}t||||\}}}t|||S)a Compute the standard deviation of a numeric iterable. Internally uses `flyingcircus.next_mean_and_sosd()` and `flyingcircus.sosd2stdev()`. This is useful for low memory footprint computation. Note that both mean and std. deviation MUST be updated at each iteration, therefore if both the mean and the standard deviation are required use `flyingcircus.i_mean_stdev()`. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. stdev_ (Number): The start standard deviation value. num (int): The number of items included in the start values. ddof (int): The number of degrees of freedom. Returns: result (Number): The standard deviation of the items. Examples: >>> items = range(0, 52, 2) >>> i_stdev(items) 15.0 >>> stdev(items) == i_stdev(items) True See Also: - flyingcircus.stdev() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean() - flyingcircus.i_mean_and_sosd() - flyingcircus.i_var() - flyingcircus.i_mean_and_var() - flyingcircus.i_mean_and_stdev() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() r rorrrr r;rrs rui_stdevrv*s9d vsD )E'ueSAE5# eS$ ''rwc`t|||}t||||\}}}|t||||fS)a+ Compute the mean and the variance of a numeric iterable. Internally uses `flyingcircus.next_mean_and_sosd()` and `flyingcircus.sosd2var()`. This is useful for low memory footprint computation. This is substantially faster than: - computing the two values separately. - both `statistics.mean()` and `statistics.variance()`. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. var_ (Number): The start variance value. num (int): The number of items included in the start values. ddof (int): The number of degrees of freedom. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `var_` (Number): The variance of the items. - `num` (int): The number of items. Examples: >>> items = range(0, 52, 2) >>> i_mean_and_var(items) (25.0, 225.0, 26) >>> mean_and_var(items) + (len(items),) == i_mean_and_var(items) True See Also: - flyingcircus.mean() - flyingcircus.var() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean() - flyingcircus.i_mean_and_sosd() - flyingcircus.i_var() - flyingcircus.i_stdev() - flyingcircus.i_mean_and_stdev() - flyingcircus.sosd2var() - flyingcircus.var2sosd() rq)rrrr;rrs rui_mean_and_varrx*+s@n T3 %E'ueSAE5# (5#t,c 11rwc`t|||}t||||\}}}|t||||fS)aK Compute the mean and standard deviation of a numeric iterable. Internally uses `flyingcircus.next_mean_and_sosd()` and `flyingcircus.sosd2stdev()`. This is useful for low memory footprint computation. This is substantially faster than: - computing the two values separately. - both `statistics.mean()` and `statistics.stdev()`. Args: items (Iterable[Number]): The input items. mean_ (Number): The start mean value. stdev_ (Number): The start standard deviation value. num (int): The number of items included in the start values. ddof (int): The number of degrees of freedom. Returns: result (tuple): The tuple contains: - `mean_` (Number): The mean of the items. - `stdev_` (Number): The std. deviation of the items. - `num` (int): The number of items. Examples: >>> items = range(0, 52, 2) >>> i_mean_and_stdev(items) (25.0, 15.0, 26) >>> mean_and_stdev(items) + (len(items),) == i_mean_and_stdev(items) True See Also: - flyingcircus.mean() - flyingcircus.var() - flyingcircus.next_mean_and_var() - flyingcircus.next_mean_and_sosd() - flyingcircus.i_amean() - flyingcircus.i_gmean() - flyingcircus.i_hmean() - flyingcircus.i_mean() - flyingcircus.i_mean_and_sosd() - flyingcircus.i_var() - flyingcircus.i_stdev() - flyingcircus.i_mean_and_var() - flyingcircus.sosd2stdev() - flyingcircus.stdev2sosd() rtrus rui_mean_and_stdevrzg+s@n vsD )E'ueSAE5# *UC. 33rwcbt|}t|}|g}|D]}t|||}|S)ar Compute the (approximate) median of a numeric iterable. This computes an approximate value. Relies on the robustness of the median. This is useful for low memory footprint approximate computation. Args: items (Iterable[Number]): The input items. max_buffer (int): The maximum size of the buffer. If `max_buffer >= len(items)` the result is exact. Returns: result (Number): The median value. Examples: >>> items = range(0, 52, 2) >>> i_median(items) 25.0 >>> i_median(items) == median(items) True >>> items = [1, 2, 3, 4, 100] >>> i_median(items) 3 >>> items = [81, 73, 99, 86, 94, 40, 75, 46, 8, 50, 51, 53, 35, 87] >>> sorted(items) [8, 35, 40, 46, 50, 51, 53, 73, 75, 81, 86, 87, 94, 99] >>> i_median(items) 63.0 >>> [i_median(items, i) for i in range(3, len(items))] [50.5, 51, 52.0, 51, 52.0, 51, 52.0, 51, 52.0, 53, 63.0] >>> items = [81, 73, 99, 86, 94, 40, 75, 46, 8, 50, 51, 53, 35] >>> sorted(items) [8, 35, 40, 46, 50, 51, 53, 73, 75, 81, 86, 94, 99] >>> i_median(items) 53 >>> [i_median(items, i) for i in range(3, len(items))] [50.5, 51, 52.0, 51, 52.0, 51, 52.0, 51, 52.0, 53] >>> all([i_median(range(i)) == median(range(i)) for i in range(1, 40)]) True >>> all([i_median(range(0, i)) == i_medoid(range(0, i)) ... for i in range(1, 40, 2)]) True See Also: - flyingcircus.median() - flyingcircus.median_and_median_abs_dev() - flyingcircus.next_median() - flyingcircus.next_medoid_and_median() - flyingcircus.i_median() - flyingcircus.i_medoid() - flyingcircus.i_medoid_and_median() - flyingcircus.i_median_and_median_abs_dev() )rxr`)rrra)rr`rr"rxrs rui_medianr|+sC|eJ:GYFJd6jIJ Nrwc|r0t|}t|}|g}|D]}t||||}|Stt |dd}|S)av Compute the (approximate) medoid of an arbitrary iterable. This computes an approximate value. Relies on the robustness of the medoid. This is useful for low memory footprint approximate computation. Args: items (Iterable[Any]): The input items. lower (bool): Pick the lower medoid for even-sized items. max_buffer (int): The maximum size of the buffer. If `max_buffer >= len(items)` the result is exact. If `max_buffer` is 0, use all items. Returns: result (Any): The medoid value. Examples: >>> items = range(0, 52, 2) >>> i_medoid(items) 24 >>> i_medoid(items) == medoid(items) True >>> items = [1, 2, 2, 2, 100] >>> i_medoid(items) 2 >>> items = [81, 73, 99, 86, 94, 40, 75, 46, 8, 50, 51, 53, 35, 87] >>> sorted(items) [8, 35, 40, 46, 50, 51, 53, 73, 75, 81, 86, 87, 94, 99] >>> i_medoid(items) 53 >>> [i_medoid(items, max_buffer=i) for i in range(3, len(items))] [51, 51, 51, 51, 51, 51, 51, 51, 53, 53, 53] >>> items = [81, 73, 99, 86, 94, 40, 75, 46, 8, 50, 53, 35, 87] >>> sorted(items) [8, 35, 40, 46, 50, 53, 73, 75, 81, 86, 87, 94, 99] >>> i_medoid(items) 73 >>> [i_medoid(items, max_buffer=i) for i in range(3, len(items))] [50, 50, 50, 50, 50, 50, 50, 53, 73, 73] >>> all([i_medoid(range(i)) == medoid(range(i)) for i in range(1, 40)]) True >>> all([i_medoid(range(0, i)) == i_median(range(0, i)) ... for i in range(1, 40, 2)]) True See Also: - flyingcircus.medoid() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() - flyingcircus.i_median() - flyingcircus.i_medoid() - flyingcircus.i_medoid_and_median() TF)rrrcr<r)rr^r`rr;rxrs rui_medoidr~+sc~%[ z" CD!$zBG C NutU3 Nrwc|rGd}t|}t|}|}|g}t|D]\}}t||||\}}|dz} n1t |}t |d|}t |d}t|} ||| fS)a Compute the (approximate) medoid and median for a numeric iterable. This computes an approximate value. Relies on the robustness of the medoid. This is useful for low memory footprint approximate computation. This is faster and more memory efficient than computing both `flyingcircus.i_medoid()` and `flyingcircus.i_median()` separately. Args: items (Iterable[Number]): The input items. lower (bool): Pick the lower medoid for even-sized items. max_buffer (int): The maximum size of the buffer. If `max_buffer >= len(items)` the result is exact. If `max_buffer` is 0, use all items. Returns: result (tuple): The tuple contains: - `medoid_`: The medoid of the items. - `median_`: The median of the items. - `num`: The number of items. Examples: >>> items = range(0, 52, 2) >>> i_medoid_and_median(items) (24, 25.0, 26) >>> (i_medoid_and_median(items) ... == (medoid(items), median(items), len(items))) True >>> items = [1, 2, 2, 2, 100] >>> i_medoid_and_median(items) (2, 2, 5) >>> items = [81, 73, 99, 86, 94, 40, 75, 46, 8, 50, 51, 53, 35, 87] >>> sorted(items) [8, 35, 40, 46, 50, 51, 53, 73, 75, 81, 86, 87, 94, 99] >>> i_medoid_and_median(items) (53, 63.0, 14) >>> [i_medoid_and_median(items, max_buffer=i) for i in range(10, 14)] [(51, 51, 14), (53, 52.0, 14), (53, 53, 14), (53, 63.0, 14)] >>> items = [81, 73, 99, 86, 94, 40, 75, 46, 8, 50, 53, 35, 87] >>> sorted(items) [8, 35, 40, 46, 50, 53, 73, 75, 81, 86, 87, 94, 99] >>> i_medoid_and_median(items) (73, 73, 13) >>> [i_medoid_and_median(items, max_buffer=i) for i in range(10, 14)] [(53, 53, 13), (73, 63.0, 13), (73, 73, 13), (73, 73, 13)] See Also: - flyingcircus.median() - flyingcircus.medoid() - flyingcircus.next_median() - flyingcircus.next_medoid() - flyingcircus.next_medoid_and_median() - flyingcircus.i_median() - flyingcircus.i_medoid() - flyingcircus.i_medoid_and_median() rr9F)r r^r%)rrrrerlr<r#r) rr^r`rMrr;r"rxrr;s rui_medoid_and_medianr6,sH %[ z" , 1GAt5feZ 1 GW 1!eu 5>51%j GS  rwctjddgtjddgtddgi}t |}||vr ||d}nt dj ||rt|trx|jd rLt|td d }tj||}t|t||z}|St d j | t|ttfr||z}||||z |z|z z }|Stjd j |||S)a Align (round) a number to a multiple of the specified base. The resulting number is computed using the formula: num = num + func(num % base / base) * base - num % base where `func` is a rounding function, as determined by `mode`. Args: num (int|float): The input number. base (int|float|str|None): The number to align to. If int, then calculate a multiple of `align` close to `num`. If str, possible options are: - 'powX' (where X >= 2 must be an int): calculate a power of X that is close to `num`. The exact number being calculated depends on the value of `mode`. mode (int|str|bool): Determine the rounding mode. If str, valid inputs are: - 'upper', '+': round to smallest multiple larger than `num`. - 'lower', '-': round to the largest multiple smaller than `num`. - 'closest', '~': round to the multiple closest to `num`. If int, valid inputs are `+1`, `0` and `-1`, mapping to 'upper', 'closest' and 'lower' respectively. Returns: num (int): The aligned number. Examples: >>> align(9, 2) 8 >>> align(447, 32, mode=1) 448 >>> align(447, 32, mode=-1) 416 >>> align(447, 32, mode=0) 448 >>> align(432, 'pow2', mode=1) 512 >>> align(432, 'pow2', mode=-1) 256 >>> align(432, 'pow2', mode=0) 512 >>> align(45, 90, mode=0) 0 >>> align(6, 'pow2', mode=0) 8 >>> align(6543, 'pow10', mode=0) 10000 >>> align(1543, 'pow10', mode=0) 1000 >>> align(128, 128, mode=1) 128 >>> align(123.37, 0.5, mode=1) 123.5 >>> align(123.37, 0.5, mode=0) 123.5 >>> align(123.37, 0.5, mode=-1) 123.0 >>> align(123.37, None) 123.37 r\r/r^r<r`rrbrcr^NzInvalid align `{align}`)alignz$Will not align `{num}` to `{align}`.)r;r)rdrerfrgr\r"rrrarsrYrlogr_warningswarn)r;r_rrirjrkrmoduluss rurr,sKF GQ< WbM 1~N ! 0E u}tQ077T7BCC dC u%4E ,-hhsD)$#fSk"223 J!!:!A!A!A!MNN sEl +DjG 6'D.)D07: :C J MM@GGtH% & Jrwc$||z|dz|dzzz S)a? Compute the pseudo-ratio of x, y: 1 / ((x / y) + (y / x)) .. math:: \frac{1}{\frac{x}{y}+\frac{y}{x}} = \frac{xy}{x^2+y^2} Args: x (int|float): First input value. y (int|float): Second input value. Returns: result (float): 1 / ((x / y) + (y / x)) Examples: >>> p_ratio(2, 2) 0.5 >>> p_ratio(200, 200) 0.5 >>> p_ratio(1, 2) 0.4 >>> p_ratio(100, 200) 0.4 >>> items = 100, 200 >>> (p_ratio(*items) == p_ratio(*items[::-1])) True r9rrs rup_ratior,s6 Ea1fqAvo &&rwcTdtdtj|dDz S)a Compute the generalized pseudo-ratio of x_i: 1 / sum_ij [ x_i / x_j ] .. math:: \frac{1}{\sum_{ij} \frac{x_i}{x_j}} Args: values (Iterable[int|float]): Input values. Returns: result (float): 1 / sum_ij [ x_i / x_j ] Examples: >>> gen_p_ratio((2, 2, 2, 2, 2)) 0.05 >>> gen_p_ratio((200, 200, 200, 200, 200)) 0.05 >>> gen_p_ratio((1, 2)) 0.4 >>> gen_p_ratio((100, 200)) 0.4 >>> values1 = [x * 10 for x in range(2, 10)] >>> values2 = [x * 1000 for x in range(2, 10)] >>> gen_p_ratio(values1) - gen_p_ratio(values2) < 1e-10 True >>> items = list(range(2, 10)) >>> gen_p_ratio(values2) - gen_p_ratio(items[::-1]) < 1e-10 True r/c3,K|] \}}||z ywrrrrHr7s rurzgen_p_ratio..+-sGTQ1q5Grr9)rVrrrs ru gen_p_ratior -s'< sGY%;%;FA%FGG GGrwc|t|trdndn|}|D]}|j||}||jS|r(t t t |j|S|j|S)a Split a string using multiple separators. This is achieved by replacing all (secondary) separators with a base separator, and finally split using the base separator. Args: text (str|bytes|bytearray): The input string. seps (Iterable[str|bytes|bytearray]): The additional separators. sep (str|bytes||bytearrayNone): The separator for the final splitting. If None, uses `.split(None)` default behavior, i.e. splits blank character (' ', ' ', ' ') simultaneously. filter_empty (bool): Remove empty string from the results. Returns: result (list[str|bytes|bytearray]): The split strings. Examples: >>> text = 'no-go to go, where? anti-matter' >>> print(multi_split(text, ('-', ','))) ['no', 'go', 'to', 'go', 'where?', 'anti', 'matter'] >>> print(multi_split(text, ('-', ','), '?')) ['no', 'go to go', ' where', ' anti', 'matter'] >>> print(multi_split(text, ('-', ',', ' '), '?')) ['no', 'go', 'to', 'go', 'where', 'anti', 'matter'] >>> print(multi_split(text, ('-', ',', ' '), '?', False)) ['no', 'go', 'to', 'go', '', 'where', '', 'anti', 'matter'] >>> text = b'no-go to go, where? anti-matter' >>> print(multi_split(text, (b'-', b','))) [b'no', b'go', b'to', b'go', b'where?', b'anti', b'matter'] >>> print(multi_split(text, (b'-', b','), b'?')) [b'no', b'go to go', b' where', b' anti', b'matter'] >>> print(multi_split(text, (b'-', b',', b' '), b'?')) [b'no', b'go', b'to', b'go', b'where', b'anti', b'matter'] >>> print(multi_split(text, (b'-', b',', b' '), b'?', False)) [b'no', b'go', b'to', b'go', b'', b'where', b'', b'anti', b'matter'] r )rrareplacerZrrrT)rsepssep filter_empty_sepsep_s ru multi_splitr/-svV8;{:dC(CdD(||D$'( {zz| F4C122zz#rwc2|D]}|j|}|S)a$ Perform multiple replacements in a string. The replaces are concatenated together, therefore the order may matter. Args: text (str|bytes|bytearray): The input string. replaces (tuple[tuple[str|bytes|bytearray]]): The replacements. Format: ((, ), ...). Returns: text (str|bytes): The string after the performed replacements. Examples: >>> multi_replace('X Y', (('X', 'flying'), ('Y', 'circus'))) 'flying circus' >>> multi_replace('x-x-x-x', (('x', 'est'), ('est', 'test'))) 'test-test-test-test' >>> multi_replace('x-x-', (('-x-', '.test'),)) 'x.test' >>> multi_replace('x-x-', (('x', 'test'), ('te', 'be'))) 'best-best-' >>> multi_replace('x-x-', (('te', 'be'), ('x-', 'test-'))) 'test-test-' >>> multi_replace(b'X Y', ((b'X', b'flying'), (b'Y', b'circus'))) b'flying circus' >>> multi_replace(b'x-x-x-x', ((b'x', b'est'), (b'est', b'test'))) b'test-test-test-test' >>> multi_replace(b'x-x-', ((b'-x-', b'.test'),)) b'x.test' >>> multi_replace(b'x-x-', ((b'x', b'test'), (b'te', b'be'))) b'best-best-' >>> multi_replace(b'x-x-', ((b'te', b'be'), (b'x-', b'test-'))) b'test-test-' )r)rreplacesrs ru multi_replacerg-s)P&t||W%& KrwcNtdjfd|DS)a Perform multiple replacements of single characters in a string. The replaces are concatenated together, therefore the order may matter. Args: text (str): The input string. replaces (tuple[tuple[str]]|dict): The listing of the replacements. Format: ((, ), ...) where must be a single char. Returns: text (str): The string after the performed replacements. Examples: >>> multi_replace_char('X Y', (('X', 'flying'), ('Y', 'circus'))) 'flying circus' >>> multi_replace_char('X Y', (('Y', 'circus'), ('X', 'flying'))) 'flying circus' >>> multi_replace_char('x-y-x-y', (('x', 'flying'), ('y', 'circus'))) 'flying-circus-flying-circus' >>> multi_replace_char('x-y-x-y', (('x', 'flying'), ('g', 'circus'))) 'flying-y-flying-y' >>> multi_replace_char('x-g-x-g', (('x', 'flying'), ('g', 'circus'))) 'flying-circus-flying-circus' >>> multi_replace_char('x-x-', (('x-', 'bye'),)) 'x-x-' r8c3BK|]}j||ywr)get)rr'rs rurz%multi_replace_char..-s4!8<<1%4r)r r )rrs `rumulti_replace_charr-s#<H~H 774t4 44rwctt|dzDcgc]'}tt|dzDcgc]}dc})}}d}g}t|D]\}}t|D]n\} } || k(s ||| dz} | ||dz| dz<| |kDr"g}| }|j||| z dz|dzL| |k(sR|j||| z dz|dzp||St ||Scc}wcc}w)ao Find the longest common consecutive subsequence(s). This version works for two Sequences. This is known as the `longest common substring` problem, or LCS for short. Args: seq1 (Sequence): The first input sequence. Must be of the same type as seq2. seq2 (Sequence): The second input sequence. Must be of the same type as seq1. sorting (callable): Sorting function passed to 'sorted' via `key` arg. Returns: commons (list[Sequence]): The longest common subsequence(s). Examples: >>> common_subseq_2('academy', 'abracadabra') ['acad'] >>> common_subseq_2('los angeles', 'lossless') ['los', 'les'] >>> common_subseq_2('los angeles', 'lossless', lambda x: x) ['les', 'los'] >>> common_subseq_2((1, 2, 3, 4, 5), (0, 1, 2)) [(1, 2)] r/rr/)r{rrrrl) seq1seq2sortingrcounterrcommonsi1item1i2item2tmps rucommon_subseq_2r-s>;@D A :NOQ5TQ/0a0OGOGGt_ > E"4 >IB~bk"o)*-QQ'= G!GNN4S1 R!V#<=G^NN4S1 R!V#<= > >g7++#1OsC1 C, C1,C1c t|}t|g}|D]b}g}|D]W}t|||}t|dk(st|dt|dk(s<|j t|||Y|}d|S)a Find the longest common consecutive subsequence(s). This version works for an Iterable of Sequences. This is known as the `longest common substring` problem, or LCS for short. Args: seqs (Iterable[Sequence]): The input sequences. All the items must be of the same type. sorting (callable): Sorting function passed to 'sorted' via `key` arg. Returns: commons (list[Sequence]): The longest common subsequence(s). Examples: >>> common_subseq(['academy', 'abracadabra', 'cadet']) ['cad'] >>> common_subseq(['los angeles', 'lossless', 'les alos']) ['los', 'les'] >>> common_subseq(['los angeles', 'lossless', 'les alos', 'losles']) ['los', 'les'] >>> common_subseq(['los angeles', 'lossless', 'dolos']) ['los'] >>> common_subseq([(1, 2, 3, 4, 5), (1, 2, 3), (0, 1, 2)]) [(1, 2)] r)rrrrr)rrrrtmpscommonrs ru common_subseqr-s: :DDzlG DF!&$8C4yA~SVDG !< OFD'BC D  Nrwcpt|tjxrt|tj S)a Check if a file object is in binary mode. Args: file_obj (File): The input file. Returns: result (bool): The binary mode status. Examples: >>> with open(__file__, 'rb') as file_obj: ... is_bin_file(file_obj) True >>> with open(__file__, 'r') as file_obj: ... is_bin_file(file_obj) False >>> is_bin_file(io.BytesIO(b'ciao')) True >>> is_bin_file(io.StringIO('ciao')) False )rioIOBase TextIOBasefile_objs ru is_bin_filer.s-, h * 7h 667rwc@t|jdtS)a@ Check if reading from a file object will return bytes. Args: file_obj (File): The input file. Returns: result (bool): The result of the check. Examples: >>> is_reading_bytes(io.BytesIO(b'ciao')) True >>> is_reading_bytes(io.StringIO('ciao')) False r)rreadrrs ruis_reading_bytesr1.s hmmA& ..rwcF |jdy#t$rYywxYw)aA Check if writing from a file object will require bytes. Args: file_obj (File): The input file. Returns: result (bool): The result of the check. Examples: >>> is_writing_bytes(io.BytesIO(b'ciao')) True >>> is_writing_bytes(io.StringIO('ciao')) False rwTF)writerrs ruis_writing_bytesrE.s, s s   )on_errorc td|D}td|D}t||S#tj$r|cYSwxYw)aA Determine if two or more file objects refer to the same file. Args: files (Iterable[file]): The input file objects. grouper (callable): Determine how to group multiple comparisons. Must accept the following signature: grouper(*Iterable[bool]): bool Can be either `all` or `any`, or any callable with the supported signature. on_error (bool): Determine what to do if `fileno` is unsupported. Returns: result (bool): If the the two file objects refer to the same file. Examples: >>> same_file(all, open(__file__, 'r'), open(__file__, 'r')) True >>> same_file(all, open(__file__, 'r'), io.StringIO('FlyingCircus')) False >>> same_file(all, io.StringIO('fc'), io.StringIO('fc')) False c3bK|]'}tj|j)ywr)rpfstatfileno)rfile_s rurzsame_file..z.sB5bhhu||~.Bs-/c3LK|]}|j|jfywr)st_inost_dev)rrys rurzsame_file..~.sLd T[[9Ls"$)rrrUnsupportedOperation)rrfilesstatsinodes_devicess ru same_filer^.sR66BEBBLeLLWn55  " "s2A  A c#dK|r|jd |j|}|sy|w)u^ Yields the data within a file in blocks of given (max) size. For non-binary file objects, the size of the block may be reduced as a result of multi-byte support in the encoding. The last block may have a smaller size regardless of the opening mode. Args: file_obj (file): The input file. size (int|None): The block size. If int, the file is yielded in blocks of the specified size. If None, the file is yielded at once. reset_offset (bool): Reset the file offset. If True, starts reading from the beginning of the file. Otherwise, starts reading from where the file current position is. Yields: block (bytes|str): The data within the blocks. Examples: >>> src = 'flyingcircus-' * 4 >>> tgt = ''.join(blocks(io.StringIO(src), 3)) >>> print(tgt) flyingcircus-flyingcircus-flyingcircus-flyingcircus- >>> print(src == tgt) True >>> src = b'flyingcircus-' * 4 >>> tgt = b''.join(blocks(io.BytesIO(src), 3)) >>> print(tgt) b'flyingcircus-flyingcircus-flyingcircus-flyingcircus-' >>> print(src == tgt) True >>> src = 'φλυινγκιρκυσ-' * 4 >>> tgt = ''.join(blocks(io.StringIO(src), 3)) >>> print(tgt) φλυινγκιρκυσ-φλυινγκιρκυσ-φλυινγκιρκυσ-φλυινγκιρκυσ- >>> print(src == tgt) True >>> with open(__file__, 'r') as file_obj: ... src = file_obj.read() ... tgt = ''.join([b for b in blocks(file_obj, 100)]) ... src == tgt True >>> with open(__file__, 'rb') as file_obj: ... src = file_obj.read() ... tgt = b''.join([b for b in blocks(file_obj, 100)]) ... src == tgt True rN)seekr)rr  reset_offsetblocks rublocksr.s9p a  d# K s.0c#K|r |jdtjn|j}|dkDr>t ||}||z}|j||j |}||dkDr=yyw)uZ Yields the data within a file in reverse order blocks of given (max) size. Note that: - the content of the block is NOT reversed. - files opened in text mode are not supported! Args: file_obj (file): The input file. size (int|None): The block size. If int, the file is yielded in blocks of the specified size. If None, the file is yielded at once. reset_offset (bool): Reset the file offset. If True, starts reading from the end of the file. Otherwise, starts reading from where the file current position is. Yields: block (bytes|str): The data within the blocks. Examples: >>> src = 'flyingcircus' * 4 >>> my_blocks = list(blocks_r(io.StringIO(src), 12)) >>> tgt = ''.join(my_blocks[::-1]) >>> print(my_blocks) ['flyingcircus', 'flyingcircus', 'flyingcircus', 'flyingcircus'] >>> print(src) flyingcircusflyingcircusflyingcircusflyingcircus >>> print(tgt) flyingcircusflyingcircusflyingcircusflyingcircus >>> print(src == tgt) True >>> src = b'flyingcircus' * 4 >>> my_blocks = list(blocks_r(io.BytesIO(src), 12)) >>> tgt = b''.join(my_blocks[::-1]) >>> print(my_blocks) [b'flyingcircus', b'flyingcircus', b'flyingcircus', b'flyingcircus'] >>> print(src) b'flyingcircusflyingcircusflyingcircusflyingcircus' >>> print(tgt) b'flyingcircusflyingcircusflyingcircusflyingcircus' >>> print(src == tgt) True >>> src = 'φλυινγκιρκυσ' * 4 >>> my_blocks = list(blocks_r(io.StringIO(src), 12)) >>> tgt = ''.join(my_blocks[::-1]) >>> print(my_blocks) ['φλυινγκιρκυσ', 'φλυινγκιρκυσ', 'φλυινγκιρκυσ', 'φλυινγκιρκυσ'] >>> print(src) φλυινγκιρκυσφλυινγκιρκυσφλυινγκιρκυσφλυινγκιρκυσ >>> print(tgt) φλυινγκιρκυσφλυινγκιρκυσφλυινγκιρκυσφλυινγκιρκυσ >>> print(src == tgt) True # THIS IS NOT SUPPORTED! # >>> with open(__file__, 'r') as file_obj: # ... src = file_obj.read() # ... tgt = ''.join([b for b in blocks_r(file_obj, 100)][::-1]) # ... src == tgt # True >>> with open(__file__, 'rb') as file_obj: ... src = file_obj.read() ... tgt = b''.join([b for b in blocks_r(file_obj, 100)][::-1]) ... src == tgt True rN)rrpSEEK_ENDtellrr)rr rr  block_sizers rublocks_rr.slR/;X]]1bkk * F 1*& * f j) 1*s A4A97A9cPt|ttfrt|g|i|S|S)a" Automatically open a file if a path is provided. Args: file_ (str|bytes|file): The file path or file object. *_args: Positional arguments for `open()`. **_kws: Keyword arguments for `open()`. Returns: file_ (file): The opened file object. )rraropen)rrrs ru auto_openr/s3 ec5\ *  & & &6056rw@ct|d}||j|||t|zt|z}t j |}t j ||j|} ||ur|j| S)a! Read data from stream. Args: in_file (str|bytes|file): The input file. Can be either a valid file path or a readable binary file object. See `flyingcircus.auto_open()` for more details. offset (int|None): The offset where to start reading. dtype (str): The data type to read. Accepted values are: - 'bool': boolean type (same as: '?', 1B) - 'char': signed char type (same as: 'b', 1B) - 'uchar': unsigned char type (same as: 'B', 1B) - 'short': signed short int type (same as: 'h', 2B) - 'ushort': unsigned short int type (same as: 'H', 2B) - 'int': signed int type (same as: 'i', 4B) - 'uint': unsigned int type (same as: 'I', 4B) - 'long': signed long type (same as: 'l', 4B) - 'ulong': unsigned long type (same as: 'L', 4B) - 'llong': signed long long type (same as: 'q', 8B) - 'ullong': unsigned long long type (same as: 'Q', 8B) - 'float': float type (same as: 'f', 4B) - 'double': double type (same as: 'd', 8B) - 'str': c-str type (same as: 's', 'p') See Python's `struct` module for more information. num_blocks (int): The number of blocks to read. mode (str): Determine the byte order, size and alignment. Accepted values are: - '@': endianness: native, size: native, align: native. - '=': endianness: native, size: standard, align: none. - '<': endianness: little, size: standard, align: none. - '>': endianness: big, size: standard, align: none. - '!': endianness: network, size: standard, align: none. whence (int): Where to reference the offset. Accepted values are: - '0': absolute file positioning. - '1': seek relative to the current position. - '2': seek relative to the file's end. Returns: data (tuple): The data read. rb) rrra DTYPE_STRstructcalcsize unpack_fromrclose) in_filedtyper num_blocksr whence in_file_obj struct_format read_sizers ru read_streamr-/sbGT*K (3z?*Yu-==M .I   m[-=-=i-H IDk! Krwc t|d}||j||g} |jdjd}||dk(rn|j |:dj |}||ur|j |S)aW Read a C-type string from file. Args: in_file (str|bytes|file): The input file. Can be either a valid file path or a readable binary file object. See `flyingcircus.auto_open()` for more details. offset (int|None): The offset where to start reading. whence (int): Where to reference the offset. Accepted values are: - '0': absolute file positioning. - '1': seek relative to the current position. - '2': seek relative to the file's end. Returns: text (str): The string read. rr/r3r8)rrrrrr r)rr rrrxr?rs ru read_cstrrj/s*GT*K ( F    Q  & &w / 9T  MM!   776?Dk! Krwcj| t|nd}| t|ni}|rdnd}t|d|z}t|d|z} tt|| } | r-|j } || g|i|} | j n|dkr&|D] } || g|i|} | j| f"n]|dkDr/t||D]} || g|i|} | j | !n)| j ||j g|i|||ur|j|| ur| jyy)a Process the content of the input file and write it to the output file. Note: `in_file` and `out_file` should be different! Args: in_file (str|bytes|file): The input file. Can be either a valid file path or readable file object. Should not be the same as `out_file`. See `flyingcircus.auto_open()` for more details. out_file (str|bytes|file): The output file. Can be either a valid file path or writable file object. Should not be the same as `in_file`. See `flyingcircus.auto_open()` for more details. func (callable): The conversion function. Must accept a string or bytes (depending on `as_binary`) as first argument: func(str|bytes, *args, **kws): str|bytes args (Iterable|None): Positional arguments for `func()`. kws (Mappable|None): Keyword arguments for `func()`. block_size (int): The block size to use. If positive, apply `func` iteratively on input blocks of the specified size. If negative, apply `func` iteratively on each line. If zero, apply `func` on the entire input at once. as_binary (bool): Force binary I/O operations. If True, the first argument of `func` must be of type `bytes`. Otherwise, must be of type `str`. Returns: None. Examples: >>> text = 'flyingcircus-' * 4 >>> i_file = io.StringIO(text) >>> o_file = io.StringIO('') >>> process_stream(i_file, o_file, str.upper) >>> pos = o_file.seek(0) >>> print(o_file.read()) FLYINGCIRCUS-FLYINGCIRCUS-FLYINGCIRCUS-FLYINGCIRCUS- >>> i_file = io.BytesIO(text.encode()) >>> o_file = io.BytesIO(b'') >>> process_stream(i_file, o_file, bytes.upper) >>> pos = o_file.seek(0) >>> print(o_file.read()) b'FLYINGCIRCUS-FLYINGCIRCUS-FLYINGCIRCUS-FLYINGCIRCUS-' >>> i_file = io.StringIO(text) >>> o_file = io.StringIO('') >>> process_stream( ... i_file, o_file, lambda x: '*' if x in 'irc' else x, ... block_size=1) >>> pos = o_file.seek(0) >>> print(o_file.read()) fly*ng****us-fly*ng****us-fly*ng****us-fly*ng****us- NrrIr8rr:r) rr rrrrr writelinesrr)rout_filerrrr as_binarybin_moder out_file_objinput_equals_outputcontentliners ruprocess_streamr/s]B*5;D$s)BCsRHGS8^4KXsX~6L#ClC""$w--- ># 1D/4/3/''0 1!^ Z8 *U1T1S1""5) *   tK$4$4$6EEE Fk!|#$rwc8|}t|d5}|jdt||D]}|j| ddd|j }|r||}|r!t |t r|j|}|S#1swYHxYw)a Compute the hash of a file. Args: in_file (str|bytes|file): The input file. Can be either a valid file path or a readable binary file object. See `flyingcircus.auto_open()` for more details. hash_algorithm (callable): The hashing algorithm. This must support the methods provided by `hashlib` module, like `md5`, `sha1`, `sha256`, `sha512`. filtering (callable|None): The filtering function. If callable, must have the following signature: filtering(bytes): bytes|str. If None, no additional filering is performed. coding (str): The coding for converting the returning object to str. If str, must be a valid coding. If None, the object is kept as bytes. block_size (int|None): The block size. See `size` argument of `flyingcircus.blocks` for exact behavior. Returns: hash_key (str|bytes): The result of the hashing. rrN)rrrrr7rrr) rhash_algorithm filteringcodingrhash_objrrhash_keys ru hash_filer/s<H 7D !#X aHj1 #E OOE " ## HX& *Xu-??6* O##s 4BBc4t|jSr)reprr!rs rurr0sT!W^^-rwc||}||j}|r||}|r!t|tr|j|}|S)aj Compute the hash of an object. Args: obj: The input object. serializer (callable): The function used to convert the object. Must have the following signature: serializer(Any): bytes hash_algorithm (callable): The hashing algorithm. This must support the methods provided by `hashlib` module, like `md5`, `sha1`, `sha256`, `sha512`. filtering (callable|None): The filtering function. If callable, must have the following signature: filtering(bytes): bytes. If None, no additional filering is performed. coding (str): The coding for converting the returning object to str. If str, must be a valid coding. If None, the object is kept as bytes. Returns: hash_key (str|bytes): The result of the hashing. )r7rrr)r+ serializerrrr obj_bytesrs ru hash_objectr0sL83Ii(//1HX& *Xu-??6* Orwz {hash_key}.pc|r t|ni}t||f}tjj |t |}tjj |r!|st|d5} || } ddd| S|di|} t|d5} || | ddd| S#1swY SxYw#1swY| SxYw)ar Compute or load from cache the result of a computation. Args: func (callable): The computation to perform. kws (dict|None): Keyword arguments for `func`. dirpath (str): The path of the caching directory. filename (str): The filename of the caching file. This is processed by `format` with `locals()`. save_func (callable): The function used to save caching file. Must have the following signature: save_func(file_obj, Any): None The value returned from `save_func` is not used. load_func (callable): The function used to load caching file. Must have the following signature: load_func(file_obj): Any force (bool): Force the calculation, regardless of caching state. Returns: result (Any): The result of the cached computation. rNwbr)r rrprqr risfiler) rrdirpathfilename save_func load_funcrrrtrrs ru from_cachedrB0s:$s)CD#;'Hww||GT(^4H ww~~h (D ! )Xx(F ) M (D ! (X h ' ( M  ) M ( Ms3 B. B;.B8;Cc#Kt|}|rdnd}|rdnd}|} t||} |st} nt} | |fi| D]m} | j |} | r|s | | dz| d<n | d| z| d<| |sdnd} |s t dddn t ddd}| |D]}|s|r||r|n|zo| s|s | |r|n|zy y w) a Flexible function for reading lines incrementally. Args: file_obj (file): The input file. reverse (bool): Read the file in reverse mode. If True, the lines will be read in reverse order. This requires a binary file object. The content of each line will NOT be reversed. skip_empty (bool): Skip empty lines. append_newline (bool): block_size (int|None): The block size. If int, the file is processed in blocks of the specified size. If None, the file is processed at once. reset_offset (bool): Reset the file offset. If True, starts reading from the beginning of the file. Otherwise, starts reading from where the file current position is. This is passed to `blocks()` or `blocks_r()` (depending on the value of reverse). Yields: line (str|bytes): The next line. Examples: >>> with open(__file__, 'rb') as file_obj: ... lines = [l for l in readline(file_obj, False)] ... lines_r = [l for l in readline(file_obj, True)][::-1] ... lines == lines_r True   rwr8)r rrr<r/N)rr rrrZr)rr  skip_emptyappend_newlinerris_bytesnewliner remainderblock_generator_kwsblock_generatorrlinesmaskrs rureadlinerm0sJ )HeTGCEIJ\J  " A-@A D G$ $uQx/a!"I 1b G"3 &-uQA5Q3C$K DD:gUCC D D n7%@@#s BC" Cc #Kd} tj|D] }tjj||} tj| } | j } ||tjj | xrN||tjj| xr&||t| xr||t| } | s| | ftjj| s|dk7st| |||||dz |} | D] \}}||f y#t$r}|||Yd}~yd}~wwxYww)a Recursively walk through sub-paths of a base directory. This produces a generator for the next sub-path item. Args: base (str): Directory where to operate. follow_links (bool): Follow links during recursion. follow_mounts (bool): Follow mount points during recursion. allow_special (bool): Include special files. allow_hidden (bool): Include hidden files. max_depth (int): Maximum depth to reach. Negative for unlimited. on_error (callable): Function to call on error. Yields: result (tuple): The tuple contains: - path (str): Path to the next object. - stats (stat_result): File stats information. Returns: None. c|xs| xr| Srr)flagrUs ru_or_not_and_notziwalk2.._or_not_and_not0s-4x-I-rwrr/N) rplistdirrqr ryst_modeislinkismountrrvisdiriwalk2OSError)r_ follow_links follow_mounts allow_special allow_hiddenrrrr-rqrrallowr next_path next_statserrors rurr0sBF.JJt$ 8D77<<d+DGGDME==D bggnnT.BC@ rwwt/DE@ {4/@A@ j.>?  Ek!77==& A~%+ , )<Q$&& 6@81Iz"+Z"778% 8*    UOsAECD.%D.D.'D.-E. E 7 EEE  Ec Lt|||||||Dcgc]}|c}Scc}w)a Recursively walk through sub paths of a base directory. This differs from `iwalk2()` in that it returns a list. Args: base (str): Directory where to operate. follow_links (bool): Follow links during recursion. follow_mounts (bool): Follow mount points during recursion. allow_special (bool): Include special files. allow_hidden (bool): Include hidden files. max_depth (int): Maximum depth to reach. Negative for unlimited. on_error (callable): Function to call on error. Returns: items (list[tuple]): The list of items. Each item contains the tuple with: - path (str): Path to the next object. - stats (stat_result): File stats information. )r r!r"r#rr)r)r_r r!r"r#rrrs ruwalk2r)0s78$ !#,h 0 1TD 11 1s !cd} tj|}tjj |d}tjj|\}}|r ||}nvd}tj djtjD]A}|jd}tjj||}||}|s?|}n|g|ddz|fS#t$rYwxYw)a& Determine the full path of an executable, if possible. It mimics the behavior of the POSIX command `which`. This has a similar behavior as `shutil.which()` except that it works on a list of arguments as returned by `shlex.split()` where the first item is the command to test. Args: args (str|list[str]): Command to execute as a list of tokens. If str this is filtered (tokenized) by `shlex.split()`. Otherwise, assumes an input like the output of `shlex.split()`. Returns: args (str|list[str]): Command to execute as a list of tokens. The first item of the list is the full path of the executable. If the executable is not found in path, returns the first token of the input. Other items are identical to input, if the input was a str list. Otherwise it will be the tokenized version of the passed string, except for the first token. is_valid (bool): True if path of executable is found, False otherwise. ctjj|xr$tj|tjSr)rprqraccessX_OK) file_paths ru is_executablezwhich..is_executable-1s)ww~~i(JRYYy"''-JJrwrFr"r/N) shlexrZr rprq expanduserenvironpathsepstripr )rr/cmdrris_validrs ruwhichr81s4K {{4  ''  T!W %C c*GX %zz&)// ; GmmC(G'',,w,C$S)H   548 X %%!    sC** C65C6callzutf-8c d\}} } t|\}} | r@tdj|rdnddj|||rtnt dn,tdjt t||sb| r_|#td j||t d tj||r|d k(stjnd|d k7rtjnd|d k(rtjntjd} |d k(r|sd} | jk| jjj|} | | z } t| ddt jj#| jk| j%}n|d k(r| j'|r|j)|nd\} } | j|} | j|} | rt| |t dd| rt| |t dd| j%}n*| j+tdj||rt,j.j1|d}| j2}| df| dffD]H\}}|s t5|}t7|d5}|j9|j)|dddJ|| | fS#1swYYxYw)a Execute command and retrieve/print output at the end of execution. Better handles `stdin`, `stdout` and `stderr`, as well as timeout, dry-run and verbosity compared to the many alternatives (as provided by the `subprocess` module, `os.system()`, `os.spawn*()`). For some applications the high-level API provided by `subprocess.run()` may be more appropriate. Args: cmd (str|Iterable[str]): The command to execute. If str, must be a shell-compatible invocation. If Iterable, each token must be a separate argument. in_pipe (str|None): Input data to be used as stdin of the process. mode (str): Set the execution mode (affects the return values). Allowed modes: - 'spawn': Spawn a new process. stdout and stderr will be lost. - 'call': Call new process and wait for execution. Once completed, obtain the return code, stdout, and stderr. - 'flush': Call new process and get stdout+stderr immediately. Once completed, obtain the return code. timeout (float): Timeout of the process in seconds. encoding (str): The encoding to use. log (str): The template filename to be used for logs. If None, no logs are produced. dry (bool): Print rather than execute the command (dry run). verbose (int): Set level of verbosity. Returns: ret_code (int|None): if mode not `spawn`, return code of the process. p_stdout (str|None): if mode not `spawn`, the stdout of the process. p_stderr (str|None): if mode is `call`, the stderr of the process. )NNN{} {}z$$>>rmediumz%W: `{}` is not in available in $PATH.Nz< {}highestflushspawnr9F)stdinstdoutstderrshellr8)fmttendhigh)rEz)E: mode `{}` and `in_pipe` not supported.routerrr)r8rrr r r rr subprocessPopenPIPESTDOUTpollrBrrsysr?wait communicater!killrprqrrpidrrr)r6in_pipertimeoutencodingrdryverboseret_codep_stdoutp_stderrr7procout_buffr-rSstreamsource log_filepathfileobjs ruexecuterbG1sV$4 Hh#JMC GNN34D#((3- @ 3ZHX,> @ 3 : :4S ? KL 8    g&), . %,TW_*//$&*go:??4&*fn:??*:K:K  7?7H))+%;;//188BH$H22.   " ))+% yy{H V^!%!1!1,3x("? Hh  x0Hx0HHgx'7bAHgx'7bAyy{H IIK ;BB4H I 77##CF+D((C$,e#4x6G"H ?#'9LlD1?W fmmH&=>?? ? Xx ''??s =!K--K6 <c b| t|nd}| t|ni}|stjdz}t |}d}t j j } |d|D cgc]} tj| d} } | D]?} tdjdd j| j|td At | } d }|sCt | }| D cgc]} | j| } } t | }||z }|dkDr||z }|| | |zD cgc]} tj| d}} |D]?} tdjdd j| j|td A| t |z } | |z } t | }t j j | z }td }t||t t#|r||i|||k(rd}nt%j&||sByycc} wcc} wcc} w) a Spawn parallel processes and wait until all processes are completed. Args: cmds (Sequence[str|Iterable[str]): The commands to execute. Each item must be a separate command. If the item is a str, it must be a shell-compatible invocation. If the item is an Iterable, each token must be a separate argument. pool_size (int|None): The size of the parallel pool. This corresponds to the maximum number of concurrent processes spawned by the function. poll_interval (int): The poll interval in s. This is the time between status updates in seconds. callback (callable|None): A callback function. This is called after each poll interval. callback_args (Iterable|None): Positional arguments for `callback()`. callback_kws (Mappable|None): Keyword arguments for `callback()`. verbose (int): Set level of verbosity. Returns: None. Nrr/rT)rDr;r<rr=FzZI: {num_processed} / {num_total} processed ({num_running} running) - Elapsed: {elapsed_dt})rr multiprocessing cpu_countrdatetimenowrJrKrrr rr rNrr rtimesleep)cmds pool_size poll_intervalcallback callback_args callback_kwsrX num_total num_processedbegin_dtr6procsr\ num_submitteddone num_batch num_runningnum_done new_procs elapsed_dtrs ruparallel_executer|1s?<-:,EE-(2M*6*B4 &L #--/!3 D IM  $$&H59*95E G.1 D) GE G) GNN4$))!4 5 Xh' ))JM DJ "'?$499;+>??%j {* a< X %M mh.FGI  D1III" 1GNN4$)))<=Xh/1 1 S^ +M Y Ee*K&&**,x7  ?@ D':& H  m 4| 4 I %D JJ} %5 G@ Is*H"-H'H'-H,c4tjjtjjtjj |}tjj |s|rtj ||St|S)aD Get the expanded absolute path from its short or relative counterpart. Args: path (str): The path to expand. create (bool): Automatically create the path if not exists. Returns: new_path (str): the expanded path. Raises: OSError: if the expanded path does not exists. )rprqabspathrealpathr2existsmakedirsr)rqcreatenew_paths rurr1sf wwrww//0B0B40HIJH 77>>( #  KK ! OM Orwc |tdj||tdtj|Dcgc]c}tj j tj j||r$|r tj j||n|e}}ntdj|rd|zdznd||tdtj|Dcgc]S}|jj|jr$|r tj j||n|U}}|r t|}|Scc}wcc}w)a Retrieve a sorted list of files matching specified extension and pattern. Args: path (str): Path to search. file_ext (str|None): File extension. Empty string for all files. None for directories. full_path (bool): Include the full path. sorting (bool): Sort results alphabetically. verbose (int): Set level of verbosity. Returns: list[str]: List of file names/paths zScanning for dirs on: {}debugzScanning for {} on: {}`r) rrr rprrqrr r^endswithrl)rqfile_ext full_pathrrXr filepathss rurr2s5( ' . .t 4 Xg& (JJt,<ww}}RWW\\$9:-6BGGLLx (8 C< < % , ,&.S8^c !GT C Xg& ( JJt,<~~(()9:-6BGGLLx (8 C< <9% <>> add_extsep('txt') '.txt' >>> add_extsep('.txt') '.txt' >>> add_extsep('') '.' >>> add_extsep(None) '.' r8rH)extextseps ru add_extsepr2s.. {..(B ;;f ;;rwc|}|ft|}|s-|jj|jn|j|}|r|dt| }||fSd}||fS|rhd}d}|r^tj j |\}}|r5|r3|djxr|dj }|r |}||z}nd}|r^||fStj j |\}}||fS)a. Split the filepath into a pair (root, ext), so that: root + ext == path. root is everything that precedes the first extension separator. ext is the extension (including the separator). It can automatically detect multiple extensions. Since `os.path.extsep` is often '.', a `os.path.extsep` between digits is not considered to be generating and extension. Args: filepath (str): The input filepath. ext (str|None): The expected extension (with or without the dot). If None, it will be obtained automatically. If empty, no split is performed. case_sensitive (bool): Case-sensitive match of old extension. If `ext` is None or empty, it has no effect. auto_multi_ext (bool): Automatically detect multiple extensions. If True, include multiple extensions. If False, only the last extension is detected. If `ext` is not None or empty, it has no effect. Returns: result (tuple): The tuple contains: - root (str): The filepath without the extension. - ext (str): The extension including the separator. Examples: >>> split_ext('test.txt', '.txt') ('test', '.txt') >>> split_ext('test.txt') ('test', '.txt') >>> split_ext('test.txt.gz') ('test', '.txt.gz') >>> split_ext('test_1.0.txt') ('test_1.0', '.txt') >>> split_ext('test.0.txt') ('test', '.0.txt') >>> split_ext('test.txt', '') ('test.txt', '') Nr8Tr/r<F)rr^rrrprqsplitextisdigit) rtrcase_sensitiveauto_multi_extrhas_extr7tmp_filepath_noexttmp_exts ru split_extr2s*\ D o!.."++CIIK8'/'8'8'=  Jc#hY'D& 9#C" 9 CH.0gg.>.>t.D+"G%'$+AJ$6$6$8%E$6r$:$B$B$D FH1%m$H 9((2ID# 9rwcptjj|\}}t||\}}|||fS)a Split the filepath into (root, base, ext). Note that: root + os.path.sep + base + ext == path. (and therfore: root + base + ext != path). root is everything that preceeds the last path separator. base is everything between the last path separator and the first extension separator. ext is the extension (including the separator). Note that this separation is performed only on the string and it is not aware of the filepath actually existing, being a file, a directory, or similar aspects. Args: filepath (str): The input filepath. auto_multi_ext (bool): Automatically detect multiple extensions. Refer to `split_ext()` for more details. Returns: result (tuple): The tuple contains: - root (str): The filepath without the last item. - base (str): The file name without the extension. - ext (str): The extension including the extension separator. Examples: >>> split_path('/path/to/file.txt') ('/path/to', 'file', '.txt') >>> split_path('/path/to/file.tar.gz') ('/path/to', 'file', '.tar.gz') >>> split_path('file.tar.gz') ('', 'file', '.tar.gz') >>> split_path('/path/to/file') ('/path/to', 'file', '') >>> root, base, ext = split_path('/path/to/file.ext') >>> root + os.path.sep + base + ext '/path/to/file.ext' See Also: - flyingcircus.join_path() - flyingcircus.multi_split_path() r)rprqrZr)rtrrbase_extr_rs ru split_pathr2s7`WW]]8,ND((>BID# s?rwc,tjj|\}}t||\}}|rO|jtjj}|ddk(r tjj|d<nd}t |||fzS)a Split the filepath into (subdir, subdir, ..., base, ext). Note that: splits[0] + os.path.sep.join(splits[1:-1]) + ext == path (and therfore e.g.: ''.join(splits) != path). `root` is everything that preceeds the last path separator. `base` is everything between the last path separator and the first extension separator. `ext` is the extension (including the separator). Note that this separation is performed only on the string and it is not aware of the filepath actually existing, being a file, a directory, or similar aspects. Args: filepath (str): The input filepath. auto_multi_ext (bool): Automatically detect multiple extensions. Refer to `split_ext()` for more details. Returns: result (tuple[str]): The parts of the file. If the first char of the filepath is `os.path.sep`, then the first item is set to `os.path.sep`. The first (n - 2) items are subdirectories, the penultimate item is the file name without the extension, the last item is the extension including the extension separator. Examples: >>> multi_split_path('/path/to/file.txt') ('/', 'path', 'to', 'file', '.txt') >>> multi_split_path('/path/to/file.tar.gz') ('/', 'path', 'to', 'file', '.tar.gz') >>> multi_split_path('file.tar.gz') ('file', '.tar.gz') >>> multi_split_path('/path/to/file') ('/', 'path', 'to', 'file', '') >>> splits = multi_split_path('/path/to/file.ext') >>> splits[0] + os.path.sep.join(splits[1:-1]) + splits[-1] '/path/to/file.ext' See Also: - flyingcircus.join_path() - flyingcircus.split_path() rrr8r)rprqrZrrr)rtrrrr_rrs rumulti_split_pathr3sxbWW]]8,ND((>BID# zz"''++& 7b=ggkkDG ;$ $$rwc~|ddrtjj|ddnd|drt|dzSdzS)a Join a list of items into a filepath. The last item is treated as the file extension. Path and extension separators do not need to be manually included. Note that this is the inverse of `split_path()`. Args: texts (Iterable[str]): The path elements to be concatenated. The last item is treated as the file extension. Returns: filepath (str): The output filepath. Examples: >>> join_path(('/path/to', 'file', '.txt')) '/path/to/file.txt' >>> join_path(('/path/to', 'file', '.tar.gz')) '/path/to/file.tar.gz' >>> join_path(('', 'file', '.tar.gz')) 'file.tar.gz' >>> join_path(('path/to', 'file', '')) 'path/to/file' >>> paths = [ ... '/path/to/file.txt', '/path/to/file.tar.gz', 'file.tar.gz'] >>> all(path == join_path(split_path(path)) for path in paths) True >>> paths = [ ... '/path/to/file.txt', '/path/to/file.tar.gz', 'file.tar.gz'] >>> all(path == join_path(multi_split_path(path)) for path in paths) True See Also: - flyingcircus.split_path() - flyingcircus.multi_split_path() Nr<r8)rprqr r)textss ru join_pathr\3sNL+0*RWW\\5": &"&+BiZb " 9:57 9:rwcftjj|}t||||\}}|S)a Remove path AND the extension from a filepath. Args: filepath (str): The input filepath. ext (str|None): The expected extension (with or without the dot). Refer to `split_ext()` for more details. case_sensitive (bool): Case-sensitive match of expected extension. Refer to `split_ext()` for more details. auto_multi_ext (bool): Automatically detect multiple extensions. Refer to `split_ext()` for more details. Returns: root (str): The file name without path and extension. Examples: >>> basename('/path/to/file/test.txt', '.txt') 'test' >>> basename('/path/to/file/test.txt.gz') 'test' )rprqrrr)rtrrrrs rurrrr3s44ww)H#~~7ID# KrwcTt||||\}}||rt|z}|Sdz}|S)a Substitute the old extension with a new one in a filepath. Args: root (str): The input filepath. new_ext (str): The new extension (with or without the dot). ext (str|None): The expected extension (with or without the dot). Refer to `split_ext()` for more details. case_sensitive (bool): Case-sensitive match of expected extension. Refer to `split_ext()` for more details. auto_multi_ext (bool): Automatically detect multiple extensions. Refer to `split_ext()` for more details. Returns: filepath (str): Output filepath Examples: >>> change_ext('test.txt', 'dat', 'txt') 'test.dat' >>> change_ext('test.txt', '.dat', 'txt') 'test.dat' >>> change_ext('test.txt', '.dat', '.txt') 'test.dat' >>> change_ext('test.txt', 'dat', '.txt') 'test.dat' >>> change_ext('test.txt', 'dat', 'TXT', False) 'test.dat' >>> change_ext('test.txt', 'dat', 'TXT', True) 'test.txt.dat' >>> change_ext('test.tar.gz', 'tgz') 'test.tgz' >>> change_ext('test.tar.gz', 'tgz', 'tar.gz') 'test.tgz' >>> change_ext('test.tar.gz', 'tgz', auto_multi_ext=False) 'test.tar.tgz' >>> change_ext('test.tar', 'gz', '') 'test.tar.gz' >>> change_ext('test.tar', 'gz', None) 'test.gz' >>> change_ext('test.tar', '') 'test' r8)rr)rnew_extrrrrts ru change_extr3sA` c>>3ID#gz'*>H O<>>H Orwz{basepath}__{counter}{ext}ctjj|rtdj ||t dt |\}}}tjj||}d}tjj|r0|dz }t|}tjj|r0tdj ||t d|S)aN Generate a non-existing filepath if current exists. Args: filepath (str): The input filepath. out_template (str): Template for the output filepath. The following variables are available for interpolation: - `dirpath`: The directory of the input. - `base`: The input base file name without extension. - `ext`: The input file extension (with leading separator). - `basepath`: The input filepath without extension. verbose (int): Set level of verbosity. Returns: filepath (str) zOLD: {}rGrr/zNEW: {}r=) rprqrrrr rr r)rt out_templaterXrr_rbasepathrs ru next_filepathr3s( ww~~h I  X &&1AB'1s77<<.ggnnX& qLGL)HggnnX& I  X &(1CD OrwcZtjdj||rdnd||S)a Return a string containing a safe filename. Args: text (str): The input string. allowed (str): The valid characters. Must comply to Python's regular expression syntax. replacing (str): The replacing text. group_consecutive (bool): Group consecutive non-allowed. If True, consecutive non-allowed characters are replaced by a single instance of `replacing`. Otherwise, each character is replaced individually. Returns: text (str): The filtered text. Examples: >>> safe_filename('flyingcircus.txt') 'flyingcircus.txt' >>> safe_filename('flyingcircus+12.txt') 'flyingcircus_12.txt' >>> safe_filename('flyingcircus+12.txt') 'flyingcircus_12.txt' >>> safe_filename('flyingcircus+++12.txt') 'flyingcircus_12.txt' >>> safe_filename('flyingcircus+++12.txt', group_consecutive=False) 'flyingcircus___12.txt' >>> safe_filename('flyingcircus+12.txt', allowed='a-zA-Z0-9._+-') 'flyingcircus+12.txt' >>> safe_filename('flyingcircus+12.txt', replacing='-') 'flyingcircus-12.txt' z[^{allowed}]{greedy}r]r8)allowedgreedy)rrr)rr replacinggroup_consecutives ru safe_filenamer4s9J 66&&+>> file_obj = magic_open(__file__, 'rb') )r!rNr/r) importlib import_modulerrrrIOErrorr  ImportError)rtrrzip_module_namesrzip_module_name zip_modules ru magic_openr,4s:%H+  "00AJ&zx@%@4@H MM!  MM!    151D1 O.+> H s>> file_obj = zopen(__file__, 'rb') rIrIrrNr9ssBZr&hrb s1AY&SYr/s7zXzFr!r#rr)rar)rr)rrrrrrrrrrrEXTr!GzipFilerBZ2FileLZMAFile)rtrrr valid_moderrhead gz_by_header bz2_by_header xz_by_header gz_by_ext bz2_by_ext xz_by_exts ruzopenr[4s"R $3d?  0DJH8%84848H    ==$D8{2L!H%B$q)t*;BQq ))+BQr &AA  86L MM! h'*33Js6{4KL x(+44ZG 5MN (#A&// 3t90EFI(#A&// 3v;0GH  9}}XDAH O j{{H4@H Oli}}hT}BH O= D && ! L!M L ! MM! s5F AF2 F/.F/2G GGGG%c t|}d}d}d}t|dkDrtjt|nd}|dkr||z n|}|t|kDs|t|dz  kr||dzz}dj ||}|St|dz  |cxkrdkrnn||z}dj ||}|S|dzdk(rd }dj ||}|S||t |zz}|d krd }dj ||} |S#t tf$r*tjd j |d }Y|SwxYw) a Convert a number into the most informative string within specified limit. Args: val (int|float): The number to be converted to string. max_lim (int): The maximum number of characters allowed for the string. Returns: val_str (str): The string with the formatted number. Examples: >>> compact_num_str(100.0, 3) '100' >>> compact_num_str(100.042, 6) '100.04' >>> compact_num_str(100.042, 9) '100.04200' rBr9r/rz {:.{size}e})r z {:.{size}f}rrz%Could not convert value `{}` to floatNaN) r_r!rdlog10rrYrr"rr)r<max_limextra_char_in_expextra_char_in_decextra_char_in_signorderr%val_strs rucompact_num_strr4s,Cj(+C3 3s8$A03c ,,w 5< 5E2Ca2G,H+H#H &* *E#**3U*;G N%)* *e 9c 9 & &E#**3U*;G N3Y# E#**3U*;G N '#e*4 5Eqy#**3U*;G N z " =DDSIJ Ns$BD 3D ?D +D 5EEc Vt|r |} n0t|tr t|} n| t g|} ndx} }|1r|ffd }|j fdt |dddD} n|j fd|D} dj|| || | S)aB Generate a meaningful string representation of an object. Args: obj (Any): The input object. names (Iterable[str]|None): The attribute names to consider. If None, uses `idir(obj, skip, methods=False, attributes=True)` skip (str|callable): The skip criterion. If str, names starting with it are skipped. If callable, skips when `skip(name)` evaluates to True. base (str|Iterable[str]|callable): The base object name. If str, uses `getattr(obj, base)`. If Iterable[str], uses `get_nested_attr(obj, *base)`. If callable, uses `base(obj)`. If None, the base part is skipped. base_sep (str): The name-to-attributes separator. attr_sep (str): The attributes separator. kv_sep (str): The key-value separator. pre_delim (str): The prefix delimiter. This is prepended to the final string. post_delim (str): The postfix delimiter. This is appended to the final string. Returns: str: A text representation of the object. Examples: >>> print(obj2str(1)) >>> print(obj2str(1, base=None)) >>> print(obj2str(1, ('real', 'imag'))) >>> print(obj2str(1, pre_delim='{', post_delim='}')) {int: denominator=1, imag=0, numerator=1, real=1} >>> print(obj2str(1, pre_delim='')) >>> print(obj2str(1, base_sep='::', attr_sep=',', kv_sep=':')) >>> print(obj2str(1, blacklist=('denominator', 'imag'))) r8c2|j|xs|vSrrH)r-rS blacklists rurJzobj2str..skip,5sq)>TY->>rwc3JK|]\}}dj||ywz{}{}{}N)r)rr-rOkv_seps rurzobj2str...5s,Bd OOD&$ /BrFTc 3pK|]-}t|rdj|t|/ywr)rrr*)rr-rr+s rurzobj2str..25s65d!3 OOD&'#t*< =5s36z {}{}{}{}{})rrrar*r.r rQr) r+r,rJrr_base_sepattr_sepr pre_delim post_delim base_namers ` ` ` ruobj2strr4sj~I D# C& #C/$/ !! H } ! ?}}B"3eT4@BB}}555   9hj ::rwcJ|j|xr|j|S)a Determine if a string is delimited by some characters (decorators). Args: text (str): The text input string. pre_delim (str): initial string decorator. post_delim (str): final string decorator. Returns: has_delim (bool): True if text is delimited by the specified chars. Examples: >>> has_delim('"test"') True >>> has_delim('"test') False >>> has_delim('', '<', '>') True )rsr)rrrs ru has_delimr:5s!. ??9 % C$-- *CCrwc|j|r t|nd}|j|r t| nd}|||S)a Strip initial and final character sequences (decorators) from a string. Args: text (str): The text input string. pre_delim (str): initial string decorator. post_delim (str): final string decorator. Returns: text (str): the text without the specified decorators. Examples: >>> strip_delim('"test"') 'test' >>> strip_delim('"test') 'test' >>> strip_delim('', '<', '>') 'test' N)rsrr)rrrbeginrFs ru strip_delimrU5s?.#ooi8C NdE"mmJ73z? TC c?rwc t|tri|r|j}|s"|j}t d|D}|D]#}t |D]\}}||k(s |dkDccS%t dt|S)a$ Conversion to boolean value. This is especially useful to interpret strings are booleans, because the built-in `bool()` method evaluates to False for empty strings and True for non-empty strings. Args: value (str|Any): The input value. If not string, attempt the built-in `bool()` casting. mappings (Sequence[Sequence]): The string values to map as boolean. Each item consists of an Sequence. Within the inner Sequence, the first element is mapped to False and all other elements map to True. case_sensitive (bool): Perform case-sensitive comparison. strip (bool): Strip whitespaces from input string. If input is not `str`, it has no effect. Returns: result (bool): The value converted to boolean. Raises: ValueError: if the conversion to boolean fails. Examples: >>> to_bool('false') False >>> to_bool('true') True >>> to_bool('0') False >>> to_bool('off') False >>> to_bool('0 ') False >>> to_bool(1) True >>> to_bool(0) False >>> to_bool(0j) False >>> to_bool('False') False >>> to_bool('False', case_sensitive=True) Traceback (most recent call last): .... ValueError: Cannot convert to bool >>> to_bool('False ', strip=False) Traceback (most recent call last): .... ValueError: Cannot convert to bool c3@K|]}td|Dyw)c3<K|]}|jywr)r^)rrs rurz$to_bool...5s9ekkm9sNr)rrTs rurzto_bool..5s#)999)srzCannot convert to bool)rrar5r^rrr"rT)r[mappingsrr5rTrMrs ruto_boolrr5sr% KKMEKKME)'))H  7G%g. !5E>q5L  ! 756 6E{rwct|tr7|r|rt|||r t|||}d}|D] } ||}n||}|S|}|S#tt f$rY*wxYw)a| Convert value to numeric if possible, or strip delimiters from string. Args: text (str|Number): The text input string. pre_delim (str): initial string decorator. post_delim (str): final string decorator. casts (Iterable[callable]): The cast conversion methods. Each callable must be able to perform the desired conversion, or raise either a ValueError or a TypeError on failure. Returns: val (Number): The numeric value of the string. Examples: >>> auto_convert('<100>', '<', '>') 100 >>> auto_convert('<100.0>', '<', '>') 100.0 >>> auto_convert('100.0+50j') (100+50j) >>> auto_convert('1e3') 1000.0 >>> auto_convert(1000) 1000 >>> auto_convert(1000.0) 1000.0 >>> auto_convert('False') False N)rrarrrr")rrrcastsr<casts rurr5sF$ $ :6tY ;D D 4j   ;C J Jz*  sA  AAcR t|d}|S#ttf$rd}Y|SwxYw)a[ Determine if a variable contains a number. Args: val (str): The variable to test. Returns: result (bool): True if the values can be converted, False otherwise. Examples: >>> is_number('<100.0>') False >>> is_number('100.0+50j') True >>> is_number('1e3') True TF)complexrr")r<rs ru is_numberr5s<$  M z " M s &&rcf|dk7r+ttjt|||zSdS)aZ Determine the order of magnitude of a number. Args: val (Number): The input number. base (Number): The base for defining the magnitude order. exp (Number): The exp for defining the magnitude order. Returns: result (int): The order of magnitude according to `(base ** exp)`. Examples: >>> order_of_magnitude(10.0) 1 >>> order_of_magnitude(1.0) 0 >>> order_of_magnitude(0.1) -1 >>> order_of_magnitude(0.0) 0 >>> order_of_magnitude(-0.0) 0 >>> order_of_magnitude(634.432) 2 >>> order_of_magnitude(1024, 2) 10 >>> order_of_magnitude(1234, 10, 3) 1 >>> order_of_magnitude(1234, 2, 10) 1 >>> all(order_of_magnitude(i) == 0 for i in range(10)) True rr)rYrdrr!)r<r_rs ruorder_of_magnituder6s/J47#:3txxC$'3. /D1DrwcRt|}||vr||Sttd)u Get the order corresponding to a given prefix. This works chiefly with SI prefixes. Args: prefix (str): The prefix to inspect. prefixes (Mappable): The conversion table for the prefixes. This must have the form: (prefix, order). Multiple prefixes can point to the same order. Returns: order (int|float): The order associate to the prefix. Raises: IndexError: If no prefix is found in the given prefixes. Examples: >>> [prefix_to_order(x) ... for x in ('', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y')] [0, 3, 6, 9, 12, 15, 18, 21, 24] >>> [prefix_to_order(x) ... for x in ('', 'm', 'µ', 'n', 'p', 'f', 'a', 'z', 'y')] [0, -3, -6, -9, -12, -15, -18, -21, -24] >>> [prefix_to_order(x) for x in ('u', 'µ', 'μ')] [-6, -6, -6] >>> all(prefix_to_order(order_to_prefix(i)) == i ... for i in range(-24, 25, SI_ORDER_STEP)) True See Also: - flyingcircus.order_to_prefix() - flyingcircus.prefix_to_factor() - flyingcircus.factor_to_prefix() - flyingcircus.order_to_factor() - flyingcircus.factor_to_order() zPrefix `{prefix}` not found!)r rr)prefixprefixess ruprefix_to_orderr<6s2PH~H <=>>rwcdtt|}||vr||Sttd)u8 Get the prefix corresponding to the order of magnitude. This works chiefly with SI prefixes. Args: order (int): The order of magnitude. prefixes (Mappable): The conversion table for the prefixes. This must have the form: (prefix, order). Must be 1-to-1. Returns: prefix (str): The prefix for the corresponding order. Raises: ValueError: If no prefix exists for the input order. Examples: >>> [order_to_prefix(i * SI_ORDER_STEP) for i in range(9)] ['', 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y'] >>> [order_to_prefix(-i * SI_ORDER_STEP) for i in range(9)] ['', 'm', 'μ', 'n', 'p', 'f', 'a', 'z', 'y'] >>> order_to_prefix(10) Traceback (most recent call last): ... ValueError: Invalid order `10` for given prefixes. See Also: - flyingcircus.prefix_to_order() - flyingcircus.prefix_to_factor() - flyingcircus.factor_to_prefix() - flyingcircus.order_to_factor() - flyingcircus.factor_to_order() z+Invalid order `{order}` for given prefixes.)rVr r"r)rrreverted_prefixess ruorder_to_prefixr l6s9H(X7 !! ''KLMMrwc ||zS)a Compute the factor from the order (for a given base). Args: order (int|float): The order. base (int|float): The base to use for the order-to-factor conversion. Must be strictly positive. Returns: factor (int|float): The factor. Examples: >>> [order_to_factor(i) for i in range(-5, 6)] [1e-05, 0.0001, 0.001, 0.01, 0.1, 1, 10, 100, 1000, 10000, 100000] >>> [order_to_factor(float(i)) for i in range(-5, 5)] [1e-05, 0.0001, 0.001, 0.01, 0.1, 1.0, 10.0, 100.0, 1000.0, 10000.0] See Also: - flyingcircus.prefix_to_order() - flyingcircus.order_to_prefix() - flyingcircus.prefix_to_factor() - flyingcircus.factor_to_prefix() - flyingcircus.factor_to_order() r)rr_s ruorder_to_factorr 6s6 5=rwcRtttj||S)a Compute the order from the factor (for a given base). Args: factor (int|float): The factor. base (int|float): The base to use for the order-to-factor conversion. Must be strictly positive. Returns: order (int|float): The order. Examples: >>> [factor_to_order(x) for x in (1, 10, 1000, 100000)] [0, 1, 3, 5] >>> [factor_to_order(x) for x in (1.0, 100.0, 10000.0, 123.45)] [0, 2, 4, 2] See Also: - flyingcircus.prefix_to_order() - flyingcircus.order_to_prefix() - flyingcircus.prefix_to_factor() - flyingcircus.factor_to_prefix() - flyingcircus.order_to_factor() )rYrgrdr)rr_s rufactor_to_orderr 6s6 uTXXfd+, --rwc.tt|||S)u Get the order corresponding to a given prefix. This works chiefly with SI prefixes. Args: prefix (str): The prefix to inspect. prefixes (Mappable): The conversion table for the prefixes. This must have the form: (prefix, order). Multiple prefixes can point to the same order. base (int|float): The base to use for the factor. Returns: factor (int|float): The factor associate to the prefix. Examples: >>> [prefix_to_factor(x) for x in ('', 'k', 'M', 'G', 'T', 'P')] [1, 1000, 1000000, 1000000000, 1000000000000, 1000000000000000] >>> [prefix_to_factor(x) ... for x in ('', 'm', 'µ', 'n', 'p', 'f', 'a', 'z', 'y')] [1, 0.001, 1e-06, 1e-09, 1e-12, 1e-15, 1e-18, 1e-21, 1e-24] >>> [prefix_to_factor(x) for x in ('u', 'µ', 'μ')] [1e-06, 1e-06, 1e-06] >>> all(prefix_to_order(order_to_prefix(i)) == i ... for i in range(-24, 25, SI_ORDER_STEP)) True See Also: - flyingcircus.prefix_to_order() - flyingcircus.order_to_prefix() - flyingcircus.factor_to_prefix() - flyingcircus.order_to_factor() - flyingcircus.factor_to_order() )r r)rrr_s ruprefix_to_factorr6sL ?68>> factor_to_prefix(1e12) 'T' >>> [factor_to_prefix(10 ** i) for i in range(-3, 4)] ['m', 'c', 'd', '', 'da', 'h', 'k'] See Also: - flyingcircus.prefix_to_order() - flyingcircus.order_to_prefix() - flyingcircus.prefix_to_factor() - flyingcircus.order_to_factor() - flyingcircus.factor_to_order() )r r )rrr_s rufactor_to_prefixr7s@ ?648( CCrwc6| t|||}|||z|zz S)a Scale a number according to its order of magnitude. Args: val (Number): The input number. base (Number): The base for defining the magnitude order. exp (Number): The exp for defining the magnitude order. order (int|None): The order of magnitude. If None, this is computed from `base` and `exp`. Returns: result (Number): The scaled value. Examples: >>> round(scale_to_order(1234.123), 6) 1.234123 >>> round(scale_to_order(1234.123, 10, 1, 2), 6) 12.34123 >>> round(scale_to_order(1234.123, 10, 3, 2), 6) 0.001234 >>> round(scale_to_order(0.001234, 10, 3, -2), 6) 1234.0 >>> n = 12345.67890 >>> all( ... round(scale_to_order(scale_to_order(n, order=i), order=-i), 5) ... == n ... for i in range(10)) True )r)r<r_rrs ruscale_to_orderr$7s,F }"3c2 $#+%' ''rwcd}d}|tjtjt|z}d| z}|t |z |z}|t|z |kDrt||z|cxkrt|krfn|S||kr]|t |z |z}d||z |z z}|dz }|t|z |kDr*t||z|cxkrt|kr n|S||kr]|S)a Guess the number of decimals in a given float number. Args: val (float): The input value. n_max (int): Maximum number of guessed decimals. base (int): The base used for the number representation. fp (int): The floating point maximum precision. A number with precision is approximated by the underlying platform. The default value corresponds to the limit of the IEEE-754 floating point arithmetic, i.e. 53 bits of precision: log10(2 ** 53) = 16 approximately. This value should not be changed unless the underlying platform follows a different floating point arithmetic. Returns: prec (int): the guessed number of decimals. Examples: >>> guess_decimals(10) 0 >>> guess_decimals(1) 0 >>> guess_decimals(0.1) 1 >>> guess_decimals(0.01) 2 >>> guess_decimals(10.01) 2 >>> guess_decimals(0.000001) 6 >>> guess_decimals(-0.72) 2 >>> guess_decimals(0.9567) 4 >>> guess_decimals(0.12345678) 8 >>> guess_decimals(0.9999999999999) 13 >>> guess_decimals(0.1234567890123456) 16 >>> guess_decimals(0.9999999999999999) 16 >>> guess_decimals(0.1234567890123456, 6) 6 >>> guess_decimals(0.54235, 10) 5 >>> guess_decimals(0x654321 / 0x10000, 16, 16) 4 r9rrr/)rdrerr!rY)r<n_maxr_fpr precr2rHs ruguess_decimalsrM7slF D$))DJJs3x( ))B )C s3x4A Q-# #a#g,"=s1v"= K CG, QZ4 b4i&())   Q-# #a#g,"=s1v"= K CG, Krwc t|}t|}t|dd}||z dz }d}t||}t ||kDr |d| zz}|dz }dj |}n|dkrd}dj |||}|S)a Format a number with the correct number of significant figures. Args: val (str|float|int): The numeric value to be correctly formatted. num (str|int): The number of significant figures to be displayed. keep_zeros (int): The number of zeros to keep after the figures. This is useful for preventing the use of the scientific notation. Returns: val (str): String containing the properly formatted number. Examples: >>> significant_figures(1.2345, 1) '1' >>> significant_figures(1.2345, 4) '1.234' >>> significant_figures(1.234e3, 2) '1200' >>> significant_figures(-1.234e3, 3) '-1230' >>> significant_figures(12345678, 4) '12350000' >>> significant_figures(1234567890, 4) '1.235e+9' >>> significant_figures(-0.1234, 1) '-0.1' >>> significant_figures(0.0001, 2) '1.0e-4' See Also: The 'decimal' Python standard module. rr/r8ze{:+d}rz{val:.{prec}f}{ofm})r<rofm)r_rYrrgr!r)r<r; keep_zerosrrrs rusignificant_figuresr7sJ *C c(C sB *E ;?D C T C 4y:BE6N"Qwooe$  & &3Ts & CC Jrwc t|}t|}|dk7r t|nd}t|dd}t|dd} t|||z |z|}t|||}||fS#t$rt |}t |}Y||fSwxYw)a Outputs correct value/error pairs formatting. Args: val (str|float|int): The numeric value to be correctly formatted. err (str|float|int): The numeric error to be correctly formatted. num (str|int): The precision to be used for the error (usually 1 or 2). keep_zeros (int): The number of zeros to keep after the figures. This is useful for preventing the use of the scientific notation. Returns: val_str (str): The string with the correctly formatted numeric value. err_str (str): The string with the correctly formatted numeric error. Examples: >>> format_value_error(1234.5, 6.7) ('1234.5', '6.7') >>> format_value_error(123.45, 6.7, 1) ('123', '7') >>> format_value_error(12345.6, 7.89, 2) ('12345.6', '7.9') >>> format_value_error(12345.6, 78.9, 2) ('12346', '79') >>> format_value_error(12345.6, 0) ('12345.6', '0.0') >>> format_value_error(12345.6, 0, 0) ('12346', '0') >>> format_value_error(12345.6, 67) ('12346', '67') >>> format_value_error(12345.6, 670) ('12350', '670') >>> format_value_error(1234567890.0, 123456.0) ('1234570000', '120000') >>> format_value_error(1234567890.0, 1234567.0) ('1.2346e+9', '1.2e+6') >>> format_value_error(-0.470, 1.722) ('-0.5', '1.7') >>> format_value_error(0.0025, 0.0001) ('2.50e-3', '1.0e-4') rr/r)r_rYrrr"ra)r<rIr;r val_order err_orderrerr_strs ruformat_value_errorr!7sZ *C *CQh#c(AC"3A.I"3A.I & Y&,j:% j" G  c(c( G s A((B  B ct)z Extract factor and base units from units. Supports all base SI units, a number of non-base SI units and some non-SI units. Args: text (str): force_si: check_si: Returns: result (tuple): )NotImplementedError)rforce_sicheck_sis ruparse_units_prefixr&8s $ rwc#<K|j}|dvr"d}||ks||||z }|dz }||kr|yy|dvr"d}||ks||||z}|dz }||kr|yy|dvr%d}||ks|d|z ||z }|dz }||kr|yyttdw)a Compute the n-th term of a notable progression. Args: name (str): The name of the progression. Accepted values are: - `a`, `arithmetic`: Use arithmetic progression. - `g`, `geometric`: Use geometric progression. - `h`, `harmonic`: Use harmonic progression. start (Number): The initial value. step (Number): The step value. num (int|None): The number of values to yield. If None, yields values indefinitely (use with care!). Yields: result (Number): The n-th term of the progression. Raises: ValueError: If `name` is not supported. Examples: >>> list(i_progression('a', 10, 2, 12)) [10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32] >>> list(i_progression('g', 10, 2, 12)) [10, 20, 40, 80, 160, 320, 640, 1280, 2560, 5120, 10240, 20480] >>> [round(x, 3) for x in i_progression('h', 1, 1, 10)] [1.0, 0.5, 0.333, 0.25, 0.2, 0.167, 0.143, 0.125, 0.111, 0.1] >>> list(i_progression('ga', 10, 2, 12)) Traceback (most recent call last): ... ValueError: Unknown progression `ga` References: - https://en.wikipedia.org/wiki/Arithmetic_progression - https://en.wikipedia.org/wiki/Geometric_progression - https://en.wikipedia.org/wiki/Harmonic_progression_(mathematics) r5 arithmeticrNr/g geometricr;harmonicUnknown progression `{name}`r^r"r)r-r~r}r;rMs ru i_progressionr18sT ::>s'1BB"BB%BBBc|j}|dvr|||zzS|dvr|||zzS|dvr d|||zzz Sttd)a Compute the n-th term of a notable progression. Args: name (str): The name of the progression. Accepted values are: - `a`, `arithmetic`: Use arithmetic progression. - `g`, `geometric`: Use geometric progression. - `h`, `harmonic`: Use harmonic progression. start (Number): The initial value. step (Number): The step value. num (int): The ordinal of the progression. The initial value is the 0th. Returns: result (Number): The n-th term of the progression. Raises: ValueError: If `name` is not supported. Examples: >>> progression('a', 0, 6, 7) 42 >>> progression('g', 1, 2, 10) 1024 >>> progression('h', 1, 1, 99) 0.01 >>> progression('ga', 10, 2, 12) Traceback (most recent call last): ... ValueError: Unknown progression `ga` References: - https://en.wikipedia.org/wiki/Arithmetic_progression - https://en.wikipedia.org/wiki/Geometric_progression - https://en.wikipedia.org/wiki/Harmonic_progression_(mathematics) r(r*r-r/r/r0r-r~r}r;s ru progressionr4`8snT ::>rwc|j}|dvr|||z||dz zdz|zzS|S|dvr5||dk(r||zS|d||zz zd|z z St|dkr|d|z z S|S|tt||||St |||d|S)aM Compute the sum of the first n terms of a notable progression. The sum of the elements of a progression is also called a series. Args: name (str): The name of the progression. Accepted values are: - `a`, `arithmetic`: Use arithmetic progression. - `g`, `geometric`: Use geometric progression. - `h`, `harmonic`: Use harmonic progression. start (Number): The initial value. step (Number): The step value. num (int|None): The number of values to sum. If None, sums to infinity. Returns: result (Number|None): The sum value. If the series diverges, returns None. Examples: >>> sum_progression('a', 10, 2, 12) 252 >>> sum_progression('g', 10, 2, 12) 40950.0 >>> round(sum_progression('h', 1, 1, 10), 3) 2.929 >>> print(sum_progression('a', 10, 2, None)) None >>> print(sum_progression('g', 10, 0.5, None)) 20.0 >>> print(sum_progression('h', 10, 0.5, None)) None >>> sum_progression('ga', 10, 2, 12) Traceback (most recent call last): ... ValueError: Unknown progression `ga` >>> print(sum_progression('ga', 10, 2, None)) Traceback (most recent call last): ... ValueError: Unknown progression `ga` >>> a, d, n = 10, 2, 20 >>> all( ... sum(i_progression(s, a, d, n)) == sum_progression(s, a, d, n) ... for s in ('a', 'g', 'h')) True References: - https://en.wikipedia.org/wiki/Series_(mathematics) - https://en.wikipedia.org/wiki/Arithmetic_progression - https://en.wikipedia.org/wiki/Geometric_progression - https://en.wikipedia.org/wiki/Harmonic_progression_(mathematics) r(r/r9r*)r^r!rVr1r4r3s rusum_progressionr68sr ::> >J # # ?qys{"DCK0AH== Y]AH% %J ?}T5$<= = eT1 -Jrwc dtd|D zd}tt|}|dtfd|Drkkr*dj t |d|t |}|Sdj t |d|t |dz|t |}|Stt|}|dtfd |Drkggggf\}}}}d} d } d } d } d} | d k\rd | z z} |j| |jtj|dtj| z |jtj|d| ztj| z |j| t|| || || || fDcgc]}|r t|ndc}}|| kr|} | } | d z } | d z } | d k\rtt||||| \} }}} dj t | |t ||t ||t | |}|Scc}w)aH Guess a compact expression for a numerical sequence. Args: seq (Sequence[Number]): The input items. rounding (int|None): The maximum number of decimals to show. Returns: result (str): The compact expression. Supported numerical sequences are: - constant sequences: '[val] * len(items)' - linear sequences: 'range(start, stop, step)' Note that both float and complex number will be detected (contrarily to Python's `range()`). - geometric sequences: 'base ** range(start, stop, step)' Examples: >>> items = [1.0] * 10 >>> print(items) [1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0] >>> print(guess_numerical_sequence(items)) [1.0] * 10 >>> items = list(range(10)) >>> print(items) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] >>> print(guess_numerical_sequence(items)) range(0, 10, 1) >>> items = list(range(5, 25, 2)) >>> print(items) [5, 7, 9, 11, 13, 15, 17, 19, 21, 23] >>> print(guess_numerical_sequence(items)) range(5, 25, 2) >>> items = [x / 1000 for x in range(5, 25, 2)] >>> print(items) [0.005, 0.007, 0.009, 0.011, 0.013, 0.015, 0.017, 0.019, 0.021, 0.023] >>> print(guess_numerical_sequence(items)) range(0.005, 0.025, 0.002) >>> items = [2 ** x for x in range(5, 25, 2)] >>> print(items) [32, 128, 512, 2048, 8192, 32768, 131072, 524288, 2097152, 8388608] >>> print(guess_numerical_sequence(items)) 2.0 ** range(5.0, 24.0, 2) >>> items = [10 ** x for x in range(8)] >>> print(items) [1, 10, 100, 1000, 10000, 100000, 1000000, 10000000] >>> print(guess_numerical_sequence(items)) 10.0 ** range(0.0, 8.0, 1) >>> items = [3.5 ** x for x in range(5, 13, 2)] >>> print(items) [525.21875, 6433.9296875, 78815.638671875, 965491.5737304688] >>> print(guess_numerical_sequence(items)) 3.5 ** range(5.0, 12.0, 2) >>> items = [4.1 ** x for x in range(4, 11, 3)] >>> print(items) [282.5760999999999, 19475.42738809999, 1342265.9310152389] >>> print(guess_numerical_sequence(items)) 4.1 ** range(4.0, 11.0, 3) >>> items = [4.1 ** (x / 10) for x in range(4, 11, 3)] >>> # 4.1 ** range(0.4, 1.1, 0.3) >>> print(items) [1.7583832685816119, 2.6850272626520213, 4.1] >>> print(guess_numerical_sequence(items)) 1.527 ** range(1.333, 4.333, 1) rc38K|]}|st|ywr)r)rrs rurz+guess_numerical_sequence..39sBdT^D)BsNrc3.K|] }|z kywrrrrHr_r2s rurz+guess_numerical_sequence..79s )a1t8c> )rz [{}] * {}zrange({}, {}, {})r<c3.K|] }|z kywrrr:s rurz+guess_numerical_sequence..C9s,!q4x#~,rr/r9@g@z{} ** range({}, {}, {}))rrrrrrgrrrrdlog2rVrrr)rr?rdiffsdivsr[firstslastsr#rMr}new_basemin_sum_decimalsmin_irH sum_decimals first_itemrAr_r2s @@ruguess_numerical_sequencerG8szV BcBBB BC F $s) E 8D )5 )) #: ''c!fh(?SJFL MG)//c!fh's2w~x)HdH%'FF M?SXAw ,t, ,*,b"b. 'E65%ADH% Ec/AH- X& diiA/$))H2EEF IIc"g01DIIh4GGI T""$QxE!HeAhGI+,^A&2I J  "22'3$E Qc/"Su56u= 2Hj)T.55h)5X+Fi*E$,ACF MIs=Ict||kDrZ| t|nd}|" ||z |||z ddj|z }nt||z d}|||||z|d|zS||||zS|S#t$rd}Y'wxYw)ah Cut and append an ellipsis sequence at the end if length is excessive. This is especially useful for strings. Args: seq (Sequence): The input sequence. length (int): The maximum allowed length ending (Sequence|None): The ending to append. If None, it is ignored. sep (Any|None): The separator to use. If None, it is ignored, otherwise cuts only at the separator. start (int): The start index for the output. Returns: result (Sequence): The sequence with the elision. Examples: >>> elide('Flying Circus FlyingCircus', 24) 'Flying Circus FlyingCi..' >>> elide('Flying Circus FlyingCircus', 24, '...') 'Flying Circus FlyingC...' >>> elide('Flying Circus FlyingCircus', 24, '...', ' ') 'Flying Circus...' >>> elide('Flying Circus FlyingCircus', 24, None) 'Flying Circus FlyingCirc' >>> elide('Flying Circus FlyingCircus', 24, '..', None, 1) 'lying Circus FlyingCir..' >>> elide('Flying Circus FlyingCircus', 1) '.' >>> elide('Flying Circus FlyingCircus', 2) '..' >>> elide('Flying Circus FlyingCircus', 3) 'F..' >>> elide('Flying Circus FlyingCircus', 5, '..', ' ') '..' >>> elide('a bc def ghij klmno pqrstu vwxyzab', 16, '..', ' ') 'a bc def ghij..' >>> elide('a bc def ghij klmno pqrstu vwxyzab', 5, '..', ' ') 'a..' >>> elide('a bc def ghij klmno pqrstu vwxyzab', 6, '..', ' ') 'a bc..' >>> elide(list(range(100)), 16, [-1]) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, -1] >>> elide(list(range(100)), 16, [-1, -1]) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1, -1] >>> elide([x % 3 for x in range(100)], 16, [-1, -1], 0) [0, 1, 2, 0, 1, 2, 0, 1, 2, 0, 1, 2, -1, -1] >>> elide(list(range(100)), 16, None) [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15] >>> elide(list(range(100)), 16, [-1, -1], None, 1) [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, -1, -1] Nrr<)rrcr"r)rrCendingrr~ len_endingr%s rueliderKd9sx 3x&$*$6S[A ? +fz15256<>> d = str2dict('{a=10,b=20,c=test}') >>> for k in sorted(d.keys()): print(k, ':', d[k]) # display dict a : 10 b : 20 c : test See Also: dict2str r/rNr9)rrrZrr5r)in_str entry_sep key_val_seprr strip_key_str strip_val_strconvertentriesout_dictentrykey_valrr<tmp_vals rustr2dictrX9sPJ/VY ;ll9%GH ++k* w<1 qz4C \Q HC))M*C \A qz712;C?BCG7==/CCC C#ii & ?"3'HSM) * ODsC$ct|j|}g} |D]R} | j|} t|| j|} | j |j | | gT||j | z|z} | S)a Convert a dictionary to a string. Args: in_dict (dict): The input dictionary. entry_sep (str): The entry separator. key_val_sep (str): The key-value separator. pre_delim (str): initial decorator (to be appended to the output). post_delim (str): final decorator (to be appended to the output). strip_key_str (str): Chars to be stripped from both ends of the key. If None, whitespaces are stripped. Empty string for no stripping. strip_val_str (str): Chars to be stripped from both ends of the value. If None, whitespaces are stripped. Empty string for no stripping. sorting (callable): Sorting function passed to 'sorted' via `key` arg. Used for sorting the dictionary keys. Returns: out_str (str): The output string generated from the dictionary. Examples: >>> dict2str({'a': 10, 'b': 20, 'c': 'test'}) '{a=10,b=20,c=test}' See Also: str2dict r/)rlrr5rarr ) in_dictrNrOrrrPrQrrout_listrr<out_strs rudict2strr]9sF ',,.g .DH6ii &'#,%%m4 ((#s456)..22Z?G Nrwc|s t|nd}|r t|nd}||vrd||vr`|r)|j||z}|j||z}n.|j||z}||dj||z|z}|||}|Sd}|S)a Isolate the string contained between two tokens Args: text (str): String to parse begin_str (str): Token at the beginning end_str (str): Token at the ending incl_begin (bool): Include 'begin_string' in the result incl_end (bool): Include 'end_str' in the result. greedy (bool): Output the largest possible string. Returns: text (str): The string contained between the specified tokens (if any) Examples: >>> string_between('roses are red violets are blue', 'ses', 'lets') ' are red vio' >>> string_between('roses are red, or not?', 'a', 'd') 're re' >>> string_between('roses are red, or not?', ' ', ' ') 'are red, or' >>> string_between('roses are red, or not?', ' ', ' ', greedy=False) 'are' >>> string_between('roses are red, or not?', 'r', 'r') 'oses are red, o' >>> string_between('roses are red, or not?', 'r', 'r', greedy=False) 'oses a' >>> string_between('roses are red, or not?', 'r', 's', True, False) 'rose' >>> string_between('roses are red violets are blue', 'x', 'y') '' rNr8)rfindrfind)r begin_strend_str incl_beginincl_endrrrFs rustring_betweenre&:sN(2YqJ's7|QHDW_ IIi(:5E**W%0CIIi(:5Euv,##G,x7%?CE# K KrwcPtjd}|jd|S)aS Remove ANSI escape sequences from text. Args: text (str): The input text. Returns: result (str): The output text. Examples: >>> s = 'foo bar' >>> print(repr(remove_ansi_escapes(s))) 'foo bar' >>> remove_ansi_escapes(s) == 'foo bar' True z(\x9B|\x1B\[)[0-?]*[ -/]*[@-~]r8)rrr)r ansi_escapes ruremove_ansi_escapesrh]:s$"**>?K ??2t $$rwct|tr|g}t|tr|g}|s-|D](}|stjj |r&d}n|r|r~|D]y}tjj |}tjj |rBtdj||tdtj|{|s|r|D],}tjj |r#tdtj||D]H\}}tjj|tjj|kDsFd}nn |r td|rHtdj||tdtdj||td|Std j||tdtdj||td|S) a Check if input files are newer than output files, to force calculation. Args: in_filepaths (str|Iterable[str]|None): Input filepaths for computation. out_filepaths (str|Iterable[str]): Output filepaths for computation. force (bool): Force computation to be re-done. verbose (int): Set level of verbosity. makedirs (bool): Create output dirpaths if not existing. no_empty_input (bool): Check if the input filepath list is empty. Returns: force (bool): True if the computation is to be re-done. Raises: IndexError: If the input filepath list is empty. Only if `no_empty_input` is True. IOError: If any of the input files do not exist. Tz mkdir: {}r>zInput file does not exists.zInput file list is empty.zCalc: {}higherzFrom: {}zSkip: {})rrarprqrdirnamerrrr rrrrgetmtime) in_filepaths out_filepathsrrXrno_empty_input out_filepath out_dirpath in_filepaths ru check_redorss:s6,$$~ -%&  ) LBGGNN<$@   ) )L''//,7K77==-K&&{3Xi02 K(  )  + A ww~~k2!"?@@ A %%lMB ) \77##K02773C3C$4&& E   56 6  J  m ,gx7IJ J  l +Why6IJ L J  m ,gx7IJ J  l +Why6IJ Lrwct|}t||rtdt||D}|Stdt||D}|S)a Check if items are increasing. Args: items (Iterable): The items to check. strict (bool): Check for strict monotonicity. If True, consecutive items cannot be equal. Otherwise they can be also equal. Returns: result (bool): True if items are increasing, False otherwise. Examples: >>> is_increasing([-20, -2, 1, 3, 5, 7, 8, 9]) True >>> is_increasing([1, 3, 5, 7, 8, 9, 9, 10, 400]) False >>> is_increasing([1, 3, 5, 7, 8, 9, 9, 10, 400], False) True >>> is_increasing([-20, -2, 1, 3, 5, 7, 8, 9]) True >>> is_increasing([-2, -2, 1, 30, 5, 7, 8, 9]) False c3,K|] \}}||kywrrrs rurz is_increasing..::tq!QU:rc3,K|] \}}||kywrrrs rurz is_increasing..:;1Q!V;rrrrrrstrictothersrs ru is_increasingr}:S6%[FL :s5&'9:: M;E6(:;; Mrwct|}t||rtdt||D}|Stdt||D}|S)a Check if items are decreasing. Args: items (Iterable): The items to check. strict (bool): Check for strict monotonicity. If True, consecutive items cannot be equal. Otherwise they can be also equal. Returns: result (bool): True if items are decreasing, False otherwise. Examples: >>> is_decreasing([312, 54, 53, 7, 3, -5, -100]) True >>> is_decreasing([312, 53, 53, 7, 3, -5, -100]) False >>> is_decreasing([312, 53, 53, 7, 3, -5, -100], False) True >>> is_decreasing([312, 54, 53, 7, 3, -5, -100]) True >>> is_decreasing([312, 5, 53, 7, 3, -5, -100]) False c3,K|] \}}||kDywrrrs rurz is_decreasing..;rvrc3,K|] \}}||k\ywrrrs rurz is_decreasing..;rxrryrzs ru is_decreasingr:r~rwcxt|} t|dk\}|D] }||dk\k7s yy#t$rYywxYw)as Determine if all items in an Iterable have the same sign. Args: items (Iterable): The items to check. The comparison operators '>=' and '<' with `0` must be defined for all items. Returns: same_sign (bool): The result of the comparison. True if the items are all positive or all negative. False otherwise, i.e. they have mixed signs. Examples: >>> is_same_sign((0, 1, 2 ,4)) True >>> is_same_sign((-1, -2 , -4)) True >>> is_same_sign((-1, 1)) False >>> is_same_sign([]) True rTFr@rs ru is_same_signr ;sZ4eJZ A%  TQY   s - 99crt|txr&tjd|j duS)a Determine if the input string contains a percent value. Args: text (str): The input string. Returns: result (bool): The result of the check. True if the input contains a valid percentage. False otherwise. Examples: >>> print(is_percent('100%')) True >>> print(is_percent('0.5%')) True >>> print(is_percent('421.43%')) True >>> print(is_percent('-433%')) True >>> print(is_percent('421.%')) True >>> print(is_percent('.5%')) True >>> print(is_percent('1.e2%')) True >>> print(is_percent('421.43')) False >>> print(is_percent('ciao421.43%')) False $[+-]?\d*(?:\.\d*)?(?:[eE][+-]?\d+)?%N)rrarrr5)rs ru is_percentr1;s6B D#   XX=tzz| Lrwctjd|j}|rt|jdddz Sy)a Convert the input string to a float value as percentage. Args: text (str): The input string. Returns: result (float|None): The percent value. If the input is invalid, returns None. Examples: >>> print(to_percent('100%')) 1.0 >>> print(to_percent('0.5%')) 0.005 >>> print(to_percent('421.43%')) 4.2143 >>> print(to_percent('-433%')) -4.33 >>> print(to_percent('421.%')) 4.21 >>> print(to_percent('.1%')) 0.001 >>> print(to_percent('421.43')) None >>> print(to_percent('ciao421.43%')) None rNr<r,)rrr5r_string)rrs ru to_percentrX;s<: HH>> scale_to_int(0.1, 10) 1 >>> scale_to_int(0.1, 10.0) 1 >>> scale_to_int(1.0, 10.0) 10 >>> scale_to_int(0.5, 11.0) 6 >>> scale_to_int(0.5, 11.0, math.floor) 5 >>> scale_to_int(1, 10.0) 1 >>> scale_to_int(1, 10) 1 )rrY)r<scaler?s ru scale_to_intr};s'B.8S-A3xe $ %JsJrwctfd|D}t||}t|r|tfd|D}|Stdt|D}|S)a Ensure values scaling of multiple values. Args: vals (int|float|Sequence[int|float|Sequence]): The input value(s) If Sequence, a value for each scale must be specified. If not Sequence, all pairs will have the same value. If any value is int, it is not scaled further. If any value is float, it is scaled to the corresponding scale, if `combine` is None, otherwise it is scaled to a combined scale according to the result of `combine(scales)`. scales (Sequence[int]): The scale sizes for the pairs. shape (Sequence[int|None]): The shape of the output. It must be a 2-tuple of int or None. None entries are replaced by `len(scales)`. combine (callable|None): The function for combining pad width scales. Must accept: combine(Sequence[int]): int|float This is used to compute a reference scaling value for the float to int conversion, using `combine(scales)`. For the int values of `width`, this parameter has no effect. If None, uses the corresponding scale from the scales. Returns: vals (int|tuple[tuple[int]]): The scaled value(s). See Also: - flyingcircus.stretch() - flyingcircus.scale_to_int() Examples: >>> scales = (10, 20, 30) >>> multi_scale_to_int(0.1, scales) ((1, 1), (2, 2), (3, 3)) >>> multi_scale_to_int(0.1, scales, combine=max) ((3, 3), (3, 3), (3, 3)) >>> multi_scale_to_int(2, scales) ((2, 2), (2, 2), (2, 2)) >>> multi_scale_to_int((1, 1, 2), scales) ((1, 1), (1, 1), (2, 2)) >>> multi_scale_to_int((0.1, 1, 2), scales) ((1, 1), (1, 1), (2, 2)) >>> multi_scale_to_int((0.1, 1, 2), scales, combine=max) ((3, 3), (1, 1), (2, 2)) >>> multi_scale_to_int(((0.1, 0.5),), scales) ((1, 5), (2, 10), (3, 15)) >>> multi_scale_to_int(((2, 3),), scales) ((2, 3), (2, 3), (2, 3)) >>> multi_scale_to_int(((2, 3), (1, 2)), scales) Traceback (most recent call last): ... ValueError: Cannot stretch `((2, 3), (1, 2))` to `(3, 2)`. >>> multi_scale_to_int(((0.1, 0.2),), scales, combine=min) ((1, 2), (1, 2), (1, 2)) >>> multi_scale_to_int(((0.1, 0.2),), scales, combine=max) ((3, 6), (3, 6), (3, 6)) >>> multi_scale_to_int(((1, 2), (3, 4)), (2, 3)) ((1, 2), (3, 4)) >>> multi_scale_to_int(((1, 2), 3), (2, 3)) ((1, 2), (3, 3)) >>> multi_scale_to_int(((1, 2), 0.7), (2, 3)) ((1, 2), (2, 2)) >>> multi_scale_to_int(((1, 1),), (3,), (None, 2)) ((1, 1),) c3<K|]}|r|n tywrr)rrHscaless rurz%multi_scale_to_int..;s9aq!c&k)9sc3FK|]}tfd|Dyw)c36K|]}t|ywrr)rrHcombineds rurz/multi_scale_to_int...;s9,q(+9rNr)rr<rs rurz%multi_scale_to_int..;s$ 9S9 9rc3LK|]\}tfd|Dyw)c36K|]}t|ywrr)rrHrs rurz/multi_scale_to_int...;s6Q,q%(6rNr)rr<rs @rurz%multi_scale_to_int..;s(1U 6#6 61s!$)rrrr)valsrrrrrs ` @rumulti_scale_to_intr;sxL 959 9E 4 D6? M1!$/11 Mrwc ,t|ddt}t|ddt}t|ddt}t|ddt}tt|ddt|t|ddt|td\} } t |t d} t tt|ddt|} t tt|ddt|} t |t d}t |t d}|r|djDcgc] \}}t|d zt|z|"}}}|d Dcgc]}tt||d z}}d d j||zzdz}t||d zkDrddj||zzdz}nd}|d}td}td}td}td}td}td}td}td}td}td} |r t|}!nddj|||| gz}!|dkDr7d j|!jD"cgc]}"t|"|c}"}!|sj|rh|!d!t|d"zd#zd$zt|d%zd&zd'zt|d(zd#zd)zt|d*zd&zd+zt|d,zz }!|!Scc}}wcc}wcc}"w)-a# Format summary result from `flyingcircus.time_profile()`. Args: summary (dict): The input summary. template (str): The template to use kws_limit (int): The maximum number of chars to use for input preview. This is only effective if `more == True`. line_limit (int): Limit for single line. more (bool): Display more information. Returns: result (str): The formatted summary. See Also: - flyingcircus.time_profile() - flyingcircus.multi_benchmark() r<rrIr;rOrCrBrrrr9(, )z( z, z(..)rz {name}{args}u({val} ± {err}) {t_units}sz t = {time_s}ztime = {time_s}z{loop_num}{l_units}z l = {loop_s}zloops = {loop_s}z{batch_num}{b_units}z b = {batch_s}zbatch = {batch_s}: z; rr z mean_time = rz; z stdev_time = rz; z min_time = rz max_time = rzminmax_range = minmax_range)r SI_ORDER_STEPr!rr  SI_PREFIXrYrgrrKrar rr splitlines)#summarytemplate kws_limit line_limitmorerr loop_order batch_orderr<rIt_unitsloop_num batch_numl_unitsb_unitsr'rkws_listr args_listrr-name_stime_stime_sstime_lsloop_sloop_ssloop_lsbatch_sbatch_ssbatch_lsrrs# ru_format_summaryr;sd0#75>2}EI"75>2}EI#GENB FJ$WW%5r=IK!wu~r=)Dwu~r=)DqHCi:)>?G5wu~r=*EGHHEww']KHJKIj)J*?@Gk9Z+@AG  ,,.01 !c'CF"I .009@I14E#c(J!O ,I ITYYy8344s: t9zQ &',,y8/C"DDsJD ; D . !F / 0F>"G$%G ' (F>"G%&G)*GO$H'(Hh 67GX"FGGA~171B1B1D EU4 $ EG  #c'&/&: :U B  #GG$4 5 68? @ !'%.1 249 : "'%.1 25< <  #&gn&=">  ? ? MG0I0 Fs+%LL >Lc|d}t|D]+}|}|}t||z }t|||}-|S)a Estimate the error associated to a specific timer. Args: timer (callable): num (int): The number of repetitions. Returns: result (float): The estimated timer error. Examples: >>> timers = time.perf_counter, time.process_time, time.time >>> timer_errors = [estimate_timer_error(timer) for timer in timers] >>> print([math.log10(t) < 0 for t in timer_errors]) [True, True, True] r)r{r!rV)timerr;rrM begin_timeend_time time_deltas ruestimate_timer_errorrF<sN&F 3Z2W 7J./ :vq1 2 Mrwg0@rirSz/: {name_s}; {time_ss}; {loop_ss}; {batch_ss}cz tj   fd}|S)u Estimate the execution time of a function using multiple repetitions. The function is repeated in batches. Each batch repeats the function to ensure a reliable time measurement. The run time is computed as the the batch time divided by the batch size. This is similar to the functionality provided by the `timeit` module, but also works as a decorator. Note that the default values are choosen under the assumption that the timer error is much larger than the execution time of the function. Args: func (callable): The input function. timeout (int|float): Maximum time for testing in s. There will be at least `min_iter` iterations. batch_timeout (int|float): Maximum time for each batch in s. If quick is False, there will be at least `min_batch` repetitions. max_iter (int): Maximum number of iterations. Must be at least 2. min_iter (int): Minimum number of iterations. If the min number of iterations requires longer than `max_time`, the `max_time` limit is ignored until at least `min_iter` iterations are performed. max_batch (int): Maximum size of the batch. Must be at least 1. min_batch (int): Minimum size of the batch. Must be at least 1. val_func (callable|None): Compute timing value from batch times. If callable, must have the signature: func(Sequence[int|float]): int|float If None, uses the mean of the runtimes. err_func (callable|None): Compute timing error from batch times. If callable, must have the signature: func(Sequence[int|float]): int|float If None, uses the standard deviation of the mean of the runtimes. timer (callable): The function used to measure the timings. use_gc (bool): Use the garbage collection during the timing. quick (bool): Force exiting the repetition loops. If this is True, the `max_time` is forced within the execution time of a single instance. The minimum number of iterations is always performed. text (str): Text to use for printing output. fmtt (str|bool|None): Format of the printed output. This is passed to `flyingcircus.msg()`. verbose (int): Set level of verbosity. Returns: decorator_profile_time (callable): The decorator. Examples: >>> @time_profile(timeout=0.1, fmtt=False) ... def my_func(a, b): ... return [0 for _ in range(a) for _ in range(b)] >>> x, summary = my_func(100, 100) # doctest:+ELLIPSIS : my_func(..); t = (... ± ...) ...s; l = ...; b = ... >>> x, summary = my_func(1000, 1000) # doctest:+ELLIPSIS : my_func(..); t = (... ± ...) ...s; l = ...; b = ... >>> def my_func(a, b): ... return [0 for _ in range(a) for _ in range(b)] >>> my_func = time_profile(timeout=0.1)(my_func) >>> x, summary = my_func(100, 100) # doctest:+ELLIPSIS : my_func(..); t = (... ± ...) ...s; l = ...; b = ... >>> x, summary = my_func(1000, 1000) # doctest:+ELLIPSIS : my_func(..); t = (... ± ...) ...s; l = ...; b = ... >>> print(list(summary.keys())) ['result', 'func_name', 'args', 'kws', 'num', 'val', 'err', 'mean', 'sosd', 'var', 'stdev', 'min', 'max', 'median', 'medoid', 'batch'] See Also: - flyingcircus.multi_benchmark() - flyingcircus._format_summary() ctj}+rtjntjdx}x}x}}*}d}d} t ,xs t } t *} rn| #z} | } | rg}ng}d})}d}t $D]}d}d}*}t #D]8}"|i|} *}||z }||z }|)kDr |&k\s'rn|| kDs0|%k\s's8nt|dz||}|| z |dzz }| rj|t||||\}}}| st|\}}}||kr|}||kDr|}|)kDs|&k\snt|t||}}| rt}t|}|}||dzz }| r&t ,r,}t r }tdid| d"j d|d|d |dzd |d |d |d |d|d|d|d|dddt#|}|rtjntj(rt%t'|(-t(!| |fS)Nrrr/rrrrrr;r<rIrrrrrrr#r<rOr)gc isenabledenabledisablerrr{rVrr\rerrr#r<r rrYrrr ).rrgc_was_enabled mean_time sosd_timemin_timemax_time init_time total_timercollect_runtimes timer_err b_timeout batch_err run_timessorted_run_times mean_batchrMr batch_timerrrun_timer medoid_time median_timevar_time stdev_timeval_timeerr_timer batch_timeouterr_funcrEr max_batchmax_iter min_batchmin_iterquickrrUruse_gcval_funcrXs. rurztime_profile..wrapper<s 2::<699 9I98G  #H-C(1C(/ %2M I8M  I!  x AAJJ9% u-- 7% 1 % 2 'Q(]e )qI~ #1q5*a8J"Y.1q59H  *&8)Y'3 #Iy!#.D./0+ [!("#("#G#X 7 8 ( 15z)Q7O*  +K +KS( !#I.!#I.##%)]]#9>#DH#A###)1##"+# #!+ #19 #?G #  # (3 # j/ #& 2::<  .T Jwrwr)rrUrrrrrrrrrrrrErXrs``````````````` ru time_profilerc<s8~__TCCCCJ Nrwc#JK|]}tddd|zdz zzyw)r9r&rbNrrs rurr=s&I!#aAQ! O45Ircbt|Dcgc]}tjc}Scc}wr)r{r)r2rs rurr=seAh?V]]_??s,c ||k(Srrrs rurr=s !q&rwzj:{lbl_s:<{len_lbls}s} N={input_size!s:<{len_n}s} {is_equal_s:>3s} {time_s:<26s} {loop_s:>5} * {batch_s}rc |D cgc]} | j} } |d}|d}| t|ni}d|vr td|d<d|vrd|d<tt d|dz}tt t | t d z}t td | t| g}g}t|D]0\}}g}||}d}| rt t| | t| ttj|||D]\}\} }}| t|nd}| t|ni}tdi|| } | |g|i|\}}|d k(r|}|||}|rd nd }t| dr | jnd}|d z }|r%t t|t|| t| ||d<|j!||s|j!||j!|3|| |fScc} w)u Benchmark multiple functions for varying input sizes. Sensible choices for input sizes are: - for linear (n) problems - (5, 10, 50, 100, 500, 1000, 5000, 10000, 50000, 100000) - tuple(10 * (i + 1) for i in range(24)) # lin-spaced - tuple(2 ** (i + 1) for i in range(16)) # geom-spaced - tuple(int(2 ** (2 + (3 * i) / 4)) for i in range(20)) # frac-pow-spaced - for quadratic (n²) problems - (5, 10, 50, 100, 500, 1000, 5000) - tuple(10 * (i + 1) for i in range(24)) # lin-space - tuple(2 ** (i + 1) for i in range(12)) # geom-space - tuple(int(2 ** (2 + (3 * i) / 4)) for i in range(15)) # frac-pow-spaced Args: funcs (Iterable[callable]): The functions to test. Must have the signature: func(input_, *args, **kws). `args` and `kws` are from `argss` and `kwss` respectively. argss (Iterable|None): The positional arguments for `funcs`. Each item correspond to an element of `funcs`. kwss (Iterable|None): The keyword arguments for `funcs`. Each item correspond to an element of `funcs`. input_sizes (Iterable[int]): The input sizes. gen_input (callable): The function used to generate the input. Must have the signature: gen_input(int): Any. equal_output (callable): The function used to compare the output. Must have the signature: gen_input(Any, Any): bool. time_prof_kws (Mappable|None): Keyword parameters for `time_profile`. These are passed to `flyingcircus.time_profile()`. store_all (bool): Store all results. If True, all results are stores. text_funcs (str): Text to use for printing output for functions. text_inputs (str): Text to use for printing output for inputs. fmtt (str|bool|None): Format of the printed output. This is passed to `flyingcircus.msg()`. verbose (int): Set level of verbosity. Returns: result (tuple): The tuple contains: - summaries (list[list[dict]]): The summary for each benchmark. - labels (list[str]): The function names. - results (list): The full results. This is non-empty only if `store_all` is True. Examples: >>> def f1(items): ... return [item * item for item in items] >>> def f2(items): ... return [item ** 2 for item in items] >>> def func_with_longer_name(items): ... return [item ** 2 for item in items] >>> funcs = f1, f2, func_with_longer_name >>> summaries, labels, results = multi_benchmark( ... funcs, input_sizes=tuple(10 ** (i + 1) for i in range(3)), ... time_prof_kws=dict(timeout=0.1, batch_timeout=0.01), ... fmtt=False) # doctest:+ELLIPSIS N = (10, 100, 1000) :f1() N=10 OK (... ± ...) ...s ... * ... :f2() N=10 OK (... ± ...) ...s ... * ... :func_with_longer_name() N=10 OK (... ± ...) ...s ... * ... :f1() N=100 OK (... ± ...) ...s ... * ... :f2() N=100 OK (... ± ...) ...s ... * ... :func_with_longer_name() N=100 OK (... ± ...) ...s ... * ... :f1() N=1000 OK (... ± ...) ...s ... * ... :f2() N=1000 OK (... ± ...) ...s ... * ... :func_with_longer_name() N=1000 OK (... ± ...) ...s ... * ... >>> print(labels, results) ['f1', 'f2', 'func_with_longer_name'] [] >>> summary_headers = list(summaries[0][0].keys()) >>> print(summary_headers) ['result', 'func_name', 'args', 'kws', 'num', 'val', 'err', 'mean', 'sosd', 'var', 'stdev', 'min', 'max', 'median', 'medoid', 'batch', 'is_equal'] See Also: - flyingcircus.time_profile() - flyingcircus._format_summary() NrrXnonerTcdttjtj|Sr)rYrdrerrs rurz!multi_benchmark..=sc$))DJJqM":;rwr/z()zN = {input_sizes}rOKERRrz is_equal)rr r rrrrrr rrrrrrrr)funcsargsskwss input_sizes gen_input equal_output time_prof_kws store_all text_funcs text_inputsrErXrrlen_nlen_lbls summariesresultsrM input_sizeinner_summaries input_datatruthrrrrrr is_equal_slbl_ss rumulti_benchmarkr =sV). .dmm .F . } |+8+DD'"M %#+F#3 i m#!% g ;[I JQ NE3sF#$s4y0H !7J=IG";/* :z*   [!7J =)//udCD ' A dC"&"25;D"$s)BC0<0-06D":<<DMMKE TMEOGT*-=>Z/"*GJ   " "7 +v&% '& )3*4 fg %%S/sG+__main__r)rF)Nr)T)rTTF)rr<)NN)r/rT)r<)FF)FN)F)Nr<N)rr<N)r9r/TNF)r/TNF)r]TF)NF)TTT)NNNNr)TF)r<rr/)r<r7r/)r3)r9NF)r9rTr)rrU)r,r/gHz>T)TT)i)TrG)rr)rrT)rrT)rrr)rrrr)r`r)rT)NNr,F)FTTrT)FFFTr<N)*roTNN)NFT)z a-zA-Z0-9._-rT)r) Nrr) __class__rrrr<>)r0r0)))falsetrue)01)offonFT)rr/)r)rr/N)rrr)rb)r9rb)r&)Oz..Nr),r{}NNT)rrrrNNN)FFT))Nr9N)r8r%rF)r(vr __future__rrrrrprrOrdr statisticsrirrr^rrJrergrryr1rrr!rcopyrrrr^r4r>picklerr flyingcircusrrr r r r r rrrrrrrrrrrr CSV_DELIMITERCSV_COMMENT_TOKENr D_TAB_SIZErrrrrdeepcopySI_PREFIX_ASCIISI_PREFIX_EXTRA_modera maketransr SUBSCRIPT_MAP _STRUCT_TYPESrrTrYr_r8r6r=partialr rrvrrrrrobjectrrrr(r.dumpsrErQrVrXr\rardrhrxrrrrrrrrrrrrrrrrrrrrrrrrrr getrandbitsr rrrrrrr%r(r+r-r2r4r8r>rBrLrPrSrZrmrqrsrvryrrrrrrrrrrrrrrrrrrrrrrrrrrrrrrr rrrrrrrr#r&r*r,r.r2r6r<r>rr@rDr{ SMALL_PRIMESrr\rUrTrxrzr~rrrrrrrrhrrrrrrrrrrrrrrrrrrr rrrrrrr#r)r+r9r<rgr@rHrKrNrQrTrVrZr\rarcrergrirkrmrorrrvrxrzr|r~rrrrrrrrrrrrrrrrSEEK_SETrrrmd5urlsafe_b64encoderrdumploadrrrr)r8rbr|rrrrrqrrrrrrrrrrrrrrrrrrrrrrrr r r rrrrrr!r&r1r4r6rGrKrXr]rerhrsr}rrrrrrrr perf_counterrr__file__r)rr'rSs000rur/s CC        $==66==-%AA          FGI Aq AE I GHJ Aq QU8 JQ1ga b! #  *Y{34 *Y{34 )%.{%;%A%A%CE!QAq=EF )%.{%;%A%A%CE!QAq=EF (9Y/0 (9Y/0$-- *$-- * ;%E"+E"24"8OE3#,U#3D#9OE4 "+E"24"8OE3t$ %--8: :<  *) )aQT ) # 3             $!,/2!E? I  chh +  6"*:4p l l` M MbX.FX.xF Jyz">B \\  J` 6;x*\<&Z8Cx+d  Nl @CH A$A$P  8|5) $&MX5) $-#f5) $*#`6z;; ):` ;;"L'Z5) $ =F5) $ J?b fZ]FeY'CR FG.VcR N5) $ >&J @&N5) $ 3r5) $H&\$$<BD AN   Lf  BR  x| AN Wz  Tt  y~ Vx sn"8R  @H@/l4!t   \=H  ?L  4AvA-P Vx 8>F <D =J  t**4.8*(D@B>F>C@@ H@H*\BLHX3n, `$T 5r0%j&%T`BLS1p'X2p.h  T0p-be9Q Q'999 "%l3h+\Vv! lb! x"|:@"aJ10\@7Nz  7Iz  dT ( %@R :<$4 &:|]#H8x(\"'P'V 8.8"L48'V!3P JJ)J,H*.`,0d.2h.4d F 87z"BPL  G5ZAP GZ5v ,D`+6f 6| 4p0-h9B  EXFZ Lf `L /j  "P  "P .h 0l   4't  4(t   92~  94~CRGZS!t]B'>HJ  4p*\5L0,l&T76/(8!6N?JOf6.{{ 9~{{"T \D{{** (\.{{** "P ++++'Z ;AB?J 1H0&l   c(RF&X8 &V $#R />ww~~<>  GZ2p9%z':Z  H  3r2F (X+bVxQ4t  &I:^D:>@ J`E7G, 3n< %EV12,?d (+,(N\B.B12 &DX (+,  DL  %(V  ?L4v  <D4  >?D2?lNhx|  KbAN*d 3n%2 H\!N!J$P#N!P!KP Qn  Kb :  > d dT IuRyII?(N T&p"# zejIJEE\ *s)n n>n :n  n"