Skip to main content
`Ctrl`+`K`

# ng911ok.lib.accessor module

exception InconsistentParityError

  Bases: `Exception`

exception InvertedAddressRangeError(from_addr: int, to_addr: int)

  Bases: `Exception`

exception NGUIDFormatError(invalid_nguid: str, problem: Literal['ERROR:DOMAIN:INVALID_VALUE', 'ERROR:GENERAL:INVALID_VALUE', 'ERROR:GENERAL:MANDATORY_IS_NULL', 'ERROR:GENERAL:MANDATORY_IS_BLANK', 'ERROR:GENERAL:NOT_UPPERCASE', 'ERROR:GENERAL:UNIQUENESS', 'WARNING:GENERAL:LEADING_TRAILING_SPACE', 'ERROR:NGUID:FORMAT', 'ERROR:NGUID:V2_FORMAT', 'ERROR:NGUID:AGENCY', 'ERROR:NGUID:LAYER', 'ERROR:NGUID:DUPLICATE', 'ERROR:ADDRESS:DUPLICATE', 'ERROR:ADDRESS_RANGE:OVERLAP', 'ERROR:ADDRESS_RANGE:DECREASING', 'ERROR:ROAD_ESN:DEVIATION', 'ERROR:ROAD_ESN:CROSSING', 'ERROR:ROAD_ESN:OUT_OF_BOUNDS', 'ERROR:PARITY:EXPECTED_ZERO', 'ERROR:PARITY:EXPECTED_NONZERO', 'ERROR:PARITY:MISMATCH', 'ERROR:PARITY:INVALID', 'ERROR:PARITY:NULL', 'ERROR:LEGACY:MISMATCH', 'ERROR:GEOCODE:UNKNOWN_MATCH', 'ERROR:GEOCODE:WRONG_SIDE', 'ERROR:GEOCODE:BOTH_SIDES', 'ERROR:GEOCODE:WRONG_COMMUNITY', 'ERROR:GEOCODE:OUT_OF_RANGE', 'ERROR:GEOCODE:NAME_MISMATCH', 'WARNING:GEOCODE:NO_MATCH', 'ERROR:CONSISTENCY:ADDRESS_ESN', 'ERROR:CONSISTENCY:ROAD_ESN', 'ERROR:CONSISTENCY:COMMUNITY', 'ERROR:MSAG:NO_ROAD_MATCH', 'WARNING:CONSISTENCY:ROAD_LEVEL', 'ERROR:GEOMETRY:TOPOLOGY', 'WARNING:GEOMETRY:CUTBACK', 'WARNING:GEOMETRY:SHORT_SEGMENT', 'NOTICE:CONSISTENCY:ROAD_ESN'], details: str | None = None, piece: Literal['LAYER', 'LOCAL_ID', 'AGENCY_ID'] | None = None)

  Bases: `ValueError`

  _raw_details: str | None
  details: str
  invalid_nguid: str
  problem: Literal['ERROR:DOMAIN:INVALID_VALUE', 'ERROR:GENERAL:INVALID_VALUE', 'ERROR:GENERAL:MANDATORY_IS_NULL', 'ERROR:GENERAL:MANDATORY_IS_BLANK', 'ERROR:GENERAL:NOT_UPPERCASE', 'ERROR:GENERAL:UNIQUENESS', 'WARNING:GENERAL:LEADING_TRAILING_SPACE', 'ERROR:NGUID:FORMAT', 'ERROR:NGUID:V2_FORMAT', 'ERROR:NGUID:AGENCY', 'ERROR:NGUID:LAYER', 'ERROR:NGUID:DUPLICATE', 'ERROR:ADDRESS:DUPLICATE', 'ERROR:ADDRESS_RANGE:OVERLAP', 'ERROR:ADDRESS_RANGE:DECREASING', 'ERROR:ROAD_ESN:DEVIATION', 'ERROR:ROAD_ESN:CROSSING', 'ERROR:ROAD_ESN:OUT_OF_BOUNDS', 'ERROR:PARITY:EXPECTED_ZERO', 'ERROR:PARITY:EXPECTED_NONZERO', 'ERROR:PARITY:MISMATCH', 'ERROR:PARITY:INVALID', 'ERROR:PARITY:NULL', 'ERROR:LEGACY:MISMATCH', 'ERROR:GEOCODE:UNKNOWN_MATCH', 'ERROR:GEOCODE:WRONG_SIDE', 'ERROR:GEOCODE:BOTH_SIDES', 'ERROR:GEOCODE:WRONG_COMMUNITY', 'ERROR:GEOCODE:OUT_OF_RANGE', 'ERROR:GEOCODE:NAME_MISMATCH', 'WARNING:GEOCODE:NO_MATCH', 'ERROR:CONSISTENCY:ADDRESS_ESN', 'ERROR:CONSISTENCY:ROAD_ESN', 'ERROR:CONSISTENCY:COMMUNITY', 'ERROR:MSAG:NO_ROAD_MATCH', 'WARNING:CONSISTENCY:ROAD_LEVEL', 'ERROR:GEOMETRY:TOPOLOGY', 'WARNING:GEOMETRY:CUTBACK', 'WARNING:GEOMETRY:SHORT_SEGMENT', 'NOTICE:CONSISTENCY:ROAD_ESN']
  property validation_message: str

    Returns a single-line string suitable for writing to a validation error table.

