dbx-tools-postgres 0.6.78__tar.gz

dbx_tools_postgres-0.6.78/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.3
+Name: dbx-tools-postgres
+Version: 0.6.78
+Summary: WorkspaceClient-backed Lakebase Postgres resolution, SQLAlchemy engines, advisory locks, and LISTEN/NOTIFY topic bus
+Requires-Dist: asyncpg>=0.30,<1
+Requires-Dist: databricks-sdk>=0.63.0,<1
+Requires-Dist: greenlet>=3.2,<4
+Requires-Dist: dbx-tools-core==0.6.78
+Requires-Dist: psycopg[binary]>=3.2.9,<4
+Requires-Dist: sqlalchemy>=2.0.41,<3
+Requires-Python: >=3.10
+Project-URL: Source, https://github.com/reggie-db/dbx-tools/tree/main/packages/py/postgres
+Description-Content-Type: text/markdown
+
+# `dbx-tools-postgres`
+
+Python Lakebase/Postgres connection setup, advisory locks, and topic fan-out for
+services that already hold a Databricks `WorkspaceClient`. This package is
+currently an unpublished workspace package, and is the Python counterpart to
+`@dbx-tools/postgres` plus `@dbx-tools/appkit`'s address parsing.
+
+Install directly from this monorepo:
+
+```bash
+pip install "dbx-tools-postgres @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/postgres"
+```
+
+Key features:
+
+- accepts the same Postgres URI, Lakebase resource path, hostname, and project-id
+  address shapes as `@dbx-tools/appkit`;
+- resolves missing autoscaling endpoint fields through
+  `WorkspaceClient.api_client`;
+- resolves provisioned Lakebase instance DNS through
+  `WorkspaceClient.database`;
+- injects a fresh database credential on SQLAlchemy's `do_connect` event rather
+  than storing an expiring password in the engine URL, using the SDK's
+  provisioned-instance API or the Autoscaling `/postgres/credentials` endpoint;
+- supports sync psycopg and asyncpg SQLAlchemy engines;
+- derives advisory-lock ids from the same stable structured keys as the Node
+  package and holds one checked-out connection for the full critical section;
+- provides blocking and try-lock context managers for session and transaction
+  locks, with sync and async SQLAlchemy variants;
+- fans messages out to every process on a channel with `PostgresTopicBus`, using
+  the same lifecycle and wire envelope as the Node package.
+
+```python
+from databricks.sdk import WorkspaceClient
+from dbx_tools.postgres import PostgresEngineConfig, create_async_engine
+
+engine = create_async_engine(
+    WorkspaceClient(),
+    PostgresEngineConfig(instance_name="my-lakebase", database="databricks_postgres"),
+    pool_pre_ping=True,
+    pool_recycle=1800,
+)
+```
+
+Pass `credential_provider=` to either engine factory to inject credentials from
+another source while retaining the same connect-time rotation behavior.
+
+```python
+from dbx_tools.postgres import advisory_transaction_lock
+
+with advisory_transaction_lock(engine, ["schema-install", "v2"]) as connection:
+    connection.exec_driver_sql("CREATE TABLE IF NOT EXISTS ...")
+```
+
+## Topic bus
+
+`PostgresTopicBus` is async Postgres topic fan-out built on `LISTEN`/`NOTIFY`. Its
+public lifecycle and wire shape match `@dbx-tools/postgres`'s `PostgresTopicBus`,
+so Node and Python services can share a channel:
+
+- `PostgresTopicBus(engine, options)`;
+- `channelName`;
+- `await start()`;
+- `await broadcast(topic, TopicPublishInput(...))`;
+- `await listen(topic, listener)` returning an async unsubscribe function;
+- `await close()`;
+- envelope fields `id`, `topic`, `type`, `metadata`, `body`, and `publishedAt`.
+
+Channel derivation ports the Node stable-key and FNV rules, so equivalent channel
+parts resolve to the same PostgreSQL identifier in Python and Node.
+
+```python
+from dbx_tools.postgres import PostgresTopicBus, TopicPublishInput
+
+bus = PostgresTopicBus(engine, channel=["billing", "production"])
+
+unsubscribe = await bus.listen("invoice.updated", handle_invoice)
+await bus.broadcast(
+    "invoice.updated",
+    TopicPublishInput(type="invoice.updated", body={"invoice_id": "inv-7"}),
+)
+```
+
+Delivery is live and unstored, like PostgreSQL `LISTEN`/`NOTIFY` itself. Use a
+table or queue when consumers need replay or acknowledgements.
+
+## Databricks notebooks and Spark
+
+Verified end to end against a Lakebase endpoint on serverless notebook compute.
+[`packages/example/notebooks/bus-lakebase.py`](../../example/notebooks/bus-lakebase.py)
+is the runnable version of everything below.
+
+Two things about the Databricks Python runtime change how the bus is called, and
+neither is a limitation of the bus itself:
+
+- **A notebook kernel already runs an event loop**, so `asyncio.run` in a cell
+  raises `RuntimeError: asyncio.run() cannot be called from a running event
+loop`. Drive the coroutine on a short-lived thread with its own loop rather
+  than reaching for `nest_asyncio` — the bus holds a dedicated `LISTEN`
+  connection bound to whichever loop started it, so one loop per bus lifetime is
+  the invariant to preserve.
+- **Install with `%pip install`, not `pip install --target`.** A `--target`
+  install leaves the runtime's preloaded `typing_extensions` ahead of the new
+  one on `sys.path`, and importing `dbx_tools.postgres` then fails with
+  `ImportError: cannot import name 'TypeAliasType'`. `%pip` restarts the Python
+  process, which resolves it.
+
+### Publishing from a Spark UDF
+
+Publishing from executors works. Listening from them does not, and should not be
+attempted: a UDF invocation is short-lived, while `listen` keeps a connection
+open until `close`.
+
+Executors have no Databricks credentials, so they cannot build a
+`WorkspaceClient`. This is where connect-time credential injection pays off — the
+driver mints the Lakebase token once and the UDF closes over it, so the executor
+builds a plain SQLAlchemy engine and installs the token as its provider:
+
+```python
+from sqlalchemy import URL
+from sqlalchemy.ext.asyncio import create_async_engine
+from dbx_tools.postgres import (
+    PostgresTopicBus,
+    TopicPublishInput,
+    install_credential_injection,
+)
+
+# driver: resolve once, capture in the closure
+resolved = resolve_postgres_connection(workspace_client, config)
+token = workspace_client.api_client.do(
+    "POST",
+    "/api/2.0/postgres/credentials",
+    body={"endpoint": resolved.endpoint},
+)["token"]
+
+
+@udf(returnType=StringType())
+def publish(key: str) -> str:
+    async def run() -> str:
+        engine = create_async_engine(
+            URL.create(
+                "postgresql+asyncpg",
+                username=resolved.user,
+                host=resolved.host,
+                port=resolved.port,
+                database=resolved.database,
+                query={"ssl": resolved.ssl_mode},
+            )
+        )
+        install_credential_injection(engine.sync_engine, lambda: token)
+        bus = PostgresTopicBus(engine, channel="app-events")
+        try:
+            message = await bus.broadcast(
+                "row.processed", TopicPublishInput(type="row.processed", body={"key": key})
+            )
+            return message.id
+        finally:
+            await bus.close()
+            await engine.dispose()
+
+    return asyncio.run(run())
+```
+
+Constraints worth knowing before this reaches production:
+
+- A captured token EXPIRES (about an hour). Re-mint per job run; a long-running
+  streaming query needs a provider that refreshes instead of a captured string.
+- Each UDF call opens and closes its own connection, so batch the publish at
+  partition scope (`mapInPandas`, `foreachPartition`) rather than per row.
+- `spark.sparkContext.broadcast` is unavailable on serverless (Spark Connect).
+  A plain closure over driver-side values serializes with the UDF and is enough.
+- Delivery stays live and unstored: if no listener is connected when the UDF
+  publishes, the message is gone. Write to a table when executors produce
+  results a consumer must not miss.

