chore(migration): Migrate code from googleapis/python-spanner-django into packages/django-google-spanner

.librarian/state.yaml

@@ -9,6 +9,15 @@ libraries:
     preserve_regex: []
     remove_regex: []
     tag_format: '{id}-v{version}'
+  - id: django-google-spanner
+    version: 4.0.2
+    last_generated_commit: ""
+    apis: []
+    source_roots:
+      - packages/django-google-spanner
+    preserve_regex: []
+    remove_regex: []
+    tag_format: '{id}-v{version}'
   - id: google-ads-admanager
     version: 0.8.0
     last_generated_commit: effe5c4fa816021e724ca856d5640f2e55b14a8b

packages/django-google-spanner/.coveragerc

@@ -0,0 +1,23 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright 2020 Google LLC
+#
+# Use of this source code is governed by a BSD-style
+# license that can be found in the LICENSE file or at
+# https://developers.google.com/open-source/licenses/bsd
+
+[run]
+branch = True
+
+[report]
+fail_under = 100
+show_missing = True
+exclude_lines =
+    # Re-enable the standard pragma
+    pragma: NO COVER
+    # Ignore debug-only repr
+    def __repr__
+    # Ignore abstract methods
+    raise NotImplementedError
+omit =
+  */site-packages/*.py

packages/django-google-spanner/.repo-metadata.json

@@ -0,0 +1,14 @@
+{
+    "name": "django-google-spanner",
+    "name_pretty": "Cloud Spanner Django",
+    "product_documentation": "https://cloud.google.com/spanner/docs/",
+    "client_documentation": "https://googleapis.dev/python/django-google-spanner/latest",
+    "issue_tracker": "https://issuetracker.google.com/issues?q=componentid:190851%2B%20status:open",
+    "release_level": "stable",
+    "language": "python",
+    "library_type": "INTEGRATION",
+    "repo": "googleapis/google-cloud-python",
+    "distribution_name": "django-google-spanner",
+    "requires_billing": true,
+    "api_shortname": "django-google-spanner"
+}

packages/django-google-spanner/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# How to Contribute
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
+
+## Community Guidelines
+
+This project follows [Google's Open Source Community
+Guidelines](https://opensource.google/conduct/).

packages/django-google-spanner/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2020 Google LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/django-google-spanner/README.rst

@@ -0,0 +1,288 @@
+Cloud Spanner support for Django
+================================
+
+|GA| |pypi| |versions|
+
+`Cloud Spanner`_ is the world's first fully managed relational database service
+to offer both strong consistency and horizontal scalability for
+mission-critical online transaction processing (OLTP) applications. With Cloud
+Spanner you enjoy all the traditional benefits of a relational database; but
+unlike any other relational database service, Cloud Spanner scales horizontally
+to hundreds or thousands of servers to handle the biggest transactional
+workloads.
+
+
+- `Client Library Documentation`_
+- `Product Documentation`_
+
+.. |GA| image:: https://img.shields.io/badge/support-GA-gold.svg
+   :target: https://github.com/googleapis/google-cloud-python/blob/main/README.rst#general-availability
+.. |pypi| image:: https://img.shields.io/pypi/v/django-google-spanner.svg
+   :target: https://pypi.org/project/django-google-spanner/
+.. |versions| image:: https://img.shields.io/pypi/pyversions/django-google-spanner.svg
+   :target: https://pypi.org/project/django-google-spanner/
+.. _Cloud Spanner: https://cloud.google.com/spanner/
+.. _Client Library Documentation: https://googleapis.dev/python/django-google-spanner/latest/index.html
+.. _Product Documentation:  https://cloud.google.com/spanner/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. `Enable billing for your project.`_
+3. `Enable the Google Cloud Spanner 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 Google Cloud Spanner API.:  https://cloud.google.com/spanner
+.. _Setup Authentication.: https://googleapis.dev/python/google-api-core/latest/auth.html
+
+This package provides a `3rd-party database backend
+<https://docs.djangoproject.com/en/4.2/ref/databases/#using-a-3rd-party-database-backend>`__
+for using `Cloud Spanner <https://cloud.google.com/spanner>`__ with the `Django
+ORM <https://docs.djangoproject.com/en/4.2/topics/db/>`__. It uses the `Cloud
+Spanner Python client library <https://github.com/googleapis/python-spanner>`__
+under the hood.
+
+Installation
+------------
+
+Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to
+create isolated Python and Django 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 versions
+~~~~~~~~~~~~~~~~~~
+
+The library supports `Django 3.2
+<https://docs.djangoproject.com/en/3.2/>`_, and `Django 4.2
+<https://docs.djangoproject.com/en/4.2/>`_.
+Both versions are long-term support (LTS) releases for the
+`Django project<https://www.djangoproject.com/download/#supported-versions>_`.
+The minimum required Python version is 3.6.
+
+.. code:: shell
+
+    pip3 install django==3.2
+
+
+Installing the package
+~~~~~~~~~~~~~~~~~~~~~~
+
+To install from PyPI:
+
+.. code:: shell
+
+    pip3 install django-google-spanner
+
+
+To install from source:
+
+.. code:: shell
+
+    git clone git@github.com:googleapis/google-cloud-python.git
+    cd python-spanner-django
+    pip3 install -e .
+
+
+Creating a Cloud Spanner instance and database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you don't already have a Cloud Spanner database, or want to start from
+scratch for a new Django application, you can `create a new instance
+<https://cloud.google.com/spanner/docs/getting-started/python#create_an_instance>`__
+and `database
+<https://cloud.google.com/spanner/docs/getting-started/python#create_a_database>`__
+using the Google Cloud SDK:
+
+.. code:: shell
+
+    gcloud spanner instances create $INSTANCE --config=regional-us-central1 --description="New Django Instance" --nodes=1
+    gcloud spanner databases create $DB --instance $INSTANCE
+
+
+Configuring ``settings.py``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This package provides a Django application named ``django_spanner``. To use the
+Cloud Spanner database backend, the application needs to installed and
+configured:
+
+-  Add ``django_spanner`` as the first entry in ``INSTALLED_APPS``:
+
+   .. code:: python
+
+       INSTALLED_APPS = [
+           'django_spanner',
+           ...
+       ]
+
+-  Edit the ``DATABASES`` setting to point to an existing Cloud Spanner database:
+
+   .. code:: python
+
+       DATABASES = {
+           'default': {
+               'ENGINE': 'django_spanner',
+               'PROJECT': '$PROJECT',
+               'INSTANCE': '$INSTANCE',
+               'NAME': '$DATABASE',
+           }
+       }
+
+Configuring primary key generation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Spanner Django engine by default uses random int64 values that are generated
+by the client as primary key values. This default is applied to all databases that are
+configured, including databases that use a different engine than Spanner. You can
+disable this behavior with the RANDOM_ID_GENERATION_ENABLED setting:
+
+   .. code:: python
+
+       DATABASES = {
+           'default': {
+               'ENGINE': 'django_spanner',
+               'PROJECT': '$PROJECT',
+               'INSTANCE': '$INSTANCE',
+               'NAME': '$DATABASE',
+               'RANDOM_ID_GENERATION_ENABLED': false,
+           }
+       }
+
+
+
+Transaction support in autocommit mode
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django version 4.2 and higher by default supports transactions in autocommit mode.
+A transaction is automatically started if you define an
+[atomic block](https://docs.djangoproject.com/en/4.2/topics/db/transactions/#controlling-transactions-explicitly).
+
+Django version 3.2 and earlier did not support transactions in autocommit mode with Spanner.
+You can enable transactions in autocommit mode with Spanner with the
+`ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` configuration option.
+
+- To enable transactions in autocommit mode in V3.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to True in your settings.py file.
+- To disable transactions in autocommit mode in V4.2, set the flag `ALLOW_TRANSACTIONS_IN_AUTO_COMMIT` to False in your settings.py file.
+
+
+Set credentials and project environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You'll need to download a service account JSON key file and point to it using an environment variable:
+
+.. code:: shell
+
+    export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
+    export GOOGLE_CLOUD_PROJECT=gcloud_project
+
+
+Apply the migrations
+~~~~~~~~~~~~~~~~~~~~
+
+Please run:
+
+.. code:: shell
+
+    $ python3 manage.py migrate
+
+That'll take a while to run. After this you should be able to see the tables and indexes created in your Cloud Spanner console.
+
+
+Create a Django admin user
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+First you’ll need to create a user who can login to the admin site. Run the following command:
+
+.. code:: shell
+
+    $ python3 manage.py createsuperuser
+
+which will then produce a prompt which will allow you to create your super user
+
+.. code:: shell
+
+    Username: admin
+    Email address: admin@example.com
+    Password: **********
+    Password (again): **********
+    Superuser created successfully.
+
+
+Login as admin
+~~~~~~~~~~~~~~
+Now, run the server
+
+.. code:: shell
+
+    python3 manage.py runserver
+
+Then visit http://127.0.0.1:8000/admin/
+
+Create and register your first model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please follow the guides in https://docs.djangoproject.com/en/4.2/intro/tutorial02/#creating-models
+to create and register the model to the Django’s automatically-generated admin site.
+
+How it works
+------------
+
+Overall design
+~~~~~~~~~~~~~~
+
+.. figure:: https://raw.githubusercontent.com/googleapis/google-cloud-python/main/assets/overview.png
+   :alt: "Overall Design"
+
+Internals
+~~~~~~~~~
+
+.. figure:: https://raw.githubusercontent.com/googleapis/google-cloud-python/main/assets/internals.png
+   :alt: "Internals"
+
+
+Executing a query
+~~~~~~~~~~~~~~~~~
+
+Here is an example of how to add a row for Model Author, save it and later query it using Django
+
+.. code:: shell
+
+    >>> author_kent = Author( first_name="Arthur", last_name="Kent", rating=Decimal("4.1"),)
+    >>> author_kent.save()
+    >>> qs1 = Author.objects.all().values("first_name", "last_name")
+
+
+How to contribute
+~~~~~~~~~~~~~~~~~
+
+Contributions to this library are always welcome and highly encouraged.
+
+See `CONTRIBUTING <https://github.com/googleapis/google-cloud-python/blob/main/CONTRIBUTING.md>`_ for more information on how to get started.
+
+Please note that this project is released with a Contributor Code of Conduct.
+By participating in this project you agree to abide by its terms. See the `Code 
+of Conduct <https://github.com/googleapis/google-cloud-python/blob/main/CODE_OF_CONDUCT.md>`_ for more information.
+
+
+Limitations
+~~~~~~~~~~~
+
+Spanner has certain limitations of its own. The full set of limitations is documented
+`here <https://cloud.google.com/spanner/quotas#schema_limits>`__.
+It is recommended that you go through that list.
+
+Django spanner has a set of limitations as well, which you can find
+`here <https://github.com/googleapis/google-cloud-python/blob/main/docs/limitations.rst>`__.
+
+Features from spanner that are not supported in Django-spanner are listed 
+`here <https://github.com/googleapis/google-cloud-python/blob/main/docs/limitations-spanner.rst>`__.