v0.37.4

Notes

• Update to support requests up to version 3.0.0 (exclusive)
• Update to corresponding zepben.auth library for requests support

v0.40.0

Breaking Changes

• The database has been split into three databases, which will change the imports of most related classes:
  1. The existing database containing the network model (*-network-model.sqlite) with classes in the network package.
  2. A new database containing the customer information (*-customers.sqlite) with classes in the customer package.
  3. A new database containing the diagrams (*-diagrams.sqlite) with classes in the diagram package.
• The database split has resulted in the database classes also being split, e.g. DatabaseReader is now NetworkDatabaseReader, CustomerDatabaseReader and DiagramDatabaseReader.
• Database table classes now return a Generator rather than a List or their index collections. This will have no impact if you are just looping over the
  result, but it will have an impact if you have inherited your own tables.
• Equipment to EquipmentContainer links for LV feeders are no longer written to the database, they should never have been.
• Converted the following classes to use @dataclass from dataclasses instead of dataclassy:
  • PositionPoint
  • TownDetail
  • StreetDetail
  • StreetAddress
  • Name
  • DiagramObjectPoint
  • RelaySetting
  • TransformerEndRatedS
  • ResistanceReactance
  • DataSource
• All private collections inside our CIM objects that index objects by mrid now raise KeyError rather than ValueError if you try and remove an object from
  an empty collection.
• Rationalised accessors for the private collections inside our CIM objects, which has added and/or removed some functions. If you were using one of the removed
  functions, there should be another that can give close/equivalent operation. The most notable change is the accessors should now be throwing exceptions
  correctly, rather than returning None in some circumstances and throwing in others.
  • Location:
    • get_point now throws when provided an invalid sequence_number rather than returning None.
    • Updated error message for providing an incorrect sequence_number to insert_point.
  • RelayInfo:
    • get_delay and remove_delay_at now throw when provided an invalid index rather than returning None.
    • Updated error message for providing an incorrect index to add_delay.
  • Sensor:
    • Type information for get_relay_function has been updated to indicate the return value is not optional, as the function throws if the mrid is unknown.
  • ConductingEquipment:
    • Updated error message for providing a Terminal with an incorrect sequence_number to add_terminal.
  • IdentifiedObject:
    • get_name now throws when provided an invalid name_type or name rather than returning None.
    • get_names now throws when provided an invalid name_type rather than returning None if it had no names, or an EmptyList if it had names, but none
      of the requested type.
  • DiagramObject:
    • Updated error message for providing an incorrect sequence_number to insert_point.
  • ProtectionRelayFunction:
    • Updated error message for providing an incorrect sequence_number to add_threshold.
    • Type information for get_threshold has been updated to indicate the return value is not optional, as the function throws if the sequence_number is
      unknown.
    • Type information for remove_threshold has been updated to indicate the threshold to remove is not optional.
    • Updated error message for providing an incorrect index to add_time_limit.
    • remove_time_limit_by_time_limit was renamed to remove_time_limit.
    • remove_time_limit was renamed to remove_time_limit_at and now throws when provided an invalid index rather than returning None.
    • Type information for the following functions have been updated to indicate the return value is not optional, as the functions throw if the mrid is
      unknown:
      • get_sensor
      • get_protected_switch
      • get_scheme
  • ProtectionRelayScheme:
    • Type information for get_function has been updated to indicate the return value is not optional, as the function throws if the mrid is unknown.
  • ProtectionRelaySystem:
    • Type information for get_scheme has been updated to indicate the return value is not optional, as the function throws if the mrid is unknown.
  • PowerTransformerEnd:
    • Updated error message for providing a PowerTransformerEnd with an incorrect end_number to add_end.
    • get_rating_by_rated_s has been removed.
    • get_rating_by_cooling_type has been renamed to get_rating and now throws when provided an invalid cooling_type rather than returning None.
    • The parameters for add_rating have been reordered, and cooling_type now defaults to UNKNOWN_COOLING_TYPE.
    • add_transformer_end_rated_s now takes a copy of the provided transformer_end_rated_s rather than adding the object directly into the collection.
    • remove_rating_by_cooling_type now throws when provided an invalid cooling_type rather than returning None.
  • ProtectedSwitch:
    • Type information for get_relay_function has been updated to indicate the return value is not optional, as the function throws if the mrid is unknown.
  • RegulatingControl:
    • Type information for get_regulating_cond_eq has been updated to indicate the return value is not optional, as the function throws if the mrid is
      unknown.