dbx_tools_postgres-0.6.78/README.md

@@ -0,0 +1,174 @@
+# `dbx-tools-postgres`
+
+Python Lakebase/Postgres connection setup, advisory locks, and topic fan-out for
+services that already hold a Databricks `WorkspaceClient`. This package is
+currently an unpublished workspace package, and is the Python counterpart to
+`@dbx-tools/postgres` plus `@dbx-tools/appkit`'s address parsing.
+
+Install directly from this monorepo:
+
+```bash
+pip install "dbx-tools-postgres @ git+https://github.com/reggie-db/dbx-tools.git@main#subdirectory=packages/py/postgres"
+```
+
+Key features:
+
+- accepts the same Postgres URI, Lakebase resource path, hostname, and project-id
+  address shapes as `@dbx-tools/appkit`;
+- resolves missing autoscaling endpoint fields through
+  `WorkspaceClient.api_client`;
+- resolves provisioned Lakebase instance DNS through
+  `WorkspaceClient.database`;
+- injects a fresh database credential on SQLAlchemy's `do_connect` event rather
+  than storing an expiring password in the engine URL, using the SDK's
+  provisioned-instance API or the Autoscaling `/postgres/credentials` endpoint;
+- supports sync psycopg and asyncpg SQLAlchemy engines;
+- derives advisory-lock ids from the same stable structured keys as the Node
+  package and holds one checked-out connection for the full critical section;
+- provides blocking and try-lock context managers for session and transaction
+  locks, with sync and async SQLAlchemy variants;
+- fans messages out to every process on a channel with `PostgresTopicBus`, using
+  the same lifecycle and wire envelope as the Node package.
+
+```python
+from databricks.sdk import WorkspaceClient
+from dbx_tools.postgres import PostgresEngineConfig, create_async_engine
+
+engine = create_async_engine(
+    WorkspaceClient(),
+    PostgresEngineConfig(instance_name="my-lakebase", database="databricks_postgres"),
+    pool_pre_ping=True,
+    pool_recycle=1800,
+)
+```
+
+Pass `credential_provider=` to either engine factory to inject credentials from
+another source while retaining the same connect-time rotation behavior.
+
+```python
+from dbx_tools.postgres import advisory_transaction_lock
+
+with advisory_transaction_lock(engine, ["schema-install", "v2"]) as connection:
+    connection.exec_driver_sql("CREATE TABLE IF NOT EXISTS ...")
+```
+
+## Topic bus
+
+`PostgresTopicBus` is async Postgres topic fan-out built on `LISTEN`/`NOTIFY`. Its
+public lifecycle and wire shape match `@dbx-tools/postgres`'s `PostgresTopicBus`,
+so Node and Python services can share a channel:
+
+- `PostgresTopicBus(engine, options)`;
+- `channelName`;
+- `await start()`;
+- `await broadcast(topic, TopicPublishInput(...))`;
+- `await listen(topic, listener)` returning an async unsubscribe function;
+- `await close()`;
+- envelope fields `id`, `topic`, `type`, `metadata`, `body`, and `publishedAt`.
+
+Channel derivation ports the Node stable-key and FNV rules, so equivalent channel
+parts resolve to the same PostgreSQL identifier in Python and Node.
+
+```python
+from dbx_tools.postgres import PostgresTopicBus, TopicPublishInput
+
+bus = PostgresTopicBus(engine, channel=["billing", "production"])
+
+unsubscribe = await bus.listen("invoice.updated", handle_invoice)
+await bus.broadcast(
+    "invoice.updated",
+    TopicPublishInput(type="invoice.updated", body={"invoice_id": "inv-7"}),
+)
+```
+
+Delivery is live and unstored, like PostgreSQL `LISTEN`/`NOTIFY` itself. Use a
+table or queue when consumers need replay or acknowledgements.
+
+## Databricks notebooks and Spark
+
+Verified end to end against a Lakebase endpoint on serverless notebook compute.
+[`packages/example/notebooks/bus-lakebase.py`](../../example/notebooks/bus-lakebase.py)
+is the runnable version of everything below.
+
+Two things about the Databricks Python runtime change how the bus is called, and
+neither is a limitation of the bus itself:
+
+- **A notebook kernel already runs an event loop**, so `asyncio.run` in a cell
+  raises `RuntimeError: asyncio.run() cannot be called from a running event
+loop`. Drive the coroutine on a short-lived thread with its own loop rather
+  than reaching for `nest_asyncio` — the bus holds a dedicated `LISTEN`
+  connection bound to whichever loop started it, so one loop per bus lifetime is
+  the invariant to preserve.
+- **Install with `%pip install`, not `pip install --target`.** A `--target`
+  install leaves the runtime's preloaded `typing_extensions` ahead of the new
+  one on `sys.path`, and importing `dbx_tools.postgres` then fails with
+  `ImportError: cannot import name 'TypeAliasType'`. `%pip` restarts the Python
+  process, which resolves it.
+
+### Publishing from a Spark UDF
+
+Publishing from executors works. Listening from them does not, and should not be
+attempted: a UDF invocation is short-lived, while `listen` keeps a connection
+open until `close`.
+
+Executors have no Databricks credentials, so they cannot build a
+`WorkspaceClient`. This is where connect-time credential injection pays off — the
+driver mints the Lakebase token once and the UDF closes over it, so the executor
+builds a plain SQLAlchemy engine and installs the token as its provider:
+
+```python
+from sqlalchemy import URL
+from sqlalchemy.ext.asyncio import create_async_engine
+from dbx_tools.postgres import (
+    PostgresTopicBus,
+    TopicPublishInput,
+    install_credential_injection,
+)
+
+# driver: resolve once, capture in the closure
+resolved = resolve_postgres_connection(workspace_client, config)
+token = workspace_client.api_client.do(
+    "POST",
+    "/api/2.0/postgres/credentials",
+    body={"endpoint": resolved.endpoint},
+)["token"]
+
+
+@udf(returnType=StringType())
+def publish(key: str) -> str:
+    async def run() -> str:
+        engine = create_async_engine(
+            URL.create(
+                "postgresql+asyncpg",
+                username=resolved.user,
+                host=resolved.host,
+                port=resolved.port,
+                database=resolved.database,
+                query={"ssl": resolved.ssl_mode},
+            )
+        )
+        install_credential_injection(engine.sync_engine, lambda: token)
+        bus = PostgresTopicBus(engine, channel="app-events")
+        try:
+            message = await bus.broadcast(
+                "row.processed", TopicPublishInput(type="row.processed", body={"key": key})
+            )
+            return message.id
+        finally:
+            await bus.close()
+            await engine.dispose()
+
+    return asyncio.run(run())
+```
+
+Constraints worth knowing before this reaches production:
+
+- A captured token EXPIRES (about an hour). Re-mint per job run; a long-running
+  streaming query needs a provider that refreshes instead of a captured string.
+- Each UDF call opens and closes its own connection, so batch the publish at
+  partition scope (`mapInPandas`, `foreachPartition`) rather than per row.
+- `spark.sparkContext.broadcast` is unavailable on serverless (Spark Connect).
+  A plain closure over driver-side values serializes with the UDF and is enough.
+- Delivery stays live and unstored: if no listener is connected when the UDF
+  publishes, the message is gone. Write to a table when executors produce
+  results a consumer must not miss.

