chore: generate CloudPDF Python SDK 3.0.0a7

.fern/metadata.json

@@ -7,9 +7,9 @@
     "client_class_name": "CloudPDFClient",
     "environment_class_name": "CloudPDFEnvironment"
   },
-  "originGitCommit": "32635f40577b214f6a6b3189a2271425c3a574fd",
+  "originGitCommit": "1345fb7a45ee660a352774d29decce25cb54b8ea",
   "originGitCommitIsDirty": false,
   "invokedBy": "ci",
-  "requestedVersion": "3.0.0a6",
+  "requestedVersion": "3.0.0a7",
   "ciProvider": "github"
 }

cloudpdf-generation.json

@@ -1,12 +1,12 @@
 {
   "language": "python",
-  "canonicalVersion": "3.0.0-next.6",
-  "sdkVersion": "3.0.0a6",
+  "canonicalVersion": "3.0.0-next.7",
+  "sdkVersion": "3.0.0a7",
   "source": {
     "repository": "embedpdf/embed-pdf-viewer",
     "openapi": "cloudpdf/contract/openapi.json",
-    "openapiSha256": "b3e236a932673e27e05825352e1bc3675369d7505040bf7d7760e542aae8d38d",
-    "gitCommit": "32635f40577b214f6a6b3189a2271425c3a574fd",
+    "openapiSha256": "f6fc610bfd193f278a7e8ec063d9e96b8fef86bdec7ade5e7bc4b19879673147",
+    "gitCommit": "1345fb7a45ee660a352774d29decce25cb54b8ea",
     "gitCommitIsDirty": false
   },
   "fern": {

pyproject.toml

@@ -4,7 +4,7 @@ dynamic = ["version"]
 
 [tool.poetry]
 name = "cloudpdf"
-version = "3.0.0a6"
+version = "3.0.0a7"
 description = "The official Python SDK for the CloudPDF API."
 readme = "README.md"
 authors = ["CloudPDF <hello@cloudpdf.com>"]

reference.md

@@ -2051,15 +2051,15 @@ client.documents.import_from(
 <dl>
 <dd>
 
-**source:** `DocumentsImportFromRequestSource` 
+**source:** `DocumentsImportFromRequestSource` — Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
 
 </dd>
 </dl>
 
 <dl>
 <dd>
 
-**expected:** `typing.Optional[DocumentsImportFromRequestExpected]` 
+**expected:** `typing.Optional[DocumentsImportFromRequestExpected]` — Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
 
 </dd>
 </dl>
@@ -2075,15 +2075,15 @@ client.documents.import_from(
 <dl>
 <dd>
 
-**idempotency_key:** `typing.Optional[str]` 
+**idempotency_key:** `typing.Optional[str]` — Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
 
 </dd>
 </dl>
 
 <dl>
 <dd>
 
-**dedup_mode:** `typing.Optional[DocumentsImportFromRequestDedupMode]` 
+**dedup_mode:** `typing.Optional[DocumentsImportFromRequestDedupMode]` — always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
 </dd>
 </dl>
@@ -2099,7 +2099,7 @@ client.documents.import_from(
 <dl>
 <dd>
 
-**mode:** `typing.Optional[DocumentsImportFromRequestMode]` 
+**mode:** `typing.Optional[DocumentsImportFromRequestMode]` — sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
 
 </dd>
 </dl>
@@ -2199,7 +2199,7 @@ client.documents.init(
 <dl>
 <dd>
 
-**dedup_mode:** `typing.Optional[DocumentsInitRequestDedupMode]` 
+**dedup_mode:** `typing.Optional[DocumentsInitRequestDedupMode]` — always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
 </dd>
 </dl>

src/cloudpdf/core/client_wrapper.py

@@ -33,12 +33,12 @@ def get_headers(self) -> typing.Dict[str, str]:
         import platform
 
         headers: typing.Dict[str, str] = {
-            "User-Agent": "cloudpdf/3.0.0a6",
+            "User-Agent": "cloudpdf/3.0.0a7",
             "X-Fern-Language": "Python",
             "X-Fern-Runtime": f"python/{platform.python_version()}",
             "X-Fern-Platform": f"{platform.system().lower()}/{platform.release()}",
             "X-Fern-SDK-Name": "cloudpdf",
-            "X-Fern-SDK-Version": "3.0.0a6",
+            "X-Fern-SDK-Version": "3.0.0a7",
             **(self.get_custom_headers() or {}),
         }
         token = self._get_token()

src/cloudpdf/documents/client.py

@@ -314,18 +314,23 @@ def import_from(
         tenant_id : str
 
         source : DocumentsImportFromRequestSource
+            Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
 
         expected : typing.Optional[DocumentsImportFromRequestExpected]
+            Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
 
         metadata : typing.Optional[typing.Dict[str, typing.Any]]
 
         idempotency_key : typing.Optional[str]
+            Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
 
         dedup_mode : typing.Optional[DocumentsImportFromRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 
         mode : typing.Optional[DocumentsImportFromRequestMode]
+            sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -392,6 +397,7 @@ def init(
         idempotency_key : typing.Optional[str]
 
         dedup_mode : typing.Optional[DocumentsInitRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 
@@ -784,18 +790,23 @@ async def import_from(
         tenant_id : str
 
         source : DocumentsImportFromRequestSource
+            Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
 
         expected : typing.Optional[DocumentsImportFromRequestExpected]
+            Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
 
         metadata : typing.Optional[typing.Dict[str, typing.Any]]
 
         idempotency_key : typing.Optional[str]
+            Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
 
         dedup_mode : typing.Optional[DocumentsImportFromRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 
         mode : typing.Optional[DocumentsImportFromRequestMode]
+            sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -870,6 +881,7 @@ async def init(
         idempotency_key : typing.Optional[str]
 
         dedup_mode : typing.Optional[DocumentsInitRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 

src/cloudpdf/documents/raw_client.py

@@ -531,18 +531,23 @@ def import_from(
         tenant_id : str
 
         source : DocumentsImportFromRequestSource
+            Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
 
         expected : typing.Optional[DocumentsImportFromRequestExpected]
+            Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
 
         metadata : typing.Optional[typing.Dict[str, typing.Any]]
 
         idempotency_key : typing.Optional[str]
+            Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
 
         dedup_mode : typing.Optional[DocumentsImportFromRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 
         mode : typing.Optional[DocumentsImportFromRequestMode]
+            sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -654,6 +659,7 @@ def init(
         idempotency_key : typing.Optional[str]
 
         dedup_mode : typing.Optional[DocumentsInitRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 
@@ -1213,18 +1219,23 @@ async def import_from(
         tenant_id : str
 
         source : DocumentsImportFromRequestSource
+            Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
 
         expected : typing.Optional[DocumentsImportFromRequestExpected]
+            Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
 
         metadata : typing.Optional[typing.Dict[str, typing.Any]]
 
         idempotency_key : typing.Optional[str]
+            Retrying with the same key resumes the same document rather than importing a second copy — including after a 502.
 
         dedup_mode : typing.Optional[DocumentsImportFromRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 
         mode : typing.Optional[DocumentsImportFromRequestMode]
+            sync (default) holds the response open for the whole transfer. async answers 202 with the document pending and transfers in the background; it requires a connection source, and filesystem connections additionally require expected.sha256.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -1336,6 +1347,7 @@ async def init(
         idempotency_key : typing.Optional[str]
 
         dedup_mode : typing.Optional[DocumentsInitRequestDedupMode]
+            always-create (default) creates a new document every time. reuse-existing returns a document that already holds the same content instead of storing it twice.
 
         doc_id : typing.Optional[str]
 

src/cloudpdf/documents/types/documents_import_from_request_expected.py

@@ -9,10 +9,25 @@
 
 
 class DocumentsImportFromRequestExpected(UniversalBaseModel):
+    """
+    Integrity pins, enforced when present. When absent, the server-observed values become authoritative.
+    """
+
     size_bytes: typing_extensions.Annotated[
-        typing.Optional[int], FieldMetadata(alias="sizeBytes"), pydantic.Field(alias="sizeBytes")
+        typing.Optional[int],
+        FieldMetadata(alias="sizeBytes"),
+        pydantic.Field(
+            alias="sizeBytes", description="Checked against the source's declared Content-Length before the transfer."
+        ),
     ] = None
-    sha256: typing.Optional[str] = None
+    """
+    Checked against the source's declared Content-Length before the transfer.
+    """
+
+    sha256: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Checked against the server-observed digest after the transfer. Required when dedupMode is reuse-existing.
+    """
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2

src/cloudpdf/documents/types/documents_import_from_request_source.py

@@ -11,6 +11,10 @@
 
 
 class DocumentsImportFromRequestSource_Url(UniversalBaseModel):
+    """
+    Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
+    """
+
     kind: typing.Literal["url"] = "url"
     url: str
 
@@ -25,6 +29,10 @@ class Config:
 
 
 class DocumentsImportFromRequestSource_Connection(UniversalBaseModel):
+    """
+    Where CloudPDF pulls the bytes from. The two shapes differ in WHO supplies the authority to read, not in which storage vendor holds the file.
+    """
+
     kind: typing.Literal["connection"] = "connection"
     connection_id: typing_extensions.Annotated[
         str, FieldMetadata(alias="connectionId"), pydantic.Field(alias="connectionId")

src/cloudpdf/documents/types/documents_import_from_request_source_connection.py

@@ -9,11 +9,28 @@
 
 
 class DocumentsImportFromRequestSourceConnection(UniversalBaseModel):
+    """
+    The operator pre-registered the authority: the request names a connection and a key inside it. Which provider backs the connection (S3, GCS, Azure Blob, filesystem, ...) is deployment configuration, never wire surface.
+    """
+
     connection_id: typing_extensions.Annotated[
-        str, FieldMetadata(alias="connectionId"), pydantic.Field(alias="connectionId")
+        str,
+        FieldMetadata(alias="connectionId"),
+        pydantic.Field(alias="connectionId", description="The operator-registered storage connection to read from."),
     ]
-    key: str
-    revision: typing.Optional[str] = None
+    """
+    The operator-registered storage connection to read from.
+    """
+
+    key: str = pydantic.Field()
+    """
+    The object key to read, inside the connection's configured scope. At most 1024 UTF-8 bytes.
+    """
+
+    revision: typing.Optional[str] = pydantic.Field(default=None)
+    """
+    Pins a specific version of the object. Provider-interpreted (S3 VersionId, GCS generation, Azure version id); providers without versioning reject it.
+    """
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2

src/cloudpdf/documents/types/documents_import_from_request_source_url.py

@@ -7,7 +7,14 @@
 
 
 class DocumentsImportFromRequestSourceUrl(UniversalBaseModel):
-    url: str
+    """
+    The caller supplies the authority: a presigned S3/GCS/Azure/R2/MinIO GET, or any HTTPS endpoint the deployment import policy allows. The URL is a capability — treat it as a secret. CloudPDF never echoes its query string back in errors, logs, or stored failure reasons.
+    """
+
+    url: str = pydantic.Field()
+    """
+    The URL to fetch. Must be allowed by the deployment import policy (scheme, network range, size) and must declare a length.
+    """
 
     if IS_PYDANTIC_V2:
         model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2