mainegeo.elections

   1"""Functions for parsing Maine Secretary of State election reporting units.
   2
   3The Maine SoS uses reporting units that provide the following challenges for parsing:
   4    1. Reporting units may be composed of one or several towns.
   5    2. Reporting units may include a non-reporting registration town.
   6    3. Reporting units may include an unspecified group of all townships that register at a
   7       particular town, or in a particular county.
   8    4. Delimiters, indicators of reporting vs. registration, and indicators of township aliases
   9       are not standard over time.
  10
  11This module provides methods for parsing Maine election result strings into consistent objects, 
  12extracting reporting and registration towns, and standardizing the format of unspecified town groups.
  13
  14The entry point methods of this module can all be run on a delimited result string containing 
  15multiple towns.
  16
  17Consider the following raw election result strings:
  18    * `T12/R13 & T9/R8 WELS (ASHLAND)`
  19    * `SHERMAN (AND BENEDICTA & SILVER RIDGE TWP) `
  20    * `BERRY/CATHANCE/MARION TWPS (EAST MACHIAS)`
  21    * `BARNARD TWP, EBEEMEE TWP (T5 R9 NWP), T4 R9 NWP TWP`
  22    * `MOUNT CHASE -- T5 R7 TWP`
  23    * `ISLAND FALLS -- T4-R3 TWP`
  24    * `DOVER-FOXCROFT`
  25
  26These examples display huge variation in how formatting is used to convey information.
  27
  28
  29Parentheses are used in three different ways in these examples:
  30
  31* In `T12/R13 & T9/R8 WELS (ASHLAND)`, parentheses convey that `Ashland`
  32    is a non-reporting registration town.
  33* In `EBEEMEE TWP (T5 R9 NWP)`, parentheses convey that `T5 R9 NWP` is 
  34    an alias of `EBEEMEE TWP`.
  35* In `SHERMAN (AND BENEDICTA & SILVER RIDGE TWP)`, parentheses convey that
  36    this reporting unit includes all of `SHERMAN`, `BENEDICTA`, and `SILVER RIDGE`,
  37    and that all three voted in `SHERMAN`.
  38
  39
  40Ampersands, commas, and forward slashes are all used interchangeably to delimit 
  41geographies within a string:
  42
  43* `BARNARD TWP, EBEEMEE TWP (T5 R9 NWP), T4 R9 NWP TWP` is delimited with commas.
  44* `BERRY/CATHANCE/MARION TWPS (EAST MACHIAS)` is delimited with forward slashes (`/`).
  45* `SHERMAN (AND BENEDICTA & SILVER RIDGE TWP) ` contains two different 
  46    delimiters--the ampersand character (`&`) and the substring `AND`.
  47    
  48    
  49Forward slashes are sometimes used as delimiters, but in `T12/R13` and
  50`T9/R8 WELS` they are used to separate township and range designators. Each of 
  51`T12/R13` and `T9/R8 WELS` is a single township, correctly written as `T12 R13` 
  52and `T9 R8 WELS`.
  53
  54
  55Hyphens and parentheses are used interchangeably to indicate 
  56a non-reporting registration town:
  57
  58* In `MOUNT CHASE -- T5 R7 TWP`, `MOUNT CHASE` is the registration town and 
  59    `T5 R7 TWP` is the reporting town. `MOUNT CHASE` is not included in the vote totals 
  60    for this reporting unit. 
  61* In `BERRY/CATHANCE/MARION TWPS (EAST MACHIAS)`, `EAST MACHIAS` is the registration
  62    town and `BERRY TWP`, `CATHANCE TWP`, and `MARION TWP` are all reporting towns.
  63    `EAST MACHIAS` is not included in the vote totals for this reporting unit.
  64        
  65However, both characters are also used in other ways (see above).
  66    
  67    
  68Single hyphens occur in the canonical names of towns, such as 
  69`DOVER-FOXCROFT`, and are sometimes used non-canonically to separate township
  70and range designators, as in the case of `T4-R3 TWP` (correctly written as `T4 R3`).
  71
  72
  73Ampersands also occur in the canonical names of some townships,
  74e.g. `King & Bartlett Twp`.
  75
  76
  77Examples:
  78    **Example 1**
  79    >>> raw_string = 'T12/R13 & T9/R8 WELS (ASHLAND)'
  80    
  81    Variations present:
  82    
  83    * Ampersand (`&`) is used as a token boundary
  84    * parentheses (`()`) indicate a non-reporting registration town
  85    * Forward slash (`/`), a character that sometimes serves as a token boundary,
  86    is used non-canonically to separate the township and range designators in a 
  87    township name
  88    
  89    >>> result = ResultString(raw_string)
  90    >>> result.normalized_string
  91    'T12 R13, T9 R8 WELS (ASHLAND)'
  92    >>> result.reporting_town_names
  93    ['T12 R13', 'T9 R8 WELS']
  94    >>> result.registration_town_names
  95    ['ASHLAND']
  96
  97
  98    **Example 2**
  99    >>> raw_string = 'SHERMAN (AND BENEDICTA & SILVER RIDGE TWP) '
 100    
 101    Variations present:
 102    
 103    * Ampersand (`&`) and the substring `AND` are both used as token boundaries
 104    * Parentheses (`()`) used to group part of the reporting unit
 105    * Trailing whitespace
 106        
 107    >>> result = ResultString(raw_string)
 108    >>> result.normalized_string
 109    'SHERMAN, BENEDICTA, SILVER RIDGE TWP'
 110    >>> result.reporting_town_names
 111    ['SHERMAN', 'BENEDICTA', 'SILVER RIDGE TWP']
 112    >>> result.registration_town_names
 113    []
 114        
 115
 116    **Example 3**
 117    >>> raw_string = 'BERRY/CATHANCE/MARION TWPS (EAST MACHIAS)'
 118    
 119    Variations present:
 120    
 121    * Forward slash (`/`) used as token boundary
 122    * Parentheses (`()`) used to indicate non-reporting registration town
 123        
 124    >>> result = ResultString(raw_string)
 125    >>> result.normalized_string
 126    'BERRY, CATHANCE, MARION TWPS (EAST MACHIAS)'
 127    >>> result.reporting_town_names
 128    ['BERRY', 'CATHANCE', 'MARION TWPS']
 129    >>> result.registration_town_names
 130    ['EAST MACHIAS']
 131    
 132    Note that the plural 'TWPS' is left unaltered. ResultString operations are 
 133    not concerned with what real-world geography or geographies a token represents 
 134    (e.g. whether MARION TWPS is a variation of MARION TWP or group of townships 
 135    that vote at MARION, whether MARION TWP is even a valid town name, etc).
 136    
 137    
 138    **Example 4**
 139    >>> raw_string = 'BARNARD TWP, EBEEMEE TWP (T5 R9 NWP), T4 R9 NWP TWP'
 140    
 141    Variations present:
 142    
 143    * Parentheses (`()`) used to indicate township alias, not registration
 144    town
 145
 146    >>> result = ResultString(raw_string)
 147    >>> result.normalized_string
 148    'BARNARD TWP, EBEEMEE TWP (T5 R9 NWP), T4 R9 NWP TWP'
 149    >>> result.reporting_town_names
 150    ['BARNARD TWP', 'EBEEMEE TWP T5 R9 NWP', 'T4 R9 NWP']
 151    >>> result.registration_town_names
 152    []
 153        
 154        
 155    **Example 5**
 156    >>> raw_string = 'MOUNT CHASE -- T5 R7 TWP'
 157    
 158    Variations present:
 159    
 160    * Double hyphen (`--`) used to indicate non-reporting registration
 161    town
 162
 163    >>> result = ResultString(raw_string)
 164    >>> result.normalized_string
 165    'MOUNT CHASE--T5 R7 TWP'
 166    >>> result.reporting_town_names
 167    ['T5 R7']
 168    >>> result.registration_town_names
 169    ['MOUNT CHASE']
 170    
 171    
 172    **Example 6**
 173    >>> raw_string = 'ISLAND FALLS -- T4-R3 TWP'
 174    
 175    Variations present:
 176    
 177    * Double hyphen (`--`) used to indicate non-reporting registration
 178    town
 179    * Hyphen, (`-`), a character that sometimes serves as a token boundary,
 180    is used non-canonically to separate the township and range designators 
 181    in a township name
 182
 183    >>> result = ResultString(raw_string)
 184    >>> result.normalized_string
 185    'ISLAND FALLS--T4 R3 TWP'
 186    >>> result.reporting_town_names
 187    ['T4 R3']
 188    >>> result.registration_town_names
 189    ['ISLAND FALLS']
 190        
 191
 192    **Example 7**
 193    >>> raw_string = 'DOVER-FOXCROFT'
 194    
 195    Variations present:
 196    
 197    * Hyphen, (`-`), a character that sometimes indicates a registration town,
 198    is used in the canonical name for a town
 199
 200    >>> result = ResultString('DOVER-FOXCROFT')
 201    >>> result.normalized_string
 202    'DOVER-FOXCROFT'
 203    >>> result.reporting_town_names
 204    ['DOVER-FOXCROFT']
 205    >>> result.registration_town_names
 206    []
 207"""
 208
 209__docformat__ = 'google'
 210
 211__all__ = [
 212    'ResultString',
 213    'ReportingUnit'
 214]
 215
 216import re
 217from dataclasses import dataclass, asdict
 218from functools import cached_property
 219from typing import List, Type
 220from itertools import filterfalse
 221
 222from mainegeo._vendor import replace_all, normalize_whitespace, chain_operations
 223from mainegeo.matching import get_town_database
 224from mainegeo.entities import County, Cousub
 225from mainegeo.townships import (
 226    clean_code,
 227    clean_codes,
 228    clean_town,
 229    is_unnamed_township,
 230    has_alias,
 231    extract_alias
 232)
 233from mainegeo.patterns import (
 234    KNOWN_TYPOS,
 235    AMBIGUOUS_GROUPS,
 236    DROP_CHARACTERS_PATTERN,
 237    STANDARD_DELIMITER,
 238    NONSTANDARD_DELIMITER_PATTERN,
 239    ORPHAN_PARENTHESIS_PATTERN,
 240    REGISTRATION_PATTERN,
 241    UNSPECIFIED_FLAG,
 242    STANDARD_FLAG,
 243    MULTI_COUNTY_PATTERN,
 244    MULTI_COUNTY_FORMAT,
 245    MULTI_COUNTY_REGISTRATION_TOWNS,
 246    PLURAL,
 247    SINGULAR,
 248    PLURAL_PATTERN,
 249    SINGULAR_PATTERN,
 250    VALID_AMPERSANDS_PATTERN,
 251    FORMATTED_GROUP_PATTERN
 252)
 253
 254@dataclass
 255class ResultString:
 256    """
 257    A string containing one or more geographies from raw election results.
 258    
 259    This dataclass performs initial normalization and parsing operations on a raw 
 260    election result string. It owns operations that are fully agnostic to which
 261    geographies the tokens in the string represent.
 262    
 263    These operations normalize variations in meaningful formatting (including 
 264    whitespace, delimiters, and other punctuation) so that two types of parsing can occur:
 265
 266    1. The splitting of result strings into a list of tokens, each
 267        one representing a single geography.
 268    2. The separation of tokens representing reporting geographies from tokens 
 269        representing non-reporting registration towns.
 270    
 271    Args:
 272        raw_string: The raw string representation of the reporting unit
 273    """
 274    raw_string: str
 275    
 276    @cached_property
 277    def exists(self) -> bool:
 278        if self.raw_string is None:
 279            return False
 280        elif len(self.raw_string) > 5:
 281            return True
 282        elif re.search(r'\w', self.raw_string):
 283            return True
 284        else:
 285            return False
 286        
 287    @cached_property
 288    def normalized_string(self) -> str:
 289        """
 290        Result string with capitalization, whitespace and delimiters normalized.
 291
 292        Errors entered in `mainegeo.lookups.Overrides.known_typos` and 
 293        `mainegeo.lookups.Overrides.ambiguous_groups` are also repaired.
 294
 295        Example:
 296            >>> result = ResultString('FORT KENT/BIG TWENTY TWP/   T15 R15 WELS')
 297            >>> result.normalized_string
 298            'FORT KENT, BIG TWENTY TWP, T15 R15 WELS'
 299            
 300            >>> result = ResultString('T12/R13 WELS/T9 R8 WELS')
 301            >>> result.normalized_string
 302            'T12 R13 WELS, T9 R8 WELS'
 303            
 304            >>> result = ResultString('T10 SD TWP (CHERRYFIELD, FRANKLIN & MILBRIDGE)')
 305            >>> result.normalized_string
 306            'T10 SD TWP (CHERRYFIELD, FRANKLIN, MILBRIDGE)'
 307        """
 308        initial_cleanup = [
 309            str.upper
 310            , ResultString._fix_known_typos
 311            , ResultString._rename_ambiguous_groups
 312            , ResultString._drop_non_meaningful_chars
 313            , clean_codes
 314            , ResultString._normalize_delimiters
 315            , normalize_whitespace
 316        ]
 317        if self.exists:
 318            return chain_operations(self.raw_string, initial_cleanup)
 319    
 320    @cached_property
 321    def registration_town_names(self) -> List[str]:
 322        """
 323        List of registration town names extracted from result string.
 324
 325        Note:
 326            Splits strings by package-level `STANDARD_DELIMITER`.
 327
 328        Example:
 329            >>> result = ResultString('MOUNT CHASE -- T5 R7 TWP')
 330            >>> result.registration_town_names
 331            ['MOUNT CHASE']
 332            
 333            >>> result = ResultString('T7 SD TWP (STEUBEN)')
 334            >>> result.registration_town_names
 335            ['STEUBEN']
 336            
 337            >>> result = ResultString('CROSS LAKE TWP (T17 R5)')
 338            >>> result.registration_town_names
 339            []
 340            
 341            >>> result = ResultString('ARGYLE TWP (ALTON, EDINBURG)')
 342            >>> result.registration_town_names
 343            ['ALTON', 'EDINBURG']
 344        """
 345        if self._registration_town_substring is None:
 346            return []
 347        else:
 348            reg_towns = self._registration_town_substring.split(STANDARD_DELIMITER)
 349            return list(map(clean_town, reg_towns))
 350
 351    @cached_property
 352    def reporting_town_names(self) -> List[str]:
 353        """
 354        Extract list of reporting town names from result string.
 355
 356        Note:
 357            Drops parentheses around township alias, but does not remove alias.
 358
 359        Args:
 360            result_str: Delimited result string with one or more towns or townships
 361
 362        Returns:
 363            List: Reporting towns with formatting identifiers stripped
 364
 365        Example:
 366            >>> ResultString('MOUNT CHASE--T5 R7 TWP').reporting_town_names
 367            ['T5 R7']
 368            
 369            >>> ResultString('HERSEYTOWN, SOLDIERTOWN TWPS (MEDWAY)').reporting_town_names
 370            ['HERSEYTOWN', 'SOLDIERTOWN TWPS']
 371            
 372            >>> ResultString('ARGYLE TWP (ALTON, EDINBURG)').reporting_town_names
 373            ['ARGYLE TWP']
 374            
 375            >>> ResultString('BARNARD TWP, EBEEMEE TWP (T5 R9 NWP), T4 R9 NWP TWP').reporting_town_names
 376            ['BARNARD TWP', 'EBEEMEE TWP T5 R9 NWP', 'T4 R9 NWP']
 377            
 378            >>> ResultString('BERRY/CATHANCE/MARIONTWPS (EAST MACHIAS)').reporting_town_names
 379            ['BERRY', 'CATHANCE', 'MARION TWPS']
 380        """
 381        if self._registration_town_substring is None:
 382            reporting_substr = self.normalized_string
 383        else:
 384            reporting_substr = re.sub(self._registration_town_substring, '', self.normalized_string)
 385
 386        reporting = reporting_substr.split(STANDARD_DELIMITER)
 387        return list(map(clean_town, reporting))
 388
 389    @cached_property
 390    def _registration_town_substring(self) -> str:
 391        """
 392        Registration town substring extracted based on SoS formatting identifiers.
 393
 394        SoS formatting identifiers include parentheticals and double dashes (--).
 395        Parentheticals that are township aliases are ignored. 
 396
 397        Note:
 398            Substring includes formatting indicators.
 399
 400        Raises:
 401            ValueError: If result string contains multiple registration town substrings.
 402
 403        Examples:
 404            >>> result = ResultString('MOUNT CHASE -- T5 R7 TWP')
 405            >>> result._registration_town_substring
 406            'MOUNT CHASE--'
 407            
 408            >>> result = ResultString('T7 SD TWP (STEUBEN)')
 409            >>> result._registration_town_substring
 410            '(STEUBEN)'
 411            
 412            >>> result = ResultString('ARGYLE TWP (ALTON, EDINBURG)')
 413            >>> result._registration_town_substring
 414            '(ALTON, EDINBURG)'
 415        """
 416        if self.exists:
 417            flagged = REGISTRATION_PATTERN.findall(self.normalized_string)
 418            substrings = list(filterfalse(is_unnamed_township, flagged))
 419            
 420            if len(substrings) > 1:
 421                raise ValueError(f'Multiple registration town substrings found in result string: {self.normalized_string}')
 422            elif len(substrings) == 0:
 423                return None
 424            else:
 425                return substrings[0]
 426
 427    @staticmethod
 428    def _fix_known_typos(result_str: str) -> str:
 429        """
 430        Fix known typos in-place in string.
 431
 432        These typos are true misspellings, which are unique and unlikely to be repeated.
 433        They are stored in the KNOWN_TYPOS dict in the patterns module.
 434
 435        Args:
 436            result_str: Delimited result string with one or more towns or townships
 437        """
 438        return replace_all(KNOWN_TYPOS, result_str)
 439
 440    @staticmethod
 441    def _rename_ambiguous_groups(result_str: str) -> str:
 442        """
 443        Fix ambiguous unspecified group names in-place in string.
 444
 445        These typos recur from time to time, but follow a general pattern. It simplifies
 446        unspecified group name detection significantly if they are corrected early in
 447        processing. They are stored in `lookups.Overrides.ambiguous_groups`.
 448
 449        Args:
 450            result_str: Delimited result string with one or more towns or townships
 451
 452        Example:
 453            >>> ResultString._rename_ambiguous_groups('MILLINOCKET -- PISCATAQUIS TWP')
 454            'MILLINOCKET -- PISCATAQUIS TWPS'
 455            
 456            >>> ResultString._rename_ambiguous_groups('PENOBSCOT TWPS')
 457            'MILLINOCKET PENOBSCOT TWPS'
 458        """
 459        return replace_all(AMBIGUOUS_GROUPS, result_str)
 460
 461    @staticmethod
 462    def _drop_non_meaningful_chars(result_str: str) -> str:
 463        """
 464        Drop or replace special characters that don't communicate meaningful info.
 465
 466        Non-meaningful characters include all punctuation characters not found in
 467        `mainegeo.patterns.MEANINGFUL_CHARACTERS`.
 468
 469        Args:
 470            result_str: Delimited result string with one or more towns or townships
 471        """
 472        result = VALID_AMPERSANDS_PATTERN.sub('AND', normalize_whitespace(result_str))
 473        return DROP_CHARACTERS_PATTERN.sub('', result)
 474
 475    @staticmethod
 476    def _normalize_delimiters(result_str: str) -> str:
 477        """
 478        Replace all delimiters in result string with standard delimiter.
 479
 480        Args:
 481            result_str: Delimited result string with one or more towns or townships
 482        """
 483        delimit = NONSTANDARD_DELIMITER_PATTERN.sub(STANDARD_DELIMITER, result_str)
 484        cleanup = ORPHAN_PARENTHESIS_PATTERN.sub(r'\g<result>', delimit)
 485        return cleanup
 486
 487@dataclass(frozen=True)
 488class ResultGeo:
 489    name: str
 490    county: County
 491    strict: bool = False
 492    
 493    @classmethod
 494    def from_strings(cls, name: str, county_code: str, strict: bool = False) -> "ResultGeo":
 495        return cls(
 496            name = name,
 497            county = County(code=county_code),
 498            strict = strict
 499        )
 500
 501@dataclass(frozen=True)
 502class Municipality(ResultGeo):
 503    @cached_property
 504    def matched_town(self):
 505        return get_town_database().match(
 506            self.name,
 507            self.county.fips,
 508            cleaned = True,
 509            strict = self.strict
 510        )
 511    
 512    @property
 513    def is_matched(self):
 514        return self.matched_town is not None
 515    
 516    @property
 517    def canonical_name(self):
 518        if self.matched_town:
 519            return self.matched_town.name
 520
 521    @property
 522    def consensus_name(self):
 523        return self.canonical_name or self.name
 524    
 525    @cached_property
 526    def matched_geocode(self) -> str:
 527        if self.matched_town:
 528            return self.matched_town.geocode
 529        
 530    @cached_property
 531    def matched_cousub(self) -> Cousub:
 532        return self.matched_town.cousub if self.matched_town else Cousub()
 533        
 534    @cached_property
 535    def matched_county(self) -> County:
 536        return self.matched_town.county if self.matched_town else County()
 537    
 538    def to_dict(self) -> dict[str]:
 539        return {
 540            'name':             self.consensus_name,
 541            'canonical_name':   self.canonical_name,
 542            'raw_name':         self.name,
 543            'county':           asdict(self.matched_county),
 544            'cousub':           asdict(self.matched_cousub),
 545            'geocode':          self.matched_geocode,
 546            'is_matched':       self.is_matched
 547        }
 548
 549@dataclass(frozen=True)
 550class NamedTownship(Municipality):
 551    pass
 552    
 553@dataclass(frozen=True)
 554class UnnamedTownship(Municipality):
 555    @property
 556    def has_alias(self):
 557        return has_alias(self.name)
 558    
 559    @property
 560    def alias(self):
 561        return extract_alias(self.name)
 562    
 563    @property
 564    def code(self):
 565        return clean_code(self.name)
 566
 567@dataclass(frozen=True)
 568class UnspecifiedGroup(ResultGeo):
 569    @cached_property
 570    def _format_match(self) -> re.Match:
 571        return FORMATTED_GROUP_PATTERN.match(self.name)
 572    
 573    @property
 574    def is_matched(self) -> bool:
 575        return all((self._format_match, self.group_registration_town.is_matched))
 576
 577    @property
 578    def group_county(self) -> County:
 579        county_code = self._format_match.group('cty') or self.county.code
 580        return County(code = county_code)
 581    
 582    @property
 583    def group_registration_town(self) -> NamedTownship:
 584        reg_town_name = self._format_match.group('regtown')
 585        return NamedTownship(
 586            name = reg_town_name,
 587            county = self.county,
 588            strict = self.strict
 589        )
 590    
 591    @property
 592    def canonical_name(self):
 593        regtown = self.group_registration_town.consensus_name
 594        
 595        if regtown.upper() in MULTI_COUNTY_REGISTRATION_TOWNS:
 596            county = f' {self.group_county.name} County '
 597        else:
 598            county = ' '
 599            
 600        formatted = f'{STANDARD_FLAG}{county}{UNSPECIFIED_FLAG}'
 601        return formatted.title()
 602    
 603    @property
 604    def consensus_name(self):
 605        return self.canonical_name or self.name
 606    
 607    def to_dict(self):
 608        return {
 609            'name':                     self.consensus_name,
 610            'canonical_name':           self.canonical_name,
 611            'raw_name':                 self.name,
 612            'county':                   asdict(self.group_county),
 613            'group_registration_town':  self.group_registration_town.to_dict(),
 614            'is_matched':               self.is_matched
 615        }
 616
 617@dataclass
 618class ReportingUnit:
 619    """A collection of towns and unspecified groups parsed from a `ResultString`.
 620        
 621    This class performs normalization operations on individual fragments of a 
 622    delimited string, coerces them into objects representing different geography
 623    types, and attempts to match them to known Maine geographies. It provides several
 624    options for representing the fully parsed unit as a string or dictionary.
 625
 626    Args:
 627        result_string: A `ResultString` object
 628        county: A `County` object
 629        strict: True if exception should be raised when a match fails
 630    """
 631    result_string: ResultString
 632    county: County
 633    strict: bool = False
 634
 635    @classmethod
 636    def from_strings(
 637        cls,
 638        result_str: str,
 639        county_code: str,
 640        strict: bool = False
 641    ) -> "ReportingUnit":
 642        """ Factory method to create a fully processed ReportingUnit.
 643        
 644        Examples:
 645            >>> result = ReportingUnit.from_strings('PRENTISS TWP (WEBSTER PLT)', 'PEN')
 646            >>> result.formatted_string
 647            'Prentiss Twp T7 R3 NBPP [Webster Plt]'
 648            >>> result.reporting_town_names
 649            ['Prentiss Twp T7 R3 NBPP']
 650            >>> result.registration_town_names
 651            ['Webster Plt']
 652            >>> result.unspecified_groups
 653            []
 654            
 655            >>> result = ReportingUnit.from_strings('MEDWAY -- GRINDSTONE/SOLDIERTOWN TWPS', 'PEN')
 656            >>> result.formatted_string
 657            'Grindstone Twp [Medway], Soldiertown Twp T2 R7 WELS [Medway]'
 658            >>> result.reporting_town_names
 659            ['Grindstone Twp', 'Soldiertown Twp T2 R7 WELS']
 660            >>> result.registration_town_names
 661            ['Medway']
 662            
 663            >>> result = ReportingUnit.from_strings('FRANKLIN/T9 T10 SD TWPS', 'HAN')
 664            >>> result.formatted_string
 665            'Franklin, T9 SD BPP, T10 SD BPP'
 666            >>> result.reporting_town_names
 667            ['Franklin', 'T9 SD BPP', 'T10 SD BPP']
 668            >>> result.registration_town_names
 669            []
 670            
 671            >>> result = ReportingUnit.from_strings('MILLINOCKET/PISCATAQUIS TWPS', 'PEN')
 672            >>> result.formatted_string
 673            'Millinocket, Unspecified Piscataquis County Twps [Millinocket]'
 674            >>> result.reporting_town_names
 675            ['Millinocket', 'Unspecified Piscataquis County Twps']
 676            >>> result.registration_town_names
 677            ['Millinocket']
 678            >>> len(result.unspecified_groups)
 679            1
 680            
 681            >>> result = ReportingUnit.from_strings('MILLINOCKET/PIS TWPS/PEN TWPS', 'PEN')
 682            >>> result.reporting_town_names
 683            ['Millinocket', 'Unspecified Piscataquis County Twps', 'Unspecified Penobscot County Twps']
 684            >>> result.registration_town_names
 685            ['Millinocket']
 686            >>> len(result.unspecified_groups)
 687            2
 688            
 689            >>> result = ReportingUnit.from_strings('MEDWAY TOWNSHIPS', 'PEN')
 690            >>> result.formatted_string
 691            'Unspecified Twps [Medway]'
 692            >>> result.reporting_town_names
 693            ['Unspecified Twps']
 694            >>> result.registration_town_names
 695            ['Medway']
 696            >>> len(result.unspecified_groups)
 697            1
 698            """
 699        unit = cls(
 700            result_string = ResultString(result_str),
 701            county = County(code = county_code),
 702            strict = strict
 703        )
 704        return unit
 705    
 706    @property
 707    def raw_string(self) -> str:
 708        """
 709        Original SoS name for this reporting unit.
 710        
 711        Examples:
 712            >>> unit = ReportingUnit.from_strings('WEBSTER PLT -- PRENTISS TWP', 'PEN')
 713            >>> unit.raw_string
 714            'WEBSTER PLT -- PRENTISS TWP'
 715        """
 716        return self.result_string.raw_string
 717
 718    @cached_property
 719    def formatted_string(self) -> str:
 720        """
 721        A formatted string representation of this reporting unit.
 722        
 723        Examples:
 724            >>> args = ('T12/R13 & T9/R8 WELS (ASHLAND)', 'ARO')
 725            >>> ReportingUnit.from_strings(*args).formatted_string
 726            'T12 R13 WELS [Ashland], T9 R8 WELS [Ashland]'
 727            
 728            >>> args = ('GRINDSTONE/HERSEYTOWN/SOLDIERTOWN TWP', 'PEN')
 729            >>> ReportingUnit.from_strings(*args).formatted_string
 730            'Grindstone Twp, Herseytown Twp, Soldiertown Twp T2 R7 WELS'
 731            
 732            >>> args = ('SHERMAN (AND BENEDICTA & SILVER RIDGE TWPS) ', 'ARO')
 733            >>> ReportingUnit.from_strings(*args).formatted_string
 734            'Sherman, Benedicta Twp, Silver Ridge Twp'
 735            
 736            >>> args = ('JACKMAN TWPS', 'SOM')
 737            >>> ReportingUnit.from_strings(*args).formatted_string
 738            'Unspecified Twps [Jackman]'
 739            
 740            >>> args = ('MILLINOCKET/PISCATAQUIS TWPS', 'PEN')
 741            >>> ReportingUnit.from_strings(*args).formatted_string
 742            'Millinocket, Unspecified Piscataquis County Twps [Millinocket]'
 743        """
 744        reporting = [
 745            town + f' [{self.registration_string}]'
 746            if
 747                len(self.registration_town_names) > 0
 748                and town not in self.registration_town_names
 749            else town
 750            for town in self.reporting_town_names
 751        ]
 752        return STANDARD_DELIMITER.join(reporting)
 753    
 754    @cached_property
 755    def reporting_string(self) -> str:
 756        """
 757        A formatted string representation of reporting towns in this unit.
 758
 759        Examples:
 760            >>> args = ('WEBSTER PLT -- PRENTISS TWP', 'PEN')
 761            >>> ReportingUnit.from_strings(*args).reporting_string
 762            'Prentiss Twp T7 R3 NBPP'
 763            
 764            >>> args = ('T12/R13 & T9/R8 WELS (ASHLAND)', 'ARO')
 765            >>> ReportingUnit.from_strings(*args).reporting_string
 766            'T12 R13 WELS, T9 R8 WELS'
 767            
 768            >>> args = ('JACKMAN TWPS', 'SOM')
 769            >>> ReportingUnit.from_strings(*args).reporting_string
 770            'Unspecified Twps'
 771            
 772            >>> args = ('MILLINOCKET/PISCATAQUIS TWPS', 'PEN')
 773            >>> ReportingUnit.from_strings(*args).reporting_string
 774            'Millinocket, Unspecified Piscataquis County Twps'
 775            
 776            >>> args = ('MILLINOCKET/PEN TWPS/PIS TWPS', 'PEN')
 777            >>> ReportingUnit.from_strings(*args).reporting_string
 778            'Millinocket, Unspecified Penobscot County Twps, Unspecified Piscataquis County Twps'
 779        """
 780        return STANDARD_DELIMITER.join(self.reporting_town_names)
 781    
 782    @cached_property
 783    def registration_string(self) -> str:
 784        """
 785        A formatted string representation of registration towns in this unit.
 786        
 787        Examples:
 788            >>> args = ('WEBSTER PLT -- PRENTISS TWP', 'PEN')
 789            >>> ReportingUnit.from_strings(*args).registration_string
 790            'Webster Plt'
 791            
 792            >>> args = ('WYMAN TWP (CARRABASSETT VALLEY & EUSTIS)', 'FRA')
 793            >>> ReportingUnit.from_strings(*args).registration_string
 794            'Carrabassett Valley, Eustis'
 795            
 796            >>> args = ('JACKMAN TWPS', 'SOM')
 797            >>> ReportingUnit.from_strings(*args).registration_string
 798            'Jackman'
 799            
 800            >>> args = ('MILLINOCKET/PISCATAQUIS TWPS', 'PEN')
 801            >>> ReportingUnit.from_strings(*args).registration_string
 802            'Millinocket'
 803            
 804            >>> args = ('MILLINOCKET/PIS TWPS/PEN TWPS', 'PEN')
 805            >>> ReportingUnit.from_strings(*args).registration_string
 806            'Millinocket'
 807        """
 808        return STANDARD_DELIMITER.join(self.registration_town_names)
 809                
 810    @cached_property
 811    def reporting_town_names(self) -> list[str]:
 812        """
 813        List of reporting town names. Canonical name if match was found, else raw name.
 814        """
 815        return [town.consensus_name for town in self.reporting_towns]
 816    
 817    @cached_property
 818    def registration_town_names(self) -> list[str]:
 819        """
 820        List of registration town names. Canonical name if match was found, else raw name.
 821        """
 822        return [town.consensus_name for town in self.registration_towns]
 823
 824    @cached_property
 825    def registration_towns(self) -> List[NamedTownship]:
 826        """
 827        List of registration towns as `NamedTownship` objects.
 828        """
 829        towns = set()
 830        for name in self.result_string.registration_town_names:
 831            regtown = NamedTownship(name, self.county, strict = self.strict)
 832            towns.add(regtown)
 833        
 834        for group in self.unspecified_groups:
 835            towns.add(group.group_registration_town)
 836        
 837        return sorted(towns, key=lambda town: town.consensus_name)
 838
 839    @cached_property
 840    def reporting_towns(self) -> List[ResultGeo]:
 841        """
 842        List of reporting towns, townships and groups as `ResultGeo` child objects.
 843        """
 844        towns = []
 845        
 846        if self.result_string.exists:
 847            formatted_reporting_names = ReportingUnit._format_reporting_towns(
 848                self.result_string.reporting_town_names,
 849                self.result_string.registration_town_names,
 850                self.has_unspecified_group
 851            )
 852            for name in formatted_reporting_names:
 853                ResultClass = ReportingUnit._classify_fragment(name)
 854                reporting_town = ResultClass(name, self.county, strict = self.strict)
 855                towns.append(reporting_town)
 856        
 857        return towns
 858    
 859    @cached_property
 860    def specified_reporting_towns(self) -> List[Municipality]:
 861        """
 862        List of reporting units that are not unspecified groups.
 863        
 864        Examples:
 865            >>> unit = ReportingUnit.from_strings('WYMAN TWP/SPRING LAKE TWP', 'FRA')
 866            >>> [town.name for town in unit.specified_reporting_towns]
 867            ['WYMAN TWP', 'SPRING LAKE TWP']
 868            
 869            >>> unit = ReportingUnit.from_strings('WYMAN TWP (CARRABASSETT VALLEY)', 'FRA')
 870            >>> [town.name for town in unit.specified_reporting_towns]
 871            ['WYMAN TWP']
 872
 873            >>> unit = ReportingUnit.from_strings('MILLINOCKET/TWPS', 'PEN')
 874            >>> [town.name for town in unit.specified_reporting_towns]
 875            ['MILLINOCKET']
 876            
 877            >>> unit = ReportingUnit.from_strings('MILLINOCKET TWPS', 'PEN')
 878            >>> [town.name for town in unit.specified_reporting_towns]
 879            []
 880        """
 881        return [t for t in self.reporting_towns if type(t) != UnspecifiedGroup]
 882    
 883    @cached_property
 884    def unspecified_groups(self) -> List[ResultGeo]:
 885        """
 886        List of reporting units that are unspecified groups.
 887        
 888        Examples:
 889            >>> unit = ReportingUnit.from_strings('MILLINOCKET/PEN TWPS', 'PEN')
 890            >>> groups = unit.unspecified_groups
 891            >>> [group.name for group in groups]
 892            ['UNSPECIFIED MILLINOCKET TWPS [PEN]']
 893            >>> [group.canonical_name for group in groups]
 894            ['Unspecified Penobscot County Twps']
 895            >>> [group.group_registration_town.canonical_name for group in groups]
 896            ['Millinocket']
 897        """
 898        return [t for t in self.reporting_towns if type(t) == UnspecifiedGroup]
 899    
 900    @cached_property
 901    def has_unspecified_group(self) -> bool:
 902        """
 903        Return True if the result object includes an unspecified group, else False.
 904
 905        Examples:
 906            >>> unit = ReportingUnit.from_strings('MEDWAY/TOWNSHIPS', 'PEN')
 907            >>> unit.has_unspecified_group
 908            True
 909            
 910            >>> unit = ReportingUnit.from_strings('ADAMSTOWN/LOWER CUPSUPTIC TWPS (RANGELEY)', 'OXF')
 911            >>> unit.has_unspecified_group
 912            False
 913            
 914            >>> unit = ReportingUnit.from_strings('MILLINOCKET PISCATAQUIS TWPS', 'PIS')
 915            >>> unit.has_unspecified_group
 916            True
 917            
 918            >>> unit = ReportingUnit.from_strings('MILLINOCKET/PEN TWPS', 'PEN')
 919            >>> unit.has_unspecified_group
 920            True
 921            
 922            >>> unit = ReportingUnit.from_strings('LEXINGTON & SPRING LAKE TWPS', 'SOM')
 923            >>> unit.has_unspecified_group
 924            False
 925        """
 926        reporting = self.result_string.reporting_town_names
 927        registration = self.result_string.registration_town_names
 928        group_name = ' '.join(filter(None, [*registration, *reporting]))
 929
 930        if len(registration) > 1:
 931            return False
 932        elif len(reporting) in (1, 2) and UNSPECIFIED_FLAG in reporting:
 933            return True
 934        elif all(UNSPECIFIED_FLAG in town for town in reporting):
 935            return True
 936        elif MULTI_COUNTY_PATTERN.match(group_name):
 937            return True
 938        else:
 939            return False
 940        
 941    @cached_property
 942    def is_matched(self) -> bool:
 943        """True if every named geography in this unit matched a known town."""
 944        if not self.result_string.exists:
 945            return False
 946        else:
 947            tokens = [*self.reporting_towns, *self.registration_towns]
 948            return bool(tokens) and all(t.is_matched for t in tokens)
 949        
 950    def to_dict(self) -> dict[str]:
 951        return {
 952            'raw_str':          self.raw_string,
 953            'formatted_str':    self.formatted_string,
 954            'reporting_str':    self.reporting_string,
 955            'registration_str': self.registration_string,
 956            'reporting':        {
 957                'specified':        [town.to_dict() for town in self.specified_reporting_towns],
 958                'unspecified':      [group.to_dict() for group in self.unspecified_groups]
 959                                },
 960            'registration':     [town.to_dict() for town in self.registration_towns],
 961            'county':           asdict(self.county),
 962            'is_matched':       self.is_matched
 963        }
 964
 965    @staticmethod
 966    def _format_reporting_towns(
 967            reporting_town_names: List[str], 
 968            registration_town_names: List[str], 
 969            has_unspecified_group: bool) -> List[str]:
 970        """
 971        Apply consistent format to towns and unspecified groups.
 972
 973        Args:
 974            reporting_towns: List of one or more towns
 975            registration_towns: List of non-reporting registration towns (if any)
 976            has_unspecified_group: True if unit contains unspecified group, else False
 977
 978        Returns:
 979            list: Reporting towns with standard formatting applied.
 980
 981        Examples:
 982            >>> ReportingUnit._format_reporting_towns(['LEXINGTON', 'SPRING LAKE TWPS'], [], False)
 983            ['LEXINGTON', 'SPRING LAKE TWP']
 984            
 985            >>> ReportingUnit._format_reporting_towns(['FRANKLIN', 'TWPS'], [], True)
 986            ['FRANKLIN', 'UNSPECIFIED FRANKLIN TWPS']
 987            
 988            >>> ReportingUnit._format_reporting_towns(['PENOBSCOT TWPS'], ['MILLINOCKET'], True)
 989            ['UNSPECIFIED MILLINOCKET TWPS [PEN]']
 990        """
 991        reporting = [
 992            ReportingUnit._format_plural(town, has_unspecified_group)
 993            for town in reporting_town_names
 994        ]
 995        
 996        if has_unspecified_group:
 997            return ReportingUnit._name_unspecified_group(reporting, registration_town_names)
 998        else:
 999            return reporting
