hec.rating.rating_specification

DEFAULT_IN_RANGE_METHOD = <LookupMethod.LINEAR: (3, 'Linear interpolation or extrapolation of independent and dependent values')>
DEFAULT_OUT_RANGE_LOW_METHOD = <LookupMethod.NEXT: (8, 'Return the value that is higher in position')>
DEFAULT_OUT_RANGE_HIGH_METHOD = <LookupMethod.PREVIOUS: (7, 'Return the value that is lower in position')>
DEFAULT_ROUNDING_SPEC = '4444444449'
class RatingSpecificationException(hec.shared.RatingException):

Base exception for all rating exceptions

class RatingSpecification:

Holds the following information about ratings and rating sets;

  • rating idendifier, comprised of
    • location identifier
    • template identifier
      • independent parameters
      • dependent parameter
      • template version
    • specification version
  • source agency
  • lookup methods for multiple effective dates in rating sets
    • method for value times within the range of effective dates
    • method for value times before the earliest effective date
    • method for value times after the latest effective date
  • rounding specifications
    • one for each independent parameter
    • one for the dependent parameter
  • whether the specification is active (should be used)
  • whether the ratings with this specification should be automatically updated from the source agency
  • whether automatically updated ratings should be set to active
  • whether automatically updated ratings should have any rating extension migrated to the new rating
  • a description of the rating specification
RatingSpecification(name: str, **kwargs: Any)

Initializer for RatingSpecification objects

Arguments:
  • name (str): The rating specification identifier
  • location (Optional[Location], must be passed by name): A Location object for the specification. Defaults to None. If specified, the location name must match the location portion of the rating specification identifier
  • template (Optional[RatingTemplate], must be passed by name): A RatingTemplate object for the specification. Defaults to None. If specified, the rating template identifier must match the template portion of the rating specification identifier.
  • office (Optional[str], must be passed by name): The office for the rating specification. Defaults to None. If specified, overrides any office in the location and template parameters.
  • agency (Optional[str], must be passed by name): The agency that generates the ratings for this specification. Defaults to None.
  • lookup (Optional[list[str]], must be passed by value): Methods for time-based lookups using effective dates in rating sets with this specification. Defaults to None. If specified, must be an array of three strings, in the following order
    • method for value times within the range of effective dates
    • method for value times before the earliest effective date
    • method for value times after the latest effective date
      If not specified, lookup methods of ['LINEAR', 'NEXT', 'PREVIOUS'] will be used.
  • rounding (Optional[list[str]], must be passed by name): Rounding specifications. Defaults to None. If specified:
    • must be the length of the number of independent parameters plus 1
    • all but the last item are applied to the independent parameters in position order
    • the last item is applied to the dependent parameter
    • each item must be a valid rounding specification
      If not specified, the rounding specification of 4444444449 is used for all parameters
  • active (Optional[bool], must be passed by name): Whether ratings and rating sets using this specification are active (should be used). Defaults to True.
  • auto_update (Optional[bool], must be passed by name): Whether ratings and rating sets using this specification are active (should be used). Defaults to False.
  • auto_activate (Optional[bool], must be passed by name): Whether automatically updated ratings should be set to active. Defaults to False.
  • auto_update_migration (Optional[bool], must be passed by name): Whether automatically updated ratings should have any rating extension migrated to the new rating. Defaults to False.
  • description (Optional[str], must be passed by name): A description for the rating specification. Defaults to None.
Raises:
  • ValueError: if the name parameter is not a properly-formed rating specification identifier
  • TypeError: if one of the named parameters has an unexpected type
  • RatingSpecificationException: if one of the named parameters is inconsistent with the rating specification identifier
active: bool

Whether ratings using this specification are active (should be used)

Operations:

Read/Write

agency: Optional[str]

The agency responsible for generating ratings using this specification

Operations:

Read/Write

auto_update: bool

Whether the ratings with this specification should be automatically updated from the source agency

Operations:

Read/Write

auto_activate: bool

Whether automatically updated ratings should be set to active

Operations:

Read/Write

auto_migrate_extension: bool

Whether automatically updated ratings should have any rating extension migrated to the new rating

Operations:

Read/Write

def copy(self) -> RatingSpecification:

Creates and returns a copy of this specificaiton

Returns:

RatingSpecification: The copy

description: Optional[str]

The description of the rating specification

Operations:

Read/Write

@staticmethod
def from_xml(xml: str) -> RatingSpecification:

Generates a RatingSpecification object from an XML string representation

Arguments:
  • xml (str): The XML string representation
Raises:
  • RatingSpecificationException: if there is an error in the XML string
Returns:

RatingSpecification: The generated RatingSpecification object

location: hec.Location

The location object of the specification

Operations:

Read/Write

lookup: list[str]

The lookup methods of the specification

Operations:

Read/Write

name: str

The specification identifier

Operations:

Read-Only

rounding: list[str]

The rounding specifications of the specification

Operations:

Read/Write

template: hec.rating.RatingTemplate

The RatingTemplate of the specification

Operations:

Read/Write

def to_xml(self, indent: str = ' ', prepend: str = '') -> str:

Returns a formatted xml representation of the rating specification.

For unformatted xml use etree.tostring(<specification_obj>.xml_element)

Arguments:
  • indent (str, optional): The string to use for each level of indentation. Defaults to " ".
  • prepend (Optional[str], optional): A string to prepend to each line. Defaults to None.
Returns:

str: The formatted xml

version: str

The version string of the specification

Operations:

Read/Write

xml_element: lxml.etree._Element

The rating specification as an lxml.etree.Element object

Operations:

Read-Only