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

[parthea]

See #10953.

This PR should be merged with a merge-commit, not a squash-commit, in order to preserve the git history.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request undertakes a significant structural reorganization by migrating the python-spanner-django project into a dedicated packages/django-google-spanner directory. This move aims to centralize the project's assets, including its source code, documentation, and testing infrastructure, into a more organized and maintainable layout. The changes ensure that the project continues to provide robust Cloud Spanner integration for Django applications, with updated development workflows and enhanced observability features.

Highlights

• Project Migration: The entire python-spanner-django project has been migrated into the packages/django-google-spanner directory, consolidating its codebase, documentation, and tests under a new, standardized path within the repository.
• Core Functionality Preservation: Existing Spanner-specific database operations, schema management, and Django compatibility logic have been moved and integrated into the new structure, ensuring no loss of functionality during the migration.
• Build and Test Infrastructure: New Nox configurations (noxfile.py) and shell scripts (django_test_suite_3.2.sh, django_test_suite_4.2.sh) have been added to manage testing across different Django versions and to streamline the build process.
• Documentation and Metadata Updates: Comprehensive documentation (under docs/), contribution guidelines (CONTRIBUTING.md), a code of conduct (CODE_OF_CONDUCT.md), and repository metadata (.repo-metadata.json) have been added or updated to reflect the new project structure and standards.
• OpenTelemetry Tracing Integration: OpenTelemetry tracing utilities have been introduced (django_spanner/_opentelemetry_tracing.py) and integrated into schema operations, allowing for better observability of database interactions.

Changelog

• packages/django-google-spanner/.coveragerc
  • Added a new coverage configuration file.
• packages/django-google-spanner/.gitignore
  • Added a new gitignore file for the package.
• packages/django-google-spanner/.librarian/state.yaml
  • Added librarian state configuration.
• packages/django-google-spanner/.repo-metadata.json
  • Added repository metadata for the django-google-spanner project.
• packages/django-google-spanner/CHANGELOG.md
  • Added the project's changelog, detailing releases up to 4.0.2.
• packages/django-google-spanner/CODE_OF_CONDUCT.md
  • Added a Contributor Code of Conduct.
• packages/django-google-spanner/CONTRIBUTING.md
  • Added contribution guidelines.
• packages/django-google-spanner/LICENSE
  • Added the BSD license file.
• packages/django-google-spanner/README.rst
  • Added the main README file for the package.
• packages/django-google-spanner/SECURITY.md
  • Added a security policy document.
• packages/django-google-spanner/create_test_instance.py
  • Added a script to create a Spanner test instance.
• packages/django-google-spanner/django_spanner/init.py
  • Added the package's initialization file, including AutoField monkey-patching and Django compatibility checks.
• packages/django-google-spanner/django_spanner/_opentelemetry_tracing.py
  • Added OpenTelemetry tracing utilities.
• packages/django-google-spanner/django_spanner/base.py
  • Added the core DatabaseWrapper implementation for Spanner.
• packages/django-google-spanner/django_spanner/client.py
  • Added the DatabaseClient for Spanner.
• packages/django-google-spanner/django_spanner/compiler.py
  • Added custom SQL compiler logic for Spanner.
• packages/django-google-spanner/django_spanner/creation.py
  • Added database creation and test skipping logic.
• packages/django-google-spanner/django_spanner/functions.py
  • Added custom SQL function registrations.
• packages/django-google-spanner/django_spanner/introspection.py
  • Added Spanner-specific database introspection.
• packages/django-google-spanner/django_spanner/lookups.py
  • Added custom Django lookup implementations for Spanner.
• packages/django-google-spanner/django_spanner/operations.py
  • Added Spanner-specific database operations.
• packages/django-google-spanner/django_spanner/schema.py
  • Added Spanner-specific schema editor logic.
• packages/django-google-spanner/django_spanner/utils.py
  • Added utility functions for Django compatibility and SQL modification.
• packages/django-google-spanner/django_spanner/version.py
  • Added the package version file.
• packages/django-google-spanner/django_test_apps.txt
  • Added a list of Django test applications.
• packages/django-google-spanner/django_test_suite_3.2.sh
  • Added a shell script for running Django 3.2 test suite.
