o ¹­§ißSã@sŠddlmZddlmZddlmZddlmZddlm Z ddl m Z erd d „Zd?dd„Zd@dd„ZddœdAdd„Z dBdd„Z dCdDd d!„Z d"d#œdEd(d)„Z *dFdGd/d0„Z dHdId3d4„ZdHdId5d6„Zd7d8œdJd;d<„Zd*S)KÚExprBinaryNameSpacez&Namespace for bin related expressions.ÚbinÚexprr ÚreturnÚNonecCs |j|_dS©N)Ú_pyexpr)Úselfr©rúI/home/app/Keep/.python/lib/python3.10/site-packages/polars/expr/binary.pyÚ__init__s zExprBinaryNameSpace.__init__Úliteralr cCót|dd}t|j |¡ƒS)u€ Check if binaries in Series contain a binary substring. Parameters ---------- literal The binary substring to look for Returns ------- Expr Expression of data type :class:`Boolean`. See Also -------- starts_with : Check if the binary substring exists at the start ends_with : Check if the binary substring exists at the end Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... "lit": [b"\x00", b"\xff\x00", b"\xff\xff"], ... } ... ) >>> colors.select( ... "name", ... pl.col("code").bin.contains(b"\xff").alias("contains_with_lit"), ... pl.col("code").bin.contains(pl.col("lit")).alias("contains_with_expr"), ... ) shape: (3, 3) ┌────────┬───────────────────┬────────────────────┠│ name ┆ contains_with_lit ┆ contains_with_expr │ │ --- ┆ --- ┆ --- │ │ str ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ false ┆ true │ │ yellow ┆ true ┆ true │ │ blue ┆ true ┆ false │ └────────┴───────────────────┴────────────────────┘ T©Z str_as_lit)rrrZ bin_contains)rrZliteral_pyexprrrrÚcontainsó ,zExprBinaryNameSpace.containsÚsuffixcCr)uñ Check if string values end with a binary substring. Parameters ---------- suffix Suffix substring. Returns ------- Expr Expression of data type :class:`Boolean`. See Also -------- starts_with : Check if the binary substring exists at the start contains : Check if the binary substring exists anywhere Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... "suffix": [b"\x00", b"\xff\x00", b"\x00\x00"], ... } ... ) >>> colors.select( ... "name", ... pl.col("code").bin.ends_with(b"\xff").alias("ends_with_lit"), ... pl.col("code").bin.ends_with(pl.col("suffix")).alias("ends_with_expr"), ... ) shape: (3, 3) ┌────────┬───────────────┬────────────────┠│ name ┆ ends_with_lit ┆ ends_with_expr │ │ --- ┆ --- ┆ --- │ │ str ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ false ┆ true │ │ yellow ┆ false ┆ true │ │ blue ┆ true ┆ false │ └────────┴───────────────┴────────────────┘ Tr)rrrZ bin_ends_with)rrZ suffix_pyexprrrrÚ ends_withLrzExprBinaryNameSpace.ends_withÚprefixcCr)uN Check if values start with a binary substring. Parameters ---------- prefix Prefix substring. Returns ------- Expr Expression of data type :class:`Boolean`. See Also -------- ends_with : Check if the binary substring exists at the end contains : Check if the binary substring exists anywhere Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... "prefix": [b"\x00", b"\xff\x00", b"\x00\x00"], ... } ... ) >>> colors.select( ... "name", ... pl.col("code").bin.starts_with(b"\xff").alias("starts_with_lit"), ... pl.col("code") ... .bin.starts_with(pl.col("prefix")) ... .alias("starts_with_expr"), ... ) shape: (3, 3) ┌────────┬─────────────────┬──────────────────┠│ name ┆ starts_with_lit ┆ starts_with_expr │ │ --- ┆ --- ┆ --- │ │ str ┆ bool ┆ bool │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ false ┆ true │ │ yellow ┆ true ┆ false │ │ blue ┆ false ┆ true │ └────────┴─────────────────┴──────────────────┘ Tr)rrrZbin_starts_with)rr!Z prefix_pyexprrrrÚ starts_with{s .zExprBinaryNameSpace.starts_withT)ÚstrictÚencodingrr#ÚboolcCsB|dkr t|j |¡ƒS|dkrt|j |¡ƒSd|›}t|ƒ‚)uç Decode values using the provided encoding. Parameters ---------- encoding : {'hex', 'base64'} The encoding to use. strict Raise an error if the underlying value cannot be decoded, otherwise mask out with a null value. Returns ------- Expr Expression of data type :class:`Binary`. Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "encoded": [b"000000", b"ffff00", b"0000ff"], ... } ... ) >>> colors.with_columns( ... pl.col("encoded").bin.decode("hex").alias("code"), ... ) shape: (3, 3) ┌────────┬───────────┬─────────────────┠│ name ┆ encoded ┆ code │ │ --- ┆ --- ┆ --- │ │ str ┆ binary ┆ binary │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ b"000000" ┆ b"\x00\x00\x00" │ │ yellow ┆ b"ffff00" ┆ b"\xff\xff\x00" │ │ blue ┆ b"0000ff" ┆ b"\x00\x00\xff" │ └────────┴───────────┴─────────────────┘ ÚhexÚbase64ú1`encoding` must be one of {'hex', 'base64'}, got )rrZbin_hex_decodeZbin_base64_decodeÚ ValueError)rr$r#ÚmsgrrrÚdecode¬s ' zExprBinaryNameSpace.decodecCs>|dkr t|j ¡ƒS|dkrt|j ¡ƒSd|›}t|ƒ‚)uS Encode a value using the provided encoding. Parameters ---------- encoding : {'hex', 'base64'} The encoding to use. Returns ------- Expr Expression of data type :class:`Binary`. Examples -------- >>> colors = pl.DataFrame( ... { ... "color": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... } ... ) >>> colors.with_columns( ... pl.col("code").bin.encode("hex").alias("encoded"), ... ) shape: (3, 3) ┌────────┬─────────────────┬─────────┠│ color ┆ code ┆ encoded │ │ --- ┆ --- ┆ --- │ │ str ┆ binary ┆ str │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡ │ black ┆ b"\x00\x00\x00" ┆ 000000 │ │ yellow ┆ b"\xff\xff\x00" ┆ ffff00 │ │ blue ┆ b"\x00\x00\xff" ┆ 0000ff │ └────────┴─────────────────┴─────────┘ r&r'r()rrZbin_hex_encodeZbin_base64_encoder))rr$r*rrrÚencodeÛs $ zExprBinaryNameSpace.encodeÚbÚunitr cCst|j ¡ƒ}t||ƒ}|S)u™ Get the size of binary values in the given unit. Parameters ---------- unit : {'b', 'kb', 'mb', 'gb', 'tb'} Scale the returned size to the given unit. Returns ------- Expr Expression of data type :class:`UInt32` or `Float64`. Examples -------- >>> from os import urandom >>> df = pl.DataFrame({"data": [urandom(n) for n in (512, 256, 1024)]}) >>> df.with_columns( # doctest: +IGNORE_RESULT ... n_bytes=pl.col("data").bin.size(), ... n_kilobytes=pl.col("data").bin.size("kb"), ... ) shape: (4, 3) ┌─────────────────────────────────┬─────────┬─────────────┠│ data ┆ n_bytes ┆ n_kilobytes │ │ --- ┆ --- ┆ --- │ │ binary ┆ u32 ┆ f64 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ b"y?~B\x83\xf4V\x07\xd3\xfb\xb… ┆ 512 ┆ 0.5 │ │ b"\xee$4@f\xc14\x07\x8e\x88\x1… ┆ 256 ┆ 0.25 │ │ b"\x80\xbd\xb9nEq;2\x99$\xf9\x… ┆ 1024 ┆ 1.0 │ └─────────────────────────────────┴─────────┴─────────────┘ )rrZbin_size_bytesr)rr.ÚszrrrÚsizes! zExprBinaryNameSpace.sizeÚlittle)Ú endiannessÚdtypeúPolarsDataType | DataTypeExprr2r cCst|ƒ}t|j |j|¡ƒS)uA Interpret bytes as another type. Supported types are numerical or temporal dtypes, or an ``Array`` of these dtypes. Parameters ---------- dtype : PolarsDataType Which type to interpret binary column into. endianness : {"big", "little"}, optional Which endianness to use when interpreting bytes, by default "little". Returns ------- Expr Expression of data type `dtype`. Note that rows of the binary array where the length does not match the size in bytes of the output array (number of items * byte size of item) will become NULL. Examples -------- >>> df = pl.DataFrame({"data": [b"\x05\x00\x00\x00", b"\x10\x00\x01\x00"]}) >>> df.with_columns( # doctest: +IGNORE_RESULT ... bin2int=pl.col("data").bin.reinterpret( ... dtype=pl.Int32, endianness="little" ... ), ... ) shape: (2, 2) ┌─────────────────────┬─────────┠│ data ┆ bin2int │ │ --- ┆ --- │ │ binary ┆ i32 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•¡ │ b"\x05\x00\x00\x00" ┆ 5 │ │ b"\x10\x00\x01\x00" ┆ 65552 │ └─────────────────────┴─────────┘ )rrrZbin_reinterpretZ_pydatatype_expr)rr3r2rrrÚ reinterpret,s*ÿzExprBinaryNameSpace.reinterpretNÚoffsetúint | IntoExprÚlengthúint | IntoExpr | NonecCs"t|ƒ}t|ƒ}t|j ||¡ƒS)u Slice the binary values. Parameters ---------- offset Start index. Negative indexing is supported. length Length of the slice. If set to ``None`` (default), the slice is taken to the end of the value. Returns ------- Expr Expression of data type :class:`Binary`. Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... } ... ) >>> colors.with_columns( ... pl.col("code").bin.slice(1, 2).alias("sliced"), ... ) shape: (3, 3) ┌────────┬─────────────────┬─────────────┠│ name ┆ code ┆ sliced │ │ --- ┆ --- ┆ --- │ │ str ┆ binary ┆ binary │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ b"\x00\x00\x00" ┆ b"\x00\x00" │ │ yellow ┆ b"\xff\xff\x00" ┆ b"\xff\x00" │ │ blue ┆ b"\x00\x00\xff" ┆ b"\x00\xff" │ └────────┴─────────────────┴─────────────┘ )rrrZ bin_slice)rr6r8Z offset_pyexprZ length_pyexprrrrÚslice\s)zExprBinaryNameSpace.sliceéÚncCr)uÐ Take the first `n` bytes of the binary values. Parameters ---------- n Length of the slice (integer or expression). Negative indexing is supported; see note (2) below. Returns ------- Expr Expression of data type :class:`Binary`. Notes ----- (1) A similar method exists for taking the last `n` bytes: :func:`tail`. (2) If `n` is negative, it is interpreted as "until the nth byte from the end", e.g., ``head(-3)`` returns all but the last three bytes. Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... } ... ) >>> colors.with_columns( ... pl.col("code").bin.head(2).alias("head"), ... ) shape: (3, 3) ┌────────┬─────────────────┬─────────────┠│ name ┆ code ┆ head │ │ --- ┆ --- ┆ --- │ │ str ┆ binary ┆ binary │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ b"\x00\x00\x00" ┆ b"\x00\x00" │ │ yellow ┆ b"\xff\xff\x00" ┆ b"\xff\xff" │ │ blue ┆ b"\x00\x00\xff" ┆ b"\x00\x00" │ └────────┴─────────────────┴─────────────┘ Fr)rrrZbin_head©rr<Zn_pyexprrrrÚhead‰ó +zExprBinaryNameSpace.headcCr)uÊ Take the last `n` bytes of the binary values. Parameters ---------- n Length of the slice (integer or expression). Negative indexing is supported; see note (2) below. Returns ------- Expr Expression of data type :class:`Binary`. Notes ----- (1) A similar method exists for taking the first `n` bytes: :func:`head`. (2) If `n` is negative, it is interpreted as "starting at the nth byte", e.g., ``tail(-3)`` returns all but the first three bytes. Examples -------- >>> colors = pl.DataFrame( ... { ... "name": ["black", "yellow", "blue"], ... "code": [b"\x00\x00\x00", b"\xff\xff\x00", b"\x00\x00\xff"], ... } ... ) >>> colors.with_columns( ... pl.col("code").bin.tail(2).alias("tail"), ... ) shape: (3, 3) ┌────────┬─────────────────┬─────────────┠│ name ┆ code ┆ tail │ │ --- ┆ --- ┆ --- │ │ str ┆ binary ┆ binary │ â•žâ•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•¡ │ black ┆ b"\x00\x00\x00" ┆ b"\x00\x00" │ │ yellow ┆ b"\xff\xff\x00" ┆ b"\xff\x00" │ │ blue ┆ b"\x00\x00\xff" ┆ b"\x00\xff" │ └────────┴─────────────────┴─────────────┘ Fr)rrrZbin_tailr=rrrÚtail·r?zExprBinaryNameSpace.tailF)Ú null_on_oobÚindexrAcCst|ƒ}t|j ||¡ƒS)uÌ Get the byte value at the given index. For example, index `0` would return the first byte of every binary value and index `-1` would return the last byte of every binary value. If an index is out of bounds, it will return a `None`. Parameters ---------- index Index to return per binary value null_on_oob Behavior if an index is out of bounds: * True -> set as null * False -> raise an error Examples -------- >>> df = pl.DataFrame({"a": [b"\x01\x02\x03", b"", b"\x04\x05"]}) >>> df.with_columns(get=pl.col("a").bin.get(0, null_on_oob=True)) shape: (3, 2) ┌─────────────────┬──────┠│ a ┆ get │ │ --- ┆ --- │ │ binary ┆ u8 │ â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•¡ │ b"\x01\x02\x03" ┆ 1 │ │ b"" ┆ null │ │ b"\x04\x05" ┆ 4 │ └─────────────────┴──────┘ )rrrZbin_get)rrBrAZ index_pyexprrrrÚgetås!zExprBinaryNameSpace.get)rr rr)rr rr )rr rr )r!r rr )r$rr#r%rr )r$rrr )r-)r.r rr )r3r4r2r rr r)r6r7r8r9rr )r;)r<r7rr )rBr7rAr%rr )Ú__name__Ú __module__Ú __qualname__Ú__doc__Ú _accessorrrr r"r+r,r0r5r:r>r@rCrrrrrs"   / /1 / ,&ÿ1 ÿ - ..rN)Ú __future__rÚtypingrZpolars._utils.parserZpolars._utils.variousrZpolars._utils.wraprZpolars.datatypesrZpolarsrr Zpolars._typingr r r r rrrrrrÚs