class AddressRange(from_addr: int, to_addr: int, parity: Parity, suppress_errors: bool = False)

  Bases: `object`

  classmethod auto_fix_directionality(from_addr: int, to_addr: int, parity: Parity, suppress_errors: bool = False) → Self
  classmethod from_set(set_: set[int], parity: Parity | None = None) → Self

    Initializes and returns an `AddressRange` from a `set` of integers. Parity is automatically determined unless provided.

    Parameters:

      - set (set[int]) – Set of integers representing addresses within the range

      - parity (Optional[Parity]) – If provided but set_ does not match it, a `ValueError` is raised

    Returns:

      Resulting `AddressRange` instance

    Return type:

      AddressRange

  classmethod zero() → Self
  _merge_adjacent(other: Self) → Self
  _merge_method(other: Self) → MergeMethod
  _merge_overlapping(other: Self) → Self
  _merge_two_sides(other: Self) → Self
  _split_and_merge(other: Self) → Self
  _validate() → bool
  overlaps(other: Self) → bool
  sides(suppress_errors: bool | None = None) → tuple[Self] | tuple[Self, Self]
  to_array() → ndarray
  to_set() → set[int]

    Returns a `set` containing all integers of appropriate parity between `from_addr` and `to_addr`, inclusive. If parity is zero, an empty set is returned.

  property as_increasing: Self
  property details: str

    Returns a more detailed informational string than `__str__()`.

  property directionality: Directionality
  property directionality_is_valid: bool

    Returns `True` if the instance’s `directionality` is `INCREASING`, `SINGLE`, or `ZERO`. Otherwise, returns `False`.

  from_addr: int
  property high: int
  property is_valid: bool
  property low: int
  parity: Parity
  suppress_errors: bool
  to_addr: int

class Directionality(value)

  Bases: `StrEnum`

  Represents the directionality of an address range.

  _generate_next_value_(start, count, last_values)

    Return the lower-cased version of the member name.

  DECREASING = 'Decreasing'

    Represents an address range where the to-address is lower than the from-address.

  INCREASING = 'Increasing'

    Represents an address range where the to-address is higher than the from-address.

  SINGLE = 'Single'

    Represents an address range where the from-address and to-address are equal and non-zero.

  ZERO = 'Zero'

    Represents an address range where the parity is `Parity.ZERO`.

class MergeMethod(value)

  Bases: `IntEnum`

  ADJACENT = 5

    The ranges have the same non-zero parity and can be returned as a range with the `from_addr` of one input and the `to_addr` of the other.

  DROP_FIRST = 1

    The first range has a parity of `ZERO`, so the second range can be returned as-is.

  DROP_SECOND = 2

    The second range has a parity of `ZERO`, so the first range can be returned as-is.

  NONE = 0

    Ranges cannot be merged.

  SPLIT_FIRST = 6

    The first range `BOTH` parity and the second is odd or even. If the first is split into odd and even, the second can be merged with one of the ranges resulting from the split. The consolidation will result in two ranges, one odd and one even.

  SPLIT_SECOND = 7

    The second range `BOTH` parity and the first is odd or even. If the second is split into odd and even, the first can be merged with one of the ranges resulting from the split. The consolidation will result in two ranges, one odd and one even.

  TWO_SIDES = 4

    One range is odd, the other is even, and they can be returned as a range with `BOTH` parity.

  ZEROS = 3

    Both ranges have parities of `ZERO`, so a `AddressRange.zero` can be returned.

class MultiAddressRange(ranges: Collection[AddressRange] | None = None)

  Bases: `object`

  classmethod consolidate(ranges: Collection[AddressRange]) → list[AddressRange]
  property ranges: frozenset[AddressRange]

class NG911Accessor(pandas_obj: DataFrame)

  Bases: `object`

  address_range_left(suppress_errors=False, auto_fix_directionality=False) → Series
  address_range_right(suppress_errors=False, auto_fix_directionality=False) → Series
  to_table(gdb: NG911Session | Path | str, name: str, convert_dtypes: bool = True, overwrite: bool = False) → Path | None
  property address_parity: Series
  property directionality_left: Series
  property directionality_right: Series
  property parity_left: Series
  property parity_right: Series

class NG911SeriesAccessor(pandas_obj: Series)

  Bases: `object`

  property field: NG911Field

