Source code for tdw_catalog.metadata_template.update_builder
from datetime import date, datetime
from typing import List, Optional
from tdw_catalog.errors import CatalogInvalidArgumentException, CatalogNotFoundException
from tdw_catalog.team import Team
import tdw_catalog.metadata_template as metadata_template
import tdw_catalog.metadata_template.creation_builder as creation_builder
import tdw_catalog.metadata_template.field as field
from tdw_catalog.metadata_template.field import T
from tdw_catalog.organization_member import OrganizationMember
# Avoid circular import caused by type-checking
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from tdw_catalog import Catalog
import tdw_catalog.dataset as dataset
[docs]class MetadataTemplateUpdateBuilder():
"""
A :class:`.MetadataTemplateUpdateBuilder` assists with the alteration and updating of :class:`.MetadataTemplate`\\ s
"""
_innerFactory: 'creation_builder.MetadataTemplateCreationBuilder'
def __init__(self, client: 'Catalog',
template: 'metadata_template.MetadataTemplate') -> None:
"""
Initializes :class:`.MetadataTemplateUpdateBuilder` which assists with the alteration and updating of :class:`.MetadataTemplate`\\ s
Parameters
----------
client : Catalog
RPC client, used to communicate with the Data :class:`.Catalog` server
organization_id : str
The unique ID of the :class:`.Organization` to which the :class:`.MetadataTemplate` belongs
template : MetadataTemplate
The :class:`.MetadataTemplate` being altered
"""
self._innerFactory = creation_builder.MetadataTemplateCreationBuilder(
client, template)
@property
def title(self):
return self._innerFactory.title
@title.setter
def title(self, value: Optional[str]):
self._innerFactory.title = value
@property
def description(self):
return self._innerFactory.description
@description.setter
def description(self, value: Optional[str]):
self._innerFactory.description = value
[docs] def add_text_field(self,
key: str,
default_value: Optional[str],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Any additional text-based information you want to add to a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for the this field
default_value : Optional[str]
An optional default `str` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.text_field(key, default_value, optional)
return self
[docs] def add_attachment_field(self,
key: str,
optional=False
) -> 'MetadataTemplateUpdateBuilder':
"""
Attach any metadata files directly to a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.attachment_field(key, optional)
return self
[docs] def add_linked_dataset_field(
self,
key: str,
default_value: 'Optional[dataset.Dataset]',
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Connect `:class:`.Dataset`\\ s together to indicate a semantic relation and/or increase discoverability
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[Dataset]
An optional object representing a :class:`.Dataset` that has been semantically linked to this :class:`.MetadataTemplate`
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.linked_dataset_field(key, default_value, optional)
return self
[docs] def add_link_field(self,
key: str,
default_value: Optional[str],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Any links, urls, or websites associated with a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[str]
An optional default `str` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.link_field(key, default_value, optional)
return self
[docs] def add_list_field(self,
key: str,
default_value: Optional[str],
allow_any: Optional[bool],
list_items: Optional[List[str]],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
A preconfigured set of options where one of the options may be applied to a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[str]
An optional default `str` value for this field. Must correspond to a value within `list_items` unless `allow_any == True`
allow_any : Optional[bool]
An optional boolean switch to determine if values not in the list can be entered
list_items : Optional[List[str]]
An optional list of values from which a user may choose a value
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.list_field(key, default_value, allow_any,
list_items, optional)
return self
[docs] def add_organization_member_field(
self,
key: str,
default_value: Optional[OrganizationMember],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Someone who is associated with a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[OrganizationMember]
An optional default :class:`.OrganizationMember` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.organization_member_field(key, default_value,
optional)
return self
[docs] def add_organization_team_field(
self,
key: str,
default_value: Optional[Team],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
A :class:`.Team` who is associated with a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[Team]
An optional default :class:`.Team` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.organization_team_field(key, default_value,
optional)
return self
[docs] def add_date_field(self,
key: str,
default_value: Optional[date],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Add dates to a :class:`.Dataset` to keep track of timelines or events
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[date]
An optional default `date` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.date_field(key, default_value, optional)
return self
[docs] def add_point_in_time_field(
self,
key: str,
default_value: Optional[datetime],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
A specific time and date associated with a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[datetime]
An optional default `datetime` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.point_in_time_field(key, default_value, optional)
return self
[docs] def add_number_field(self,
key: str,
default_value: Optional[int],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Track numbers associated with a :class:`.Dataset`, like total number of allowed :class:`.User`\\ s
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[int]
An optional default `int` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.number_field(key, default_value, optional)
return self
[docs] def add_currency_field(self,
key: str,
currency: Optional[str],
amount: Optional[float],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
A field for currency values
Parameters
----------
key : str
An identifying key for this field
currency : Optional[str]
An optional three character string representation for this currency type (e.g. USD)
amount: Optional[float]
An optional fractional amount of currency for this currency field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.currency_field(key, currency, amount, optional)
return self
[docs] def add_decimal_field(self,
key: str,
default_value: Optional[float],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
A field for confidence values or other fractional information
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[float]
An optional default `float` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.decimal_field(key, default_value, optional)
return self
[docs] def add_alias_field(self,
key: str,
default_value: Optional[str],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
An alternative unique identifier for this :class:`.Dataset`\\ , for integrating with external systems
Parameters
----------
key : str
An identifying key for the this field
default_value : Optional[str]
An optional default `str` value for this field
Returns
-------
MetadataTemplaceUpdateFactory
Returns this builder for further template modification
"""
self._innerFactory.alias_field(key, default_value, optional)
return self
[docs] def add_data_cost_recommended_field(
self,
currency: Optional[str],
amount: Optional[float],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Track and report on a :class:`.Dataset` license cost. The key of this field will automatically be set
Parameters
----------
currency : Optional[str]
An optional three character string representation for this currency type (e.g. USD)
amount: Optional[float]
An optional fractional amount of currency for this currency field
Returns
-------
MetadataTemplateUpdateBuilder
Returns this builder for further template modification
"""
self._innerFactory.data_cost_recommended_field(currency,
amount,
optional,
key="cost__0")
return self
[docs] def add_point_of_contact_recommended_field(
self,
default_value: Optional[OrganizationMember],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Primary person who manages the :class:`.Dataset` license. The key of this field will automatically be set
Parameters
----------
default_value: Optional[OrganizationMember]
An optional :class:`.OrganizationMember` object representing a member of this :class:`.Organization`
Returns
-------
MetadataTemplateUpdateBuilder
Returns this builder for further template modification
"""
self._innerFactory.point_of_contact_recommended_field(default_value,
optional,
key="poc__0")
return self
[docs] def add_license_expiry_recommended_field(
self,
default_value: Optional[date],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Monitor :class:`.Dataset` license term limits. The key of this field will automatically be set
Parameters
----------
default_value : Optional[date]
An optional `date` value that this field represents
Returns
-------
MetadataTemplateUpdateBuilder
Returns this builder for further template modification
"""
self._innerFactory.license_expiry_recommended_field(
default_value, optional, key="expiryDate__0")
return self
[docs] def add_contract_owner_recommended_field(
self,
default_value: Optional[Team],
optional=False) -> 'MetadataTemplateUpdateBuilder':
"""
Team or department that owns the :class:`.Dataset` license. The key of this field will automatically be set
Parameters
----------
default_value : Optional[Team]
An optional :class:`.Team` object representing a team in this :class:`.Organization`
Returns
-------
MetadataTemplateUpdateBuilder
Returns this builder for further template modification
"""
self._innerFactory.contract_owner_recommended_field(
default_value, optional, key="contractOwner__0")
return self
[docs] def get_field(
self,
key: str,
cls: 'field.MetadataTemplateField[T]' = None
) -> 'field.MetadataTemplateField[T]':
"""
Get a specific field belonging to this :class:`.MetadataTemplate`. The field's properties can then be changed directly
Parameters
----------
key : str
The key of the desired field
Returns
---------
MetadataTemplateField[T]
The specificed field whose key matches the provided key
Raises
------
CatalogNotFoundException
If no :class:`.MetadataTemplateField` with a matching key can be found
"""
f = next((field
for field in self._innerFactory._metadata_template.fields
if field.key == key), None)
if f is None:
raise CatalogNotFoundException(
message="No field with that key was found on this template")
return f
[docs] def remove_field(self, key: str) -> 'MetadataTemplateUpdateBuilder':
"""
Remove a field from the fields_list of this :class:`.MetadataTemplate`. Changes will not persist unless the template is saved
Parameters
----------
key : str
The key of the field to be removed
"""
self._innerFactory._metadata_template.fields = list(
filter(lambda field: field["key"] != key,
self._innerFactory._metadata_template.fields))
return self
[docs] def keys(self) -> List[str]:
"""
Return a list of keys for each field in this :class:`.MetadataTemplate`\\ 's fields list
Parameters
----------
None
Returns
--------
List[str]
A list of strings representing the keys for each :class:`.MetadataTemplateField` in the :class:`.MetadataTemplate`
"""
return list(
map(lambda field: field["key"],
self._innerFactory._metadata_template.fields))
[docs] def list_fields(self) -> 'List[field.MetadataTemplateField]':
"""
Return a list of all the fields currently attached to this :class:`.MetadataTemplate`
Parameters
----------
None
Returns
-------
List[field.MetadataTemplateField]
The list of fields on the :class:`.MetadataTemplate` being updated
"""
return self._innerFactory._metadata_template.fields
[docs] def reorder(
self, fields: 'List[field.MetadataTemplateField]'
) -> 'MetadataTemplateUpdateBuilder':
"""
Reorder the fields list of this :class:`.MetadataTemplate`
Parameters
----------
fields : List[MetadataTemplateField]
The newly ordered list of :class:`.MetadataTemplateField`\\ s to replace the old list on this :class:`.MetadataTemplate`. Must contain the same fields as the original list, with the only allowed change being the list's order
Raises
------
CatalogInvalidArgumentException
If the user supplied fields list contains a field with a key that does not exist on this :class:`.MetadataTemplate`, the number of fields in the list provided does not match the number of fields on the :class:`.MetadataTemplate`, or if a provided field matches the key of a field on the :class:`.MetadataTemplate` but is of a different type
"""
if len(self._innerFactory._metadata_template.fields) != len(fields):
raise CatalogInvalidArgumentException(
message=
"The number of fields provided must equal the number of fields on the MetadataTemplate"
)
if set(fields).issubset(
self._innerFactory._metadata_template.fields) == False:
raise CatalogInvalidArgumentException(
message=
"One or more of the fields provided does not match the original fields list of this MetadataTemplate"
)
keys = self.keys()
for f in fields:
if f.key not in keys:
raise CatalogInvalidArgumentException(
message=
f"No field with key {f.key} exists on this MetadataTemplate"
)
self._innerFactory._metadata_template.fields = fields
return self
[docs] def save(self) -> 'metadata_template.MetadataTemplate':
"""
Save the :class:`.MetadataTemplate` under construction inside this :class:`.MetadataTemplateUpdateBuilder`
Parameters
----------
None
Returns
-------
MetadataTemplate
The updated :class:`.MetadataTemplate` with any alterations made to its title, description, or fields list
"""
return self._innerFactory._metadata_template.save()