• packages/django-google-spanner/django_test_suite_4.2.sh
  • Added a shell script for running Django 4.2 test suite.
• packages/django-google-spanner/docs/README.rst
  • Added documentation README.
• packages/django-google-spanner/docs/_static/custom.css
  • Added custom CSS for documentation.
• packages/django-google-spanner/docs/_templates/layout.html
  • Added custom layout for documentation.
• packages/django-google-spanner/docs/api-reference.rst
  • Added API reference documentation.
• packages/django-google-spanner/docs/base-api.rst
  • Added base API documentation.
• packages/django-google-spanner/docs/compiler-api.rst
  • Added compiler API documentation.
• packages/django-google-spanner/docs/conf.py
  • Added Sphinx configuration for documentation.
• packages/django-google-spanner/docs/creation-api.rst
  • Added creation API documentation.
• packages/django-google-spanner/docs/example_from_scratch.md
  • Added example documentation.
• packages/django-google-spanner/docs/example_healthchecks.md
  • Added example documentation.
• packages/django-google-spanner/docs/expressions-api.rst
  • Added expressions API documentation.
• packages/django-google-spanner/docs/functions-api.rst
  • Added functions API documentation.
• packages/django-google-spanner/docs/index.rst
  • Added main documentation index.
• packages/django-google-spanner/docs/introspection-api.rst
  • Added introspection API documentation.
• packages/django-google-spanner/docs/limitations-spanner.rst
  • Added Spanner-specific limitations documentation.
• packages/django-google-spanner/docs/limitations.rst
  • Added general limitations documentation.
• packages/django-google-spanner/docs/lookups-api.rst
  • Added lookups API documentation.
• packages/django-google-spanner/docs/operations-api.rst
  • Added operations API documentation.
• packages/django-google-spanner/docs/samples.rst
  • Added samples documentation.
• packages/django-google-spanner/docs/schema-api.rst
  • Added schema API documentation.
• packages/django-google-spanner/docs/utils-api.rst
  • Added utilities API documentation.
• packages/django-google-spanner/examples/from-scratch/README.md
  • Added example README.
• packages/django-google-spanner/examples/healthchecks/README.md
  • Added example README.
• packages/django-google-spanner/foreign_key_test.sh
  • Added a foreign key test script.
• packages/django-google-spanner/noxfile.py
  • Added Nox configuration for testing and building.
• packages/django-google-spanner/pyproject.toml
  • Added Black configuration.
• packages/django-google-spanner/renovate.json
  • Added Renovate configuration.
• packages/django-google-spanner/run_testing_worker.py
  • Added a script for running testing workers.
• packages/django-google-spanner/setup.cfg
  • Added Flake8 and isort configuration.
• packages/django-google-spanner/setup.py
  • Added the package setup file.
• packages/django-google-spanner/testing/constraints-3.6.txt
  • Added dependency constraints for testing.
• packages/django-google-spanner/tests/init.py
  • Added test package initialization.
• packages/django-google-spanner/tests/_helpers.py
  • Added test helper utilities, including OpenTelemetry base class.
• packages/django-google-spanner/tests/conftest.py
  • Added Pytest configuration.
• packages/django-google-spanner/tests/mockserver_tests/mock_database_admin.py
  • Added mock Spanner Database Admin servicer.
• packages/django-google-spanner/tests/mockserver_tests/mock_server_test_base.py
  • Added base class for mock server tests.
• packages/django-google-spanner/tests/mockserver_tests/mock_spanner.py
  • Added mock Spanner servicer.
• packages/django-google-spanner/tests/mockserver_tests/models.py
  • Added models for mock server tests.
• packages/django-google-spanner/tests/mockserver_tests/spanner_database_admin_pb2_grpc.py
  • Added gRPC generated code for Database Admin.
• packages/django-google-spanner/tests/mockserver_tests/spanner_pb2_grpc.py
  • Added gRPC generated code for Spanner.
• packages/django-google-spanner/tests/mockserver_tests/test_basics.py
  • Added basic mock server tests.
• packages/django-google-spanner/tests/performance/init.py
  • Added performance test package initialization.
• packages/django-google-spanner/tests/performance/django_spanner/init.py
  • Added performance test package initialization.