1000
1001    @staticmethod    
1002    def _format_plural(town: str, has_unspecified_group: bool) -> str:
1003        """
1004        Correct errors of pluralization in town or group names.
1005
1006        After this function is used, the presence or absence of a plural in a town name
1007        reliably indicates whether it is an unspecified group.
1008        """  
1009        if has_unspecified_group:
1010            return SINGULAR_PATTERN.sub(PLURAL, town)
1011        else:
1012            return PLURAL_PATTERN.sub(SINGULAR, town)
1013
1014    @staticmethod
1015    def _format_unspecified_group(group_name: str) -> str:
1016        """
1017        Apply special format to unspecified groups that include a county.
1018        """
1019        return MULTI_COUNTY_PATTERN.sub(MULTI_COUNTY_FORMAT, group_name)
1020        
1021    @staticmethod
1022    def _name_unspecified_group(
1023            reporting_town_names: List[str], 
1024            registration_town_names: List[str]) -> List[str]:
1025        """
1026        Label unspecified groups with their reporting town and a standard 'unspecified' flag.
1027        """
1028        is_specified_reporting = lambda token: UNSPECIFIED_FLAG not in token
1029        reporting_hosts = filter(is_specified_reporting, reporting_town_names)
1030        hosts = registration_town_names + list(reporting_hosts)
1031        
1032        formatted_tokens = []
1033        for town in reporting_town_names:
1034            if UNSPECIFIED_FLAG in town:                
1035                unformatted = ' '.join(filter(None, [STANDARD_FLAG, *hosts, town]))
1036                group_name = ReportingUnit._format_unspecified_group(unformatted)
1037                formatted_tokens.append(group_name)
1038            else:
1039                formatted_tokens.append(town)
1040        
1041        return formatted_tokens
1042    
1043    @staticmethod
1044    def _classify_fragment(fragment_name: str) -> Type[ResultGeo]:
1045        """
1046        Return correct ResultGeo child class for a reporting towns string fragment.
1047        """
1048        if is_unnamed_township(fragment_name):
1049            return UnnamedTownship
1050        elif UNSPECIFIED_FLAG in fragment_name:
1051            return UnspecifiedGroup
1052        else:
1053            return NamedTownship