databricks-sdk 0.19.1__py3-none-any.whl → 0.21.0__py3-none-any.whl

databricks/sdk/service/dashboards.py

@@ -39,6 +39,20 @@ class PublishRequest:
                    warehouse_id=d.get('warehouse_id', None))
 
 
+@dataclass
+class PublishResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the PublishResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> PublishResponse:
+        """Deserializes the PublishResponse from a dictionary."""
+        return cls()
+
+
 class LakeviewAPI:
     """These APIs provide specific management operations for Lakeview dashboards. Generic resource management can
     be done with Workspace API (import, export, get-status, list, delete)."""
@@ -69,6 +83,7 @@ class LakeviewAPI:
         if embed_credentials is not None: body['embed_credentials'] = embed_credentials
         if warehouse_id is not None: body['warehouse_id'] = warehouse_id
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST',
                      f'/api/2.0/lakeview/dashboards/{dashboard_id}/published',
                      body=body,

databricks/sdk/service/files.py

@@ -34,6 +34,20 @@ class AddBlock:
         return cls(data=d.get('data', None), handle=d.get('handle', None))
 
 
+@dataclass
+class AddBlockResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the AddBlockResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> AddBlockResponse:
+        """Deserializes the AddBlockResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class Close:
     handle: int
@@ -51,6 +65,20 @@ class Close:
         return cls(handle=d.get('handle', None))
 
 
+@dataclass
+class CloseResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the CloseResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> CloseResponse:
+        """Deserializes the CloseResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class Create:
     path: str
@@ -72,6 +100,20 @@ class Create:
         return cls(overwrite=d.get('overwrite', None), path=d.get('path', None))
 
 
+@dataclass
+class CreateDirectoryResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the CreateDirectoryResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> CreateDirectoryResponse:
+        """Deserializes the CreateDirectoryResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class CreateResponse:
     handle: Optional[int] = None
@@ -112,6 +154,34 @@ class Delete:
         return cls(path=d.get('path', None), recursive=d.get('recursive', None))
 
 
+@dataclass
+class DeleteDirectoryResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the DeleteDirectoryResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> DeleteDirectoryResponse:
+        """Deserializes the DeleteDirectoryResponse from a dictionary."""
+        return cls()
+
+
+@dataclass
+class DeleteResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the DeleteResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> DeleteResponse:
+        """Deserializes the DeleteResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class DirectoryEntry:
     file_size: Optional[int] = None
@@ -124,7 +194,7 @@ class DirectoryEntry:
     """Last modification time of given file in milliseconds since unix epoch."""
 
     name: Optional[str] = None
-    """The name of the file or directory."""
+    """The name of the file or directory. This is the last component of the path."""
 
     path: Optional[str] = None
     """The absolute path of the file or directory."""
@@ -151,8 +221,31 @@ class DirectoryEntry:
 
 @dataclass
 class DownloadResponse:
+    content_length: Optional[int] = None
+
+    content_type: Optional[str] = None
+
     contents: Optional[BinaryIO] = None
 
+    last_modified: Optional[str] = None
+
+    def as_dict(self) -> dict:
+        """Serializes the DownloadResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        if self.content_length is not None: body['content-length'] = self.content_length
+        if self.content_type is not None: body['content-type'] = self.content_type
+        if self.contents: body['contents'] = self.contents
+        if self.last_modified is not None: body['last-modified'] = self.last_modified
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> DownloadResponse:
+        """Deserializes the DownloadResponse from a dictionary."""
+        return cls(content_length=int(d.get('content-length', None)),
+                   content_type=d.get('content-type', None),
+                   contents=d.get('contents', None),
+                   last_modified=d.get('last-modified', None))
+
 
 @dataclass
 class FileInfo:
@@ -186,6 +279,44 @@ class FileInfo:
                    path=d.get('path', None))
 
 
+@dataclass
+class GetDirectoryMetadataResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the GetDirectoryMetadataResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> GetDirectoryMetadataResponse:
+        """Deserializes the GetDirectoryMetadataResponse from a dictionary."""
+        return cls()
+
+
+@dataclass
+class GetMetadataResponse:
+    content_length: Optional[int] = None
+
+    content_type: Optional[str] = None
+
+    last_modified: Optional[str] = None
+
+    def as_dict(self) -> dict:
+        """Serializes the GetMetadataResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        if self.content_length is not None: body['content-length'] = self.content_length
+        if self.content_type is not None: body['content-type'] = self.content_type
+        if self.last_modified is not None: body['last-modified'] = self.last_modified
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> GetMetadataResponse:
+        """Deserializes the GetMetadataResponse from a dictionary."""
+        return cls(content_length=int(d.get('content-length', None)),
+                   content_type=d.get('content-type', None),
+                   last_modified=d.get('last-modified', None))
+
+
 @dataclass
 class ListDirectoryResponse:
     contents: Optional[List[DirectoryEntry]] = None
