diff --git a/.codegen.json b/.codegen.json index 3b6511760..873459285 100644 --- a/.codegen.json +++ b/.codegen.json @@ -1 +1 @@ -{ "engineHash": "f97463c", "specHash": "b7abe0d", "version": "10.2.0" } +{ "engineHash": "b5860f1", "specHash": "1e0848d", "version": "10.2.0" } diff --git a/box_sdk_gen/client.py b/box_sdk_gen/client.py index 914844877..155301d2e 100644 --- a/box_sdk_gen/client.py +++ b/box_sdk_gen/client.py @@ -168,6 +168,8 @@ from box_sdk_gen.managers.ai_studio import AiStudioManager +from box_sdk_gen.managers.metadata_taxonomies import MetadataTaxonomiesManager + from box_sdk_gen.managers.docgen_template import DocgenTemplateManager from box_sdk_gen.managers.docgen import DocgenManager @@ -427,6 +429,9 @@ def __init__(self, auth: Authentication, *, network_session: NetworkSession = No self.ai_studio = AiStudioManager( auth=self.auth, network_session=self.network_session ) + self.metadata_taxonomies = MetadataTaxonomiesManager( + auth=self.auth, network_session=self.network_session + ) self.docgen_template = DocgenTemplateManager( auth=self.auth, network_session=self.network_session ) diff --git a/box_sdk_gen/managers/__init__.py b/box_sdk_gen/managers/__init__.py index 59e3e15f2..9ab97dc30 100644 --- a/box_sdk_gen/managers/__init__.py +++ b/box_sdk_gen/managers/__init__.py @@ -142,6 +142,8 @@ from box_sdk_gen.managers.ai_studio import * +from box_sdk_gen.managers.metadata_taxonomies import * + from box_sdk_gen.managers.docgen_template import * from box_sdk_gen.managers.docgen import * diff --git a/box_sdk_gen/managers/file_metadata.py b/box_sdk_gen/managers/file_metadata.py index 8dc0577f2..21b7236af 100644 --- a/box_sdk_gen/managers/file_metadata.py +++ b/box_sdk_gen/managers/file_metadata.py @@ -132,7 +132,11 @@ def __init__( self.network_session = network_session def get_file_metadata( - self, file_id: str, *, extra_headers: Optional[Dict[str, Optional[str]]] = None + self, + file_id: str, + *, + view: Optional[str] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None ) -> Metadatas: """ Retrieves all metadata for a given file. @@ -145,11 +149,18 @@ def get_file_metadata( the `file_id` is `123`. Example: "12345" :type file_id: str + :param view: Taxonomy field values are returned in `API view` by default, meaning + the value is represented with a taxonomy node identifier. + To retrieve the `Hydrated view`, where taxonomy values are represented + with the full taxonomy node information, set this parameter to `hydrated`. + This is the only supported value for this parameter., defaults to None + :type view: Optional[str], optional :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None :type extra_headers: Optional[Dict[str, Optional[str]]], optional """ if extra_headers is None: extra_headers = {} + query_params_map: Dict[str, str] = prepare_params({'view': to_string(view)}) headers_map: Dict[str, str] = prepare_params({**extra_headers}) response: FetchResponse = self.network_session.network_client.fetch( FetchOptions( @@ -162,6 +173,7 @@ def get_file_metadata( ] ), method='GET', + params=query_params_map, headers=headers_map, response_format=ResponseFormat.JSON, auth=self.auth, @@ -176,6 +188,7 @@ def get_file_metadata_by_id( scope: GetFileMetadataByIdScope, template_key: str, *, + view: Optional[str] = None, extra_headers: Optional[Dict[str, Optional[str]]] = None ) -> MetadataFull: """ @@ -198,11 +211,18 @@ def get_file_metadata_by_id( :param template_key: The name of the metadata template. Example: "properties" :type template_key: str + :param view: Taxonomy field values are returned in `API view` by default, meaning + the value is represented with a taxonomy node identifier. + To retrieve the `Hydrated view`, where taxonomy values are represented + with the full taxonomy node information, set this parameter to `hydrated`. + This is the only supported value for this parameter., defaults to None + :type view: Optional[str], optional :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None :type extra_headers: Optional[Dict[str, Optional[str]]], optional """ if extra_headers is None: extra_headers = {} + query_params_map: Dict[str, str] = prepare_params({'view': to_string(view)}) headers_map: Dict[str, str] = prepare_params({**extra_headers}) response: FetchResponse = self.network_session.network_client.fetch( FetchOptions( @@ -218,6 +238,7 @@ def get_file_metadata_by_id( ] ), method='GET', + params=query_params_map, headers=headers_map, response_format=ResponseFormat.JSON, auth=self.auth, diff --git a/box_sdk_gen/managers/folder_metadata.py b/box_sdk_gen/managers/folder_metadata.py index 602effef4..3a88749a9 100644 --- a/box_sdk_gen/managers/folder_metadata.py +++ b/box_sdk_gen/managers/folder_metadata.py @@ -135,6 +135,7 @@ def get_folder_metadata( self, folder_id: str, *, + view: Optional[str] = None, extra_headers: Optional[Dict[str, Optional[str]]] = None ) -> Metadatas: """ @@ -154,11 +155,18 @@ def get_folder_metadata( always represented by the ID `0`. Example: "12345" :type folder_id: str + :param view: Taxonomy field values are returned in `API view` by default, meaning + the value is represented with a taxonomy node identifier. + To retrieve the `Hydrated view`, where taxonomy values are represented + with the full taxonomy node information, set this parameter to `hydrated`. + This is the only supported value for this parameter., defaults to None + :type view: Optional[str], optional :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None :type extra_headers: Optional[Dict[str, Optional[str]]], optional """ if extra_headers is None: extra_headers = {} + query_params_map: Dict[str, str] = prepare_params({'view': to_string(view)}) headers_map: Dict[str, str] = prepare_params({**extra_headers}) response: FetchResponse = self.network_session.network_client.fetch( FetchOptions( @@ -171,6 +179,7 @@ def get_folder_metadata( ] ), method='GET', + params=query_params_map, headers=headers_map, response_format=ResponseFormat.JSON, auth=self.auth, diff --git a/box_sdk_gen/managers/metadata_taxonomies.py b/box_sdk_gen/managers/metadata_taxonomies.py new file mode 100644 index 000000000..868e22249 --- /dev/null +++ b/box_sdk_gen/managers/metadata_taxonomies.py @@ -0,0 +1,901 @@ +from enum import Enum + +from typing import Optional + +from typing import Dict + +from box_sdk_gen.serialization.json import serialize + +from box_sdk_gen.serialization.json import deserialize + +from box_sdk_gen.internal.utils import to_string + +from typing import List + +from box_sdk_gen.networking.fetch_options import ResponseFormat + +from box_sdk_gen.schemas.metadata_taxonomy import MetadataTaxonomy + +from box_sdk_gen.schemas.client_error import ClientError + +from box_sdk_gen.schemas.metadata_taxonomies import MetadataTaxonomies + +from box_sdk_gen.schemas.metadata_taxonomy_levels import MetadataTaxonomyLevels + +from box_sdk_gen.schemas.metadata_taxonomy_level import MetadataTaxonomyLevel + +from box_sdk_gen.schemas.metadata_taxonomy_nodes import MetadataTaxonomyNodes + +from box_sdk_gen.schemas.metadata_taxonomy_node import MetadataTaxonomyNode + +from box_sdk_gen.box.errors import BoxSDKError + +from box_sdk_gen.networking.auth import Authentication + +from box_sdk_gen.networking.network import NetworkSession + +from box_sdk_gen.networking.fetch_options import FetchOptions + +from box_sdk_gen.networking.fetch_response import FetchResponse + +from box_sdk_gen.internal.utils import prepare_params + +from box_sdk_gen.internal.utils import to_string + +from box_sdk_gen.internal.utils import ByteStream + +from box_sdk_gen.serialization.json import SerializedData + +from box_sdk_gen.serialization.json import sd_to_json + + +class GetMetadataTemplateFieldOptionsScope(str, Enum): + GLOBAL = 'global' + ENTERPRISE = 'enterprise' + + +class MetadataTaxonomiesManager: + def __init__( + self, + *, + auth: Optional[Authentication] = None, + network_session: NetworkSession = None + ): + if network_session is None: + network_session = NetworkSession() + self.auth = auth + self.network_session = network_session + + def create_metadata_taxonomy( + self, + display_name: str, + namespace: str, + *, + key: Optional[str] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomy: + """ + Creates a new metadata taxonomy that can be used in + + metadata templates. + + :param display_name: The display name of the taxonomy. + :type display_name: str + :param namespace: The namespace of the metadata taxonomy to create. + :type namespace: str + :param key: The taxonomy key. If it is not provided in the request body, it will be + generated from the `displayName`. The `displayName` would be converted + to lower case, and all spaces and non-alphanumeric characters replaced + with underscores., defaults to None + :type key: Optional[str], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + request_body: Dict = { + 'key': key, + 'displayName': display_name, + 'namespace': namespace, + } + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies', + ] + ), + method='POST', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomy) + + def get_metadata_taxonomies( + self, + namespace: str, + *, + marker: Optional[str] = None, + limit: Optional[int] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomies: + """ + Used to retrieve all metadata taxonomies in a namespace. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param marker: Defines the position marker at which to begin returning results. This is + used when paginating using marker-based pagination. + + This requires `usemarker` to be set to `true`., defaults to None + :type marker: Optional[str], optional + :param limit: The maximum number of items to return per page., defaults to None + :type limit: Optional[int], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + query_params_map: Dict[str, str] = prepare_params( + {'marker': to_string(marker), 'limit': to_string(limit)} + ) + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + ] + ), + method='GET', + params=query_params_map, + headers=headers_map, + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomies) + + def get_metadata_taxonomy_by_key( + self, + namespace: str, + taxonomy_key: str, + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomy: + """ + Used to retrieve a metadata taxonomy by taxonomy key. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + ] + ), + method='GET', + headers=headers_map, + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomy) + + def update_metadata_taxonomy( + self, + namespace: str, + taxonomy_key: str, + display_name: str, + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomy: + """ + Updates an existing metadata taxonomy. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param display_name: The display name of the taxonomy. + :type display_name: str + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + request_body: Dict = {'displayName': display_name} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + ] + ), + method='PATCH', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomy) + + def delete_metadata_taxonomy( + self, + namespace: str, + taxonomy_key: str, + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> None: + """ + Delete a metadata taxonomy. + + This deletion is permanent and cannot be reverted. + + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + ] + ), + method='DELETE', + headers=headers_map, + response_format=ResponseFormat.NO_CONTENT, + auth=self.auth, + network_session=self.network_session, + ) + ) + return None + + def create_metadata_taxonomy_level( + self, + namespace: str, + taxonomy_key: str, + request_body: List[MetadataTaxonomyLevel], + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyLevels: + """ + Creates new metadata taxonomy levels. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param request_body: Request body of createMetadataTaxonomyLevel method + :type request_body: List[MetadataTaxonomyLevel] + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/levels', + ] + ), + method='POST', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyLevels) + + def patch_metadata_taxonomies_id_id_levels_id( + self, + namespace: str, + taxonomy_key: str, + level_index: int, + display_name: str, + *, + description: Optional[str] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyLevel: + """ + Updates an existing metadata taxonomy level. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param level_index: The index of the metadata taxonomy level. + Example: 1 + :type level_index: int + :param display_name: The display name of the taxonomy level. + :type display_name: str + :param description: The description of the taxonomy level., defaults to None + :type description: Optional[str], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + request_body: Dict = {'displayName': display_name, 'description': description} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/levels/', + to_string(level_index), + ] + ), + method='PATCH', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyLevel) + + def add_metadata_taxonomy_level( + self, + namespace: str, + taxonomy_key: str, + display_name: str, + *, + description: Optional[str] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyLevels: + """ + Creates a new metadata taxonomy level and appends it to the existing levels. + + If there are no levels defined yet, this will create the first level. + + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param display_name: The display name of the taxonomy level. + :type display_name: str + :param description: The description of the taxonomy level., defaults to None + :type description: Optional[str], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + request_body: Dict = {'displayName': display_name, 'description': description} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/levels:append', + ] + ), + method='POST', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyLevels) + + def delete_metadata_taxonomy_level( + self, + namespace: str, + taxonomy_key: str, + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyLevels: + """ + Deletes the last level of the metadata taxonomy. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/levels:trim', + ] + ), + method='POST', + headers=headers_map, + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyLevels) + + def get_metadata_taxonomy_nodes( + self, + namespace: str, + taxonomy_key: str, + *, + level: Optional[List[int]] = None, + parent: Optional[List[str]] = None, + ancestor: Optional[List[str]] = None, + query: Optional[str] = None, + include_total_result_count: Optional[bool] = None, + marker: Optional[str] = None, + limit: Optional[int] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyNodes: + """ + Used to retrieve metadata taxonomy nodes based on the parameters specified. + + Results are sorted in lexicographic order unless a `query` parameter is passed. + + + With a `query` parameter specified, results are sorted in order of relevance. + + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param level: Filters results by taxonomy level. Multiple values can be provided. + Results include nodes that match any of the specified values., defaults to None + :type level: Optional[List[int]], optional + :param parent: Node identifier of a direct parent node. Multiple values can be provided. + Results include nodes that match any of the specified values., defaults to None + :type parent: Optional[List[str]], optional + :param ancestor: Node identifier of any ancestor node. Multiple values can be provided. + Results include nodes that match any of the specified values., defaults to None + :type ancestor: Optional[List[str]], optional + :param query: Query text to search for the taxonomy nodes., defaults to None + :type query: Optional[str], optional + :param include_total_result_count: When set to `true` this provides the total number of nodes that matched the query. + The response will compute counts of up to 10,000 elements. Defaults to `false`., defaults to None + :type include_total_result_count: Optional[bool], optional + :param marker: Defines the position marker at which to begin returning results. This is + used when paginating using marker-based pagination. + + This requires `usemarker` to be set to `true`., defaults to None + :type marker: Optional[str], optional + :param limit: The maximum number of items to return per page., defaults to None + :type limit: Optional[int], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + query_params_map: Dict[str, str] = prepare_params( + { + 'level': to_string(level), + 'parent': to_string(parent), + 'ancestor': to_string(ancestor), + 'query': to_string(query), + 'include-total-result-count': to_string(include_total_result_count), + 'marker': to_string(marker), + 'limit': to_string(limit), + } + ) + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/nodes', + ] + ), + method='GET', + params=query_params_map, + headers=headers_map, + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyNodes) + + def create_metadata_taxonomy_node( + self, + namespace: str, + taxonomy_key: str, + display_name: str, + level: int, + *, + parent_id: Optional[str] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyNode: + """ + Creates a new metadata taxonomy node. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param display_name: The display name of the taxonomy node. + :type display_name: str + :param level: The level of the taxonomy node. + :type level: int + :param parent_id: The identifier of the parent taxonomy node. + Omit this field for root-level nodes., defaults to None + :type parent_id: Optional[str], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + request_body: Dict = { + 'displayName': display_name, + 'level': level, + 'parentId': parent_id, + } + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/nodes', + ] + ), + method='POST', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyNode) + + def get_metadata_taxonomy_node_by_id( + self, + namespace: str, + taxonomy_key: str, + node_id: str, + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyNode: + """ + Retrieves a metadata taxonomy node by its identifier. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param node_id: The identifier of the metadata taxonomy node. + Example: "14d3d433-c77f-49c5-b146-9dea370f6e32" + :type node_id: str + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/nodes/', + to_string(node_id), + ] + ), + method='GET', + headers=headers_map, + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyNode) + + def update_metadata_taxonomy_node( + self, + namespace: str, + taxonomy_key: str, + node_id: str, + *, + display_name: Optional[str] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyNode: + """ + Updates an existing metadata taxonomy node. + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param node_id: The identifier of the metadata taxonomy node. + Example: "14d3d433-c77f-49c5-b146-9dea370f6e32" + :type node_id: str + :param display_name: The display name of the taxonomy node., defaults to None + :type display_name: Optional[str], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + request_body: Dict = {'displayName': display_name} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/nodes/', + to_string(node_id), + ] + ), + method='PATCH', + headers=headers_map, + data=serialize(request_body), + content_type='application/json', + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyNode) + + def delete_metadata_taxonomy_node( + self, + namespace: str, + taxonomy_key: str, + node_id: str, + *, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> None: + """ + Delete a metadata taxonomy node. + + This deletion is permanent and cannot be reverted. + + + Only metadata taxonomy nodes without any children can be deleted. + + :param namespace: The namespace of the metadata taxonomy. + Example: "enterprise_123456" + :type namespace: str + :param taxonomy_key: The key of the metadata taxonomy. + Example: "geography" + :type taxonomy_key: str + :param node_id: The identifier of the metadata taxonomy node. + Example: "14d3d433-c77f-49c5-b146-9dea370f6e32" + :type node_id: str + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_taxonomies/', + to_string(namespace), + '/', + to_string(taxonomy_key), + '/nodes/', + to_string(node_id), + ] + ), + method='DELETE', + headers=headers_map, + response_format=ResponseFormat.NO_CONTENT, + auth=self.auth, + network_session=self.network_session, + ) + ) + return None + + def get_metadata_template_field_options( + self, + scope: GetMetadataTemplateFieldOptionsScope, + template_key: str, + field_key: str, + *, + level: Optional[List[int]] = None, + parent: Optional[List[str]] = None, + ancestor: Optional[List[str]] = None, + query: Optional[str] = None, + include_total_result_count: Optional[bool] = None, + only_selectable_options: Optional[bool] = None, + marker: Optional[str] = None, + limit: Optional[int] = None, + extra_headers: Optional[Dict[str, Optional[str]]] = None + ) -> MetadataTaxonomyNodes: + """ + Used to retrieve metadata taxonomy nodes which are available for the taxonomy field based + + on its configuration and the parameters specified. + + + Results are sorted in lexicographic order unless a `query` parameter is passed. + + + With a `query` parameter specified, results are sorted in order of relevance. + + :param scope: The scope of the metadata template. + Example: "global" + :type scope: GetMetadataTemplateFieldOptionsScope + :param template_key: The name of the metadata template. + Example: "properties" + :type template_key: str + :param field_key: The key of the metadata taxonomy field in the template. + Example: "geography" + :type field_key: str + :param level: Filters results by taxonomy level. Multiple values can be provided. + Results include nodes that match any of the specified values., defaults to None + :type level: Optional[List[int]], optional + :param parent: Node identifier of a direct parent node. Multiple values can be provided. + Results include nodes that match any of the specified values., defaults to None + :type parent: Optional[List[str]], optional + :param ancestor: Node identifier of any ancestor node. Multiple values can be provided. + Results include nodes that match any of the specified values., defaults to None + :type ancestor: Optional[List[str]], optional + :param query: Query text to search for the taxonomy nodes., defaults to None + :type query: Optional[str], optional + :param include_total_result_count: When set to `true` this provides the total number of nodes that matched the query. + The response will compute counts of up to 10,000 elements. Defaults to `false`., defaults to None + :type include_total_result_count: Optional[bool], optional + :param only_selectable_options: When set to `true`, this only returns valid selectable options for this template + taxonomy field. Otherwise, it returns all taxonomy nodes, whether or not they are selectable. + Defaults to `true`., defaults to None + :type only_selectable_options: Optional[bool], optional + :param marker: Defines the position marker at which to begin returning results. This is + used when paginating using marker-based pagination. + + This requires `usemarker` to be set to `true`., defaults to None + :type marker: Optional[str], optional + :param limit: The maximum number of items to return per page., defaults to None + :type limit: Optional[int], optional + :param extra_headers: Extra headers that will be included in the HTTP request., defaults to None + :type extra_headers: Optional[Dict[str, Optional[str]]], optional + """ + if extra_headers is None: + extra_headers = {} + query_params_map: Dict[str, str] = prepare_params( + { + 'level': to_string(level), + 'parent': to_string(parent), + 'ancestor': to_string(ancestor), + 'query': to_string(query), + 'include-total-result-count': to_string(include_total_result_count), + 'only-selectable-options': to_string(only_selectable_options), + 'marker': to_string(marker), + 'limit': to_string(limit), + } + ) + headers_map: Dict[str, str] = prepare_params({**extra_headers}) + response: FetchResponse = self.network_session.network_client.fetch( + FetchOptions( + url=''.join( + [ + self.network_session.base_urls.base_url, + '/2.0/metadata_templates/', + to_string(scope), + '/', + to_string(template_key), + '/fields/', + to_string(field_key), + '/options', + ] + ), + method='GET', + params=query_params_map, + headers=headers_map, + response_format=ResponseFormat.JSON, + auth=self.auth, + network_session=self.network_session, + ) + ) + return deserialize(response.data, MetadataTaxonomyNodes) diff --git a/box_sdk_gen/managers/metadata_templates.py b/box_sdk_gen/managers/metadata_templates.py index 445c66a57..3c6e12b83 100644 --- a/box_sdk_gen/managers/metadata_templates.py +++ b/box_sdk_gen/managers/metadata_templates.py @@ -150,6 +150,7 @@ class CreateMetadataTemplateFieldsTypeField(str, Enum): DATE = 'date' ENUM = 'enum' MULTISELECT = 'multiSelect' + TAXONOMY = 'taxonomy' class CreateMetadataTemplateFieldsOptionsField(BaseObject): @@ -163,16 +164,58 @@ def __init__(self, key: str, **kwargs): self.key = key +class CreateMetadataTemplateFieldsOptionsRulesField(BaseObject): + _fields_to_json_mapping: Dict[str, str] = { + 'multi_select': 'multiSelect', + 'selectable_levels': 'selectableLevels', + **BaseObject._fields_to_json_mapping, + } + _json_to_fields_mapping: Dict[str, str] = { + 'multiSelect': 'multi_select', + 'selectableLevels': 'selectable_levels', + **BaseObject._json_to_fields_mapping, + } + + def __init__( + self, + *, + multi_select: Optional[bool] = None, + selectable_levels: Optional[List[int]] = None, + **kwargs + ): + """ + :param multi_select: Whether to allow users to select multiple values., defaults to None + :type multi_select: Optional[bool], optional + :param selectable_levels: An array of integers defining which levels of the taxonomy are + selectable by users., defaults to None + :type selectable_levels: Optional[List[int]], optional + """ + super().__init__(**kwargs) + self.multi_select = multi_select + self.selectable_levels = selectable_levels + + class CreateMetadataTemplateFields(BaseObject): _fields_to_json_mapping: Dict[str, str] = { 'display_name': 'displayName', + 'taxonomy_key': 'taxonomyKey', + 'options_rules': 'optionsRules', **BaseObject._fields_to_json_mapping, } _json_to_fields_mapping: Dict[str, str] = { 'displayName': 'display_name', + 'taxonomyKey': 'taxonomy_key', + 'optionsRules': 'options_rules', **BaseObject._json_to_fields_mapping, } - _discriminator = 'type', {'string', 'float', 'date', 'enum', 'multiSelect'} + _discriminator = 'type', { + 'string', + 'float', + 'date', + 'enum', + 'multiSelect', + 'taxonomy', + } def __init__( self, @@ -183,16 +226,22 @@ def __init__( description: Optional[str] = None, hidden: Optional[bool] = None, options: Optional[List[CreateMetadataTemplateFieldsOptionsField]] = None, + taxonomy_key: Optional[str] = None, + namespace: Optional[str] = None, + options_rules: Optional[CreateMetadataTemplateFieldsOptionsRulesField] = None, **kwargs ): """ :param type: The type of field. The basic fields are a `string` field for text, a - `float` field for numbers, and a `date` fields to present the user with a + `float` field for numbers, and a `date` field to present the user with a date-time picker. Additionally, metadata templates support an `enum` field for a basic list of items, and ` multiSelect` field for a similar list of items where the user can select more than one value. + + Metadata taxonomies are also supported as a `taxonomy` field type + with a specific set of additional properties, which describe its structure. :type type: CreateMetadataTemplateFieldsTypeField :param key: A unique identifier for the field. The identifier must be unique within the template to which it belongs. @@ -208,6 +257,15 @@ def __init__( :param options: A list of options for this field. This is used in combination with the `enum` and `multiSelect` field types., defaults to None :type options: Optional[List[CreateMetadataTemplateFieldsOptionsField]], optional + :param taxonomy_key: The unique key of the metadata taxonomy to use for this taxonomy field. + This property is required when the field `type` is set to `taxonomy`., defaults to None + :type taxonomy_key: Optional[str], optional + :param namespace: The namespace of the metadata taxonomy to use for this taxonomy field. + This property is required when the field `type` is set to `taxonomy`., defaults to None + :type namespace: Optional[str], optional + :param options_rules: An object defining additional rules for the options of the taxonomy field. + This property is required when the field `type` is set to `taxonomy`., defaults to None + :type options_rules: Optional[CreateMetadataTemplateFieldsOptionsRulesField], optional """ super().__init__(**kwargs) self.type = type @@ -216,6 +274,9 @@ def __init__( self.description = description self.hidden = hidden self.options = options + self.taxonomy_key = taxonomy_key + self.namespace = namespace + self.options_rules = options_rules class MetadataTemplatesManager: diff --git a/box_sdk_gen/schemas/__init__.py b/box_sdk_gen/schemas/__init__.py index 5a2ff543c..023aac177 100644 --- a/box_sdk_gen/schemas/__init__.py +++ b/box_sdk_gen/schemas/__init__.py @@ -216,6 +216,20 @@ from box_sdk_gen.schemas.metadata_query import * +from box_sdk_gen.schemas.metadata_taxonomy_ancestor import * + +from box_sdk_gen.schemas.metadata_taxonomy_node import * + +from box_sdk_gen.schemas.metadata_taxonomy_nodes import * + +from box_sdk_gen.schemas.metadata_taxonomy_level import * + +from box_sdk_gen.schemas.metadata_taxonomy_levels import * + +from box_sdk_gen.schemas.metadata_taxonomy import * + +from box_sdk_gen.schemas.metadata_taxonomies import * + from box_sdk_gen.schemas.metadata_template import * from box_sdk_gen.schemas.metadata_templates import * diff --git a/box_sdk_gen/schemas/metadata_taxonomies.py b/box_sdk_gen/schemas/metadata_taxonomies.py new file mode 100644 index 000000000..fcfb9e6a3 --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomies.py @@ -0,0 +1,38 @@ +from typing import Optional + +from typing import List + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.schemas.metadata_taxonomy import MetadataTaxonomy + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomies(BaseObject): + def __init__( + self, + *, + limit: Optional[int] = None, + next_marker: Optional[str] = None, + prev_marker: Optional[str] = None, + entries: Optional[List[MetadataTaxonomy]] = None, + **kwargs + ): + """ + :param limit: The limit that was used for these entries. This will be the same as the + `limit` query parameter unless that value exceeded the maximum value + allowed. The maximum value varies by API., defaults to None + :type limit: Optional[int], optional + :param next_marker: The marker for the start of the next page of results., defaults to None + :type next_marker: Optional[str], optional + :param prev_marker: The marker for the start of the previous page of results., defaults to None + :type prev_marker: Optional[str], optional + :param entries: A list of metadata taxonomies., defaults to None + :type entries: Optional[List[MetadataTaxonomy]], optional + """ + super().__init__(**kwargs) + self.limit = limit + self.next_marker = next_marker + self.prev_marker = prev_marker + self.entries = entries diff --git a/box_sdk_gen/schemas/metadata_taxonomy.py b/box_sdk_gen/schemas/metadata_taxonomy.py new file mode 100644 index 000000000..796d43822 --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomy.py @@ -0,0 +1,52 @@ +from typing import Optional + +from typing import List + +from typing import Dict + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.schemas.metadata_taxonomy_level import MetadataTaxonomyLevel + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomy(BaseObject): + _fields_to_json_mapping: Dict[str, str] = { + 'display_name': 'displayName', + **BaseObject._fields_to_json_mapping, + } + _json_to_fields_mapping: Dict[str, str] = { + 'displayName': 'display_name', + **BaseObject._json_to_fields_mapping, + } + + def __init__( + self, + id: str, + display_name: str, + namespace: str, + *, + key: Optional[str] = None, + levels: Optional[List[MetadataTaxonomyLevel]] = None, + **kwargs + ): + """ + :param id: A unique identifier of the metadata taxonomy. + :type id: str + :param display_name: The display name of the metadata taxonomy. This can be seen in the Box web app. + :type display_name: str + :param namespace: A namespace that the metadata taxonomy is associated with. + :type namespace: str + :param key: A unique identifier of the metadata taxonomy. The identifier must be unique within + the namespace to which it belongs., defaults to None + :type key: Optional[str], optional + :param levels: Levels of the metadata taxonomy., defaults to None + :type levels: Optional[List[MetadataTaxonomyLevel]], optional + """ + super().__init__(**kwargs) + self.id = id + self.display_name = display_name + self.namespace = namespace + self.key = key + self.levels = levels diff --git a/box_sdk_gen/schemas/metadata_taxonomy_ancestor.py b/box_sdk_gen/schemas/metadata_taxonomy_ancestor.py new file mode 100644 index 000000000..b781c0d5e --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomy_ancestor.py @@ -0,0 +1,39 @@ +from typing import Optional + +from typing import Dict + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomyAncestor(BaseObject): + _fields_to_json_mapping: Dict[str, str] = { + 'display_name': 'displayName', + **BaseObject._fields_to_json_mapping, + } + _json_to_fields_mapping: Dict[str, str] = { + 'displayName': 'display_name', + **BaseObject._json_to_fields_mapping, + } + + def __init__( + self, + *, + id: Optional[str] = None, + display_name: Optional[str] = None, + level: Optional[int] = None, + **kwargs + ): + """ + :param id: A unique identifier of the metadata taxonomy node., defaults to None + :type id: Optional[str], optional + :param display_name: The display name of the metadata taxonomy node., defaults to None + :type display_name: Optional[str], optional + :param level: An index of the level to which the node belongs., defaults to None + :type level: Optional[int], optional + """ + super().__init__(**kwargs) + self.id = id + self.display_name = display_name + self.level = level diff --git a/box_sdk_gen/schemas/metadata_taxonomy_level.py b/box_sdk_gen/schemas/metadata_taxonomy_level.py new file mode 100644 index 000000000..91f2d7f18 --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomy_level.py @@ -0,0 +1,39 @@ +from typing import Optional + +from typing import Dict + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomyLevel(BaseObject): + _fields_to_json_mapping: Dict[str, str] = { + 'display_name': 'displayName', + **BaseObject._fields_to_json_mapping, + } + _json_to_fields_mapping: Dict[str, str] = { + 'displayName': 'display_name', + **BaseObject._json_to_fields_mapping, + } + + def __init__( + self, + *, + display_name: Optional[str] = None, + description: Optional[str] = None, + level: Optional[int] = None, + **kwargs + ): + """ + :param display_name: The display name of the level as it is shown to the user., defaults to None + :type display_name: Optional[str], optional + :param description: A description of the level., defaults to None + :type description: Optional[str], optional + :param level: An index of the level within the taxonomy. Levels are indexed starting from 1., defaults to None + :type level: Optional[int], optional + """ + super().__init__(**kwargs) + self.display_name = display_name + self.description = description + self.level = level diff --git a/box_sdk_gen/schemas/metadata_taxonomy_levels.py b/box_sdk_gen/schemas/metadata_taxonomy_levels.py new file mode 100644 index 000000000..e2582a8d1 --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomy_levels.py @@ -0,0 +1,21 @@ +from typing import Optional + +from typing import List + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.schemas.metadata_taxonomy_level import MetadataTaxonomyLevel + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomyLevels(BaseObject): + def __init__( + self, *, entries: Optional[List[MetadataTaxonomyLevel]] = None, **kwargs + ): + """ + :param entries: An array of all taxonomy levels., defaults to None + :type entries: Optional[List[MetadataTaxonomyLevel]], optional + """ + super().__init__(**kwargs) + self.entries = entries diff --git a/box_sdk_gen/schemas/metadata_taxonomy_node.py b/box_sdk_gen/schemas/metadata_taxonomy_node.py new file mode 100644 index 000000000..eabe4c15a --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomy_node.py @@ -0,0 +1,61 @@ +from typing import Optional + +from typing import List + +from typing import Dict + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.schemas.metadata_taxonomy_ancestor import MetadataTaxonomyAncestor + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomyNode(BaseObject): + _fields_to_json_mapping: Dict[str, str] = { + 'display_name': 'displayName', + 'parent_id': 'parentId', + 'node_path': 'nodePath', + **BaseObject._fields_to_json_mapping, + } + _json_to_fields_mapping: Dict[str, str] = { + 'displayName': 'display_name', + 'parentId': 'parent_id', + 'nodePath': 'node_path', + **BaseObject._json_to_fields_mapping, + } + + def __init__( + self, + id: str, + display_name: str, + level: int, + *, + parent_id: Optional[str] = None, + node_path: Optional[List[str]] = None, + ancestors: Optional[List[MetadataTaxonomyAncestor]] = None, + **kwargs + ): + """ + :param id: A unique identifier of the metadata taxonomy node. + :type id: str + :param display_name: The display name of the metadata taxonomy node. + :type display_name: str + :param level: An index of the level to which the node belongs. + :type level: int + :param parent_id: The identifier of the parent node., defaults to None + :type parent_id: Optional[str], optional + :param node_path: An array of identifiers for all ancestor nodes. + Not returned for root-level nodes., defaults to None + :type node_path: Optional[List[str]], optional + :param ancestors: An array of objects for all ancestor nodes. + Not returned for root-level nodes., defaults to None + :type ancestors: Optional[List[MetadataTaxonomyAncestor]], optional + """ + super().__init__(**kwargs) + self.id = id + self.display_name = display_name + self.level = level + self.parent_id = parent_id + self.node_path = node_path + self.ancestors = ancestors diff --git a/box_sdk_gen/schemas/metadata_taxonomy_nodes.py b/box_sdk_gen/schemas/metadata_taxonomy_nodes.py new file mode 100644 index 000000000..d678d0925 --- /dev/null +++ b/box_sdk_gen/schemas/metadata_taxonomy_nodes.py @@ -0,0 +1,38 @@ +from typing import Optional + +from typing import List + +from box_sdk_gen.internal.base_object import BaseObject + +from box_sdk_gen.schemas.metadata_taxonomy_node import MetadataTaxonomyNode + +from box_sdk_gen.box.errors import BoxSDKError + + +class MetadataTaxonomyNodes(BaseObject): + def __init__( + self, + *, + limit: Optional[int] = None, + next_marker: Optional[str] = None, + prev_marker: Optional[str] = None, + entries: Optional[List[MetadataTaxonomyNode]] = None, + **kwargs + ): + """ + :param limit: The limit that was used for these entries. This will be the same as the + `limit` query parameter unless that value exceeded the maximum value + allowed. The maximum value varies by API., defaults to None + :type limit: Optional[int], optional + :param next_marker: The marker for the start of the next page of results., defaults to None + :type next_marker: Optional[str], optional + :param prev_marker: The marker for the start of the previous page of results., defaults to None + :type prev_marker: Optional[str], optional + :param entries: A list of metadata taxonomy nodes., defaults to None + :type entries: Optional[List[MetadataTaxonomyNode]], optional + """ + super().__init__(**kwargs) + self.limit = limit + self.next_marker = next_marker + self.prev_marker = prev_marker + self.entries = entries diff --git a/docs/README.md b/docs/README.md index 5e353d405..61d2c712a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,6 +49,7 @@ the SDK are available by topic: - [List collaborations](list_collaborations.md) - [Memberships](memberships.md) - [Metadata cascade policies](metadata_cascade_policies.md) +- [Metadata taxonomies](metadata_taxonomies.md) - [Metadata templates](metadata_templates.md) - [Recent items](recent_items.md) - [Retention policies](retention_policies.md) diff --git a/docs/authentication.md b/docs/authentication.md index cbe78f305..115db3994 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -60,9 +60,11 @@ print(f"My user ID is {me.id}") Authenticating with a JWT requires some extra dependencies. To get them, use ``` -pip install "box-sdk-gen[jwt]" +pip install "boxsdk[jwt]" ``` +You may need to specify a version to install. + Before using JWT Auth make sure you set up correctly your Box platform app. The guide with all required steps can be found here: [Setup with JWT][jwt_guide] diff --git a/docs/file_metadata.md b/docs/file_metadata.md index 5f611f001..3d1a48cd6 100644 --- a/docs/file_metadata.md +++ b/docs/file_metadata.md @@ -25,6 +25,8 @@ client.file_metadata.get_file_metadata(file.id) - file_id `str` - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345" +- view `Optional[str]` + - Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter. - extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. @@ -63,6 +65,8 @@ client.file_metadata.get_file_metadata_by_id( - The scope of the metadata template. Example: "global" - template_key `str` - The name of the metadata template. Example: "properties" +- view `Optional[str]` + - Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter. - extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. diff --git a/docs/folder_metadata.md b/docs/folder_metadata.md index 0f6b729cb..b3d5e63fc 100644 --- a/docs/folder_metadata.md +++ b/docs/folder_metadata.md @@ -26,6 +26,8 @@ client.folder_metadata.get_folder_metadata(folder.id) - folder_id `str` - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folder/123` the `folder_id` is `123`. The root folder of a Box account is always represented by the ID `0`. Example: "12345" +- view `Optional[str]` + - Taxonomy field values are returned in `API view` by default, meaning the value is represented with a taxonomy node identifier. To retrieve the `Hydrated view`, where taxonomy values are represented with the full taxonomy node information, set this parameter to `hydrated`. This is the only supported value for this parameter. - extra_headers `Optional[Dict[str, Optional[str]]]` - Extra headers that will be included in the HTTP request. diff --git a/docs/metadata_taxonomies.md b/docs/metadata_taxonomies.md new file mode 100644 index 000000000..9c03b697e --- /dev/null +++ b/docs/metadata_taxonomies.md @@ -0,0 +1,482 @@ +# MetadataTaxonomiesManager + +- [Create metadata taxonomy](#create-metadata-taxonomy) +- [Get metadata taxonomies for namespace](#get-metadata-taxonomies-for-namespace) +- [Get metadata taxonomy by taxonomy key](#get-metadata-taxonomy-by-taxonomy-key) +- [Update metadata taxonomy](#update-metadata-taxonomy) +- [Remove metadata taxonomy](#remove-metadata-taxonomy) +- [Create metadata taxonomy levels](#create-metadata-taxonomy-levels) +- [Update metadata taxonomy level](#update-metadata-taxonomy-level) +- [Add metadata taxonomy level](#add-metadata-taxonomy-level) +- [Delete metadata taxonomy level](#delete-metadata-taxonomy-level) +- [List metadata taxonomy nodes](#list-metadata-taxonomy-nodes) +- [Create metadata taxonomy node](#create-metadata-taxonomy-node) +- [Get metadata taxonomy node by ID](#get-metadata-taxonomy-node-by-id) +- [Update metadata taxonomy node](#update-metadata-taxonomy-node) +- [Remove metadata taxonomy node](#remove-metadata-taxonomy-node) +- [List metadata template's options for taxonomy field](#list-metadata-templates-options-for-taxonomy-field) + +## Create metadata taxonomy + +Creates a new metadata taxonomy that can be used in +metadata templates. + +This operation is performed by calling function `create_metadata_taxonomy`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-metadata-taxonomies/). + +_Currently we don't have an example for calling `create_metadata_taxonomy` in integration tests_ + +### Arguments + +- key `Optional[str]` + - The taxonomy key. If it is not provided in the request body, it will be generated from the `displayName`. The `displayName` would be converted to lower case, and all spaces and non-alphanumeric characters replaced with underscores. +- display_name `str` + - The display name of the taxonomy. +- namespace `str` + - The namespace of the metadata taxonomy to create. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomy`. + +The schema representing the metadata taxonomy created. + +## Get metadata taxonomies for namespace + +Used to retrieve all metadata taxonomies in a namespace. + +This operation is performed by calling function `get_metadata_taxonomies`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/get-metadata-taxonomies-id/). + +_Currently we don't have an example for calling `get_metadata_taxonomies` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- marker `Optional[str]` + - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. +- limit `Optional[int]` + - The maximum number of items to return per page. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomies`. + +Returns all of the metadata taxonomies within a namespace +and their corresponding schema. + +## Get metadata taxonomy by taxonomy key + +Used to retrieve a metadata taxonomy by taxonomy key. + +This operation is performed by calling function `get_metadata_taxonomy_by_key`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/get-metadata-taxonomies-id-id/). + +_Currently we don't have an example for calling `get_metadata_taxonomy_by_key` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomy`. + +Returns the metadata taxonomy identified by the taxonomy key. + +## Update metadata taxonomy + +Updates an existing metadata taxonomy. + +This operation is performed by calling function `update_metadata_taxonomy`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/patch-metadata-taxonomies-id-id/). + +_Currently we don't have an example for calling `update_metadata_taxonomy` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- display_name `str` + - The display name of the taxonomy. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomy`. + +The schema representing the updated metadata taxonomy. + +## Remove metadata taxonomy + +Delete a metadata taxonomy. +This deletion is permanent and cannot be reverted. + +This operation is performed by calling function `delete_metadata_taxonomy`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/delete-metadata-taxonomies-id-id/). + +_Currently we don't have an example for calling `delete_metadata_taxonomy` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `None`. + +Returns an empty response when the metadata taxonomy is successfully deleted. + +## Create metadata taxonomy levels + +Creates new metadata taxonomy levels. + +This operation is performed by calling function `create_metadata_taxonomy_level`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-metadata-taxonomies-id-id-levels/). + +_Currently we don't have an example for calling `create_metadata_taxonomy_level` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- request_body `List[MetadataTaxonomyLevel]` + - Request body of createMetadataTaxonomyLevel method +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyLevels`. + +Returns an array of all taxonomy levels. + +## Update metadata taxonomy level + +Updates an existing metadata taxonomy level. + +This operation is performed by calling function `patch_metadata_taxonomies_id_id_levels_id`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/patch-metadata-taxonomies-id-id-levels-id/). + +_Currently we don't have an example for calling `patch_metadata_taxonomies_id_id_levels_id` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- level_index `int` + - The index of the metadata taxonomy level. Example: 1 +- display_name `str` + - The display name of the taxonomy level. +- description `Optional[str]` + - The description of the taxonomy level. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyLevel`. + +The updated taxonomy level. + +## Add metadata taxonomy level + +Creates a new metadata taxonomy level and appends it to the existing levels. +If there are no levels defined yet, this will create the first level. + +This operation is performed by calling function `add_metadata_taxonomy_level`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-metadata-taxonomies-id-id-levels:append/). + +_Currently we don't have an example for calling `add_metadata_taxonomy_level` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- display_name `str` + - The display name of the taxonomy level. +- description `Optional[str]` + - The description of the taxonomy level. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyLevels`. + +Returns an array of all taxonomy levels. + +## Delete metadata taxonomy level + +Deletes the last level of the metadata taxonomy. + +This operation is performed by calling function `delete_metadata_taxonomy_level`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-metadata-taxonomies-id-id-levels:trim/). + +_Currently we don't have an example for calling `delete_metadata_taxonomy_level` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyLevels`. + +Returns an array of all taxonomy levels. + +## List metadata taxonomy nodes + +Used to retrieve metadata taxonomy nodes based on the parameters specified. +Results are sorted in lexicographic order unless a `query` parameter is passed. +With a `query` parameter specified, results are sorted in order of relevance. + +This operation is performed by calling function `get_metadata_taxonomy_nodes`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/get-metadata-taxonomies-id-id-nodes/). + +_Currently we don't have an example for calling `get_metadata_taxonomy_nodes` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- level `Optional[List[int]]` + - Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values. +- parent `Optional[List[str]]` + - Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values. +- ancestor `Optional[List[str]]` + - Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values. +- query `Optional[str]` + - Query text to search for the taxonomy nodes. +- include_total_result_count `Optional[bool]` + - When set to `true` this provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to `false`. +- marker `Optional[str]` + - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. +- limit `Optional[int]` + - The maximum number of items to return per page. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyNodes`. + +Returns a list of the taxonomy nodes that match the specified parameters. + +## Create metadata taxonomy node + +Creates a new metadata taxonomy node. + +This operation is performed by calling function `create_metadata_taxonomy_node`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/post-metadata-taxonomies-id-id-nodes/). + +_Currently we don't have an example for calling `create_metadata_taxonomy_node` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- display_name `str` + - The display name of the taxonomy node. +- level `int` + - The level of the taxonomy node. +- parent_id `Optional[str]` + - The identifier of the parent taxonomy node. Omit this field for root-level nodes. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyNode`. + +The schema representing the taxonomy node created. + +## Get metadata taxonomy node by ID + +Retrieves a metadata taxonomy node by its identifier. + +This operation is performed by calling function `get_metadata_taxonomy_node_by_id`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/get-metadata-taxonomies-id-id-nodes-id/). + +_Currently we don't have an example for calling `get_metadata_taxonomy_node_by_id` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- node_id `str` + - The identifier of the metadata taxonomy node. Example: "14d3d433-c77f-49c5-b146-9dea370f6e32" +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyNode`. + +Returns the metadata taxonomy node that matches the identifier. + +## Update metadata taxonomy node + +Updates an existing metadata taxonomy node. + +This operation is performed by calling function `update_metadata_taxonomy_node`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/patch-metadata-taxonomies-id-id-nodes-id/). + +_Currently we don't have an example for calling `update_metadata_taxonomy_node` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- node_id `str` + - The identifier of the metadata taxonomy node. Example: "14d3d433-c77f-49c5-b146-9dea370f6e32" +- display_name `Optional[str]` + - The display name of the taxonomy node. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyNode`. + +The schema representing the updated taxonomy node. + +## Remove metadata taxonomy node + +Delete a metadata taxonomy node. +This deletion is permanent and cannot be reverted. +Only metadata taxonomy nodes without any children can be deleted. + +This operation is performed by calling function `delete_metadata_taxonomy_node`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/delete-metadata-taxonomies-id-id-nodes-id/). + +_Currently we don't have an example for calling `delete_metadata_taxonomy_node` in integration tests_ + +### Arguments + +- namespace `str` + - The namespace of the metadata taxonomy. Example: "enterprise_123456" +- taxonomy_key `str` + - The key of the metadata taxonomy. Example: "geography" +- node_id `str` + - The identifier of the metadata taxonomy node. Example: "14d3d433-c77f-49c5-b146-9dea370f6e32" +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `None`. + +Returns an empty response when the metadata taxonomy node is successfully deleted. + +## List metadata template's options for taxonomy field + +Used to retrieve metadata taxonomy nodes which are available for the taxonomy field based +on its configuration and the parameters specified. +Results are sorted in lexicographic order unless a `query` parameter is passed. +With a `query` parameter specified, results are sorted in order of relevance. + +This operation is performed by calling function `get_metadata_template_field_options`. + +See the endpoint docs at +[API Reference](https://developer.box.com/reference/get-metadata-templates-id-id-fields-id-options/). + +_Currently we don't have an example for calling `get_metadata_template_field_options` in integration tests_ + +### Arguments + +- scope `GetMetadataTemplateFieldOptionsScope` + - The scope of the metadata template. Example: "global" +- template_key `str` + - The name of the metadata template. Example: "properties" +- field_key `str` + - The key of the metadata taxonomy field in the template. Example: "geography" +- level `Optional[List[int]]` + - Filters results by taxonomy level. Multiple values can be provided. Results include nodes that match any of the specified values. +- parent `Optional[List[str]]` + - Node identifier of a direct parent node. Multiple values can be provided. Results include nodes that match any of the specified values. +- ancestor `Optional[List[str]]` + - Node identifier of any ancestor node. Multiple values can be provided. Results include nodes that match any of the specified values. +- query `Optional[str]` + - Query text to search for the taxonomy nodes. +- include_total_result_count `Optional[bool]` + - When set to `true` this provides the total number of nodes that matched the query. The response will compute counts of up to 10,000 elements. Defaults to `false`. +- only_selectable_options `Optional[bool]` + - When set to `true`, this only returns valid selectable options for this template taxonomy field. Otherwise, it returns all taxonomy nodes, whether or not they are selectable. Defaults to `true`. +- marker `Optional[str]` + - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`. +- limit `Optional[int]` + - The maximum number of items to return per page. +- extra_headers `Optional[Dict[str, Optional[str]]]` + - Extra headers that will be included in the HTTP request. + +### Returns + +This function returns a value of type `MetadataTaxonomyNodes`. + +Returns a list of the taxonomy nodes that match the specified parameters.