New Features

• Support zepben.auth 0.12.0 which brings support for auth against EWB servers backed by EntraID.

Enhancements

• Added the following accessors/helpers to our CIM objects:
  • Location.for_each_point
  • RelayInfo.for_each_point
  • IdentifiedObject.has_name
  • DiagramObject.for_each_point
  • DiagramObject.remove_point_by_sequence_number
  • ProtectionRelayFunction.for_each_threshold
  • ProtectionRelayFunction.remove_threshold_at
  • ProtectionRelayFunction.for_each_time_limit
• Added missing num_controls field to PowerSystemResource.

Fixes

• Added missing type information to the following NameType functions: get_or_add_name, remove_name and remove_names

Notes

• Updated to support zepben.protobuf 0.27.0. This has actually been supported since 0.38.0, however the released version was not captured in the dependencies.

v0.39.0

Breaking Changes

• None.

New Features

• Added EwbDataFilePaths class for working with the EWB various database files

Enhancements

• Added feature list to documentation.

Fixes

• Updated zepben.auth to 0.11.1 to fix incorrect audience processing when requesting tokens with Entra.

Notes

• None.

v0.38.0

Breaking Changes

• This is the last release using an artifact name of zepben.evolve, future releases will be made as zepben.ewb.
• connect_with_secret() and connect_with_password() will no longer create a ZepbenTokenFetcher directly from kwargs.
• IdentifiedObject.addName has been refactored to take in a str and a NameType. This is doing the same thing under the hood as previous add_name()
  function,
  but simplifies the input by lowering the amount of objects that needed to be created prior to adding names.
  Example usage change:
  obj.add_name(nameType, "name", obj)) or obj.add_name(nameType.getOrAddName("name", obj)) becomes obj.add_name("name", nameType)
• add_name()/remove_name() related function for both IdentifiedObject and NameType will now also perform the same function on the other object type.
  i.e. Removing a name from the identified object will remove it from the name type and vice versa. Same interaction is also applied to adding a name.
• Removed ProtectionEquipment.
• Change of inheritance: CurrentRelay → ProtectionEquipment.
  becomes CurrentRelay → ProtectionRelayFunction.
• Removed symmetric relation ProtectionEquipment ↔ ProtectedSwitch.
• Renamed CurrentRelayInfo to RelayInfo.
  • The override CurrentRelay.relay_info has been moved from CurrentRelay to its new parent class, ProtectionRelayFunction.
  • Renamed RelayInfo.remove_delay to RelayInfo.remove_delay_at. The original method name has been repurposed to remove a delay by its value rather than its
    index.
• Reworked values for enumerable type ProtectionKind.

New Features

