Skip to content

Commit 87306fd

Browse files
tseavertseaver
authored
Bigtable: prep docs for repo split. (#6014)
- Move 'docs/bigtable' -> 'bigtable/docs', leaving a symlink. - Harmonize / DRY 'bigtable/README.rst' and 'bigtable/docs/index.rst'. - Remove generated GAPIC docs (not part of the surface).
1 parent 59513b7 commit 87306fd

18 files changed

+993
-116
lines changed

‎README.rst

+70-33
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,90 @@
1-
Python Client for Google Cloud Bigtable
2-
=======================================
1+
Python Client for Google Cloud Bigtable (`Alpha`_)
2+
==================================================
33

4-
Python idiomatic client for `Google Cloud Bigtable`_
4+
|pypi| |versions|
55

6-
.. _Google Cloud Bigtable: https://cloud.google.com/bigtable/docs/
76

8-
|pypi| |versions|
7+
`Google Cloud Bigtable`_ is Google's NoSQL Big Data database service. It's the
8+
same database that powers many core Google services, including Search,
9+
Analytics, Maps, and Gmail.
910

10-
- `Documentation`_
11+
- `Client Library Documentation`_
12+
- `Product Documentation`_
1113

12-
.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigtable/usage.html
14+
.. _Alpha: https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/README.rst
15+
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigtable.svg
16+
:target: https://pypi.org/project/google-cloud-bigtable/
17+
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigtable.svg
18+
:target: https://pypi.org/project/google-cloud-bigtable/
19+
.. _Google Cloud Bigtable: https://cloud.google.com/bigtable
20+
.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/bigtable/usage.html
21+
.. _Product Documentation: https://cloud.google.com/bigtable/docs
1322

1423
Quick Start
1524
-----------
1625

17-
.. code-block:: console
26+
In order to use this library, you first need to go through the following steps:
1827

19-
$ pip install --upgrade google-cloud-bigtable
28+
1. `Select or create a Cloud Platform project.`_
29+
2. `Enable billing for your project.`_
30+
3. `Enable the Cloud Bigtable API.`_
31+
4. `Setup Authentication.`_
2032

21-
For more information on setting up your Python development environment,
22-
such as installing ``pip`` and ``virtualenv`` on your system, please refer
23-
to `Python Development Environment Setup Guide`_ for Google Cloud Platform.
33+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
34+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
35+
.. _Enable the Cloud Bigtable API.: https://cloud.google.com/bigtable
36+
.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html
2437

25-
.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup
38+
Installation
39+
~~~~~~~~~~~~
2640

27-
Authentication
28-
--------------
41+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
42+
create isolated Python environments. The basic problem it addresses is one of
43+
dependencies and versions, and indirectly permissions.
2944

30-
With ``google-cloud-python`` we try to make authentication as painless as
31-
possible. Check out the `Authentication section`_ in our documentation to
32-
learn more. You may also find the `authentication document`_ shared by all
33-
the ``google-cloud-*`` libraries to be helpful.
45+
With `virtualenv`_, it's possible to install this library without needing system
46+
install permissions, and without clashing with the installed system
47+
dependencies.
3448

35-
.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html
36-
.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication
49+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
3750

38-
Using the API
39-
-------------
4051

41-
Cloud `Bigtable`_ is Google's NoSQL Big Data database service. It's the same
42-
database that powers many core Google services, including Search,
43-
Analytics, Maps, and Gmail.
52+
Mac/Linux
53+
^^^^^^^^^
4454

45-
.. _Bigtable: https://cloud.google.com/bigtable/docs/
55+
.. code-block:: console
4656
47-
See the ``google-cloud-python`` API Bigtable `Documentation`_ to learn
48-
how to manage your data in Bigtable tables.
57+
pip install virtualenv
58+
virtualenv <your-env>
59+
source <your-env>/bin/activate
60+
<your-env>/bin/pip install google-cloud-bigtable
4961
50-
.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-bigtable.svg
51-
:target: https://pypi.org/project/google-cloud-bigtable/
52-
.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-bigtable.svg
53-
:target: https://pypi.org/project/google-cloud-bigtable/
62+
63+
Windows
64+
^^^^^^^
65+
66+
.. code-block:: console
67+
68+
pip install virtualenv
69+
virtualenv <your-env>
70+
<your-env>\Scripts\activate
71+
<your-env>\Scripts\pip.exe install google-cloud-bigtable
72+
73+
Next Steps
74+
~~~~~~~~~~
75+
76+
- Read the `Client Library Documentation`_ for Cloud Bigtable API
77+
to see other available methods on the client.
78+
- Read the `Product documentation`_ to learn
79+
more about the product and see How-to Guides.
80+
81+
``google-cloud-happybase``
82+
--------------------------
83+
84+
In addition to the core ``google-cloud-bigtable``, we provide a
85+
`google-cloud-happybase
86+
<http://google-cloud-python-happybase.readthedocs.io/en/latest/>`__ library
87+
with the same interface as the popular `HappyBase
88+
<https://happybase.readthedocs.io/en/latest/>`__ library. Unlike HappyBase,
89+
``google-cloud-happybase`` uses ``google-cloud-bigtable`` under the covers,
90+
rather than Apache HBase.

‎docs/changelog.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../CHANGELOG.md

‎docs/client-intro.rst

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
Base for Everything
2+
===================
3+
4+
To use the API, the :class:`Client <google.cloud.bigtable.client.Client>`
5+
class defines a high-level interface which handles authorization
6+
and creating other objects:
7+
8+
.. code:: python
9+
10+
from google.cloud.bigtable.client import Client
11+
client = Client()
12+
13+
Long-lived Defaults
14+
-------------------
15+
16+
When creating a :class:`Client <google.cloud.bigtable.client.Client>`, the
17+
``user_agent`` argument has sensible a default
18+
(:data:`DEFAULT_USER_AGENT <google.cloud.bigtable.client.DEFAULT_USER_AGENT>`).
19+
However, you may over-ride it and the value will be used throughout all API
20+
requests made with the ``client`` you create.
21+
22+
Configuration
23+
-------------
24+
25+
- For an overview of authentication in ``google-cloud-python``,
26+
see :doc:`/core/auth`.
27+
28+
- In addition to any authentication configuration, you can also set the
29+
:envvar:`GOOGLE_CLOUD_PROJECT` environment variable for the Google Cloud Console
30+
project you'd like to interact with. If your code is running in Google App
31+
Engine or Google Compute Engine the project will be detected automatically.
32+
(Setting this environment variable is not required, you may instead pass the
33+
``project`` explicitly when constructing a
34+
:class:`Client <google.cloud.storage.client.Client>`).
35+
36+
- After configuring your environment, create a
37+
:class:`Client <google.cloud.storage.client.Client>`
38+
39+
.. code::
40+
41+
>>> from google.cloud import bigtable
42+
>>> client = bigtable.Client()
43+
44+
or pass in ``credentials`` and ``project`` explicitly
45+
46+
.. code::
47+
48+
>>> from google.cloud import bigtable
49+
>>> client = bigtable.Client(project='my-project', credentials=creds)
50+
51+
.. tip::
52+
53+
Be sure to use the **Project ID**, not the **Project Number**.
54+
55+
Admin API Access
56+
----------------
57+
58+
If you'll be using your client to make `Instance Admin`_ and `Table Admin`_
59+
API requests, you'll need to pass the ``admin`` argument:
60+
61+
.. code:: python
62+
63+
client = bigtable.Client(admin=True)
64+
65+
Read-Only Mode
66+
--------------
67+
68+
If, on the other hand, you only have (or want) read access to the data,
69+
you can pass the ``read_only`` argument:
70+
71+
.. code:: python
72+
73+
client = bigtable.Client(read_only=True)
74+
75+
This will ensure that the
76+
:data:`READ_ONLY_SCOPE <google.cloud.bigtable.client.READ_ONLY_SCOPE>` is used
77+
for API requests (so any accidental requests that would modify data will
78+
fail).
79+
80+
Next Step
81+
---------
82+
83+
After a :class:`Client <google.cloud.bigtable.client.Client>`, the next highest-level
84+
object is an :class:`Instance <google.cloud.bigtable.instance.Instance>`. You'll need
85+
one before you can interact with tables or data.
86+
87+
Head next to learn about the :doc:`instance-api`.
88+
89+
.. _Instance Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/instance/v1
90+
.. _Table Admin: https://github.com/GoogleCloudPlatform/cloud-bigtable-client/tree/master/bigtable-protos/src/main/proto/google/bigtable/admin/table/v1

‎docs/client.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Client
2+
~~~~~~
3+
4+
.. automodule:: google.cloud.bigtable.client
5+
:members:
6+
:show-inheritance:

‎docs/cluster.rst

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Cluster
2+
~~~~~~~
3+
4+
.. automodule:: google.cloud.bigtable.cluster
5+
:members:
6+
:show-inheritance:

‎docs/column-family.rst

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
Column Families
2+
===============
3+
4+
When creating a
5+
:class:`ColumnFamily <google.cloud.bigtable.column_family.ColumnFamily>`, it is
6+
possible to set garbage collection rules for expired data.
7+
8+
By setting a rule, cells in the table matching the rule will be deleted
9+
during periodic garbage collection (which executes opportunistically in the
10+
background).
11+
12+
The types
13+
:class:`MaxAgeGCRule <google.cloud.bigtable.column_family.MaxAgeGCRule>`,
14+
:class:`MaxVersionsGCRule <google.cloud.bigtable.column_family.MaxVersionsGCRule>`,
15+
:class:`GarbageCollectionRuleUnion <google.cloud.bigtable.column_family.GarbageCollectionRuleUnion>` and
16+
:class:`GarbageCollectionRuleIntersection <google.cloud.bigtable.column_family.GarbageCollectionRuleIntersection>`
17+
can all be used as the optional ``gc_rule`` argument in the
18+
:class:`ColumnFamily <google.cloud.bigtable.column_family.ColumnFamily>`
19+
constructor. This value is then used in the
20+
:meth:`create() <google.cloud.bigtable.column_family.ColumnFamily.create>` and
21+
:meth:`update() <google.cloud.bigtable.column_family.ColumnFamily.update>` methods.
22+
23+
These rules can be nested arbitrarily, with a
24+
:class:`MaxAgeGCRule <google.cloud.bigtable.column_family.MaxAgeGCRule>` or
25+
:class:`MaxVersionsGCRule <google.cloud.bigtable.column_family.MaxVersionsGCRule>`
26+
at the lowest level of the nesting:
27+
28+
.. code:: python
29+
30+
import datetime
31+
32+
max_age = datetime.timedelta(days=3)
33+
rule1 = MaxAgeGCRule(max_age)
34+
rule2 = MaxVersionsGCRule(1)
35+
36+
# Make a composite that matches anything older than 3 days **AND**
37+
# with more than 1 version.
38+
rule3 = GarbageCollectionIntersection(rules=[rule1, rule2])
39+
40+
# Make another composite that matches our previous intersection
41+
# **OR** anything that has more than 3 versions.
42+
rule4 = GarbageCollectionRule(max_num_versions=3)
43+
rule5 = GarbageCollectionUnion(rules=[rule3, rule4])
44+
45+
----
46+
47+
.. automodule:: google.cloud.bigtable.column_family
48+
:members:
49+
:show-inheritance:

0 commit comments

Comments
 (0)