Skip to content

Commit 216c2e0

Browse files
asthamohtavi3k6i5
asthamohta
and
vi3k6i5
authored
docs: Adding documentation for GA (#665)
* changes to docs for sphinx * remvoing warnings * adding sample code * linting * modifying import settings * settings changes * line accidently deleted in creation.py * lint_setup_py test * adding new lines and making changes to read me Co-authored-by: Vikash Singh <3116482+vi3k6i5@users.noreply.github.com>
1 parent fc51086 commit 216c2e0

17 files changed

+254
-46
lines changed

‎README.rst‎

Lines changed: 139 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,37 @@
11
Cloud Spanner support for Django
22
================================
33

4+
`Cloud Spanner`_ is the world's first fully managed relational database service
5+
to offer both strong consistency and horizontal scalability for
6+
mission-critical online transaction processing (OLTP) applications. With Cloud
7+
Spanner you enjoy all the traditional benefits of a relational database; but
8+
unlike any other relational database service, Cloud Spanner scales horizontally
9+
to hundreds or thousands of servers to handle the biggest transactional
10+
workloads.
11+
12+
13+
- `Client Library Documentation`_
14+
- `Product Documentation`_
15+
16+
.. _Cloud Spanner: https://cloud.google.com/spanner/
17+
.. _Client Library Documentation: https://googleapis.dev/python/django-google-spanner/latest/index.html
18+
.. _Product Documentation: https://cloud.google.com/spanner/docs
19+
20+
Quick Start
21+
-----------
22+
23+
In order to use this library, you first need to go through the following steps:
24+
25+
1. `Select or create a Cloud Platform project.`_
26+
2. `Enable billing for your project.`_
27+
3. `Enable the Google Cloud Spanner API.`_
28+
4. `Setup Authentication.`_
29+
30+
.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project
31+
.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project
32+
.. _Enable the Google Cloud Spanner API.: https://cloud.google.com/spanner
33+
.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
34+
435
This package provides a `3rd-party database backend
536
<https://docs.djangoproject.com/en/2.2/ref/databases/#using-a-3rd-party-database-backend>`__
637
for using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django
@@ -11,10 +42,40 @@ under the hood.
1142
Installation
1243
------------
1344

14-
To use this library, you'll need a Google Cloud Platform project with the Cloud
15-
Spanner API enabled. For details on enabling the API and authenticating with
16-
GCP, see the `Cloud Spanner Python client library quickstart guide
17-
<https://github.com/googleapis/python-spanner/#quick-start>`__.
45+
Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
46+
create isolated Python and Django environments. The basic problem it addresses is one of
47+
dependencies and versions, and indirectly permissions.
48+
49+
With `virtualenv`_, it's possible to install this library without needing system
50+
install permissions, and without clashing with the installed system
51+
dependencies.
52+
53+
.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/
54+
55+
56+
Mac/Linux
57+
~~~~~~~~~
58+
59+
.. code-block:: console
60+
61+
pip install virtualenv
62+
virtualenv <your-env>
63+
source <your-env>/bin/activate
64+
<your-env>/bin/pip install python-spanner-django
65+
<your-env>/bin/pip install google-cloud-spanner
66+
67+
68+
Windows
69+
~~~~~~~
70+
71+
.. code-block:: console
72+
73+
pip install virtualenv
74+
virtualenv <your-env>
75+
<your-env>\Scripts\activate
76+
<your-env>\Scripts\pip.exe install python-spanner-django
77+
<your-env>\Scripts\pip.exe install google-cloud-spanner
78+
1879
1980
Supported versions
2081
~~~~~~~~~~~~~~~~~~
@@ -93,52 +154,104 @@ configured:
93154
}
94155
95156
157+
Set credentials and project environment variables
158+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
159+
You'll need to download a service account JSON key file and point to it using an environment variable:
160+
161+
.. code:: shell
162+
163+
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
164+
export GOOGLE_CLOUD_PROJECT=gcloud_project
165+
166+
167+
Apply the migrations
168+
~~~~~~~~~~~~~~~~~~~~
169+
170+
Please run:
171+
172+
.. code:: shell
173+
174+
$ python3 manage.py migrate
175+
176+
and that'll take a while to run. After this you should be able to see the tables and indices created in your Cloud Spanner console.
177+
178+
Now run your server
179+
~~~~~~~~~~~~~~~~~~~
180+
After those migrations are completed, that will be all. Please continue on with the guides.
181+
182+
Create an Django admin user
183+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
184+
First you’ll need to create a user who can login to the admin site. Run the following command:
185+
186+
.. code:: shell
187+
188+
$ python3 manage.py createsuperuser
189+
190+
which will then produce a prompt which will allow you to create your super user
191+
192+
.. code:: shell
193+
194+
Username: admin
195+
Email address: admin@example.com
196+
Password: **********
197+
Password (again): **********
198+
Superuser created successfully.
199+
200+
201+
Login as admin
202+
~~~~~~~~~~~~~~
203+
Let’s run the server
204+
205+
.. code:: shell
206+
207+
python3 manage.py runserver
208+
209+
Then visit http://127.0.0.1:8000/admin/
210+
211+
Create and register your first model
212+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
213+
214+
Please follow the guides in https://docs.djangoproject.com/en/2.2/intro/tutorial02/#creating-models
215+
to create and register the model to the Django’s automatically-generated admin site.
216+
96217
How it works
97218
------------
98219

