Source code for tdw_catalog.metadata_template.creation_builder
from datetime import date, datetime
from typing import List, Optional
from tdw_catalog import Catalog
from tdw_catalog.errors import CatalogFailedPreconditionException, _convert_error
from tdw_catalog.team import Team
import tdw_catalog.metadata_template as metadata_template
import tdw_catalog.metadata_template.contract_owner as contract_owner
import tdw_catalog.metadata_template.data_cost as data_cost
import tdw_catalog.metadata_template.license_expiry as license_expiry
import tdw_catalog.metadata_template.point_of_contact as point_of_contact
from tdw_catalog.organization_member import OrganizationMember
# Avoid circular import caused by type-checking
from typing import TYPE_CHECKING
if TYPE_CHECKING:
import tdw_catalog.dataset as dataset
[docs]class MetadataTemplateCreationBuilder:
"""
A :class:`.MetadataTemplateCreationBuilder` assists with the creation of :class:`.MetadataTemplate`\\ s
"""
_client: 'Catalog'
_metadata_template: 'metadata_template.MetadataTemplate'
def __init__(self, client: 'Catalog',
template: 'metadata_template.MetadataTemplate') -> None:
"""
Initializes :class:`.MetadataTemplateCreationBuilder` which assists with the creation of :class:`.MetadataTemplate`\\ s
Parameters
----------
client : Catalog
RPC client, used to communicate with the Data :class:`.Catalog` server
template : MetadataTemplate
The :class:`.MetadataTemplate` being built
"""
self._client = client
self._metadata_template = template
@property
def title(self):
return self._metadata_template.title
@title.setter
def title(self, value: Optional[str]):
self._metadata_template.title = value
@property
def description(self):
return self._metadata_template.description
@description.setter
def description(self, value: Optional[str]):
self._metadata_template.description = value
[docs] def text_field(self,
key: str,
default_value: Optional[str] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.text as text
field = text.Field(key=key,
default_value=default_value,
optional=optional)
self._metadata_template.fields.append(field)
return self
[docs] def attachment_field(self,
key: str,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
Attach any metadata files directly to a :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
Returns
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.attachment as attachment
field = attachment.Field(key=key, optional=optional)
self._metadata_template.fields.append(field)
return self
[docs] def linked_dataset_field(
self,
key: str,
default_value: 'Optional[dataset.Dataset]' = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
Associate :class:`.Dataset`\\ s with one another to indicate a semantic relation and/or increase discoverability.
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[Dataset]
An optional default :class:`.Dataset` value for this field
Returns
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.linked_dataset as linked_dataset
field = linked_dataset.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def link_field(self,
key: str,
default_value: Optional[str] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.link as link
field = link.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def list_field(self,
key: str,
default_value: Optional[str] = None,
allow_any: Optional[bool] = True,
list_items: Optional[List[str]] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.list_field as list_field
field = list_field.Field(
key=key,
default_value=default_value,
allow_any=allow_any,
list_items=list_items,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def organization_member_field(
self,
key: str,
default_value: Optional[OrganizationMember] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.organization_member as organization_member
field = organization_member.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def organization_team_field(
self,
key: str,
default_value: Optional[Team] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
A :class:`.Team` who is associated with the :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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.organization_team as organization_team
field = organization_team.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def date_field(self,
key: str,
default_value: Optional[date] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.date_field as date_field
field = date_field.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def point_in_time_field(
self,
key: str,
default_value: Optional[datetime] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
A specific time and date associated with the :class:`.Dataset`
Parameters
----------
key : str
An identifying key for this field
default_value : Optional[datetime]
An optional default `datetime` value for this field
Returns
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.point_in_time as point_in_time
field = point_in_time.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def number_field(self,
key: str,
default_value: Optional[int] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
Track numbers associated with the :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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.number as number
field = number.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def currency_field(self,
key: str,
currency: Optional[str] = None,
amount: Optional[float] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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 default fractional amount of currency for this currency field
Returns
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.currency as template_currency
field = template_currency.Field(key=key,
optional=optional,
currency=currency,
amount=amount)
self._metadata_template.fields.append(field)
return self
[docs] def decimal_field(self,
key: str,
default_value: Optional[float] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.decimal as decimal
field = decimal.Field(
key=key,
default_value=default_value,
optional=optional,
)
self._metadata_template.fields.append(field)
return self
[docs] def alias_field(self,
key: str,
default_value: Optional[str] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.alias as alias
field = alias.Field(key=key,
default_value=default_value,
optional=optional)
self._metadata_template.fields.append(field)
return self
[docs] def data_cost_recommended_field(
self,
currency: Optional[str] = None,
amount: Optional[float] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
Track and report on the :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 default fractional amount of currency for this currency field
Returns
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.data_cost as data_cost
for field in self._metadata_template.fields:
if isinstance(field, data_cost.Field):
raise CatalogFailedPreconditionException(
message=
"Only one contract owner recommended field may be applied per template"
)
field = data_cost.Field(key="cost__0",
optional=optional,
amount=amount,
currency=currency)
self._metadata_template.fields.append(field)
return self
[docs] def point_of_contact_recommended_field(
self,
default_value: Optional[OrganizationMember] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.point_of_contact as point_of_contact
for field in self._metadata_template.fields:
if isinstance(field, point_of_contact.Field):
raise CatalogFailedPreconditionException(
message=
"Only one contract owner recommended field may be applied per template"
)
field = point_of_contact.Field(key="poc__0",
default_value=default_value,
optional=optional)
self._metadata_template.fields.append(field)
return self
[docs] def license_expiry_recommended_field(
self,
default_value: Optional[date] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
import tdw_catalog.metadata_template.license_expiry as license_expiry
for field in self._metadata_template.fields:
if isinstance(field, license_expiry.Field):
raise CatalogFailedPreconditionException(
message=
"Only one contract owner recommended field may be applied per template"
)
field = license_expiry.Field(key="expiryDate__0",
default_value=default_value,
optional=optional)
self._metadata_template.fields.append(field)
return self
[docs] def contract_owner_recommended_field(
self,
default_value: Optional[Team] = None,
optional=False) -> 'MetadataTemplateCreationBuilder':
"""
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
-------
MetadataTemplateCreationBuilder
Returns this builder for further field creation
"""
for field in self._metadata_template.fields:
if isinstance(field, contract_owner.Field):
raise CatalogFailedPreconditionException(
message=
"Only one contract owner recommended field may be applied per template"
)
field = contract_owner.Field(key="contractOwner__0",
default_value=default_value,
optional=optional)
self._metadata_template.fields.append(field)
return self
[docs] def save(self) -> 'metadata_template.MetadataTemplate':
"""
Persist this new :class:`.MetadataTemplate`, saving any changes to its name, description or fields list
Parameters
----------
None
Returns
-------
An updated :class:`.MetadataTemplate` with persisted changes
Raises
------
CatalogPermissionDeniedException
If the caller is not allowed to update this :class:`.MetadataTemplate`
CatalogNotFoundException
If a :class:`.MetadataTemplate` with this id does not exist
CatalogMalformedException
If the :class:`.MetadataTemplate` name or fields is empty
CatalogAlreadyExistsException
If a :class:`.MetadataTemplate` already exists with the same name
CatalogException
If call to the :class:`.Catalog` server fails
"""
try:
res = self._client._create_field_template(
template=self._metadata_template.serialize())
return metadata_template.MetadataTemplate(client=self._client,
**res)
except Exception as e:
raise _convert_error(e)