Metadata-Version: 2.4
Name: connparse
Version: 0.5.0
Summary: Parse database connection strings, DSNs, URLs, file paths, and cloud storage URIs.
Project-URL: Homepage, https://github.com/clidey/connparse#readme
Project-URL: Repository, https://github.com/clidey/connparse
Project-URL: Source, https://github.com/clidey/connparse
Project-URL: Issues, https://github.com/clidey/connparse/issues
Project-URL: Documentation, https://github.com/clidey/connparse/tree/main/packages/python#readme
Author: Clidey
License: Apache-2.0
Keywords: adls,athena,aurora,aws-s3,azure-blob,azure-cosmosdb,azure-data-lake,azure-files,bigquery,business-central,cassandra,clickhouse,cloud-storage,cockroachdb,connection-string,connection-strings,connection-uri,connection-url,connparse,cratedb,credentials,data-source,database,database-uri,database-url,databricks,datasource,documentdb,doris,dragonfly,dsn,dsn-parser,duckdb,dynamodb,elasticache,elasticsearch,ferretdb,file-path,gcs,google-cloud-storage,jdbc,mariadb,materialize,memcached,mongodb,mssql,mysql,neo4j,neptune,object-storage,oceanbase,opensearch,oracle,parser,postgres,postgresql,questdb,redaction,redis,redshift,risingwave,s3,saphana,singlestore,snowflake,spanner,sqlite,sqlserver,starrocks,tallyprime,tidb,trino,uri,valkey,yugabytedb
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# connparse

Connparse parses database connection strings, DSNs, URLs, file paths, and cloud
storage URIs into one predictable Python dict.

Connparse is useful when your app accepts connection strings from different
systems and you want to pull out the host, port, database, bucket, path,
credentials, query options, and a safe redacted string.

Supported sources include PostgreSQL, MySQL, MariaDB, SQLite, DuckDB,
ClickHouse, Redis, Memcached, Elasticsearch, MongoDB, CockroachDB, QuestDB,
YugabyteDB, TiDB, Valkey, Dragonfly, OpenSearch, FerretDB, ElastiCache,
DocumentDB, SQL Server, Oracle, Snowflake, Cassandra, BigQuery, Redshift,
Aurora, Neo4j, Trino, Databricks, DynamoDB, StarRocks, SAP HANA, Athena,
Spanner, Google Cloud Storage, Azure Blob, Azure Data Lake Storage, Azure Files,
Azure Cosmos DB, Business Central, TallyPrime, Amazon S3, and local file paths.

## Install

```bash
pip install connparse
```

## Basic Usage

```py
from connparse import parse

result = parse("postgres://user:pass@localhost:5432/app?sslmode=require")

if not result["ok"]:
    print(result["errors"])
else:
    print(result["value"])
```

Result:

```json
{
  "scheme": "postgres",
  "type": "database",
  "authority": {
    "host": "localhost",
    "port": 5432
  },
  "resource": {
    "type": "database",
    "name": "app"
  },
  "path": "",
  "query": {
    "sslmode": "require"
  },
  "fragment": null,
  "credentials": {
    "username": "user",
    "password": "pass"
  },
  "options": {},
  "raw": "postgres://user:pass@localhost:5432/app?sslmode=require",
  "safe": "postgres://user:***@localhost:5432/app?sslmode=require"
}
```

## Recommended Usage

Use `parse()` for form handling, validation, and showing parsed connection
details to users.

```py
result = parse(input)

if result["ok"]:
    address = result["value"]
    save_connection(
        host=address["authority"].get("host"),
        port=address["authority"].get("port"),
        database=address["resource"]["name"],
        safe_label=address["safe"],
    )
```

Use `safe` for logs and UI labels. Do not log `raw` or `credentials` unless the
user explicitly asks to reveal secrets.

```py
logger.info("connection=%s", result["value"]["safe"])
```