dbx_tools_postgres-0.6.78/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "dbx-tools-postgres"
+version = "0.6.78"
+description = "WorkspaceClient-backed Lakebase Postgres resolution, SQLAlchemy engines, advisory locks, and LISTEN/NOTIFY topic bus"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "asyncpg>=0.30,<1",
+    "databricks-sdk>=0.63.0,<1",
+    "greenlet>=3.2,<4",
+    "dbx-tools-core==0.6.78",
+    "psycopg[binary]>=3.2.9,<4",
+    "sqlalchemy>=2.0.41,<3",
+]
+
+[project.urls]
+Source = "https://github.com/reggie-db/dbx-tools/tree/main/packages/py/postgres"
+
+[build-system]
+requires = ["uv_build>=0.11.28,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dbx_tools.postgres"
+module-root = "src"
+namespace = true

dbx_tools_postgres-0.6.78/pyproject.toml.orig

@@ -0,0 +1,28 @@
+# ~~ Generated by projen. To modify, edit .projenrc.js and run "bunx projen".
+
+[project]
+name = "dbx-tools-postgres"
+version = "0.6.78"
+description = "WorkspaceClient-backed Lakebase Postgres resolution, SQLAlchemy engines, advisory locks, and LISTEN/NOTIFY topic bus"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "asyncpg>=0.30,<1",
+  "databricks-sdk>=0.63.0,<1",
+  "greenlet>=3.2,<4",
+  "dbx-tools-core==0.6.78",
+  "psycopg[binary]>=3.2.9,<4",
+  "sqlalchemy>=2.0.41,<3"
+]
+
+  [project.urls]
+  Source = "https://github.com/reggie-db/dbx-tools/tree/main/packages/py/postgres"
+
+[build-system]
+requires = [ "uv_build>=0.11.28,<0.12.0" ]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "dbx_tools.postgres"
+module-root = "src"
+namespace = true

