ˀh]UddlmZddlZddlZddlmZmZmZmZm Z ddl m Z ddl m Z ddlmZddlmZddlmZmZdd lmZdd lmZmZdd lmZdd lmZmZdd lmZ ddlm!Z"ddl#m$Z$ddl%m&Z&ejNe(5ddl)m*Z*ddderddl+Z+ddl,m-Z-m.Z.ddl/m0Z0ddlm1Z1m2Z2m3Z3e+jhdk\rddlm5Z5nddl6m5Z5e+jhdk\rddlm7Z7nddl6m7Z7eee$e&e j6e jLe1e"jpe"jrfZ:de;d<dgZddd d#dZ?Gd dee Z@y#1swYxYw)$) annotationsN) TYPE_CHECKINGCallableGenericUnionoverload) FrameType)deprecate_renamed_parameter) is_pycapsule)issue_unstable_warning)_get_stack_localsqualified_type_name)wrap_ldf) from_arrow from_pandas) DataFrame)_check_for_pandas_check_for_pyarrow)pandas)pyarrow) LazyFrame)Series) PySQLContext) CollectionMapping) TracebackType)AnyFinalLiteral) ) TypeAlias)r )Selfr"CompatibleFrameType SQLContextc t|xst|txspt|xr*t|tj tj fxs7t|xr*t|tjtjfS)z2Check if the object can be converted to DataFrame.) r isinstancerrpdrrrpaTable RecordBatch)objs n/var/www/html/wine-match-dev/backend/winematch-backend/venv/lib/python3.12/site-packages/polars/sql/context.py_compatible_framer/;sq S U c9 % U c " Qz# bii7P'Q U s # S 32>>8R(S cnt|ttfr|jSt|tr|j jSt |ret|tjtjfr;tt|x}tr|j }|jSt|s5t|rCt|tjtjfrt|jSdt|}t!|)z'Return LazyFrame from compatible input.zunrecognised frame type: )r(rrlazyrto_framerr)rr rr*r+r,rr ValueError)r-framemsgs r._ensure_lazyframer7Es# 9-.xxz C ||~""$$ 3 JsR\\2994M$N {3//e 8NN$Ezz| c 3JsRXXr~~4N$O###%%)*=c*B)CDor0) n_objectsnamedcP|rtntttf}t |||S)z5Return compatible frame objects from the local stack.)of_typer8r9)r/rrrr )all_compatibler8r9r;s r._get_frame_localsr=Xs$$2 9f7UG W  OOr0c"eZdZUdZded<ded<ded<e d-ddd d  d.d Ze d-ddd  d/dZe d-ddd  d0dZedd d d1d d d d2dZeed d d3dZ eed4dZ eed5dZ ed d d5dZ d6dZ d7dZ d8dZ edd d9dZ e d:dZ e d;d Z edd dd#Z edd d?d$Z dd d?d%Z d@d&Z d1d'd( dAd)Z d1 dBd*ZdCd+ZdDd,Zy)Er&a  Run SQL queries against DataFrame, LazyFrame, and Series data. .. warning:: This functionality is considered **unstable**, although it is close to being considered stable. It may be changed at any point without it being considered a breaking change. r_ctxtz Final[bool]_eager_executionzlist[set[str]]_tables_scope_stack.F)register_globalsr<eagerrCc yNselfframesrBr<rC named_framess r.__init__zSQLContext.__init__wr0)rBr<c yrErFrGs r.rKzSQLContext.__init__rLr0c yrErFrGs r.rKzSQLContext.__init__rLr0eager_executionz0.20.31)versionN)rBrCc ,tdtj|_||_t |xsi}|r1t djD]\}}||vs ||vs|||<|s|r#|j||j|yy)u Initialize a new `SQLContext`. .. versionchanged:: 0.20.31 The `eager_execution` parameter was renamed `eager`. Parameters ---------- frames A `{name:frame, ...}` mapping which can include Polars frames *and* pandas DataFrames, Series and pyarrow Table and RecordBatch objects. register_globals Register compatible objects (polars DataFrame, LazyFrame, and Series) found in the globals, automatically mapping their variable name to a table name. To register other objects (pandas/pyarrow data) pass them explicitly, or call the `execute_global` classmethod. If given an integer then only the most recent "n" objects found will be registered. eager If True, returns execution results as `DataFrame` instead of `LazyFrame`. (Note that the query itself is always executed in lazy-mode; this parameter impacts whether :meth:`execute` returns an eager or lazy result frame). **named_frames Named eager/lazy frames, provided as kwargs. Examples -------- >>> lf = pl.LazyFrame({"a": [1, 2, 3], "b": ["x", None, "z"]}) >>> res = pl.SQLContext(frame=lf).execute( ... "SELECT b, a*2 AS two_a FROM frame WHERE b IS NOT NULL" ... ) >>> res.collect() shape: (2, 2) ┌─────┬───────┐ │ b ┆ two_a │ │ --- ┆ --- │ │ str ┆ i64 │ ╞═════╪═══════╡ │ x ┆ 2 │ │ z ┆ 6 │ └─────┴───────┘ zY`SQLContext` is considered **unstable**, although it is close to being considered stable.Fr<N) r rnewr?r@dictr=itemsupdate register_many)rHrIrBrCrJnamer-s r.rKzSQLContext.__init__sd  g "%%' %fl# .$eg - cv%$l*B),L&  - \ MM, '   v &"r0)rCcyrErFclsqueryrCs r.execute_globalzSQLContext.execute_globalsr0cyrErFrZs r.r]zSQLContext.execute_globalsORr0cyrErFrZs r.r]zSQLContext.execute_globalsRUr0ctjd|dtj}t|dkDr\tjd|dDchc]9}tjd|s|j r|j d;c}n t}td|}||d 5}|j|| cd d d Scc}w#1swYy xYw) u Immediately execute a SQL query, automatically registering frame globals. Notes ----- * This convenience method automatically registers all compatible objects in the local stack that are referenced in the query, mapping their variable name to a table name. Note that in addition to polars DataFrame, LazyFrame, and Series this method *also* registers pandas DataFrame, Series, and pyarrow Table and RecordBatch objects. * Instead of calling this classmethod you should consider using `pl.sql`, which will use this code internally. Parameters ---------- query A valid SQL query string. eager If True, returns execution results as `DataFrame` instead of `LazyFrame`. (Note that the query itself is always executed in lazy-mode). Examples -------- >>> import pandas as pd >>> df = pl.LazyFrame({"a": [1, 2, 3], "b": [4, 5, 6]}) >>> df_pandas = pd.DataFrame({"a": [2, 3, 4], "c": [7, 8, 9]}) Join a polars LazyFrame with a pandas DataFrame (note use of the preferred `pl.sql` method, which is equivalent to `SQLContext.execute_global`): >>> pl.sql("SELECT df.*, c FROM df JOIN df_pandas USING(a)").collect() shape: (2, 3) ┌─────┬─────┬─────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ i64 │ ╞═════╪═════╪═════╡ │ 2 ┆ 5 ┆ 7 │ │ 3 ┆ 6 ┆ 8 │ └─────┴─────┴─────┘ z\bFROM\b)maxsplitflagsz\bz ^("[^"]+")$"T)r<r9F)rIrB)r\rCN) resplitIlenmatch isidentifierstripsetr=execute)r[r\rCqnmpossible_namesrJctxs r.r]zSQLContext.execute_globals` HH[%!244 @1vz((5!A$/ 88NB/2??3D    )NS  u = 9;;U%;8 9 9  9 9s>C3CCct|dg|_|jjt|j |S)zITrack currently registered tables on scope entry; supports nested scopes.rA)getattrrAappendrltablesrHs r. __enter__zSQLContext.__enter__)s8#*41F#K    ''DKKM(:; r0c|jt|j|jj z y)z Unregister any tables created within the given scope on context exit. See Also -------- unregister )namesN) unregisterrlrurApop)rHexc_typeexc_valexc_tbs r.__exit__zSQLContext.__exit__/s7 t{{}%(@(@(D(D(FF  r0cZt|j}d|dt|ddS)Nz)rhruid)rHn_tabless r.__repr__zSQLContext.__repr__@s-t{{}%%hZwr$xl!DDr0cyrErFrHr\rCs r.rmzSQLContext.executeGr0cyrErFrs r.rmzSQLContext.executeLrr0cyrErFrs r.rmzSQLContext.executeQrr0cyrErFrs r.rmzSQLContext.executeVrr0cyrErFrs r.rmzSQLContext.execute[rr0cyrErFrs r.rmzSQLContext.execute`rr0cyrErFrs r.rmzSQLContext.executees!$r0ct|jj|}|s |jr|j S|S)u Parse the given SQL query and execute it against the registered frame data. Parameters ---------- query A valid string SQL query. eager Apply the query eagerly, returning `DataFrame` instead of `LazyFrame`. If unset, the value of the init-time "eager" parameter will be used. Note that the query itself is always executed in lazy-mode; this parameter only impacts the type of the returned frame. Examples -------- Declare frame data and register with a SQLContext: >>> df = pl.DataFrame( ... data=[ ... ("The Godfather", 1972, 6_000_000, 134_821_952, 9.2), ... ("The Dark Knight", 2008, 185_000_000, 533_316_061, 9.0), ... ("Schindler's List", 1993, 22_000_000, 96_067_179, 8.9), ... ("Pulp Fiction", 1994, 8_000_000, 107_930_000, 8.9), ... ("The Shawshank Redemption", 1994, 25_000_000, 28_341_469, 9.3), ... ], ... schema=["title", "release_year", "budget", "gross", "imdb_score"], ... orient="row", ... ) >>> ctx = pl.SQLContext(films=df) Execute a SQL query against the registered frame data: >>> ctx.execute( ... ''' ... SELECT title, release_year, imdb_score ... FROM films ... WHERE release_year > 1990 ... ORDER BY imdb_score DESC ... ''', ... eager=True, ... ) shape: (4, 3) ┌──────────────────────────┬──────────────┬────────────┐ │ title ┆ release_year ┆ imdb_score │ │ --- ┆ --- ┆ --- │ │ str ┆ i64 ┆ f64 │ ╞══════════════════════════╪══════════════╪════════════╡ │ The Shawshank Redemption ┆ 1994 ┆ 9.3 │ │ The Dark Knight ┆ 2008 ┆ 9.0 │ │ Schindler's List ┆ 1993 ┆ 8.9 │ │ Pulp Fiction ┆ 1994 ┆ 8.9 │ └──────────────────────────┴──────────────┴────────────┘ Execute a GROUP BY query: >>> ctx.execute( ... ''' ... SELECT ... MAX(release_year / 10) * 10 AS decade, ... SUM(gross) AS total_gross, ... COUNT(title) AS n_films, ... FROM films ... GROUP BY (release_year / 10) -- decade ... ORDER BY total_gross DESC ... ''', ... eager=True, ... ) shape: (3, 3) ┌────────┬─────────────┬─────────┐ │ decade ┆ total_gross ┆ n_films │ │ --- ┆ --- ┆ --- │ │ i64 ┆ i64 ┆ u32 │ ╞════════╪═════════════╪═════════╡ │ 2000 ┆ 533316061 ┆ 1 │ │ 1990 ┆ 232338648 ┆ 3 │ │ 1970 ┆ 134821952 ┆ 1 │ └────────┴─────────────┴─────────┘ )rr?rmr@collect)rHr\rCress r.rmzSQLContext.executejs9btzz))%01!&$*?*?s{{}IcIr0c| tn t|}|jj||j|S)u Register a single frame as a table, using the given name. Parameters ---------- name Name of the table. frame eager/lazy frame to associate with this table name. See Also -------- register_globals register_many unregister Examples -------- >>> df = pl.DataFrame({"hello": ["world"]}) >>> ctx = pl.SQLContext() >>> ctx.register("frame_data", df).execute("SELECT * FROM frame_data").collect() shape: (1, 1) ┌───────┐ │ hello │ │ --- │ │ str │ ╞═══════╡ │ world │ └───────┘ )rr7r?register_ldf)rHrXr5s r.rzSQLContext.registers4> %} 2CE2J D%**- r0TrRc@t||}|j|S)u9 Register all frames (lazy or eager) found in the current globals scope. Automatically maps variable names to table names. See Also -------- register register_many unregister Parameters ---------- n Register only the most recent "n" frames. all_compatible Control whether we *also* register pandas DataFrame, Series, and pyarrow Table and RecordBatch objects. If False, only Polars classes are registered with the SQL engine. Examples -------- >>> df1 = pl.DataFrame({"a": [1, 2, 3], "b": ["x", None, "z"]}) >>> df2 = pl.DataFrame({"a": [2, 3, 4], "c": ["t", "w", "v"]}) Register frames directly from variables found in the current globals scope: >>> ctx = pl.SQLContext(register_globals=True) >>> ctx.tables() ['df1', 'df2'] Query using the register variable/frame names >>> ctx.execute( ... "SELECT a, b, c FROM df1 LEFT JOIN df2 USING (a) ORDER BY a DESC" ... ).collect() shape: (3, 3) ┌─────┬──────┬──────┐ │ a ┆ b ┆ c │ │ --- ┆ --- ┆ --- │ │ i64 ┆ str ┆ str │ ╞═════╪══════╪══════╡ │ 3 ┆ z ┆ w │ │ 2 ┆ null ┆ t │ │ 1 ┆ x ┆ null │ └─────┴──────┴──────┘ )r<r8)rI)r=rW)rHnr<rIs r.rBzSQLContext.register_globalss%d#.AN!!!00r0c t|xsi}|j||jD]\}}|j|||S)a Register multiple eager/lazy frames as tables, using the associated names. Parameters ---------- frames A `{name:frame, ...}` mapping. **named_frames Named eager/lazy frames, provided as kwargs. See Also -------- register register_globals unregister Examples -------- >>> lf1 = pl.LazyFrame({"a": [1, 2, 3], "b": ["m", "n", "o"]}) >>> lf2 = pl.LazyFrame({"a": [2, 3, 4], "c": ["p", "q", "r"]}) >>> lf3 = pl.LazyFrame({"a": [3, 4, 5], "b": ["s", "t", "u"]}) >>> lf4 = pl.LazyFrame({"a": [4, 5, 6], "c": ["v", "w", "x"]}) Register multiple frames at once, either by passing in as a dict... >>> ctx = pl.SQLContext().register_many({"tbl1": lf1, "tbl2": lf2}) >>> ctx.tables() ['tbl1', 'tbl2'] ...or using keyword args: >>> ctx.register_many(tbl3=lf3, tbl4=lf4).tables() ['tbl1', 'tbl2', 'tbl3', 'tbl4'] )rTrVrUr)rHrIrJrXr5s r.rWzSQLContext.register_manysKNfl# l#!<<> 'KD% MM$ & ' r0cpt|tr|g}|D]}|jj||S)a Unregister one or more eager/lazy frames by name. Parameters ---------- names Names of the tables to unregister. Notes ----- You can also control table registration lifetime by using `SQLContext` as a context manager; this can often be more useful when such control is wanted: >>> df0 = pl.DataFrame({"colx": [0, 1, 2]}) >>> df1 = pl.DataFrame({"colx": [1, 2, 3]}) >>> df2 = pl.DataFrame({"colx": [2, 3, 4]}) Frames registered in-scope are automatically unregistered on scope-exit. Note that frames registered on construction will persist through subsequent scopes. >>> # register one frame at construction time, and the other two in-scope >>> with pl.SQLContext(tbl0=df0) as ctx: ... ctx.register_many(tbl1=df1, tbl2=df2).tables() ['tbl0', 'tbl1', 'tbl2'] After scope exit, none of the tables registered in-scope remain: >>> ctx.tables() ['tbl0'] See Also -------- register register_globals register_many Examples -------- >>> df0 = pl.DataFrame({"ints": [9, 8, 7, 6, 5]}) >>> lf1 = pl.LazyFrame({"text": ["a", "b", "c"]}) >>> lf2 = pl.LazyFrame({"misc": ["testing1234"]}) Register with a SQLContext object: >>> ctx = pl.SQLContext(test1=df0, test2=lf1, test3=lf2) >>> ctx.tables() ['test1', 'test2', 'test3'] Unregister one or more of the tables: >>> ctx.unregister(["test1", "test3"]).tables() ['test2'] >>> ctx.unregister("test2").tables() [] )r(strr?rz)rHryros r.rzzSQLContext.unregisterCs<p eS !GE &B JJ ! !" % & r0cHt|jjS)u) Return a list of the registered table names. Notes ----- The :meth:`tables` method will return the same values as the "SHOW TABLES" SQL statement, but as a list instead of a frame. Executing as SQL: >>> frame_data = pl.DataFrame({"hello": ["world"]}) >>> ctx = pl.SQLContext(hello_world=frame_data) >>> ctx.execute("SHOW TABLES", eager=True) shape: (1, 1) ┌─────────────┐ │ name │ │ --- │ │ str │ ╞═════════════╡ │ hello_world │ └─────────────┘ Calling the method: >>> ctx.tables() ['hello_world'] Examples -------- >>> df1 = pl.DataFrame({"hello": ["world"]}) >>> df2 = pl.DataFrame({"foo": ["bar", "baz"]}) >>> ctx = pl.SQLContext(hello_data=df1, foo_bar=df2) >>> ctx.tables() ['foo_bar', 'hello_data'] )sortedr? get_tablesrvs r.ruzSQLContext.tablessHdjj++-..r0).)rHSQLContext[LazyFrame]rI/Mapping[str, CompatibleFrameType | None] | NonerB bool | intr<boolrCLiteral[False]rJCompatibleFrameType | NonereturnNone)rHSQLContext[DataFrame]rIrrBrr<rrC Literal[True]rJrrr)rHrrIrrBrr<rrCrrJrrrrE) rIrrBrrCrrJrrr)r\rrCrrr)r\rrCrrr)r\rrCrrzDataFrame | LazyFrame)rzSQLContext[FrameType])r|ztype[BaseException] | Noner}zBaseException | Noner~zTracebackType | Nonerr)rr)rHrr\rrCrrr)rHrr\rrCrrr)rHrr\rrCrrr)rHrr\rrCrrr)rHrr\rrCrrr)rHrr\rrCrrr)r\rrCz bool | NonerzLazyFrame | DataFrame)rXrr5rrr$)r int | Noner<rrr$)rIrrJrrr$)ryzstr | Collection[str]rr$)rz list[str])__name__ __module__ __qualname____doc____annotations__rrKr classmethodr]rwrrrmrrBrWrzrurFr0r.r&r&cs !!''CF(+" % #?%     3 CF(+" #?%     3 CF(+" #?%     3 !!2GYOCGA'(- A'?A'% A'  A' 3 A' A'PA'F49#1 RR UU*/<9<9#'<9 <9<9|  , & %    "EBE#,/;? #,/;I #,/;H BE#,/;? #,/;I #,/;H 25$$$/$ $$ 37RJRJ$/RJ RJh!H#31>B31317;31 31nCG+?+3+  +Z<|$/r0)r-rrr)r-rrr)r<rr8rr9z4str | Collection[str] | Callable[[str], bool] | Nonerzdict[str, Any])A __future__r contextlibretypingrrrrrpolars._typingr polars._utils.deprecationr polars._utils.pycapsuler polars._utils.unstabler polars._utils.variousr rpolars._utils.wraprpolars.convertrrpolars.dataframerpolars.dependenciesrrrr)rr*polars.lazyframer polars.seriesrsuppress ImportError polars.polarsrsyscollections.abcrrtypesrrrr version_infor"typing_extensionsr$r+r,r%r__all__r/r7r=r&rFr0r.rsE" %A09H'2&E,-& Z%+*+3#** 7"$/ 7"*%*  #    & .,!BF PPP @ P  PB /#B /Q++s EE