99220
Overall design
100221
~~~~~~~~~~~~~~
101222

102-
.. figure:: ./assets/overview.png
103-
:alt:
223+
.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/master/assets/overview.png
224+
:alt: "Overall Design"
104225

105226
Internals
106227
~~~~~~~~~
107228

108-
.. figure:: ./assets/internals.png
109-
:alt:
110-
229+
.. figure:: https://raw.githubusercontent.com/googleapis/python-spanner-django/master/assets/internals.png
230+
:alt: "Internals"
111231

112232

113233
Executing a query
114234
~~~~~~~~~~~~~~~~~
115235

116-
.. code:: python
117-
118-
from google.cloud.spanner_dbapi import connect
236+
Here is an example of how to add a row for Model Author, save it and later query it using Django
119237

120-
connection = connect('<instance_id>', '<database_id>')
121-
cursor = connection.cursor()
122-
123-
cursor.execute(
124-
"SELECT *"
125-
"FROM Singers"
126-
"WHERE SingerId = 15"
127-
)
238+
.. code:: shell
128239
129-
results = cursor.fetchall()
240+
>>> author_kent = Author( first_name="Arthur", last_name="Kent", rating=Decimal("4.1"),)
241+
>>> author_kent.save()
242+
>>> qs1 = Author.objects.all().values("first_name", "last_name")
130243
131244
132-
Contributing
133-
------------
245+
HOW TO CONTRIBUTE
246+
-----------------
134247

135248
Contributions to this library are always welcome and highly encouraged.
136249

137-
See [CONTRIBUTING][contributing] for more information on how to get started.
250+
See `CONTRIBUTING <https://github.com/googleapis/python-spanner-django/blob/master/CONTRIBUTING.md>`_ for more information on how to get started.
138251

139252
Please note that this project is released with a Contributor Code of Conduct.
140-
By participating in this project you agree to abide by its terms. See the `Code
141-
of Conduct <code-of-conduct.md>`_ for more information.
253+
By participating in this project you agree to abide by its terms. See the `Code
254+
of Conduct <https://github.com/googleapis/python-spanner-django/blob/master/CODE_OF_CONDUCT.md>`_ for more information.
142255

143256
Current limitations
144257
-------------------