@@ -242,6 +373,20 @@ class MkDirs:
         return cls(path=d.get('path', None))
 
 
+@dataclass
+class MkDirsResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the MkDirsResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> MkDirsResponse:
+        """Deserializes the MkDirsResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class Move:
     source_path: str
@@ -263,6 +408,20 @@ class Move:
         return cls(destination_path=d.get('destination_path', None), source_path=d.get('source_path', None))
 
 
+@dataclass
+class MoveResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the MoveResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> MoveResponse:
+        """Deserializes the MoveResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class Put:
     path: str
@@ -290,6 +449,20 @@ class Put:
                    path=d.get('path', None))
 
 
+@dataclass
+class PutResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the PutResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> PutResponse:
+        """Deserializes the PutResponse from a dictionary."""
+        return cls()
+
+
 @dataclass
 class ReadResponse:
     bytes_read: Optional[int] = None
@@ -312,6 +485,20 @@ class ReadResponse:
         return cls(bytes_read=d.get('bytes_read', None), data=d.get('data', None))
 
 
+@dataclass
+class UploadResponse:
+
+    def as_dict(self) -> dict:
+        """Serializes the UploadResponse into a dictionary suitable for use as a JSON request body."""
+        body = {}
+        return body
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, any]) -> UploadResponse:
+        """Deserializes the UploadResponse from a dictionary."""
+        return cls()
+
+
 class DbfsAPI:
     """DBFS API makes it simple to interact with various data sources without having to include a users
     credentials every time to read a file."""
@@ -338,6 +525,7 @@ class DbfsAPI:
         if data is not None: body['data'] = data
         if handle is not None: body['handle'] = handle
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST', '/api/2.0/dbfs/add-block', body=body, headers=headers)
 
     def close(self, handle: int):
@@ -354,6 +542,7 @@ class DbfsAPI:
         body = {}
         if handle is not None: body['handle'] = handle
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST', '/api/2.0/dbfs/close', body=body, headers=headers)
 
     def create(self, path: str, *, overwrite: Optional[bool] = None) -> CreateResponse:
@@ -379,6 +568,7 @@ class DbfsAPI:
         if overwrite is not None: body['overwrite'] = overwrite
         if path is not None: body['path'] = path
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         res = self._api.do('POST', '/api/2.0/dbfs/create', body=body, headers=headers)
         return CreateResponse.from_dict(res)
 
@@ -412,6 +602,7 @@ class DbfsAPI:
         if path is not None: body['path'] = path
         if recursive is not None: body['recursive'] = recursive
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST', '/api/2.0/dbfs/delete', body=body, headers=headers)
 
     def get_status(self, path: str) -> FileInfo:
@@ -429,6 +620,7 @@ class DbfsAPI:
         query = {}
         if path is not None: query['path'] = path
         headers = {'Accept': 'application/json', }
+
         res = self._api.do('GET', '/api/2.0/dbfs/get-status', query=query, headers=headers)
         return FileInfo.from_dict(res)
 
@@ -454,6 +646,7 @@ class DbfsAPI:
         query = {}
         if path is not None: query['path'] = path
         headers = {'Accept': 'application/json', }
+
         json = self._api.do('GET', '/api/2.0/dbfs/list', query=query, headers=headers)
         parsed = ListStatusResponse.from_dict(json).files
         return parsed if parsed is not None else []
@@ -474,6 +667,7 @@ class DbfsAPI:
         body = {}
         if path is not None: body['path'] = path
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST', '/api/2.0/dbfs/mkdirs', body=body, headers=headers)
 
     def move(self, source_path: str, destination_path: str):
