Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
docs: build documentation with Sphinx (#97)
Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/python-bigquery-sqlalchemy/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)

Fixes #90  🦕
  • Loading branch information
tswast committed Mar 25, 2021
1 parent e9d66fb commit 1707737
Show file tree
Hide file tree
Showing 6 changed files with 118 additions and 66 deletions.
28 changes: 0 additions & 28 deletions CONTRIBUTING.md

This file was deleted.

127 changes: 89 additions & 38 deletions README.rst
@@ -1,12 +1,88 @@
SQLAlchemy dialect and API client for BigQuery.
SQLAlchemy Dialect for BigQuery
===============================

|beta| |pypi| |versions|

Usage
=====
`SQLALchemy Dialects`_

- `Dialect Documentation`_
- `Product Documentation`_

.. |beta| image:: https://img.shields.io/badge/support-beta-orange.svg
:target: https://github.com/googleapis/google-cloud-python/blob/master/README.rst#beta-support
.. |pypi| image:: https://img.shields.io/pypi/v/pybigquery.svg
:target: https://pypi.org/project/pybigquery/
.. |versions| image:: https://img.shields.io/pypi/pyversions/pybigquery.svg
:target: https://pypi.org/project/pybigquery/
.. _SQLAlchemy Dialects: https://docs.sqlalchemy.org/en/14/dialects/
.. _Dialect Documentation: https://googleapis.dev/python/pybigquery/latest
.. _Product Documentation: https://cloud.google.com/bigquery/docs/


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
------------

Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
create isolated Python environments. The basic problem it addresses is one of
dependencies and versions, and indirectly permissions.

With `virtualenv`_, it's possible to install this library without needing system
install permissions, and without clashing with the installed system
dependencies.

.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/


Supported Python Versions
^^^^^^^^^^^^^^^^^^^^^^^^^
Python >= 3.6

Unsupported Python Versions
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Python <= 3.5.


Mac/Linux
^^^^^^^^^

.. code-block:: console
pip install virtualenv
virtualenv <your-env>
source <your-env>/bin/activate
<your-env>/bin/pip install pybigquery
Windows
^^^^^^^

.. code-block:: console
pip install virtualenv
virtualenv <your-env>
<your-env>\Scripts\activate
<your-env>\Scripts\pip.exe install pybigquery
Usage
-----

SQLAlchemy
__________
^^^^^^^^^^

.. code-block:: python
Expand All @@ -18,7 +94,7 @@ __________
print(select([func.count('*')], from_obj=table).scalar())
API Client
__________
^^^^^^^^^^

.. code-block:: python
Expand All @@ -27,12 +103,12 @@ __________
print(api_client.dry_run_query(query=sqlstr).total_bytes_processed)
Project
_______
^^^^^^^

``project`` in ``bigquery://project`` is used to instantiate BigQuery client with the specific project ID. To infer project from the environment, use ``bigquery://`` – without ``project``

Authentication
______________
^^^^^^^^^^^^^^

Follow the `Google Cloud library guide <https://google-cloud-python.readthedocs.io/en/latest/core/auth.html>`_ for authentication. Alternatively, you can provide the path to a service account JSON file in ``create_engine()``:

Expand All @@ -42,7 +118,7 @@ Follow the `Google Cloud library guide <https://google-cloud-python.readthedocs.
Location
________
^^^^^^^^

To specify location of your datasets pass ``location`` to ``create_engine()``:

Expand All @@ -52,7 +128,7 @@ To specify location of your datasets pass ``location`` to ``create_engine()``:
Table names
___________
^^^^^^^^^^^

To query tables from non-default projects or datasets, use the following format for the SQLAlchemy schema name: ``[project.]dataset``, e.g.:

Expand All @@ -64,7 +140,7 @@ To query tables from non-default projects or datasets, use the following format
sample_table_2 = Table('natality', schema='bigquery-public-data')
Batch size
__________
^^^^^^^^^^

By default, ``arraysize`` is set to ``5000``. ``arraysize`` is used to set the batch size for fetching results. To change it, pass ``arraysize`` to ``create_engine()``:

Expand All @@ -74,7 +150,7 @@ By default, ``arraysize`` is set to ``5000``. ``arraysize`` is used to set the b
Adding a Default Dataset
________________________
^^^^^^^^^^^^^^^^^^^^^^^^

If you want to have the ``Client`` use a default dataset, specify it as the "database" portion of the connection string.

Expand All @@ -100,7 +176,7 @@ Note that specifying a default dataset doesn't restrict execution of queries to
Connection String Parameters
____________________________
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

There are many situations where you can't call ``create_engine`` directly, such as when using tools like `Flask SQLAlchemy <http://flask-sqlalchemy.pocoo.org/2.3/>`_. For situations like these, or for situations where you want the ``Client`` to have a `default_query_job_config <https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/generated/google.cloud.bigquery.client.Client.html#google.cloud.bigquery.client.Client>`_, you can pass many arguments in the query of the connection string.

Expand Down Expand Up @@ -132,7 +208,7 @@ Here are examples of all the supported arguments. Any not present are either for
Creating tables
_______________
^^^^^^^^^^^^^^^

To add metadata to a table:

Expand All @@ -145,28 +221,3 @@ To add metadata to a column:
.. code-block:: python
Column('mycolumn', doc='my column description')
Requirements
============

Install using

- ``pip install pybigquery``


Testing
============

Load sample tables::

./scripts/load_test_data.sh

This will create a dataset ``test_pybigquery`` with tables named ``sample_one_row`` and ``sample``.

Set up an environment and run tests::

pyvenv .env
source .env/bin/activate
pip install -r dev_requirements.txt
pytest
1 change: 1 addition & 0 deletions docs/README.rst
1 change: 1 addition & 0 deletions docs/changelog.md
20 changes: 20 additions & 0 deletions docs/index.rst
@@ -0,0 +1,20 @@
.. include:: README.rst

.. include:: multiprocessing.rst

API Reference
-------------
.. toctree::
:maxdepth: 2

pybigquery/api

Changelog
---------

For a list of all ``pybigquery`` releases:

.. toctree::
:maxdepth: 2

changelog
7 changes: 7 additions & 0 deletions docs/pybigquery/api.rst
@@ -0,0 +1,7 @@
PyBigQuery API
==============

.. automodule:: pybigquery.api
:members:
:undoc-members:
:inherited-members:

0 comments on commit 1707737

Please sign in to comment.