Use `parse_normalize()` when you need a stable identity for dedupe, cache keys,
or config comparison.

```py
from connparse import parse_normalize

parse_normalize("postgresql://LOCALHOST:5432/app?sslmode=require")["value"]["canonical"]
# "postgres://localhost/app?sslmode=require"
```

Use `provider` when the string does not clearly identify the source type.

```py
parse("host=db.example.com port=5432 dbname=app user=alice", {
    "provider": "postgres",
})

parse("https://clickhouse.example.com:8443/default", {
    "provider": "clickhouse",
})
```

Use `strict` when you want unknown query parameters to fail validation.

```py
parse("postgres://localhost/app?unexpected=1", {"strict": True})
```

## Examples

| Source | Input | Parsed result |
| --- | --- | --- |
| PostgreSQL | `postgres://user:pass@localhost:5432/app?sslmode=require` | `authority.host = "localhost"`, `authority.port = 5432`, `resource.name = "app"`, `query.sslmode = "require"` |
| MySQL | `mysql://root:secret@127.0.0.1/shop?charset=utf8mb4` | `authority.host = "127.0.0.1"`, `authority.port = 3306`, `resource.name = "shop"`, `query.charset = "utf8mb4"` |
| MariaDB | `mariadb://root:secret@mariadb.example.com:3306/app` | `authority.host = "mariadb.example.com"`, `authority.port = 3306`, `resource.name = "app"` |
| SQLite | `sqlite::memory:` | `scheme = "sqlite"`, `resource.name = ":memory:"`, `path = ":memory:"`, `options.memory = true` |
| DuckDB | `duckdb:///tmp/analytics.duckdb?access_mode=read_only` | `scheme = "duckdb"`, `path = "/tmp/analytics.duckdb"`, `query.access_mode = "read_only"` |
| ClickHouse | `jdbc:clickhouse:http://localhost:8123/analytics?ssl=false` | `authority.host = "localhost"`, `authority.port = 8123`, `resource.name = "analytics"`, `options.protocol = "http"` |
| Memcached | `memcached://cache.example.com` | `authority.host = "cache.example.com"`, `authority.port = 11211`, `type = "cache"` |
| Redis | `rediss://:pass@cache.example.com/0` | `authority.host = "cache.example.com"`, `authority.port = 6379`, `resource.name = "0"`, `options.tls = true` |
| Elasticsearch | `elasticsearch+https://elastic:secret@es.example.com:9243/logs?api_key=abc` | `authority.host = "es.example.com"`, `authority.port = 9243`, `resource.name = "logs"`, `credentials.api_key = "abc"` |
| MongoDB | `mongodb+srv://user:pass@cluster.mongodb.net/app?retryWrites=true` | `authority.host = "cluster.mongodb.net"`, `resource.name = "app"`, `query.retryWrites = "true"`, `options.srv = true` |
| CockroachDB | `cockroach://root@servername:26257/mydb?sslmode=disable` | `authority.host = "servername"`, `authority.port = 26257`, `resource.name = "mydb"`, `options.compatible_with = "postgres"` |
| QuestDB | `https::addr=questdb.example.com:9000;username=admin;password=quest;auto_flush_rows=5000;` | `authority.host = "questdb.example.com"`, `authority.port = 9000`, `query.auto_flush_rows = "5000"`, `options.ingestion = true` |
| YugabyteDB | `yugabyte://yugabyte:yugabyte@localhost:5433/yugabyte?loadBalance=any` | `authority.host = "localhost"`, `authority.port = 5433`, `resource.name = "yugabyte"`, `query.loadBalance = "any"` |
| S3 | `s3://my-bucket/path/to/file.csv?versionId=123` | `authority.bucket = "my-bucket"`, `resource.name = "my-bucket"`, `path = "path/to/file.csv"` |
| File | `file:///tmp/data.csv#header` | `scheme = "file"`, `path = "/tmp/data.csv"`, `fragment = "header"` |