@@ -495,6 +689,7 @@ class DbfsAPI:
         if destination_path is not None: body['destination_path'] = destination_path
         if source_path is not None: body['source_path'] = source_path
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST', '/api/2.0/dbfs/move', body=body, headers=headers)
 
     def put(self, path: str, *, contents: Optional[str] = None, overwrite: Optional[bool] = None):
@@ -525,6 +720,7 @@ class DbfsAPI:
         if overwrite is not None: body['overwrite'] = overwrite
         if path is not None: body['path'] = path
         headers = {'Accept': 'application/json', 'Content-Type': 'application/json', }
+
         self._api.do('POST', '/api/2.0/dbfs/put', body=body, headers=headers)
 
     def read(self, path: str, *, length: Optional[int] = None, offset: Optional[int] = None) -> ReadResponse:
@@ -554,12 +750,26 @@ class DbfsAPI:
         if offset is not None: query['offset'] = offset
         if path is not None: query['path'] = path
         headers = {'Accept': 'application/json', }
+
         res = self._api.do('GET', '/api/2.0/dbfs/read', query=query, headers=headers)
         return ReadResponse.from_dict(res)
 
 
 class FilesAPI:
-    """The Files API allows you to read, write, and delete files and directories in Unity Catalog volumes."""
+    """The Files API is a standard HTTP API that allows you to read, write, list, and delete files and
+    directories by referring to their URI. The API makes working with file content as raw bytes easier and
+    more efficient.
+    
+    The API supports [Unity Catalog volumes], where files and directories to operate on are specified using
+    their volume URI path, which follows the format
+    /Volumes/<catalog_name>/<schema_name>/<volume_name>/<path_to_file>.
+    
+    The Files API has two distinct endpoints, one for working with files (`/fs/files`) and another one for
+    working with directories (`/fs/directories`). Both endpoints, use the standard HTTP methods GET, HEAD,
+    PUT, and DELETE to manage files and directories specified using their URI path. The path is always
+    absolute.
+    
+    [Unity Catalog volumes]: https://docs.databricks.com/en/connect/unity-catalog/volumes.html"""
 
     def __init__(self, api_client):
         self._api = api_client
@@ -567,7 +777,9 @@ class FilesAPI:
     def create_directory(self, directory_path: str):
         """Create a directory.
         
-        Creates an empty directory. If called on an existing directory, the API returns a success response.
+        Creates an empty directory. If necessary, also creates any parent directories of the new, empty
+        directory (like the shell command `mkdir -p`). If called on an existing directory, returns a success
+        response; this method is idempotent (it will succeed if the directory already exists).
         
         :param directory_path: str
           The absolute path of a directory.
@@ -576,12 +788,13 @@ class FilesAPI:
         """
 
         headers = {}
+
         self._api.do('PUT', f'/api/2.0/fs/directories{directory_path}', headers=headers)
 
     def delete(self, file_path: str):
         """Delete a file.
         
-        Deletes a file.
+        Deletes a file. If the request is successful, there is no response body.
         
         :param file_path: str
           The absolute path of the file.
@@ -590,12 +803,16 @@ class FilesAPI:
         """
 
         headers = {}
+
         self._api.do('DELETE', f'/api/2.0/fs/files{file_path}', headers=headers)
 
     def delete_directory(self, directory_path: str):
         """Delete a directory.
         
-        Deletes an empty directory. If the directory is not empty, the API returns a HTTP 400 error.
+        Deletes an empty directory.
+        
+        To delete a non-empty directory, first delete all of its contents. This can be done by listing the
+        directory contents and deleting each file and subdirectory recursively.
         
         :param directory_path: str
           The absolute path of a directory.
@@ -604,12 +821,14 @@ class FilesAPI:
         """
 
         headers = {}
+
         self._api.do('DELETE', f'/api/2.0/fs/directories{directory_path}', headers=headers)
 
     def download(self, file_path: str) -> DownloadResponse:
         """Download a file.
         
-        Downloads a file of up to 5 GiB.
+        Downloads a file of up to 5 GiB. The file contents are the response body. This is a standard HTTP file
+        download, not a JSON RPC.
         
         :param file_path: str
           The absolute path of the file.
@@ -618,8 +837,53 @@ class FilesAPI:
         """
 
         headers = {'Accept': 'application/octet-stream', }