‎django_spanner/functions.py‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ def cast(self, compiler, connection, **extra_context):
3838
A method to extend Django Cast class. Cast SQL query for given
3939
parameters.
4040
41-
:type self: :class:`~django.db.models.functions.comparison.Cast`
41+
:type self: :class:`~django.db.models.functions.Cast`
4242
:param self: the instance of the class that owns this method.
4343
4444
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -71,7 +71,7 @@ def chr_(self, compiler, connection, **extra_context):
7171
A method to extend Django Chr class. Returns a SQL query where the code
7272
points are displayed as a string.
7373
74-
:type self: :class:`~django.db.models.functions.text.Chr`
74+
:type self: :class:`~django.db.models.functions.Chr`
7575
:param self: the instance of the class that owns this method.
7676
7777
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -101,7 +101,7 @@ def concatpair(self, compiler, connection, **extra_context):
101101
A method to extend Django ConcatPair class. Concatenates a SQL query
102102
into the sequence of :class:`IfNull` objects.
103103
104-
:type self: :class:`~django.db.models.functions.text.ConcatPair`
104+
:type self: :class:`~django.db.models.functions.ConcatPair`
105105
:param self: the instance of the class that owns this method.
106106
107107
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -132,7 +132,7 @@ def cot(self, compiler, connection, **extra_context):
132132
A method to extend Django Cot class. Returns a SQL query of calculated
133133
trigonometric cotangent function.
134134
135-
:type self: :class:`~django.db.models.functions.math.Cot`
135+
:type self: :class:`~django.db.models.functions.Cot`
136136
:param self: the instance of the class that owns this method.
137137
138138
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -162,7 +162,7 @@ def degrees(self, compiler, connection, **extra_context):
162162
A method to extend Django Degress class. Returns a SQL query of the
163163
angle converted to degrees.
164164
165-
:type self: :class:`~django.db.models.functions.math.Degrees`
165+
:type self: :class:`~django.db.models.functions.Degrees`
166166
:param self: the instance of the class that owns this method.
167167
168168
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -190,8 +190,8 @@ def degrees(self, compiler, connection, **extra_context):
190190
def left_and_right(self, compiler, connection, **extra_context):
191191
"""A method to extend Django Left and Right classes.
192192
193-
:type self: :class:`~django.db.models.functions.text.Left` or
194-
:class:`~django.db.models.functions.text.Right`
193+
:type self: :class:`~django.db.models.functions.Left` or
194+
:class:`~django.db.models.functions.Right`
195195
:param self: the instance of the class that owns this method.
196196
197197
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -216,7 +216,7 @@ def log(self, compiler, connection, **extra_context):
216216
A method to extend Django Log class. Returns a SQL query of calculated
217217
logarithm.
218218
219-
:type self: :class:`~django.db.models.functions.math.Log`
219+
:type self: :class:`~django.db.models.functions.Log`
220220
:param self: the instance of the class that owns this method.
221221
222222
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -245,7 +245,7 @@ def ord_(self, compiler, connection, **extra_context):
245245
A method to extend Django Ord class. Returns a SQL query of the
246246
expression converted to ord.
247247
248-
:type self: :class:`~django.db.models.functions.text.Ord`
248+
:type self: :class:`~django.db.models.functions.Ord`
249249
:param self: the instance of the class that owns this method.
250250
251251
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -275,7 +275,7 @@ def pi(self, compiler, connection, **extra_context):
275275
A method to extend Django Pi class. Returns a SQL query of the Pi
276276
constant.
277277
278-
:type self: :class:`~django.db.models.functions.math.Pi`
278+
:type self: :class:`~django.db.models.functions.Pi`
279279
:param self: the instance of the class that owns this method.
280280
281281
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -302,7 +302,7 @@ def radians(self, compiler, connection, **extra_context):
302302
A method to extend Django Radians class. Returns a SQL query of the
303303
angle converted to radians.
304304
305-
:type self: :class:`~django.db.models.functions.math.Radians`
305+
:type self: :class:`~django.db.models.functions.Radians`
306306
:param self: the instance of the class that owns this method.
307307
308308
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -332,7 +332,7 @@ def strindex(self, compiler, connection, **extra_context):
332332
A method to extend Django StrIndex class. Returns a SQL query of the
333333
string position.
334334
335-
:type self: :class:`~django.db.models.functions.text.StrIndex`
335+
:type self: :class:`~django.db.models.functions.StrIndex`
336336
:param self: the instance of the class that owns this method.
337337
338338
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`
@@ -359,7 +359,7 @@ def substr(self, compiler, connection, **extra_context):
359359
A method to extend Django Substr class. Returns a SQL query of a
360360
substring.
361361
362-
:type self: :class:`~django.db.models.functions.text.Substr`
362+
:type self: :class:`~django.db.models.functions.Substr`
363363
:param self: the instance of the class that owns this method.
364364
365365
:type compiler: :class:`~django_spanner.compiler.SQLCompilerst`

‎docs/api-reference.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,12 @@ The following classes and methods constitute the Django Spanner API.
77
:maxdepth: 1
88

99
schema-api
10+
base-api
11+
compiler-api
12+
expressions-api
13+
functions-api
14+
introspection-api
15+
lookups-api
16+
utils-api
17+
creation-api
18+
operations-api

‎docs/base-api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Base API
2+
=====================
3+
4+
.. automodule:: django_spanner.base
5+
:members:
6+
:inherited-members:
7+

‎docs/compiler-api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Compiler API
2+
=====================
3+
4+
.. automodule:: django_spanner.compiler
5+
:members:
6+
:inherited-members:
7+

‎docs/conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,11 @@
1919
import sys
2020
import os
2121
import shlex
22+
import django
2223

24+
sys.path.insert(0, os.path.abspath(".."))
25+
os.environ["DJANGO_SETTINGS_MODULE"] = "tests.settings"
26+
django.setup()
2327
# If extensions (or modules to document with autodoc) are in another directory,
2428
# add this directory to sys.path here. If the directory is relative to the
2529
# documentation root, use os.path.abspath to make it absolute, like shown here.

‎docs/creation-api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Creation API
2+
=====================
3+
4+
.. automodule:: django_spanner.creation
5+
:members:
6+
:inherited-members:
7+

‎docs/expressions-api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Expressions API
2+
=====================
3+
4+
.. automodule:: django_spanner.expressions
5+
:members:
6+
:inherited-members:
7+

‎docs/functions-api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
Functions API
2+
=====================
3+
4+
.. automodule:: django_spanner.functions
5+
:members:
6+
:inherited-members:
7+

‎docs/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Usage Documentation
66
:maxdepth: 1
77
:titlesonly:
88

9-
schema-usage
9+
samples
1010

1111
API Documentation
1212
-----------------

0 commit comments

Comments
 (0)