• Added support for passing the grpc channel configuration options to the GrpcChannelBuilder.
• Added get_names(IdentifiedObject) to NameType to retrieve all names associated with the NameType that belongs to an IdentifiedObject.
• Added get_names(NameType) and get_names(String) to IdentifiedObject so user can retrieve all names for a given NameType of the IdentifiedObject
• Added new classes and fields to support advanced modelling of protection relays:
  • SeriesCompensator: A series capacitor or reactor or an AC transmission line without charging susceptance.
  • Ground: A point where the system is grounded used for connecting conducting equipment to ground.
  • GroundDisconnector: A manually operated or motor operated mechanical switching device used for isolating a circuit
    or equipment from ground.
  • ProtectionRelayScheme: A scheme that a group of relay functions implement. For example, typically schemes are
    primary and secondary, or main and failsafe.
  • ProtectionRelayFunction: A function that a relay implements to protect equipment.
  • ProtectionRelaySystem: A relay system for controlling ProtectedSwitches.
  • RelaySetting: The threshold settings for a given relay.
  • VoltageRelay: A device that detects when the voltage in an AC circuit reaches a preset voltage.
  • DistanceRelay: A protective device used in power systems that measures the impedance of a transmission line to
    determine the distance to a fault, and initiates circuit breaker tripping to isolate the faulty
    section and safeguard the power system.
  • RelayInfo.reclose_fast: True if reclose_delays are associated with a fast Curve, False otherwise.
  • RegulatingControl.rated_current: The rated current of associated CT in amps for a RegulatingControl.

Enhancements

• GrpcChannelBuilder tests the connectivity of newly created channels before returning them to the user. This is done by calling getMetadata() against all
  known services, the channel is returned after the first successful response. Any connectivity errors will be propagated to the user. If no connectivity errors
  are encountered but no successful response is received from the known services, a GrpcConnectionException is thrown.

Fixes

• SetDirection now traces through non-substation transformers.
• Feeder.normal_head_terminal can now be freely updated when the Feeder has no equipment assigned to it.
• PotentialTransformer now recognised as a valid identified object type when deserializing gRPC messages.

Notes

• Default grpc channel message size is now 20MB.

v0.37.3

Breaking Changes

• None.

New Features

• None.

Enhancements

• None.

Fixes

• PotentialTransformer now recognised as a valid identified object type when deserializing gRPC messages.

Notes

• None.

v0.37.2

Breaking Changes

• None.

New Features

• Added support for passing the grpc channel configuration options to the GrpcChannelBuilder.

Enhancements

• None.

Fixes

• None.

Notes

• Default grpc channel message size is now 20MB.

v0.37.1

Fixes

• Use zepben.auth 0.11.1.

v0.37.0

Zepben Python SDK

[0.37.0] - 2024-11-14

Breaking Changes

• • Updated to evolve-grpc 0.26.0.

New Features

• PowerTransformerEnd now supports multiple ratings based on cooling types attached to the transformer. Use new add_rating and get_rating methods.
  • See notes section for deprecation information of rated_s.
• Added new classes:
  • TapChangerControl
  • EvChargingUnit
  • RegulatingControl
• Added new fields:
  • Equipment.commissioned_date
  • UsagePoint
    • rated_power
    • approved_inverter_capacity
  • ProtectionEquipment
    • directable
    • power_direction
  • CurrentRelayInfo.reclose_delays
  • DER register fields on PowerElectronicsConnection
• Added new enums
  • PowerDirectionKind
  • RegulatingControlModeKind
  • TransformerCoolingType

Enhancements

• Update docusaurus and its configuration.

Fixes

• None.

Notes

• Setting PowerTransformerEnd.rated_s directly has been deprecated. You should now use add_rating and get_rating to set a rated_s alongside a defined
  TransformerCoolingType if one is known. By default the coolingType will be UNKNOWN.

v0.36.0

Zepben Python SDK

[0.36.0] - UNRELEASED

Breaking Changes

• None.

New Features

• Support using Azure Entra ID as an auth provider
• Added support for connecting to EWB utilising Azure managed identities. Use the new function connect_with_identity()

Enhancements

• None.

Fixes

• None.

Notes

• None.

v0.35.0

[0.35.0]

Breaking Changes

• Renamed the module for GrpcChannelBuilder from channel_builder to grpc_channel_builder.

• GrpcChannelBuilder().make_secure now takes filenames instead of bytestrings.
  The order of the parameters has also been changed: private_key now comes after certificate_chain.

  • This changes also applies to any TLS parameters in connect_* functions.

• GrpcChannelBuilder().socket_address has been renamed to for_address.

• GrpcChannelBuilder().token_fetcher has been renamed to with_token_fetcher.