-        res = self._api.do('GET', f'/api/2.0/fs/files{file_path}', headers=headers, raw=True)
-        return DownloadResponse(contents=res)
+        response_headers = ['content-length', 'content-type', 'last-modified', ]
+        res = self._api.do('GET',
+                           f'/api/2.0/fs/files{file_path}',
+                           headers=headers,
+                           response_headers=response_headers,
+                           raw=True)
+        return DownloadResponse.from_dict(res)
+
+    def get_directory_metadata(self, directory_path: str):
+        """Get directory metadata.
+        
+        Get the metadata of a directory. The response HTTP headers contain the metadata. There is no response
+        body.
+        
+        This method is useful to check if a directory exists and the caller has access to it.
+        
+        If you wish to ensure the directory exists, you can instead use `PUT`, which will create the directory
+        if it does not exist, and is idempotent (it will succeed if the directory already exists).
+        
+        :param directory_path: str
+          The absolute path of a directory.
+        
+        
+        """
+
+        headers = {}
+
+        self._api.do('HEAD', f'/api/2.0/fs/directories{directory_path}', headers=headers)
+
+    def get_metadata(self, file_path: str) -> GetMetadataResponse:
+        """Get file metadata.
+        
+        Get the metadata of a file. The response HTTP headers contain the metadata. There is no response body.
+        
+        :param file_path: str
+          The absolute path of the file.
+        
+        :returns: :class:`GetMetadataResponse`
+        """
+
+        headers = {}
+        response_headers = ['content-length', 'content-type', 'last-modified', ]
+        res = self._api.do('HEAD',
+                           f'/api/2.0/fs/files{file_path}',
+                           headers=headers,
+                           response_headers=response_headers)
+        return GetMetadataResponse.from_dict(res)
 
     def list_directory_contents(self,
                                 directory_path: str,
@@ -634,16 +898,22 @@ class FilesAPI:
         :param directory_path: str
           The absolute path of a directory.
         :param page_size: int (optional)
-          The maximum number of directory entries to return. The API may return fewer than this value.
-          Receiving fewer results does not imply there are no more results. As long as the response contains a
-          next_page_token, there may be more results.
+          The maximum number of directory entries to return. The response may contain fewer entries. If the
+          response contains a `next_page_token`, there may be more entries, even if fewer than `page_size`
+          entries are in the response.
+          
+          We recommend not to set this value unless you are intentionally listing less than the complete
+          directory contents.
           
           If unspecified, at most 1000 directory entries will be returned. The maximum value is 1000. Values
           above 1000 will be coerced to 1000.
         :param page_token: str (optional)
-          A page token, received from a previous `list` call. Provide this to retrieve the subsequent page.
-          When paginating, all other parameters provided to `list` must match the call that provided the page
-          token.
+          An opaque page token which was the `next_page_token` in the response of the previous request to list
+          the contents of this directory. Provide this token to retrieve the next page of directory entries.
+          When providing a `page_token`, all other parameters provided to the request must match the previous
+          request. To list all of the entries in a directory, it is necessary to continue requesting pages of
+          entries until the response contains no `next_page_token`. Note that the number of entries returned
+          must not be used to determine when the listing is complete.
         
         :returns: Iterator over :class:`DirectoryEntry`
         """
@@ -668,7 +938,10 @@ class FilesAPI:
     def upload(self, file_path: str, contents: BinaryIO, *, overwrite: Optional[bool] = None):
         """Upload a file.
         
-        Uploads a file of up to 5 GiB.
+        Uploads a file of up to 5 GiB. The file contents should be sent as the request body as raw bytes (an
+        octet stream); do not encode or otherwise modify the bytes before sending. The contents of the
+        resulting file will be exactly the bytes sent in the request body. If the request is successful, there
+        is no response body.
         
         :param file_path: str
           The absolute path of the file.
@@ -682,4 +955,5 @@ class FilesAPI:
         query = {}
         if overwrite is not None: query['overwrite'] = overwrite
         headers = {'Content-Type': 'application/octet-stream', }
+
         self._api.do('PUT', f'/api/2.0/fs/files{file_path}', query=query, headers=headers, data=contents)