class NGUID(layer: str, local_id, agency_id: str)

  Bases: `object`

  classmethod _diagnose_v3(string: str) → NGUIDFormatError

    Method to attempt to diagnose the specific format violation of (what should be) a v3 NGUID.

    Parameters:

      string (str) – The v3 NGUID string in violation

    Returns:

      Exception to analyze and/or raise

    Return type:

      NGUIDFormatError

  classmethod from_string(string: str) → Self
  classmethod from_v2_string(string: str) → Self
  classmethod validate_string(string: str) → NGUIDFormatError | None

    Validates the format of an NGUID string.

    Parameters:

      string (str) – NGUID to validate

    Returns:

      `None` if the NGUID is valid, otherwise, an instance of `NGUIDFormatError`

    Return type:

      NGUIDFormatError | None

  AGENCYID_PATTERN: ClassVar[Pattern] = re.compile('[A-Za-z\\d][A-Za-z\\d-]*(?:\\.[A-Za-z\\d][A-Za-z\\d-]*)+')
  LAYER_PATTERN: ClassVar[Pattern] = re.compile('[A-Za-z_]\\w*')
  LOCALID_PATTERN: ClassVar[Pattern] = re.compile('[\\w\\(\\)\\[\\]\\{\\}-]+')
  NGUID_PATTERN: ClassVar[Pattern] = re.compile('urn:emergency:uid:gis:([A-Za-z_]\\w*):([\\w\\(\\)\\[\\]\\{\\}-]+):([A-Za-z\\d][A-Za-z\\d-]*(?:\\.[A-Za-z\\d][A-Za-z\\d-]*)+)')
  V2_LOCALID_PATTERN: ClassVar[Pattern] = re.compile('[\\x20-\\x39\\x3b-\\x3f\\x41-\\x7e]+')
  V2_NGUID_PATTERN: ClassVar[Pattern] = re.compile('^([A-Za-z_]\\w*)_([\\x20-\\x39\\x3b-\\x3f\\x41-\\x7e]+)@([A-Za-z\\d][A-Za-z\\d-]*(?:\\.[A-Za-z\\d][A-Za-z\\d-]*)+)$')
  agency_id: str
  property feature_class: NG911FeatureClass
  layer: str
  local_id: str
  property nguid_field: NG911Field

class RoadRangeCoverage(name: str, community: str, esn: str, odd_ranges: ndarray | Sequence[tuple[int, int]] | None = None, even_ranges: ndarray | Sequence[tuple[int, int]] | None = None, both_ranges: ndarray | Sequence[tuple[int, int]] | None = None, source_id: str | int | None = None, odd_side: Literal['LEFT', 'RIGHT'] | None = None, even_side: Literal['LEFT', 'RIGHT'] | None = None)

  Bases: `object`

  Keeps track of address ranges covered by a road, even if that road is represented by multiple features with non-adjacent ranges.

  Unlike `AddressRange`, this class is not intended to keep track of or compare the address ranges of individual features. The method `_consolidate()`, called as part of various internal procedures, automatically sorts and (when applicable) merges address ranges.

  static _consolidate_side(ranges: ArrayLike[np.int32]) → np.ndarray

    Implements much of the logic for, and is only intended to be called from, `_consolidate()`.

  static _intersect_side(ranges1: ndarray, ranges2: ndarray) → ndarray

    Implements much of the logic for, and is only intended to be called from, `__and__()`.

  static _split_both(both_range: ndarray) → tuple[ndarray, ndarray]
  static _sub_side(ranges1: ndarray, ranges2: ndarray) → ndarray
  static _validate_array_parity(ranges: ndarray, parity: Parity) → None
  _consolidate() → None
  nonzero_contains(item: int) → bool

    Returns whether the value is within the ranges. Unlike `__contains__()`, however, `0` is not considered to be in the ranges.

  _even_ranges: ndarray

    Even address ranges as a 2D array. Each entry on axis 0 represents a range, and the two entries on axis 1 represent the from- and to-values, in that order. This array is not guaranteed to be consolidated. For a consolidated array, use `even_ranges`.

  _is_consolidated: bool

    Whether `_consolidate()` has been called since either range array was last updated.

  _odd_ranges: ndarray

    Odd address ranges as a 2D array. Each entry on axis 0 represents a range, and the two entries on axis 1 represent the from- and to-values, in that order. This array is not guaranteed to be consolidated. For a consolidated array, use `odd_ranges`.

  community: str

    MSAG community for the range. Intended to correspond to `
    MSAGComm_L`, or `
    MSAGComm_R`

  property empty: bool
  esn: str

    ESN for the range. Intended to correspond to `
    Esn_L` or `
    Esn_R`.

  property even_ranges: ndarray
  even_side: Literal['LEFT', 'RIGHT'] | None

    Side of the road with even parity.

  name: str

    Full name of the road. Intended to correspond to `
    FullName` or `
    LgcyFulSt`.

  property odd_ranges: ndarray
  odd_side: Literal['LEFT', 'RIGHT'] | None

    Side of the road with odd parity.

  source_id: int | str | None

    ID from the data source. If provided, this should correspond to `
    NGUID_RDCL` or to the MSAG row number.

_oe_set: Final[frozenset[Parity]] = frozenset({Parity.EVEN, Parity.ODD})

  A `frozenset` of `Parity.ODD` and `Parity.EVEN`, intended for use like `if parity in _oe_set: ...`.