• Refactored AuthTokenPlugin to a separate module.

• Removed deprecated connect and connect_async functions. They have been replaced with several simpler functions, e.g. connect_with_password.

• Changed connect_with_secret and connect_with_password parameters:

  • The address of the authentication config is now specified with a single parameter: conf_address.
  • Added optional parameters verify_conf and verify_auth, which are passed through to requests.get and requests.put
    when fetching the authentication config and requesting access tokens respectively.
  • ca is replaced with ca_filename, which can be set to the filename of a CA to use when verifying the certificate
    of the gRPC service.

• Refactored TreeNode class to its own submodule: zepben.evolve.services.network.tracing.tree.tree_node.

• Renamed FeederDirection.has to FeederDirection.__contains__, which can be used via its operator version in. e.g. BOTH.has(DOWNSTREAM) can be replaced
  with BOTH.__contains__(DOWNSTREAM) or DOWNSTREAM in BOTH

• Removed deprecated function NetworkConsumerClient.get_feeder.

• Refactored the following Switch descendant classes to their own submodules in zepben.evolve.model.cim.iec61970.base.wires:

  • Breaker moved to breaker
  • Disconnector moved to disconnector
  • Fuse moved to fuse
  • Jumper moved to jumper
  • LoadBreakSwitch moved to load_break_switch
  • ProtectedSwitch moved to protected_switch
  • Recloser moved to recloser

  Note that from zepben.evolve import <ClassName> will still work as usual for all of the above classes.

• DatabaseReader().load is now an asynchronous function.

• The addition of the mrid and connectivity_node_mrid arguments to the TestNetworkBuilder functions has changed the position of the action argument. If
  you are using positional arguments you will need to add action= before your actions if you do not specify your own mRIDs.

• SetDirection.run(NetworkService) will no longer set directions for feeders with a head terminal on an open switch. It is expected these feeders are either
  placeholder feeders with no meaningful equipment, or are energised from another feeder which will set the directions from the other end.

New Features

• Added support for current transformers and power transformers with the following classes in zepben.evolve.cim.*:
  • In zepben.evolve.cim.iec61968.infiec61968.infassetinfo:
    • CurrentTransformerInfo: Properties of current transformer asset.
    • PotentialTransformerInfo: Properties of potential transformer asset.
  • In zepben.evolve.cim.iec61968.infiec61968.infcommon:
    • Ratio: Fraction specified explicitly with a numerator and denominator, which can be used to calculate the quotient.
  • In zepben.evolve.cim.iec61970.base.auxiliaryequipment:
    • CurrentTransformer: Instrument transformer used to measure electrical qualities of the circuit that is being protected and/or monitored.
    • PotentialTransformer: Instrument transformer (also known as Voltage Transformer) used to measure electrical qualities of the circuit that
      is being protected and/or monitored.
    • PotentialTransformerKind: The construction kind of the potential transformer. (Enum)
    • Sensor: This class describes devices that transform a measured quantity into signals that can be presented at displays,
      used in control or be recorded.
• Added PowerTransformer().get_end_by_terminal, which gets a PowerTransformerEnd by the Terminal it's connected to.
• Added the following functions to connected_equipment_trace.py for creating traces that work on ConductingEquipment, and ignore phase connectivity, instead
  considering things to be connected if they share a ConnectivityNode:
  • new_normal_downstream_equipment_trace: Creates a trace that traverses in the downstream direction using the normal state of the network.
  • new_normal_upstream_equipment_trace: Creates a trace that traverses in the upstream direction using the normal state of the network.
  • new_current_downstream_equipment_trace: Creates a trace that traverses in the downstream direction using the current state of the network.
  • new_current_upstream_equipment_trace: Creates a trace that traverses in the upstream direction using the current state of the network.