• packages/django-google-spanner/tests/performance/django_spanner/models.py
  • Added models for performance tests.
• packages/django-google-spanner/tests/performance/django_spanner/test_benchmark.py
  • Added benchmark tests.
• packages/django-google-spanner/tests/settings.py
  • Added Django settings for tests.
• packages/django-google-spanner/tests/system/init.py
  • Added system test package initialization.
• packages/django-google-spanner/tests/system/django_spanner/models.py
  • Added models for system tests.
• packages/django-google-spanner/tests/system/django_spanner/test_check_constraint.py
  • Added system tests for check constraints.
• packages/django-google-spanner/tests/system/django_spanner/test_decimal.py
  • Added system tests for decimal fields.
• packages/django-google-spanner/tests/system/django_spanner/test_json_field.py
  • Added system tests for JSON fields.
• packages/django-google-spanner/tests/system/django_spanner/test_queries.py
  • Added system tests for queries.
• packages/django-google-spanner/tests/system/django_spanner/utils.py
  • Added utilities for system tests.
• packages/django-google-spanner/tests/unit/django_spanner/models.py
  • Added models for unit tests.
• packages/django-google-spanner/tests/unit/django_spanner/simple_test.py
  • Added simple unit test base class.
• packages/django-google-spanner/tests/unit/django_spanner/test__opentelemetry_tracing.py
  • Added unit tests for OpenTelemetry tracing.
• packages/django-google-spanner/tests/unit/django_spanner/test_base.py
  • Added unit tests for DatabaseWrapper.
• packages/django-google-spanner/tests/unit/django_spanner/test_client.py
  • Added unit tests for DatabaseClient.
• packages/django-google-spanner/tests/unit/django_spanner/test_compiler.py
  • Added unit tests for SQL compiler.
• packages/django-google-spanner/tests/unit/django_spanner/test_expressions.py
  • Added unit tests for expressions.
• packages/django-google-spanner/tests/unit/django_spanner/test_functions.py
  • Added unit tests for custom functions.
• packages/django-google-spanner/tests/unit/django_spanner/test_introspection.py
  • Added unit tests for database introspection.
• packages/django-google-spanner/tests/unit/django_spanner/test_lookups.py
  • Added unit tests for custom lookups.
• packages/django-google-spanner/tests/unit/django_spanner/test_operations.py
  • Added unit tests for database operations.
• packages/django-google-spanner/tests/unit/django_spanner/test_schema.py
  • Added unit tests for schema editor.
• packages/django-google-spanner/tests/unit/django_spanner/test_utils.py
  • Added unit tests for utility functions.
• scripts/split_repo_migration/single-library.git-migrate-history.sh
  • Modified git clone and tree-filter commands to include an additional --recurse-submodules flag, ensuring proper handling of nested submodules during the migration process.

Activity

• The pull request description indicates that this PR should be merged with a merge-commit to preserve git history, referencing issue Adopt split repo: _python-spanner-django_ #10953.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request migrates the python-spanner-django library into the monorepo. The changes are extensive as they include the entire codebase and configuration files. My review focused on identifying potential issues introduced during the migration, such as outdated configurations, inconsistencies, and minor bugs. I've found several issues, primarily in the CI/CD configuration files, where incorrect paths could lead to build failures. I've also noted some critical inconsistencies in documentation regarding Python version requirements, which have been highlighted with reference to repository guidelines on breaking changes. Additionally, there are a few minor code improvements. Overall, the migration looks good, but these issues should be addressed to ensure a smooth transition and maintainability.

I am having trouble creating individual review comments. Click here to see my feedback.

packages/django-google-spanner/.kokoro/samples/python3.10/periodic-head.cfg (9-10)

The TRAMPOLINE_BUILD_FILE path appears to be incorrect. It points to a file in the python-pubsub repository, which is likely a copy-paste error. It should probably point to a file within the python-spanner-django repository, such as .kokoro/test-samples-against-head.sh.

    key: "TRAMPOLINE_BUILD_FILE"
    value: "github/python-spanner-django/.kokoro/test-samples-against-head.sh"

packages/django-google-spanner/.kokoro/samples/python3.6/periodic-head.cfg (9-10)

