azure/aria/aria-extension-cloudify/src/aria/extensions/aria_extension_tosca/simple_v1_0/definitions.py

   1 # Licensed to the Apache Software Foundation (ASF) under one or more
   2 # contributor license agreements.  See the NOTICE file distributed with
   3 # this work for additional information regarding copyright ownership.
   4 # The ASF licenses this file to You under the Apache License, Version 2.0
   5 # (the "License"); you may not use this file except in compliance with
   6 # the License.  You may obtain a copy of the License at
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15
  16 from aria.utils.collections import FrozenDict
  17 from aria.utils.caching import cachedmethod
  18 from aria.parser import implements_specification
  19 from aria.parser.presentation import (has_fields, short_form_field, allow_unknown_fields,
  20                                       primitive_field, primitive_list_field, object_field,
  21                                       object_list_field, object_dict_field,
  22                                       object_dict_unknown_fields, field_validator,
  23                                       field_getter, type_validator, list_type_validator)
  24
  25 from .data_types import Range
  26 from .misc import (Description, ConstraintClause, OperationImplementation, EntrySchema)
  27 from .presentation.extensible import ExtensiblePresentation
  28 from .presentation.field_getters import data_type_class_getter
  29 from .presentation.field_validators import (data_type_validator, data_value_validator,
  30                                             entry_schema_validator)
  31 from .presentation.types import (convert_name_to_full_type_name, get_type_by_name)
  32 from .modeling.data_types import get_data_type, get_property_constraints
  33 from .modeling.interfaces import (get_and_override_input_definitions_from_type,
  34                                   get_and_override_operation_definitions_from_type)
  35
  36
  37 @has_fields
  38 @implements_specification('3.5.8', 'tosca-simple-1.0')
  39 class PropertyDefinition(ExtensiblePresentation):
  40     """
  41     A property definition defines a named, typed value and related data that can be associated with
  42     an entity defined in this specification (e.g., Node Types, Relationship Types, Capability Types,
  43     etc.). Properties are used by template authors to provide input values to TOSCA entities which
  44     indicate their "desired state" when they are instantiated. The value of a property can be
  45     retrieved using the ``get_property`` function within TOSCA Service Templates.
  46
  47     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
  48     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
  49     #DEFN_ELEMENT_PROPERTY_DEFN>`__
  50     """
  51
  52     @field_validator(data_type_validator())
  53     @primitive_field(str, required=True)
  54     def type(self):
  55         """
  56         The required data type for the property.
  57
  58         :type: :obj:`basestring`
  59         """
  60
  61     @object_field(Description)
  62     def description(self):
  63         """
  64         The optional description for the property.
  65
  66         :type: :class:`Description`
  67         """
  68
  69     @primitive_field(bool, default=True)
  70     def required(self):
  71         """
  72         An optional key that declares a property as required (true) or not (false).
  73
  74         :type: bool
  75         """
  76
  77     @field_validator(data_value_validator)
  78     @primitive_field()
  79     def default(self):
  80         """
  81         An optional key that may provide a value to be used as a default if not provided by another
  82         means.
  83
  84         :type: :obj:`basestring`
  85         """
  86
  87     @primitive_field(str, default='supported', allowed=('supported', 'unsupported', 'experimental',
  88                                                         'deprecated'))
  89     @implements_specification(section='3.5.8.3', spec='tosca-simple-1.0')
  90     def status(self):
  91         """
  92         The optional status of the property relative to the specification or implementation.
  93
  94         :type: :obj:`basestring`
  95         """
  96
  97     @object_list_field(ConstraintClause)
  98     def constraints(self):
  99         """
 100         The optional list of sequenced constraint clauses for the property.
 101
 102         :type: list of (str, :class:`ConstraintClause`)
 103         """
 104
 105     @field_validator(entry_schema_validator)
 106     @object_field(EntrySchema)
 107     def entry_schema(self):
 108         """
 109         The optional key that is used to declare the name of the Datatype definition for entries of
 110         set types such as the TOSCA list or map.
 111
 112         :type: :obj:`basestring`
 113         """
 114
 115     @cachedmethod
 116     def _get_type(self, context):
 117         return get_data_type(context, self, 'type')
 118
 119     @cachedmethod
 120     def _get_constraints(self, context):
 121         return get_property_constraints(context, self)
 122
 123
 124 @has_fields
 125 @implements_specification('3.5.10', 'tosca-simple-1.0')
 126 class AttributeDefinition(ExtensiblePresentation):
 127     """
 128     An attribute definition defines a named, typed value that can be associated with an entity
 129     defined in this specification (e.g., a Node, Relationship or Capability Type). Specifically, it
 130     is used to expose the "actual state" of some property of a TOSCA entity after it has been
 131     deployed and instantiated (as set by the TOSCA orchestrator). Attribute values can be retrieved
 132     via the ``get_attribute`` function from the instance model and used as values to other
 133     entities within TOSCA Service Templates.
 134
 135     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
 136     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
 137     #DEFN_ELEMENT_ATTRIBUTE_DEFN>`__
 138     """
 139
 140     @field_validator(data_type_validator())
 141     @primitive_field(str, required=True)
 142     def type(self):
 143         """
 144         The required data type for the attribute.
 145
 146         :type: :obj:`basestring`
 147         """
 148
 149     @object_field(Description)
 150     def description(self):
 151         """
 152         The optional description for the attribute.
 153
 154         :type: :class:`Description`
 155         """
 156
 157     @field_validator(data_value_validator)
 158     @primitive_field()
 159     def default(self):
 160         """
 161         An optional key that may provide a value to be used as a default if not provided by another
 162         means.
 163
 164         This value SHALL be type compatible with the type declared by the property definition's type
 165         keyname.
 166
 167         :type: :obj:`basestring`
 168         """
 169
 170     @primitive_field(str, default='supported', allowed=('supported', 'unsupported', 'experimental',
 171                                                         'deprecated'))
 172     def status(self):
 173         """
 174         The optional status of the attribute relative to the specification or implementation.
 175
 176         :type: :obj:`basestring`
 177         """
 178
 179     @field_validator(entry_schema_validator)
 180     @object_field(EntrySchema)
 181     def entry_schema(self):
 182         """
 183         The optional key that is used to declare the name of the Datatype definition for entries of
 184         set types such as the TOSCA list or map.
 185
 186         :type: :obj:`basestring`
 187         """
 188
 189     @cachedmethod
 190     def _get_type(self, context):
 191         return get_data_type(context, self, 'type')
 192
 193
 194 @has_fields
 195 @implements_specification('3.5.12', 'tosca-simple-1.0')
 196 class ParameterDefinition(PropertyDefinition):
 197     """
 198     A parameter definition is essentially a TOSCA property definition; however, it also allows a
 199     value to be assigned to it (as for a TOSCA property assignment). In addition, in the case of
 200     output parameters, it can optionally inherit the data type of the value assigned to it rather
 201     than have an explicit data type defined for it.
 202
 203     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
 204     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
 205     #DEFN_ELEMENT_PARAMETER_DEF>`__
 206     """
 207
 208     @field_validator(data_type_validator())
 209     @primitive_field(str)
 210     def type(self):
 211         """
 212         The required data type for the parameter.
 213
 214         Note: This keyname is required for a TOSCA Property definition, but is not for a TOSCA
 215         Parameter definition.
 216
 217         :type: :obj:`basestring`
 218         """
 219
 220     @field_validator(data_value_validator)
 221     @primitive_field()
 222     def value(self):
 223         """
 224         The type-compatible value to assign to the named parameter. Parameter values may be provided
 225         as the result from the evaluation of an expression or a function.
 226         """
 227
 228
 229 @short_form_field('implementation')
 230 @has_fields
 231 @implements_specification('3.5.13-1', 'tosca-simple-1.0')
 232 class OperationDefinition(ExtensiblePresentation):
 233     """
 234     An operation definition defines a named function or procedure that can be bound to an
 235     implementation artifact (e.g., a script).
 236
 237     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
 238     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
 239     #DEFN_ELEMENT_OPERATION_DEF>`__
 240     """
 241
 242     @object_field(Description)
 243     def description(self):
 244         """
 245         The optional description string for the associated named operation.
 246
 247         :type: :class:`Description`
 248         """
 249
 250     @object_field(OperationImplementation)
 251     def implementation(self):
 252         """
 253         The optional implementation artifact name (e.g., a script file name within a TOSCA CSAR
 254         file).
 255
 256         :type: :class:`OperationImplementation`
 257         """
 258
 259     @object_dict_field(PropertyDefinition)
 260     def inputs(self):
 261         """
 262         The optional list of input property definitions available to all defined operations for
 263         interface definitions that are within TOSCA Node or Relationship Type definitions. This
 264         includes when interface definitions are included as part of a Requirement definition in a
 265         Node Type.
 266
 267         :type: {:obj:`basestring`: :class:`PropertyDefinition`}
 268         """
 269
 270
 271 @allow_unknown_fields
 272 @has_fields
 273 @implements_specification('3.5.14-1', 'tosca-simple-1.0')
 274 class InterfaceDefinition(ExtensiblePresentation):
 275     """
 276     An interface definition defines a named interface that can be associated with a Node or
 277     Relationship Type.
 278
 279     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
 280     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
 281     #DEFN_ELEMENT_INTERFACE_DEF>`__
 282     """
 283
 284     @field_validator(type_validator('interface type', convert_name_to_full_type_name,
 285                                     'interface_types'))
 286     @primitive_field(str)
 287     def type(self):
 288         """
 289         ARIA NOTE: This field is not mentioned in the spec, but is implied.
 290
 291         :type: :obj:`basestring`
 292         """
 293
 294     @object_dict_field(PropertyDefinition)
 295     def inputs(self):
 296         """
 297         The optional list of input property definitions available to all defined operations for
 298         interface definitions that are within TOSCA Node or Relationship Type definitions. This
 299         includes when interface definitions are included as part of a Requirement definition in a
 300         Node Type.
 301
 302         :type: {:obj:`basestring`: :class:`PropertyDefinition`}
 303         """
 304
 305     @object_dict_unknown_fields(OperationDefinition)
 306     def operations(self):
 307         """
 308         :type: {:obj:`basestring`: :class:`OperationDefinition`}
 309         """
 310
 311     @cachedmethod
 312     def _get_type(self, context):
 313         return get_type_by_name(context, self.type, 'interface_types')
 314
 315     @cachedmethod
 316     def _get_inputs(self, context):
 317         return FrozenDict(get_and_override_input_definitions_from_type(context, self))
 318
 319     @cachedmethod
 320     def _get_operations(self, context):
 321         return FrozenDict(get_and_override_operation_definitions_from_type(context, self))
 322
 323     def _validate(self, context):
 324         super(InterfaceDefinition, self)._validate(context)
 325         if self.operations:
 326             for operation in self.operations.itervalues(): # pylint: disable=no-member
 327                 operation._validate(context)
 328
 329
 330 @short_form_field('type')
 331 @has_fields
 332 class RelationshipDefinition(ExtensiblePresentation):
 333     """
 334     Relationship definition.
 335     """
 336
 337     @field_validator(type_validator('relationship type', convert_name_to_full_type_name,
 338                                     'relationship_types'))
 339     @primitive_field(str, required=True)
 340     def type(self):
 341         """
 342         The optional reserved keyname used to provide the name of the Relationship Type for the
 343         requirement definition's relationship keyname.
 344
 345         :type: :obj:`basestring`
 346         """
 347
 348     @object_dict_field(InterfaceDefinition)
 349     def interfaces(self):
 350         """
 351         The optional reserved keyname used to reference declared (named) interface definitions of
 352         the corresponding Relationship Type in order to declare additional Property definitions for
 353         these interfaces or operations of these interfaces.
 354
 355         :type: list of :class:`InterfaceDefinition`
 356         """
 357
 358     @cachedmethod
 359     def _get_type(self, context):
 360         return get_type_by_name(context, self.type, 'relationship_types')
 361
 362
 363
 364 @short_form_field('capability')
 365 @has_fields
 366 @implements_specification('3.6.2', 'tosca-simple-1.0')
 367 class RequirementDefinition(ExtensiblePresentation):
 368     """
 369     The Requirement definition describes a named requirement (dependencies) of a TOSCA Node Type or
 370     Node template which needs to be fulfilled by a matching Capability definition declared by
 371     another TOSCA modelable entity. The requirement definition may itself include the specific name
 372     of the fulfilling entity (explicitly) or provide an abstract type, along with additional
 373     filtering characteristics, that a TOSCA orchestrator can use to fulfill the capability at
 374     runtime (implicitly).
 375
 376     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
 377     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
 378     #DEFN_ELEMENT_REQUIREMENT_DEF>`__
 379     """
 380
 381     @field_validator(type_validator('capability type', convert_name_to_full_type_name,
 382                                     'capability_types'))
 383     @primitive_field(str, required=True)
 384     def capability(self):
 385         """
 386         The required reserved keyname used that can be used to provide the name of a valid
 387         Capability Type that can fulfill the requirement.
 388
 389         :type: :obj:`basestring`
 390         """
 391
 392     @field_validator(type_validator('node type', convert_name_to_full_type_name,
 393                                     'node_types'))
 394     @primitive_field(str)
 395     def node(self):
 396         """
 397         The optional reserved keyname used to provide the name of a valid Node Type that contains
 398         the capability definition that can be used to fulfill the requirement.
 399
 400         :type: :obj:`basestring`
 401         """
 402
 403     @object_field(RelationshipDefinition)
 404     def relationship(self):
 405         """
 406         The optional reserved keyname used to provide the name of a valid Relationship Type to
 407         construct when fulfilling the requirement.
 408
 409         :type: :class:`RelationshipDefinition`
 410         """
 411
 412     @field_getter(data_type_class_getter(Range))
 413     @primitive_field()
 414     def occurrences(self):
 415         """
 416         The optional minimum and maximum occurrences for the requirement.
 417
 418         Note: the keyword UNBOUNDED is also supported to represent any positive integer.
 419
 420         :type: :class:`Range`
 421         """
 422
 423     @cachedmethod
 424     def _get_capability_type(self, context):
 425         return get_type_by_name(context, self.capability, 'capability_types')
 426
 427     @cachedmethod
 428     def _get_node_type(self, context):
 429         return context.presentation.get_from_dict('service_template', 'node_types', self.node)
 430
 431
 432 @short_form_field('type')
 433 @has_fields
 434 @implements_specification('3.6.1', 'tosca-simple-1.0')
 435 class CapabilityDefinition(ExtensiblePresentation):
 436     """
 437     A capability definition defines a named, typed set of data that can be associated with Node Type
 438     or Node Template to describe a transparent capability or feature of the software component the
 439     node describes.
 440
 441     See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
 442     /TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html
 443     #DEFN_ELEMENT_CAPABILITY_DEFN>`__
 444     """
 445
 446     @field_validator(type_validator('capability type', convert_name_to_full_type_name,
 447                                     'capability_types'))
 448     @primitive_field(str, required=True)
 449     def type(self):
 450         """
 451         The required name of the Capability Type the capability definition is based upon.
 452
 453         :type: :obj:`basestring`
 454         """
 455
 456     @object_field(Description)
 457     def description(self):
 458         """
 459         The optional description of the Capability definition.
 460
 461         :type: :class:`Description`
 462         """
 463
 464     @object_dict_field(PropertyDefinition)
 465     def properties(self):
 466         """
 467         An optional list of property definitions for the Capability definition.
 468
 469         :type: {:obj:`basestring`: :class:`PropertyDefinition`}
 470         """
 471
 472     @object_dict_field(AttributeDefinition)
 473     def attributes(self):
 474         """
 475         An optional list of attribute definitions for the Capability definition.
 476
 477         :type: {:obj:`basestring`: :class:`AttributeDefinition`}
 478         """
 479
 480     @field_validator(list_type_validator('node type', convert_name_to_full_type_name,
 481                                          'node_types'))
 482     @primitive_list_field(str)
 483     def valid_source_types(self):
 484         """
 485         An optional list of one or more valid names of Node Types that are supported as valid
 486         sources of any relationship established to the declared Capability Type.
 487
 488         :type: [:obj:`basestring`]
 489         """
 490
 491     @field_getter(data_type_class_getter(Range))
 492     @primitive_field()
 493     def occurrences(self):
 494         """
 495         The optional minimum and maximum occurrences for the capability. By default, an exported
 496         Capability should allow at least one relationship to be formed with it with a maximum of
 497         ``UNBOUNDED`` relationships.
 498
 499         Note: the keyword ``UNBOUNDED`` is also supported to represent any positive integer.
 500
 501         ARIA NOTE: The spec seems wrong here: the implied default should be ``[0,UNBOUNDED]``, not
 502         ``[1,UNBOUNDED]``, otherwise it would imply that at 1 least one relationship *must* be
 503         formed.
 504
 505         :type: :class:`Range`
 506         """
 507
 508     @cachedmethod
 509     def _get_type(self, context):
 510         return get_type_by_name(context, self.type, 'capability_types')
 511
 512     @cachedmethod
 513     def _get_parent(self, context):
 514         container_parent = self._container._get_parent(context)
 515         container_parent_capabilities = container_parent._get_capabilities(context) \
 516             if container_parent is not None else None
 517         return container_parent_capabilities.get(self._name) \
 518             if container_parent_capabilities is not None else None