• Added support for protection equipment with the following classes, enums, and fields:
  • SwitchInfo: Switch datasheet information.
  • ProtectionEquipment: An electrical device designed to respond to input conditions in a prescribed manner and after specified conditions are met to cause
    contact operation or similar abrupt change in associated electric control circuits, or simply to display the detected condition.
  • CurrentRelay: A device that checks current flow values in any direction or designated direction.
  • CurrentRelayInfo: Current relay datasheet information.
  • ProtectionKind: The kind of protection being provided by this protection equipment.
  • ProtectedSwitch().breaking_capacity: The maximum fault current in amps a breaking device can break safely under prescribed conditions of use.
  • ProtectedSwitch().operated_by_protection_equipment: The collection of ProtectionEquipment operating the ProtectedSwitch.
  • Switch().rated_current: The maximum continuous current carrying capacity in amps governed by the device material and construction.
    The attribute shall be a positive value.
  • Breaker().in_transit_time: The transition time from open to close in seconds.
• Added getCustomersForContainer to CustomerConsumerClient which allows fetching all the Customers for a given EquipmentContainer
• Added getDiagramObjects to DiagramConsumerClient which allows fetching all the DiagramObjects matching a given mRID.
• Traversal has two new helper methods:
  • if_not_stopping: Adds a step action that is only called if the traversal is not stopping on the item.
  • if_stopping: Adds a step action that is only called if the traversal is stopping on the item.

Enhancements

• tracker is now a field in Traversal, rather than its subclasses.
• The constructor for BranchRecursiveTraversal now defaults the process_queue field to depth_first().
• TreeNode is now more closely aligned with its Kotlin version:
  • TreeNode().parent is now a read-only property.
  • TreeNode().children has been added as a read-only property that yields each child node.
  • TreeNode().sort_weight has been added as a read-only property that returns the sort weight of the node.
• All Tracker classes can now be copied using the copy method.
• Added FeederDirection.__not__ operator function.
• Performance enhancement for connected_equipment_trace.py when traversing elements with single terminals.
• Added support for LV2 transformers.
• Improved logging when saving a database.
• The TestNetworkBuilder has been enhanced with the following features:
  • You can now set the ID's without having to create a customer 'other' creator.
  • Added Kotlin wrappers for .fromOther and .toOther that allow you to pass a class type rather than a creator. e.g. .toOther<Fuse>() instead
    of .toOther(::Fuse) or .toOther( { Fuse(it) } ).
  • Added inbuilt support for PowerElectronicsConnection and EnergyConsumer
  • The to* and connect functions can specify the connectivity node mRID to use. This will only be used if the terminals are not already connected.
• Added + and - operators to PhaseCode and SinglePhaseKind.

Fixes

• StreetDetail.to_cim now references the protobuf -> CIM translation function for the StreetDetail protobuf type.
• PerLengthImpedance.to_cim now references the protobuf -> CIM translation function for the PerLengthImpedance protobuf type.
• ZepbenTokenFetcher now includes the refresh token in token refresh requests.
• Fixed connectivity traces.
• Fixed bug where running a limited connected equipment trace with maximum_steps=1
  included equipment two steps away from the starting equipment if feeder_direction is set.
• Each stop condition of a traversal is now checked on each step, regardless if a previous one in the internal list has returned True.
• Add normal_upstream_trace, current_upstream_trace, and phase_inferrer to __all__ in zepben.evolve.services.network.tracing.tracing.
• Added missing run method for DownstreamTree.
• Added missing TreeNodeTracker.
• Classes in the zepben.evolve.services.network.tracing.tree.* submodules may now be imported from zepben.evolve.
• Add normal_upstream_trace, current_upstream_trace, and phase_inferrer to __all__ in zepben.evolve.services.network.tracing.tracing.
• Stopped the NetworkConsumerClient from resolving the equipment of an EquipmentContainer when resolving references. Equipment for containers must always be
  explicitly requested by the client.
• Asking for the traced phases as a phase code when there are no nominal phases no longer throws.
• Feeder directions are now stopped at substation transformers in the same way as assigning equipment incase the feeder has no breaker, or the start point is
  not inline.

Notes

• None.