fix(ci): bump version to 0.58.2, fix ruff format and ty type suppression

- Bump version 0.58.1 → 0.58.2 (patch; src/ modified on this branch)
- Collapse multiline raise in _validation.py to satisfy ruff-format
- Add ty: ignore[invalid-argument-type] suppression on intentional
  non-string test inputs in test_validation.py
- Add resource name validation section and @Level shorthand docs to
  destination user-guide.md

Author: tiagoek

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sap-cloud-sdk"
-version = "0.58.1"
+version = "0.58.2"
 description = "SAP Cloud SDK for Python"
 readme = "README.md"
 license = "Apache-2.0"

src/sap_cloud_sdk/destination/user-guide.md

@@ -162,6 +162,11 @@ client.patch_destination_labels(
   - SUBACCOUNT: Subscriber subaccount scope
   - INSTANCE: Subscriber service instance scope
 
+  **Shorthand syntax:** `get_destination` accepts the `ConsumptionLevel` value as an `@`-suffix
+  directly in the name string for backward compatibility
+  (`"my-dest@provider_subaccount"` is equivalent to passing `level=ConsumptionLevel.PROVIDER_SUBACCOUNT`).
+  The `level=` parameter form is the canonical and more explicit usage.
+
 - AccessStrategy (applies to subaccount reads):
   - SUBSCRIBER_ONLY: Only subscriber (tenant required)
   - PROVIDER_ONLY: Only provider (no tenant)
@@ -925,6 +930,48 @@ Entries with a `"tenant"` field are treated as subscriber-specific. Entries with
 - `HttpError`: HTTP-related or local store read/write errors with `status_code` and `response_text` when applicable
 - `DestinationCertificateError`: raised when a client certificate cannot be loaded or wired into the HTTP session (unsupported format, wrong/missing KeyStorePassword, malformed content, cert/key mismatch)
 
+## Resource Name Validation
+
+All public methods that accept a resource `name` parameter validate it against the following grammar before any OAuth token is fetched or HTTP request is sent:
+
+```
+[A-Za-z0-9][A-Za-z0-9._\-]{0,199}
+```
+
+- The first character must be alphanumeric (prevents `.` / `..` path segments).
+- The remaining characters may be letters, digits, dot (`.`), underscore (`_`), or hyphen (`-`).
+- Maximum length: 200 characters.
+
+A `ValueError` is raised immediately for names that do not match — no network call is made:
+
+```python
+# Valid names — all accepted
+client.get_destination("my-destination")
+client.get_destination("MyDest.v2")
+client.get_destination("AuditLogV3_Destination")
+
+# Invalid names — ValueError raised before any HTTP call
+client.get_destination("../etc/passwd")   # path traversal
+client.get_destination("a/b")             # path separator
+client.get_destination("a%2Fb")           # encoded separator
+client.get_destination("a?query=1")       # query delimiter
+client.get_destination("")                # empty
+```
+
+### `get_destination` — ConsumptionLevel shorthand
+
+`get_destination` additionally accepts a `@ConsumptionLevel` suffix embedded in the name for backward compatibility:
+
+```python
+# Shorthand — still works, produces identical URL
+client.get_destination("my-dest@provider_subaccount")
+
+# Canonical form — explicit and preferred
+client.get_destination("my-dest", level=ConsumptionLevel.PROVIDER_SUBACCOUNT)
+```
+
+The SDK splits on `@`, validates the base name, and resolves the level automatically. If both the suffix and the `level=` parameter are provided with conflicting values, a `ValueError` is raised.
+
 ## Configuration
 
 ### Service Binding

src/sap_cloud_sdk/destination/utils/_validation.py

@@ -50,9 +50,7 @@ def validate_resource_name(name: str) -> str:
         ValueError: If *name* does not match the allowlist grammar.
     """
     if not isinstance(name, str) or not _RESOURCE_NAME_RE.fullmatch(name):
-        raise ValueError(
-            f"Invalid resource name {name!r}: must match {_NAME_PATTERN}"
-        )
+        raise ValueError(f"Invalid resource name {name!r}: must match {_NAME_PATTERN}")
     return name
 
 

tests/destination/unit/test_validation.py

@@ -63,11 +63,11 @@ def test_rejects_invalid_names(self, name: str):
 
     def test_rejects_non_string_input(self):
         with pytest.raises(ValueError):
-            validate_resource_name(None)  # type: ignore[arg-type]
+            validate_resource_name(None)  # type: ignore[arg-type]  # ty: ignore[invalid-argument-type]
 
     def test_rejects_integer_input(self):
         with pytest.raises(ValueError):
-            validate_resource_name(42)  # type: ignore[arg-type]
+            validate_resource_name(42)  # type: ignore[arg-type]  # ty: ignore[invalid-argument-type]
 
     def test_error_message_includes_name(self):
         with pytest.raises(ValueError, match="Invalid resource name"):