docs: add code snippets for session and IO public docs

samples/snippets/sessions_and_io_test.py

@@ -0,0 +1,169 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def test_sessions_and_io(project_id: str, dataset_id: str) -> None:
+    YOUR_PROJECT_ID = project_id
+    YOUR_LOCATION = "us"
+
+    # [START bigquery_dataframes_create_and_use_session_instance]
+    import bigframes
+    import bigframes.pandas as bpd
+
+    # Create session object
+    context = bigframes.BigQueryOptions(
+        project=YOUR_PROJECT_ID,
+        location=YOUR_LOCATION,
+    )
+    session = bigframes.Session(context)
+
+    # Load a BigQuery table into a dataframe
+    df1 = session.read_gbq("bigquery-public-data.ml_datasets.penguins")
+
+    # Create a dataframe with local data:
+    df2 = bpd.DataFrame({"my_col": [1, 2, 3]}, session=session)
+    # [END bigquery_dataframes_create_and_use_session_instance]
+    assert df1 is not None
+    assert df2 is not None
+
+    # [START bigquery_dataframes_combine_data_from_multiple_sessions_raise_error]
+    import bigframes
+    import bigframes.pandas as bpd
+
+    context = bigframes.BigQueryOptions(location=YOUR_LOCATION, project=YOUR_PROJECT_ID)
+
+    session1 = bigframes.Session(context)
+    session2 = bigframes.Session(context)
+
+    series1 = bpd.Series([1, 2, 3, 4, 5], session=session1)
+    series2 = bpd.Series([1, 2, 3, 4, 5], session=session2)
+
+    try:
+        series1 + series2
+    except ValueError as e:
+        print(e)  # Error message: Cannot use combine sources from multiple sessions
+    # [END bigquery_dataframes_combine_data_from_multiple_sessions_raise_error]
+
+    # [START bigquery_dataframes_set_options_for_global_session]
+    import bigframes.pandas as bpd
+
+    # Set project ID for the global session
+    bpd.options.bigquery.project = YOUR_PROJECT_ID
+    # Update the global default session location
+    bpd.options.bigquery.location = YOUR_LOCATION
+    # [END bigquery_dataframes_set_options_for_global_session]
+
+    # [START bigquery_dataframes_global_session_is_the_default_session]
+    # The following two statements are essentiall the same
+    df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
+    df = bpd.get_global_session().read_gbq("bigquery-public-data.ml_datasets.penguins")
+    # [END bigquery_dataframes_global_session_is_the_default_session]
+    assert df is not None
+
+    # [START bigquery_dataframes_create_dataframe_from_py_and_np]
+    import numpy as np
+
+    import bigframes.pandas as bpd
+
+    s = bpd.Series([1, 2, 3])
+
+    # Create a dataframe with Python dict
+    df = bpd.DataFrame(
+        {
+            "col_1": [1, 2, 3],
+            "col_2": [4, 5, 6],
+        }
+    )
+
+    # Create a series with Numpy
+    s = bpd.Series(np.arange(10))
+    # [END bigquery_dataframes_create_dataframe_from_py_and_np]
+    assert s is not None
+
+    # [START bigquery_dataframes_create_dataframe_from_pandas]
+    import numpy as np
+    import pandas as pd
+
+    import bigframes.pandas as bpd
+
+    pd_df = pd.DataFrame(np.random.randn(4, 2))
+
+    # Convert Pandas dataframe to BigQuery DataFrame with read_pandas()
+    df_1 = bpd.read_pandas(pd_df)
+    # Convert Pandas dataframe to BigQuery DataFrame with the dataframe constructor
+    df_2 = bpd.DataFrame(pd_df)
+    # [END bigquery_dataframes_create_dataframe_from_pandas]
+    assert df_1 is not None
+    assert df_2 is not None
+
+    # [START bigquery_dataframes_convert_bq_dataframe_to_pandas]
+    import bigframes.pandas as bpd
+
+    bf_df = bpd.DataFrame({"my_col": [1, 2, 3]})
+    # Returns a Pandas Dataframe
+    bf_df.to_pandas()
+
+    bf_s = bpd.Series([1, 2, 3])
+    # Returns a Pandas Series
+    bf_s.to_pandas()
+    # [END bigquery_dataframes_convert_bq_dataframe_to_pandas]
+    assert bf_s.to_pandas() is not None
+
+    # [START bigquery_dataframes_to_pandas_dry_run]
+    import bigframes.pandas as bpd
+
+    df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
+
+    # Returns a Pandas series with dry run stats
+    df.to_pandas(dry_run=True)
+    # [END bigquery_dataframes_to_pandas_dry_run]
+    assert df.to_pandas(dry_run=True) is not None
+
+    # [START bigquery_dataframes_read_data_from_csv]
+    import bigframes.pandas as bpd
+
+    # Read a CSV file from GCS
+    df = bpd.read_csv("gs://cloud-samples-data/bigquery/us-states/us-states.csv")
+    # [END bigquery_dataframes_read_data_from_csv]
+    assert df is not None
+
+    # [START bigquery_dataframes_read_data_from_bigquery_table]
+    import bigframes.pandas as bpd
+
+    df = bpd.read_gbq("bigquery-public-data.ml_datasets.penguins")
+    # [END bigquery_dataframes_read_data_from_bigquery_table]
+    assert df is not None
+
+    # [START bigquery_dataframes_read_from_sql_query]
+    import bigframes.pandas as bpd
+
+    sql = """
+    SELECT species, island, body_mass_g
+    FROM bigquery-public-data.ml_datasets.penguins
+    WHERE sex = 'MALE'
+    """
+
+    df = bpd.read_gbq(sql)
+    # [END bigquery_dataframes_read_from_sql_query]
+    assert df is not None
+
+    table_name = "snippets-session-and-io-test"
+
+    # [START bigquery_dataframes_dataframe_to_bigquery_table]
+    import bigframes.pandas as bpd
+
+    df = bpd.DataFrame({"my_col": [1, 2, 3]})
+
+    df.to_gbq(f"{project_id}.{dataset_id}.{table_name}")
+    # [END bigquery_dataframes_dataframe_to_bigquery_table]