dbx_tools_postgres-0.6.78/src/dbx_tools/postgres/__init__.py

@@ -0,0 +1,109 @@
+from .address import (
+    SSL_MODES,
+    LakebaseConnectionInputs,
+    ParsedAddress,
+    SslMode,
+    parse_address,
+    parse_resource_path,
+    parseAddress,
+    parseResourcePath,
+)
+from .advisory_lock import (
+    ExplicitAdvisoryLockId,
+    acquire_advisory_lock,
+    acquire_advisory_lock_async,
+    advisory_lock,
+    advisory_lock_async,
+    advisory_lock_id,
+    advisory_transaction_lock,
+    advisory_transaction_lock_async,
+    explicit_advisory_lock_id,
+    release_advisory_lock,
+    release_advisory_lock_async,
+    try_advisory_lock,
+    try_advisory_lock_async,
+    try_advisory_transaction_lock,
+    try_advisory_transaction_lock_async,
+)
+from .engine import (
+    CredentialProvider,
+    PostgresEngineConfig,
+    ResolvedPostgresConnection,
+    WorkspaceClientLike,
+    autoscaling_credential_provider,
+    autoscalingCredentialProvider,
+    create_async_engine,
+    create_engine,
+    createAsyncEngine,
+    createEngine,
+    install_credential_injection,
+    installCredentialInjection,
+    resolve_postgres_connection,
+    resolvePostgresConnection,
+    workspace_credential_provider,
+    workspaceCredentialProvider,
+)
+from .topic_bus import (
+    PostgresTopicBus,
+    PostgresTopicBusOptions,
+    SerializableValue,
+    TopicListener,
+    TopicMessage,
+    TopicMetadata,
+    TopicMetadataProvider,
+    TopicPublishInput,
+    channel_name,
+    channelName,
+)
+
+__all__ = [
+    "SSL_MODES",
+    "CredentialProvider",
+    "ExplicitAdvisoryLockId",
+    "LakebaseConnectionInputs",
+    "ParsedAddress",
+    "PostgresEngineConfig",
+    "PostgresTopicBus",
+    "PostgresTopicBusOptions",
+    "ResolvedPostgresConnection",
+    "SerializableValue",
+    "SslMode",
+    "TopicListener",
+    "TopicMessage",
+    "TopicMetadata",
+    "TopicMetadataProvider",
+    "TopicPublishInput",
+    "WorkspaceClientLike",
+    "acquire_advisory_lock",
+    "acquire_advisory_lock_async",
+    "advisory_lock",
+    "advisory_lock_async",
+    "advisory_lock_id",
+    "advisory_transaction_lock",
+    "advisory_transaction_lock_async",
+    "autoscalingCredentialProvider",
+    "autoscaling_credential_provider",
+    "channelName",
+    "channel_name",
+    "createAsyncEngine",
+    "createEngine",
+    "create_async_engine",
+    "create_engine",
+    "explicit_advisory_lock_id",
+    "installCredentialInjection",
+    "install_credential_injection",
+    "parseAddress",
+    "parseResourcePath",
+    "parse_address",
+    "parse_resource_path",
+    "release_advisory_lock",
+    "release_advisory_lock_async",
+    "resolvePostgresConnection",
+    "resolve_postgres_connection",
+    "try_advisory_lock",
+    "try_advisory_lock_async",
+    "try_advisory_transaction_lock",
+    "try_advisory_transaction_lock_async",
+    "workspaceCredentialProvider",
+    "workspace_credential_provider",
+]

