Ë L iZVãó€—ddlmZddlmZmZmZddlmZmZer ddl m Z ddl m Z edd¬«Z Gd „d ee «Zy ) é)Ú annotations)Ú TYPE_CHECKINGÚGenericÚTypeVar)ÚExprKindÚExprNode)ÚExpr)ÚIntoExprÚExprTr )ÚboundcóÜ—eZdZdd„Zdd„Zdddœ dd„Zddœ dd„Zddd „Zdd „Zdd „Z ddœd d „Z dd!d„Z d"d„Z d#d$d„Z d#d$d„Zdd%d„Zdd%d„Zdd„Zdd„Zdd„Zd&d„Zy )'ÚExprStringNamespacecó—||_y©N)Ú_expr)ÚselfÚexprs úW/mnt/ssd/data/python-lab/Trading/venv/lib/python3.12/site-packages/narwhals/expr_str.pyÚ__init__zExprStringNamespace.__init__s €Øˆ ócóh—|jjttjd««S)u]Return the length of each string as the number of characters. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"words": ["foo", "345", None]}) >>> df = nw.from_native(df_native) >>> df.with_columns(words_len=nw.col("words").str.len_chars()) ┌─────────────────────┠| Narwhals DataFrame | |---------------------| |shape: (3, 2) | |┌───────┬───────────â”| |│ words ┆ words_len │| |│ --- ┆ --- │| |│ str ┆ u32 │| |â•žâ•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•¡| |│ foo ┆ 3 │| |│ 345 ┆ 3 │| |│ null ┆ null │| |└───────┴───────────┘| └─────────────────────┘ z str.len_chars©rÚ _append_noderrÚ ELEMENTWISE©rs rÚ len_charszExprStringNamespace.len_charss&€ð0z‰z×&Ñ&¤x´×0DÑ0DÀoÓ'VÓWÐWrFé)ÚliteralÚnc ót—|jjttjd||||d¬««S)uÑReplace first matching regex/literal substring with a new string value. Arguments: pattern: A valid regular expression pattern. value: String that will replace the matched substring. literal: Treat `pattern` as a literal string. n: Number of matches to replace. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": ["123abc", "abc abc123"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(replaced=nw.col("foo").str.replace("abc", "")) ┌──────────────────────┠| Narwhals DataFrame | |----------------------| | foo replaced| |0 123abc 123| |1 abc abc123 abc123| └──────────────────────┘ z str.replaceT)ÚpatternrrÚ str_as_litr)rr!Úvaluerrs rÚreplacezExprStringNamespace.replace,s>€ð2z‰z×&Ñ&Ü Ü×$Ñ$ØØØØØØô ó  ð r)rc ór—|jjttjd|||d¬««S)u¦Replace all matching regex/literal substring with a new string value. Arguments: pattern: A valid regular expression pattern. value: String that will replace the matched substring. literal: Treat `pattern` as a literal string. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"foo": ["123abc", "abc abc123"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(replaced=nw.col("foo").str.replace_all("abc", "")) ┌──────────────────────┠| Narwhals DataFrame | |----------------------| | foo replaced| |0 123abc 123| |1 abc abc123 123| └──────────────────────┘ zstr.replace_allT)r!rr"r)rr!r#rs rÚ replace_allzExprStringNamespace.replace_allQs;€ð0z‰z×&Ñ&Ü Ü×$Ñ$Ø!ØØØØô  ó  ð rNcól—|jjttjd|¬««S)aRemove leading and trailing characters. Arguments: characters: The set of characters to be removed. All combinations of this set of characters will be stripped from the start and end of the string. If set to None (default), all leading and trailing whitespace is removed instead. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"fruits": ["apple", "\nmango"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(stripped=nw.col("fruits").str.strip_chars()).to_dict( ... as_series=False ... ) {'fruits': ['apple', '\nmango'], 'stripped': ['apple', 'mango']} zstr.strip_chars)Ú charactersr)rr(s rÚ strip_charszExprStringNamespace.strip_charsts.€ð&z‰z×&Ñ&Ü ”X×)Ñ)Ð+<ÈÔ Tó ð rcól—|jjttjd|¬««S)uCheck if string values start with a substring. Arguments: prefix: prefix substring Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"fruits": ["apple", "mango", None]}) >>> df = nw.from_native(df_native) >>> df.with_columns(has_prefix=nw.col("fruits").str.starts_with("app")) ┌───────────────────┠|Narwhals DataFrame | |-------------------| | fruits has_prefix| |0 apple True| |1 mango False| |2 None None| └───────────────────┘ zstr.starts_with)Úprefixr)rr+s rÚ starts_withzExprStringNamespace.starts_with‹s.€ð*z‰z×&Ñ&Ü ”X×)Ñ)Ð+<ÀVÔ Ló ð rcól—|jjttjd|¬««S)uÿCheck if string values end with a substring. Arguments: suffix: suffix substring Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"fruits": ["apple", "mango", None]}) >>> df = nw.from_native(df_native) >>> df.with_columns(has_suffix=nw.col("fruits").str.ends_with("ngo")) ┌───────────────────┠|Narwhals DataFrame | |-------------------| | fruits has_suffix| |0 apple False| |1 mango True| |2 None None| └───────────────────┘ z str.ends_with)Úsuffixr)rr.s rÚ ends_withzExprStringNamespace.ends_with¤s-€ð*z‰z×&Ñ&Ü ”X×)Ñ)¨?À6Ô Jó ð rcón—|jjttjd||¬««S)a+Check if string contains a substring that matches a pattern. Arguments: pattern: A Character sequence or valid regular expression pattern. literal: If True, treats the pattern as a literal string. If False, assumes the pattern is a regular expression. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"pets": ["cat", "dog", "rabbit and parrot"]}) >>> df = nw.from_native(df_native) >>> df.with_columns( ... default_match=nw.col("pets").str.contains("cat|parrot"), ... case_insensitive_match=nw.col("pets").str.contains("cat|(?i)parrot"), ... ).to_native() pyarrow.Table pets: string default_match: bool case_insensitive_match: bool ---- pets: [["cat","dog","rabbit and parrot"]] default_match: [[true,false,true]] case_insensitive_match: [[true,false,true]] z str.contains)r!rr)rr!rs rÚcontainszExprStringNamespace.contains½s2€ð4z‰z×&Ñ&Ü Ü×$Ñ$ n¸gÈwô ó ð rcón—|jjttjd||¬««S)u’Create subslices of the string values of an expression. Arguments: 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 string. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"s": ["pear", None, "papaya"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(s_sliced=nw.col("s").str.slice(4, length=3)) ┌──────────────────┠|Narwhals DataFrame| |------------------| | s s_sliced| |0 pear | |1 None None| |2 papaya ya| └──────────────────┘ ú str.slice©ÚoffsetÚlengthr)rr5r6s rÚslicezExprStringNamespace.sliceÝs/€ð.z‰z×&Ñ&Ü ”X×)Ñ)¨;¸vÈfÔ Uó ð rcól—|jjttjd|¬««S)u Split the string values of an expression by a substring. Arguments: by: Substring to split by. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"s": ["foo bar", "foo_bar"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(nw.col("s").str.split("_").alias("s_split")) ┌────────────────────────────┠| Narwhals DataFrame | |----------------------------| |shape: (2, 2) | |┌─────────┬────────────────â”| |│ s ┆ s_split │| |│ --- ┆ --- │| |│ str ┆ list[str] │| |â•žâ•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡| |│ foo bar ┆ ["foo bar"] │| |│ foo_bar ┆ ["foo", "bar"] │| |└─────────┴────────────────┘| └────────────────────────────┘ z str.split)Úbyr)rr9s rÚsplitzExprStringNamespace.splitøs)€ð4z‰z×&Ñ&¤x´×0DÑ0DÀkÐVXÔ'YÓZÐZrcón—|jjttjdd|¬««S)aTake the first n elements of each string. Arguments: n: Number of elements to take. Negative indexing is **not** supported. Notes: If the length of the string has fewer than `n` characters, the full string is returned. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"lyrics": ["taata", "taatatata", "zukkyun"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(lyrics_head=nw.col("lyrics").str.head()).to_native() pyarrow.Table lyrics: string lyrics_head: string ---- lyrics: [["taata","taatatata","zukkyun"]] lyrics_head: [["taata","taata","zukky"]] r3rr4r©rrs rÚheadzExprStringNamespace.heads/€ð,z‰z×&Ñ&Ü ”X×)Ñ)¨;¸qÈÔ Kó ð rcóp—|jjttjd| d¬««S)aTake the last n elements of each string. Arguments: n: Number of elements to take. Negative indexing is **not** supported. Notes: If the length of the string has fewer than `n` characters, the full string is returned. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"lyrics": ["taata", "taatatata", "zukkyun"]}) >>> df = nw.from_native(df_native) >>> df.with_columns(lyrics_tail=nw.col("lyrics").str.tail()).to_native() pyarrow.Table lyrics: string lyrics_tail: string ---- lyrics: [["taata","taatatata","zukkyun"]] lyrics_tail: [["taata","atata","kkyun"]] r3Nr4rr<s rÚtailzExprStringNamespace.tail.s1€ð,z‰z×&Ñ&Ü ”X×)Ñ)¨;À¸rÈ$Ô Oó ð rcól—|jjttjd|¬««S)uConvert to Datetime dtype. Notes: - pandas defaults to nanosecond time unit, Polars to microsecond. Prior to pandas 2.0, nanoseconds were the only time unit supported in pandas, with no ability to set any other one. The ability to set the time unit in pandas, if the version permits, will arrive. - timezone-aware strings are all converted to and parsed as UTC. Warning: As different backends auto-infer format in different ways, if `format=None` there is no guarantee that the result will be equal. Arguments: format: Format to use for conversion. If set to None (default), the format is inferred from the data. Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame({"a": ["2020-01-01", "2020-01-02"]}) >>> df = nw.from_native(df_native) >>> df.select(nw.col("a").str.to_datetime(format="%Y-%m-%d")) ┌───────────────────────┠| Narwhals DataFrame | |-----------------------| |shape: (2, 1) | |┌─────────────────────â”| |│ a │| |│ --- │| |│ datetime[μs] │| |â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡| |│ 2020-01-01 00:00:00 │| |│ 2020-01-02 00:00:00 │| |└─────────────────────┘| └───────────────────────┘ zstr.to_datetime©Úformatr©rrBs rÚ to_datetimezExprStringNamespace.to_datetimeHs/€ðLz‰z×&Ñ&Ü ”X×)Ñ)Ð+<ÀVÔ Ló ð rcól—|jjttjd|¬««S)u=Convert to date dtype. Warning: As different backends auto-infer format in different ways, if `format=None` there is no guarantee that the result will be equal. Arguments: format: Format to use for conversion. If set to None (default), the format is inferred from the data. Examples: >>> import pyarrow as pa >>> import narwhals as nw >>> df_native = pa.table({"a": ["2020-01-01", "2020-01-02"]}) >>> df = nw.from_native(df_native) >>> df.select(nw.col("a").str.to_date(format="%Y-%m-%d")) ┌────────────────────────────┠| Narwhals DataFrame | |----------------------------| |pyarrow.Table | |a: date32[day] | |---- | |a: [[2020-01-01,2020-01-02]]| └────────────────────────────┘ z str.to_daterArrCs rÚto_datezExprStringNamespace.to_daters-€ð2z‰z×&Ñ&Ü ”X×)Ñ)¨=ÀÔ Hó ð rcóh—|jjttjd««S)u Transform string to uppercase variant. Notes: The PyArrow backend will convert 'ß' to 'ẞ' instead of 'SS'. For more info see [the related issue](https://github.com/apache/arrow/issues/34599). There may be other unicode-edge-case-related variations across implementations. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"fruits": ["apple", None]}) >>> df = nw.from_native(df_native) >>> df.with_columns(upper_col=nw.col("fruits").str.to_uppercase()) ┌──────────────────┠|Narwhals DataFrame| |------------------| | fruits upper_col| |0 apple APPLE| |1 None None| └──────────────────┘ zstr.to_uppercaserrs rÚ to_uppercasez ExprStringNamespace.to_uppercases'€ð,z‰z×&Ñ&¤x´×0DÑ0DÐFXÓ'YÓZÐZrcóh—|jjttjd««S)u‡Transform string to lowercase variant. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"fruits": ["APPLE", None]}) >>> df = nw.from_native(df_native) >>> df.with_columns(lower_col=nw.col("fruits").str.to_lowercase()) ┌──────────────────┠|Narwhals DataFrame| |------------------| | fruits lower_col| |0 APPLE apple| |1 None None| └──────────────────┘ zstr.to_lowercaserrs rÚ to_lowercasez ExprStringNamespace.to_lowercase§s'€ð"z‰z×&Ñ&¤x´×0DÑ0DÐFXÓ'YÓZÐZrcóh—|jjttjd««S)u¨ Modify strings to their titlecase equivalent. Notes: This is a form of case transform where the first letter of each word is capitalized, with the rest of the word in lowercase. Word boundaries are defined by non-**alphabetic** characters, matching the behavior of [`str.title`](https://docs.python.org/3/library/stdtypes.html#str.title) Examples: >>> import polars as pl >>> import narwhals as nw >>> df_native = pl.DataFrame( ... { ... "quotes": [ ... "'e.t. phone home'", ... "you talkin' to me?", ... "to infinity,and BEYOND!", ... ] ... } ... ) >>> df = nw.from_native(df_native) >>> df.with_columns(quotes_title=nw.col("quotes").str.to_titlecase()) ┌─────────────────────────────────────────────────────┠| Narwhals DataFrame | |-----------------------------------------------------| |shape: (3, 2) | |┌─────────────────────────┬─────────────────────────â”| |│ quotes ┆ quotes_title │| |│ --- ┆ --- │| |│ str ┆ str │| |â•žâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•ªâ•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•â•¡| |│ 'e.t. phone home' ┆ 'E.T. Phone Home' │| |│ you talkin' to me? ┆ You Talkin' To Me? │| |│ to infinity,and BEYOND! ┆ To Infinity,And Beyond! │| |└─────────────────────────┴─────────────────────────┘| └─────────────────────────────────────────────────────┘ zstr.to_titlecaserrs rÚ to_titlecasez ExprStringNamespace.to_titlecaseºs(€ðNz‰z×&Ñ&¤x´×0DÑ0DÐFXÓ'YÓZÐZrcól—|jjttjd|¬««S)uÂTransform string to zero-padded variant. Arguments: width: The desired length of the string after padding. If the length of the string is greater than `width`, no padding is applied. If `width` is less than 0, no padding is applied. Examples: >>> import pandas as pd >>> import narwhals as nw >>> df_native = pd.DataFrame({"digits": ["+1", "-1", "1", None]}) >>> df = nw.from_native(df_native) >>> df.with_columns(zfill_col=nw.col("digits").str.zfill(3)) ┌──────────────────┠|Narwhals DataFrame| |------------------| | digits zfill_col| |0 +1 +01| |1 -1 -01| |2 1 001| |3 None None| └──────────────────┘ z str.zfill)Úwidthr)rrNs rÚzfillzExprStringNamespace.zfillãs-€ð0z‰z×&Ñ&Ü ”X×)Ñ)¨;¸eÔ Dó ð r)rr ÚreturnÚNone)rPr ) r!Ústrr#zstr | IntoExprrÚboolrÚintrPr )r!rRr#r rrSrPr r)r(ú str | NonerPr )r+rRrPr )r.rRrPr )r!rRrrSrPr )r5rTr6z int | NonerPr )r9rRrPr )é)rrTrPr )rBrUrPr )rNrTrPr )Ú__name__Ú __module__Ú __qualname__rrr$r&r)r,r/r1r7r:r=r?rDrFrHrJrLrO©rrrrsÄ„óóXð6GLÐVWñ# Øð# Ø#1ð# Ø?Cð# ØPSð# à ó# ðLAFñ! Øð! Ø#+ð! Ø9=ð! à ó! ôF ó. ó2 ð29>õ ô@ ó6[ô8 ô4 ô4( ôT ó:[ó0[ó&'[ôR rrN)Ú __future__rÚtypingrrrÚnarwhals._expression_parsingrrÚ narwhals.exprr Únarwhals.typingr r rrZrrúr`s8ðÝ"ç2Ñ2ç;áÝ"Ý(á˜vÔ&€ôo ˜' %™.õo r