diff --git a/README.rst b/README.rst index 5ea347c..a14a61d 100644 --- a/README.rst +++ b/README.rst @@ -18,21 +18,6 @@ Pandas Data Types for SQL systems (BigQuery, Spanner) .. _Library Documentation: https://googleapis.dev/python/db-dtypes/latest -Quick Start ------------ - -In order to use this library, you first need to go through the following steps: - -1. `Select or create a Cloud Platform project.`_ -2. [Optional] `Enable billing for your project.`_ -3. `Enable the BigQuery Storage API.`_ -4. `Setup Authentication.`_ - -.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project -.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project -.. _Enable the BigQuery Storage API.: https://console.cloud.google.com/apis/library/bigquery.googleapis.com -.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html - Installation ------------ diff --git a/docs/conf.py b/docs/conf.py index 9482b97..5cf73ba 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -351,7 +351,7 @@ "grpc": ("https://grpc.github.io/grpc/python/", None), "proto-plus": ("https://proto-plus-python.readthedocs.io/en/latest/", None), "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None), - "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), } diff --git a/docs/index.rst b/docs/index.rst index f5f0b6f..ca497d5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,14 @@ .. include:: README.rst +How-to Guides +------------- + +.. toctree:: + :maxdepth: 2 + + usage + + API Reference ------------- diff --git a/docs/reference.rst b/docs/reference.rst index df1541d..fc9efb6 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -1,4 +1,4 @@ API Reference ^^^^^^^^^^^^^ -.. automodule:: db_dtypes.version +.. automodule:: db_dtypes diff --git a/docs/samples b/docs/samples new file mode 120000 index 0000000..e804737 --- /dev/null +++ b/docs/samples @@ -0,0 +1 @@ +../samples \ No newline at end of file diff --git a/docs/usage.rst b/docs/usage.rst new file mode 100644 index 0000000..5ecc562 --- /dev/null +++ b/docs/usage.rst @@ -0,0 +1,80 @@ +Using the db-dtypes package +--------------------------- + +Importing the :mod:`db_dtypes` module registers the extension dtypes for use +in pandas. + +Construct a date :class:`~pandas.Series` with strings in ``YYYY-MM-DD`` format +or :class:`datetime.date` objects. + +.. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_date_create] + :end-before: [END bigquery_pandas_date_create] + +Working with dates +^^^^^^^^^^^^^^^^^^ + +Convert a date :class:`~pandas.Series` to a ``datetime64`` Series with +:meth:`~pandas.Series.astype`. The resulting values use midnight as the +time part. + +.. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_date_as_datetime] + :end-before: [END bigquery_pandas_date_as_datetime] + +Just like ``datetime64`` values, date values can be subtracted. This is +equivalent to first converting to ``datetime64`` and then subtracting. + +.. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_date_sub] + :end-before: [END bigquery_pandas_date_sub] + +Just like ``datetime64`` values, :class:`~pandas.tseries.offsets.DateOffset` +values can be added to them. + +.. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_date_add_offset] + :end-before: [END bigquery_pandas_date_add_offset] + + +Working with times +^^^^^^^^^^^^^^^^^^ + +Construct a time :class:`~pandas.Series` with strings in ``HH:MM:SS.fraction`` +24-hour format or :class:`datetime.time` objects. + +.. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_time_create] + :end-before: [END bigquery_pandas_time_create] + +Convert a time :class:`~pandas.Series` to a ``timedelta64`` Series with +:meth:`~pandas.Series.astype`. + +.. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_time_as_timedelta] + :end-before: [END bigquery_pandas_time_as_timedelta] + + +Combining dates and times +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Combine a date :class:`~pandas.Series` with a time :class:`~pandas.Series` to +create a ``datetime64`` :class:`~pandas.Series`. + + .. literalinclude:: samples/snippets/pandas_date_and_time.py + :language: python + :dedent: 4 + :start-after: [START bigquery_pandas_combine_date_time] + :end-before: [END bigquery_pandas_combine_date_time] diff --git a/owlbot.py b/owlbot.py index 176e179..e6c264c 100644 --- a/owlbot.py +++ b/owlbot.py @@ -31,7 +31,9 @@ unit_test_python_versions=["3.6", "3.7", "3.8", "3.9"], system_test_python_versions=["3.8"], cov_level=100, - intersphinx_dependencies={"pandas": "http://pandas.pydata.org/pandas-docs/dev"}, + intersphinx_dependencies={ + "pandas": "https://pandas.pydata.org/pandas-docs/stable/" + }, ) s.move(templated_files, excludes=["docs/multiprocessing.rst"]) diff --git a/samples/snippets/pandas_date_and_time.py b/samples/snippets/pandas_date_and_time.py index bcb654d..3292e6c 100644 --- a/samples/snippets/pandas_date_and_time.py +++ b/samples/snippets/pandas_date_and_time.py @@ -14,7 +14,7 @@ def pandas_date_and_time(): - # [START bigquery_date_create] + # [START bigquery_pandas_date_create] import datetime import pandas as pd @@ -22,46 +22,45 @@ def pandas_date_and_time(): dates = pd.Series([datetime.date(2021, 9, 17), "2021-9-18"], dtype="dbdate") - # [END bigquery_date_create] - # [START bigquery_date_as_datetime] + # [END bigquery_pandas_date_create] + # [START bigquery_pandas_date_as_datetime] datetimes = dates.astype("datetime64") - # [END bigquery_date_as_datetime] - # [START bigquery_date_sub] + # [END bigquery_pandas_date_as_datetime] + # [START bigquery_pandas_date_sub] dates2 = pd.Series(["2021-1-1", "2021-1-2"], dtype="dbdate") diffs = dates - dates2 - # [END bigquery_date_sub] - # [START bigquery_date_do] + # [END bigquery_pandas_date_sub] + # [START bigquery_pandas_date_add_offset] do = pd.DateOffset(days=1) after = dates + do before = dates - do - # [END bigquery_date_do] - # [START bigquery_time_create] + # [END bigquery_pandas_date_add_offset] + # [START bigquery_pandas_time_create] times = pd.Series([datetime.time(1, 2, 3, 456789), "12:00:00.6"], dtype="dbtime") - # [END bigquery_time_create] - # [START bigquery_time_as_timedelta] + # [END bigquery_pandas_time_create] + # [START bigquery_pandas_time_as_timedelta] timedeltas = times.astype("timedelta64") - # [END bigquery_time_as_timedelta] - # [START bigquery_combine_date_time] + # [END bigquery_pandas_time_as_timedelta] - combined = datetimes + timedeltas + # Combine datetime64 and timedelta64 to confirm adding dates and times are + # equivalent. + combined0 = datetimes + timedeltas - # [END bigquery_combine_date_time] - combined0 = combined - # [START bigquery_combine2_date_time] + # [START bigquery_pandas_combine_date_time] combined = dates + times - # [END bigquery_combine2_date_time] + # [END bigquery_pandas_combine_date_time] return ( dates,