dbx_tools_postgres-0.6.78/src/dbx_tools/postgres/address.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass
+from typing import Literal
+from urllib.parse import parse_qs, unquote, urlparse
+
+SslMode = Literal["require", "disable", "prefer"]
+SSL_MODES: tuple[SslMode, ...] = ("require", "disable", "prefer")
+
+_URL_SCHEME_RE = re.compile(r"^(postgres|postgresql)://", re.IGNORECASE)
+_PROJECT_ID_RE = re.compile(r"^[a-z][a-z0-9-]{0,61}[a-z0-9]$|^[a-z]$")
+_HOSTNAME_HINT_RE = re.compile(r"^[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)+$", re.IGNORECASE)
+
+
+@dataclass(frozen=True, slots=True)
+class LakebaseConnectionInputs:
+    project: str | None = None
+    branch: str | None = None
+    endpoint: str | None = None
+    database: str | None = None
+    host: str | None = None
+    port: int | None = None
+    ssl_mode: SslMode | None = None
+
+    def as_dict(self) -> dict[str, object]:
+        return {key: value for key, value in asdict(self).items() if value is not None}
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedAddress(LakebaseConnectionInputs):
+    endpoint_id: str | None = None
+    database_resource_id: str | None = None
+    user: str | None = None
+
+
+def parse_address(value: str | None) -> ParsedAddress:
+    if not value or not (address := value.strip()):
+        return ParsedAddress()
+    if _URL_SCHEME_RE.match(address):
+        return _parse_uri(address)
+    if address.startswith("projects/"):
+        return _parse_resource_path_segments(address)
+    if "." in address and _HOSTNAME_HINT_RE.fullmatch(address):
+        return ParsedAddress(host=address)
+    if _PROJECT_ID_RE.fullmatch(address):
+        return ParsedAddress(project=address)
+    return ParsedAddress()
+
+
+def parse_resource_path(value: str | None) -> ParsedAddress:
+    if not value or not (address := value.strip()).startswith("projects/"):
+        return ParsedAddress()
+    return _parse_resource_path_segments(address)
+
+
+def _parse_uri(address: str) -> ParsedAddress:
+    try:
+        parsed = urlparse(address)
+        port = parsed.port
+    except ValueError:
+        return ParsedAddress()
+    if parsed.scheme.lower() not in {"postgres", "postgresql"}:
+        return ParsedAddress()
+    ssl_mode_value = parse_qs(parsed.query).get("sslmode") or parse_qs(parsed.query).get("sslMode")
+    ssl_mode = ssl_mode_value[0].lower() if ssl_mode_value else None
+    return ParsedAddress(
+        host=parsed.hostname or None,
+        port=port,
+        user=unquote(parsed.username) if parsed.username else None,
+        database=unquote(parsed.path.removeprefix("/")) or None,
+        ssl_mode=ssl_mode if ssl_mode in SSL_MODES else None,
+    )
+
+
+def _parse_resource_path_segments(address: str) -> ParsedAddress:
+    parts = address.split("/")
+    if len(parts) < 2 or parts[0] != "projects" or not parts[1]:
+        return ParsedAddress()
+    project = parts[1]
+    if len(parts) == 2:
+        return ParsedAddress(project=project)
+    if len(parts) == 4 and parts[2] == "branches" and parts[3]:
+        return ParsedAddress(project=project, branch=parts[3])
+    if (
+        len(parts) == 6
+        and parts[2] == "branches"
+        and parts[3]
+        and parts[4] == "endpoints"
+        and parts[5]
+    ):
+        return ParsedAddress(
+            project=project,
+            branch=parts[3],
+            endpoint=address,
+            endpoint_id=parts[5],
+        )
+    if (
+        len(parts) == 6
+        and parts[2] == "branches"
+        and parts[3]
+        and parts[4] == "databases"
+        and parts[5]
+    ):
+        return ParsedAddress(
+            project=project,
+            branch=parts[3],
+            database_resource_id=parts[5],
+        )
+    return ParsedAddress()
+
+
+parseAddress = parse_address
+parseResourcePath = parse_resource_path