feat: create alias alloydbconnector package (#451)

This PR creates a new package: google.cloud.alloydbconnector, which is an alias to google.cloud.alloydb.connector. The implementation resides in google.cloud.alloydbconnector, and google.cloud.alloydb.connector points to it.
So importing google.cloud.alloydbconnector is the same as importing google.cloud.alloydb.connector.

This PR aims to fix googleapis/google-cloud-python#13871, where a PEX environment, containing google-cloud-alloydb and alloydb-python-connector packages, fails to import google.cloud.alloydb.connector, because it attempts to find a connector/ directory under the google-cloud-alloydb package, which does not exist. The fix is that the user should import the google.cloud.alloydbconnector package instead.

This PR also updates the README and integration tests to mention importing google.cloud.alloydbconnector instead of google.cloud.alloydb.connector. This serves as documentation so that new users of the library will instead import google.cloud.alloydbconnector. Existing users can continue to import google.cloud.alloydb.connector without any issues.

Author: rhatgadkar-goog

README.md

@@ -105,9 +105,18 @@ AlloyDB private IP address.
 
 Please see [Configuring AlloyDB Connectivity][alloydb-connectivity] for more details.
 
+There are two ways to import this AlloyDB connector package:
+1. `import google.cloud.alloydbconnector`
+2. `import google.cloud.alloydb.connector`
+
+The preferred way is `import google.cloud.alloydbconnector` to avoid namespace
+collisions with the [google-cloud-alloydb][alloydb-py-lib] package. Meanwhile,
+`import google.cloud.alloydb.connector` will continue to work forever.
+
 [vpc]: https://cloud.google.com/vpc/docs/vpc
 [alloydb-connectivity]: https://cloud.google.com/alloydb/docs/configure-connectivity
 [psc]: https://cloud.google.com/vpc/docs/private-service-connect
+[alloydb-py-lib]: https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-alloydb
 
 ### Synchronous Driver Usage
 
@@ -128,7 +137,7 @@ like `user`, `password` and `db` etc.
 To use this connector with SQLAlchemy, use the `creator` argument for `sqlalchemy.create_engine`:
 
 ```python
-from google.cloud.alloydb.connector import Connector
+from google.cloud.alloydbconnector import Connector
 import sqlalchemy
 
 # initialize Connector object
@@ -188,7 +197,7 @@ calls to `connector.close()`.
 Connector as a context manager:
 
 ```python
-from google.cloud.alloydb.connector import Connector
+from google.cloud.alloydbconnector import Connector
 import sqlalchemy
 
 # initialize Connector as context manager
@@ -239,7 +248,7 @@ currently supports the following asyncio database drivers:
 
 ```python
 import asyncpg
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 async def main():
     # initialize AsyncConnector object for connections to AlloyDB
@@ -273,7 +282,7 @@ import asyncpg
 import sqlalchemy
 from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 async def init_connection_pool(connector: AsyncConnector) -> AsyncEngine:
     # The AlloyDB Python Connector can be used along with SQLAlchemy using the
@@ -326,7 +335,7 @@ need for explicit calls to `connector.close()` to cleanup resources.
 
 ```python
 import asyncpg
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 async def main():
     # initialize AsyncConnector object for connections to AlloyDB
@@ -358,7 +367,7 @@ import asyncpg
 import sqlalchemy
 from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine
 
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 async def init_connection_pool(connector: AsyncConnector) -> AsyncEngine:
     # The AlloyDB Python Connector can be used along with SQLAlchemy using the
@@ -453,7 +462,7 @@ and `"PSC"`.
 Example:
 
 ```python
-from google.cloud.alloydb.connector import Connector
+from google.cloud.alloydbconnector import Connector
 
 import sqlalchemy
 
@@ -489,7 +498,7 @@ Python Connector:
 import logging
 
 logging.basicConfig(format="%(asctime)s [%(levelname)s]: %(message)s")
-logger = logging.getLogger(name="google.cloud.alloydb.connector")
+logger = logging.getLogger(name="google.cloud.alloydbconnector")
 logger.setLevel(logging.DEBUG)
 ```
 

google/cloud/alloydb/connector/__init__.py

@@ -11,11 +11,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from google.cloud.alloydb.connector.async_connector import AsyncConnector
-from google.cloud.alloydb.connector.connector import Connector
-from google.cloud.alloydb.connector.enums import IPTypes
-from google.cloud.alloydb.connector.enums import RefreshStrategy
-from google.cloud.alloydb.connector.version import __version__
+from google.cloud.alloydbconnector import __version__
+from google.cloud.alloydbconnector import AsyncConnector
+from google.cloud.alloydbconnector import Connector
+from google.cloud.alloydbconnector import IPTypes
+from google.cloud.alloydbconnector import RefreshStrategy
 
 __all__ = [
     "__version__",

google/cloud/alloydbconnector/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from google.cloud.alloydbconnector.async_connector import AsyncConnector
+from google.cloud.alloydbconnector.connector import Connector
+from google.cloud.alloydbconnector.enums import IPTypes
+from google.cloud.alloydbconnector.enums import RefreshStrategy
+from google.cloud.alloydbconnector.version import __version__
+
+__all__ = [
+    "__version__",
+    "Connector",
+    "AsyncConnector",
+    "IPTypes",
+    "RefreshStrategy",
+]

google/cloud/alloydb/connector/async_connector.py renamed to google/cloud/alloydbconnector/async_connector.py

@@ -23,16 +23,16 @@
 from google.auth.credentials import with_scopes_if_required
 import google.auth.transport.requests
 
-import google.cloud.alloydb.connector.asyncpg as asyncpg
-from google.cloud.alloydb.connector.client import AlloyDBClient
-from google.cloud.alloydb.connector.enums import IPTypes
-from google.cloud.alloydb.connector.enums import RefreshStrategy
-from google.cloud.alloydb.connector.exceptions import ClosedConnectorError
-from google.cloud.alloydb.connector.instance import RefreshAheadCache
-from google.cloud.alloydb.connector.lazy import LazyRefreshCache
-from google.cloud.alloydb.connector.types import CacheTypes
-from google.cloud.alloydb.connector.utils import generate_keys
-from google.cloud.alloydb.connector.utils import strip_http_prefix
+import google.cloud.alloydbconnector.asyncpg as asyncpg
+from google.cloud.alloydbconnector.client import AlloyDBClient
+from google.cloud.alloydbconnector.enums import IPTypes
+from google.cloud.alloydbconnector.enums import RefreshStrategy
+from google.cloud.alloydbconnector.exceptions import ClosedConnectorError
+from google.cloud.alloydbconnector.instance import RefreshAheadCache
+from google.cloud.alloydbconnector.lazy import LazyRefreshCache
+from google.cloud.alloydbconnector.types import CacheTypes
+from google.cloud.alloydbconnector.utils import generate_keys
+from google.cloud.alloydbconnector.utils import strip_http_prefix
 
 if TYPE_CHECKING:
     from google.auth.credentials import Credentials

google/cloud/alloydb/connector/asyncpg.py renamed to google/cloud/alloydbconnector/asyncpg.py

@@ -26,8 +26,8 @@
 import google.cloud.alloydb_v1beta as v1beta
 from google.protobuf import duration_pb2
 
-from google.cloud.alloydb.connector.connection_info import ConnectionInfo
-from google.cloud.alloydb.connector.version import __version__ as version
+from google.cloud.alloydbconnector.connection_info import ConnectionInfo
+from google.cloud.alloydbconnector.version import __version__ as version
 
 if TYPE_CHECKING:
     from google.auth.credentials import Credentials

google/cloud/alloydb/connector/client.py renamed to google/cloud/alloydbconnector/client.py

@@ -21,15 +21,15 @@
 
 from aiofiles.tempfile import TemporaryDirectory
 
-from google.cloud.alloydb.connector.exceptions import IPTypeNotFoundError
-from google.cloud.alloydb.connector.utils import _write_to_file
+from google.cloud.alloydbconnector.exceptions import IPTypeNotFoundError
+from google.cloud.alloydbconnector.utils import _write_to_file
 
 if TYPE_CHECKING:
     import datetime
 
     from cryptography.hazmat.primitives.asymmetric.types import PrivateKeyTypes
 
-    from google.cloud.alloydb.connector.enums import IPTypes
+    from google.cloud.alloydbconnector.enums import IPTypes
 
 logger = logging.getLogger(name=__name__)
 

google/cloud/alloydb/connector/connection_info.py renamed to google/cloud/alloydbconnector/connection_info.py

@@ -29,17 +29,17 @@
 from google.auth.credentials import with_scopes_if_required
 from google.auth.transport import requests
 
-from google.cloud.alloydb.connector.client import AlloyDBClient
-from google.cloud.alloydb.connector.enums import IPTypes
-from google.cloud.alloydb.connector.enums import RefreshStrategy
-from google.cloud.alloydb.connector.exceptions import ClosedConnectorError
-from google.cloud.alloydb.connector.instance import RefreshAheadCache
-from google.cloud.alloydb.connector.lazy import LazyRefreshCache
-import google.cloud.alloydb.connector.pg8000 as pg8000
-from google.cloud.alloydb.connector.types import CacheTypes
-from google.cloud.alloydb.connector.utils import generate_keys
-from google.cloud.alloydb.connector.utils import strip_http_prefix
 import google.cloud.alloydb_connectors_v1.proto.resources_pb2 as connectorspb
+from google.cloud.alloydbconnector.client import AlloyDBClient
+from google.cloud.alloydbconnector.enums import IPTypes
+from google.cloud.alloydbconnector.enums import RefreshStrategy
+from google.cloud.alloydbconnector.exceptions import ClosedConnectorError
+from google.cloud.alloydbconnector.instance import RefreshAheadCache
+from google.cloud.alloydbconnector.lazy import LazyRefreshCache
+import google.cloud.alloydbconnector.pg8000 as pg8000
+from google.cloud.alloydbconnector.types import CacheTypes
+from google.cloud.alloydbconnector.utils import generate_keys
+from google.cloud.alloydbconnector.utils import strip_http_prefix
 
 if TYPE_CHECKING:
     import ssl

google/cloud/alloydb/connector/connector.py renamed to google/cloud/alloydbconnector/connector.py

@@ -22,16 +22,16 @@
 import re
 from typing import TYPE_CHECKING
 
-from google.cloud.alloydb.connector.connection_info import ConnectionInfo
-from google.cloud.alloydb.connector.exceptions import RefreshError
-from google.cloud.alloydb.connector.rate_limiter import AsyncRateLimiter
-from google.cloud.alloydb.connector.refresh_utils import _is_valid
-from google.cloud.alloydb.connector.refresh_utils import _seconds_until_refresh
+from google.cloud.alloydbconnector.connection_info import ConnectionInfo
+from google.cloud.alloydbconnector.exceptions import RefreshError
+from google.cloud.alloydbconnector.rate_limiter import AsyncRateLimiter
+from google.cloud.alloydbconnector.refresh_utils import _is_valid
+from google.cloud.alloydbconnector.refresh_utils import _seconds_until_refresh
 
 if TYPE_CHECKING:
     from cryptography.hazmat.primitives.asymmetric import rsa
 
-    from google.cloud.alloydb.connector.client import AlloyDBClient
+    from google.cloud.alloydbconnector.client import AlloyDBClient
 
 logger = logging.getLogger(name=__name__)
 

google/cloud/alloydb/connector/enums.py renamed to google/cloud/alloydbconnector/enums.py

@@ -19,10 +19,10 @@
 import logging
 from typing import Optional
 
-from google.cloud.alloydb.connector.client import AlloyDBClient
-from google.cloud.alloydb.connector.connection_info import ConnectionInfo
-from google.cloud.alloydb.connector.instance import _parse_instance_uri
-from google.cloud.alloydb.connector.refresh_utils import _refresh_buffer
+from google.cloud.alloydbconnector.client import AlloyDBClient
+from google.cloud.alloydbconnector.connection_info import ConnectionInfo
+from google.cloud.alloydbconnector.instance import _parse_instance_uri
+from google.cloud.alloydbconnector.refresh_utils import _refresh_buffer
 
 logger = logging.getLogger(name=__name__)
 

google/cloud/alloydb/connector/exceptions.py renamed to google/cloud/alloydbconnector/exceptions.py

@@ -20,7 +20,7 @@
 
 from cryptography.hazmat.primitives import serialization
 
-from google.cloud.alloydb.connector.connection_info import ConnectionInfo
+from google.cloud.alloydbconnector.connection_info import ConnectionInfo
 
 
 class StaticConnectionInfoCache:

google/cloud/alloydb/connector/instance.py renamed to google/cloud/alloydbconnector/instance.py

@@ -14,9 +14,9 @@
 
 import typing
 
-from google.cloud.alloydb.connector.instance import RefreshAheadCache
-from google.cloud.alloydb.connector.lazy import LazyRefreshCache
-from google.cloud.alloydb.connector.static import StaticConnectionInfoCache
+from google.cloud.alloydbconnector.instance import RefreshAheadCache
+from google.cloud.alloydbconnector.lazy import LazyRefreshCache
+from google.cloud.alloydbconnector.static import StaticConnectionInfoCache
 
 CacheTypes = typing.Union[
     RefreshAheadCache, LazyRefreshCache, StaticConnectionInfoCache

google/cloud/alloydb/connector/lazy.py renamed to google/cloud/alloydbconnector/lazy.py

@@ -137,7 +137,7 @@ def default(session, path):
     session.run(
         "coverage",
         "run",
-        "--include=*/google/cloud/alloydb/connector/*.py",
+        "--include=*/google/cloud/alloydbconnector/*.py",
         "-m",
         "pytest",
         "-v",

google/cloud/alloydb/connector/pg8000.py renamed to google/cloud/alloydbconnector/pg8000.py

@@ -63,10 +63,10 @@ pg8000 = ["pg8000>=1.31.1"]
 asyncpg = ["asyncpg>=0.30.0"]
 
 [tool.setuptools.dynamic]
-version = { attr = "google.cloud.alloydb.connector.version.__version__" }
+version = { attr = "google.cloud.alloydbconnector.version.__version__" }
 
 [tool.setuptools.package-data]
-"google.cloud.alloydb.connector" = ["py.typed"]
+"google.cloud.alloydbconnector" = ["py.typed"]
 
 [tool.setuptools.packages.find]
 # Only include packages under the 'google' namespace. Do not include tests,

google/cloud/alloydb/connector/py.typed renamed to google/cloud/alloydbconnector/py.typed

@@ -0,0 +1,28 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import google.cloud.alloydb.connector as conn_old
+import google.cloud.alloydbconnector as conn_new
+
+
+def test_alloydbconnector_package() -> None:
+    """
+    Test imported objects are same in google.cloud.alloydb.connector and
+    google.cloud.alloydbconnector packages.
+    """
+    assert conn_old.AsyncConnector == conn_new.AsyncConnector
+    assert conn_old.Connector == conn_new.Connector
+    assert conn_old.IPTypes == conn_new.IPTypes
+    assert conn_old.RefreshStrategy == conn_new.RefreshStrategy
+    assert conn_old.__version__ == conn_new.__version__

google/cloud/alloydb/connector/rate_limiter.py renamed to google/cloud/alloydbconnector/rate_limiter.py

@@ -19,7 +19,7 @@
 import sqlalchemy
 import sqlalchemy.ext.asyncio
 
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 
 async def create_sqlalchemy_engine(

google/cloud/alloydb/connector/refresh_utils.py renamed to google/cloud/alloydbconnector/refresh_utils.py

@@ -19,7 +19,7 @@
 import sqlalchemy
 import sqlalchemy.ext.asyncio
 
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 
 async def create_sqlalchemy_engine(

google/cloud/alloydb/connector/static.py renamed to google/cloud/alloydbconnector/static.py

@@ -18,7 +18,7 @@
 import sqlalchemy
 import sqlalchemy.ext.asyncio
 
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 
 async def create_sqlalchemy_engine(

google/cloud/alloydb/connector/types.py renamed to google/cloud/alloydbconnector/types.py

@@ -19,7 +19,7 @@
 import sqlalchemy
 import sqlalchemy.ext.asyncio
 
-from google.cloud.alloydb.connector import AsyncConnector
+from google.cloud.alloydbconnector import AsyncConnector
 
 
 async def create_sqlalchemy_engine(

google/cloud/alloydb/connector/utils.py renamed to google/cloud/alloydbconnector/utils.py

@@ -18,7 +18,7 @@
 # [START alloydb_sqlalchemy_connect_connector]
 import sqlalchemy
 
-from google.cloud.alloydb.connector import Connector
+from google.cloud.alloydbconnector import Connector
 
 
 def create_sqlalchemy_engine(

google/cloud/alloydb/connector/version.py renamed to google/cloud/alloydbconnector/version.py

@@ -18,7 +18,7 @@
 # [START alloydb_sqlalchemy_connect_connector_iam_authn]
 import sqlalchemy
 
-from google.cloud.alloydb.connector import Connector
+from google.cloud.alloydbconnector import Connector
 
 
 def create_sqlalchemy_engine(

noxfile.py

@@ -17,7 +17,7 @@
 
 import sqlalchemy
 
-from google.cloud.alloydb.connector import Connector
+from google.cloud.alloydbconnector import Connector
 
 
 def create_sqlalchemy_engine(