The TRAMPOLINE_BUILD_FILE path appears to be incorrect. It points to a file in the python-pubsub repository, which is likely a copy-paste error. It should probably point to a file within the python-spanner-django repository, such as .kokoro/test-samples-against-head.sh.

    key: "TRAMPOLINE_BUILD_FILE"
    value: "github/python-spanner-django/.kokoro/test-samples-against-head.sh"

packages/django-google-spanner/.kokoro/samples/python3.7/periodic-head.cfg (9-10)

The TRAMPOLINE_BUILD_FILE path appears to be incorrect. It points to a file in the python-pubsub repository, which is likely a copy-paste error. It should probably point to a file within the python-spanner-django repository, such as .kokoro/test-samples-against-head.sh.

    key: "TRAMPOLINE_BUILD_FILE"
    value: "github/python-spanner-django/.kokoro/test-samples-against-head.sh"

packages/django-google-spanner/.kokoro/samples/python3.8/periodic-head.cfg (9-10)

The TRAMPOLINE_BUILD_FILE path appears to be incorrect. It points to a file in the python-pubsub repository, which is likely a copy-paste error. It should probably point to a file within the python-spanner-django repository, such as .kokoro/test-samples-against-head.sh.

    key: "TRAMPOLINE_BUILD_FILE"
    value: "github/python-spanner-django/.kokoro/test-samples-against-head.sh"

packages/django-google-spanner/.kokoro/samples/python3.9/periodic-head.cfg (9-10)

The TRAMPOLINE_BUILD_FILE path appears to be incorrect. It points to a file in the python-pubsub repository, which is likely a copy-paste error. It should probably point to a file within the python-spanner-django repository, such as .kokoro/test-samples-against-head.sh.

    key: "TRAMPOLINE_BUILD_FILE"
    value: "github/python-spanner-django/.kokoro/test-samples-against-head.sh"

packages/django-google-spanner/README.rst (72)

The README states that the minimum required Python version is 3.6. However, setup.py specifies python_requires=">=3.8". This inconsistency is critical. Given the setup.py configuration, the README should be updated to state Python 3.8 as the minimum version. Note that changing the minimum supported Python version is a breaking change in environment requirements, which typically warrants a minor version bump to allow for patching previous versions, as per repository guidelines.

The minimum required Python version is 3.8.

References

1. Updating the minimum supported Python version from 3.6 to 3.8 constitutes a breaking change in environment requirements. Repository guidelines suggest a minor version bump for such changes to ensure proper versioning and support for users on older environments.

packages/django-google-spanner/setup.py (74)

The python_requires is set to >=3.8, which contradicts the README that states Python 3.6 is the minimum supported version. This inconsistency is critical. Please ensure all documentation and configuration files are consistent regarding the minimum Python version. If the minimum Python version is indeed 3.8, this represents a breaking change in environment requirements, which typically warrants a minor version bump to allow for patching previous versions, as per repository guidelines.

References

1. Updating the minimum supported Python version from 3.6 to 3.8 constitutes a breaking change in environment requirements. Repository guidelines suggest a minor version bump for such changes to ensure proper versioning and support for users on older environments.

packages/django-google-spanner/.github/workflows/integration-tests-against-emulator-3.10.yml (21)

There's a typo in the step name. It should be "Set up Python 3.10" to match the Python version being set up in this workflow.

      - name: Set up Python 3.10

packages/django-google-spanner/CHANGELOG.md (7)

The release date (2025-06-05) is in the future. This is likely a typo and should be corrected to the actual release date.

packages/django-google-spanner/django_spanner/init.py (70-75)

The comments on lines 72 and 74 refer to a DISABLE_RANDOM_ID_GENERATION setting, but the code uses RANDOM_ID_GENERATION_ENABLED. To avoid confusion, the comments should be updated to use the correct setting name.

packages/django-google-spanner/django_spanner/base.py (155)

The user_agent is hardcoded to an old version string "django_spanner/2.2.0a1". This should be dynamically set using the __version__ from django_spanner.version to ensure it's always up-to-date. You'll need to import __version__ from .version at the top of the file.

            "user_agent": f"django_spanner/{__version__}",