atlus 0.2.2__py3-none-any.whl

atlus/__about__.py

@@ -0,0 +1,3 @@
+"""Top-level package for atlus_py."""
+
+__version__ = "0.2.2"

atlus/__init__.py

@@ -0,0 +1,44 @@
+"""`atlus` is a Python package to convert raw address and phone number strings into the OSM format.
+It's designed to be used with US and Canadian phone numbers and addresses.
+
+```python
+>>> import atlus
+>>> atlus.abbrs("St. Francis")
+"Saint Francis"
+>>> atlus.get_address("789 Oak Dr, Smallville California, 98765")[0]
+{"addr:housenumber": "789", "addr:street": "Oak Drive", "addr:city": "Smallville", "addr:state": "CA", "addr:postcode": "98765"}
+>>> atlus.get_phone("(202) 900-9019")
+"+1 202-900-9019"
+```
+
+"""
+
+# SPDX-FileCopyrightText: 2024-present Will <wahubsch@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from .atlus import (
+    get_address,
+    get_phone,
+    abbrs,
+    get_title,
+    mc_replace,
+    us_replace,
+    ord_replace,
+    remove_br_unicode,
+)
+from . import atlus
+from . import resources
+
+__all__ = [
+    "get_address",
+    "get_phone",
+    "abbrs",
+    "get_title",
+    "mc_replace",
+    "us_replace",
+    "ord_replace",
+    "remove_br_unicode",
+    "atlus",
+    "resources",
+]

atlus/atlus.py

@@ -0,0 +1,519 @@
+"""Functions and tools to process the raw address strings."""
+
+from collections import Counter
+from typing import Union, List, Dict, Tuple
+from pydantic import ValidationError
+import usaddress
+import regex
+
+from .objects import Address
+from .resources import (
+    street_expand,
+    direction_expand,
+    name_expand,
+    state_expand,
+    saint_comp,
+    abbr_join_comp,
+    dir_fill_comp,
+    sr_comp,
+    usa_comp,
+    paren_comp,
+    grid_comp,
+    post_comp,
+    street_comp,
+)
+
+toss_tags = [
+    "Recipient",
+    "IntersectionSeparator",
+    "LandmarkName",
+    "USPSBoxGroupID",
+    "USPSBoxGroupType",
+    "USPSBoxID",
+    "USPSBoxType",
+    "OccupancyType",
+]
+"""Tags from the `usaddress` package to remove."""
+
+osm_mapping = {
+    "AddressNumber": "addr:housenumber",
+    "AddressNumberPrefix": "addr:housenumber",
+    "AddressNumberSuffix": "addr:housenumber",
+    "StreetName": "addr:street",
+    "StreetNamePreDirectional": "addr:street",
+    "StreetNamePreModifier": "addr:street",
+    "StreetNamePreType": "addr:street",
+    "StreetNamePostDirectional": "addr:street",
+    "StreetNamePostModifier": "addr:street",
+    "StreetNamePostType": "addr:street",
+    "OccupancyIdentifier": "addr:unit",
+    "PlaceName": "addr:city",
+    "StateName": "addr:state",
+    "ZipCode": "addr:postcode",
+}
+"""Mapping from `usaddress` fields to OSM tags."""
+
+
+def get_title(value: str, single_word: bool = False) -> str:
+    """Fix ALL-CAPS string.
+
+    ```python
+    >>> get_title("PALM BEACH")
+    "Palm Beach"
+    >>> get_title("BOSTON")
+    "BOSTON"
+    >>> get_title("BOSTON", single_word=True)
+    "Boston"
+    ```
+
+    Args:
+        value: String to fix.
+        single_word: Whether the string should be fixed even if it is a single word.
+
+    Returns:
+        str: Fixed string.
+    """
+    if (value.isupper() and " " in value) or (value.isupper() and single_word):
+        return mc_replace(value.title())
+    return value
+
+
+def us_replace(value: str) -> str:
+    """Fix string containing improperly formatted US.
+
+    ```python
+    >>> us_replace("U.S. Route 15")
+    "US Route 15"
+    ```
+
+    Args:
+        value: String to fix.
+
+    Returns:
+        str: Fixed string.
+    """
+    return value.replace("U.S.", "US").replace("U. S.", "US").replace("U S ", "US ")
+
+
+def mc_replace(value: str) -> str:
+    """Fix string containing improperly formatted Mc- prefix.
+
+    ```python
+    >>> mc_replace("Fort Mchenry")
+    "Fort McHenry"
+    ```
+
+    Args:
+        value: String to fix.
+
+    Returns:
+        str: Fixed string.
+    """
+    words = []
+    for word in value.split():
+        mc_match = word.partition("Mc")
+        words.append(mc_match[0] + mc_match[1] + mc_match[2].capitalize())
+    return " ".join(words)
+
+
+def ord_replace(value: str) -> str:
+    """Fix string containing improperly capitalized ordinal.
+
+    ```python
+    >>> ord_replace("3Rd St. NW")
+    "3rd St. NW"
+    ```
+
+    Args:
+        value: String to fix.
+
+    Returns:
+        str: Fixed string.
+    """
+    return regex.sub(r"(\b\d+[SNRT][tTdDhH]\b)", lower_match, value)
+
+
+def name_street_expand(match: regex.Match) -> str:
+    """Expand matched street type abbreviations.
+
+    Args:
+        match (regex.Match): Matched string.
+
+    Returns:
+        str: Expanded string.
+    """
+    mat = match.group(1).upper().rstrip(".")
+    if mat:
+        return ({**name_expand, **street_expand})[mat].title()
+    raise ValueError
+
+
+def direct_expand(match: regex.Match) -> str:
+    """Expand matched directional abbreviations.
+
+    Args:
+        match (regex.Match): Matched string.
+
+    Returns:
+        str: Expanded string.
+    """
+    mat = match.group(1).upper().replace(".", "")
+    if mat:
+        return direction_expand[mat].title()
+    raise ValueError
+
+
+def cap_match(match: regex.Match) -> str:
+    """Make matches uppercase.
+
+    Args:
+        match (regex.Match): Matched string.
+
+    Returns:
+        str: Capitalized string.
+    """
+    return "".join(match.groups()).upper().replace(".", "")
+
+
+def lower_match(match: regex.Match) -> str:
+    """Lower-case improperly cased ordinal values.
+
+    Args:
+        value: String to fix.
+
+    Returns:
+        str: Fixed string.
+    """
+    return match.group(1).lower()
+
+
+def grid_match(match_str: regex.Match) -> str:
+    """Clean grid addresses."""
+    return match_str.group(0).replace(" ", "").upper()
+
+
+def abbrs(value: str) -> str:
+    """Bundle most common abbreviation expansion functions.
+
+    ```python
+    >>> abbrs("St. Francis")
+    "Saint Francis"
+    >>> abbrs("E St.")
+    "E Street"
+    >>> abbrs("E Sewell St")
+    "East Sewell Street"
+    ```
+
+    Args:
+        value (str): String to expand.
+
+    Returns:
+        str: Expanded string.
+    """
+    value = ord_replace(us_replace(mc_replace(get_title(value))))
+
+    # change likely 'St' to 'Saint'
+    value = saint_comp.sub(
+        "Saint",
+        value,
+    )
+
+    # expand common street and word abbreviations
+    value = abbr_join_comp.sub(
+        name_street_expand,
+        value,
+    )
+
+    # expand directionals
+    value = dir_fill_comp.sub(
+        direct_expand,
+        value,
+    )
+
+    # normalize 'US'
+    value = us_replace(value)
+
+    # uppercase shortened street descriptors
+    value = regex.sub(
+        r"\b(C[rh]|S[rh]|[FR]m|Us)\b",
+        cap_match,
+        value,
+    )
+
+    # remove unremoved abbr periods
+    value = regex.sub(
+        r"([a-zA-Z]{2,})\.",
+        r"\1",
+        value,
+    )
+
+    # expand 'SR' if no other street types
+    value = sr_comp.sub("State Route", value)
+    return value.strip(" .")
+
+
+def remove_br_unicode(old: str) -> str:
+    """Clean the input string before sending to parser by removing newlines and unicode.
+
+    Args:
+        old (str): String to clean.
+
+    Returns:
+        str: Cleaned string.
+    """
+    old = regex.sub(r"<br ?/>", ",", old)
+    return regex.sub(r"[^\x00-\x7F\n\r\t]", "", old)  # remove unicode
+
+
+def clean_address(address_string: str) -> str:
+    """Clean the input string before sending to parser by removing newlines and unicode.
+
+    Args:
+        address_string (str): String to clean.
+
+    Returns:
+        str: Cleaned string.
+    """
+    address_string = usa_comp.sub(
+        "", remove_br_unicode(address_string).replace("  ", " ").strip(" ,.")
+    )
+    address_string = paren_comp.sub("", address_string)
+    return grid_comp.sub(grid_match, address_string)
+
+
+def help_join(tags, keep: List[str]) -> str:
+    """Help to join address fields."""
+    tag_join: List[str] = [v for k, v in tags.items() if k in keep]
+    return " ".join(tag_join)
+
+
+def addr_street(tags: Dict[str, str]) -> str:
+    """Build the street field."""
+    return help_join(
+        tags,
+        [
+            "StreetName",
+            "StreetNamePreDirectional",
+            "StreetNamePreModifier",
+            "StreetNamePreType",
+            "StreetNamePostDirectional",
+            "StreetNamePostModifier",
+            "StreetNamePostType",
+        ],
+    )
+
+
+def addr_housenumber(tags: Dict[str, str]) -> str:
+    """Build the housenumber field."""
+    return help_join(
+        tags, ["AddressNumberPrefix", "AddressNumber", "AddressNumberSuffix"]
+    )
+
+
+def _combine_consecutive_tuples(
+    tuples_list: List[Tuple[str, str]]
+) -> List[Tuple[str, str]]:
+    """Join adjacent `usaddress` fields."""
+    combined_list = []
+    current_tag = None
+    current_value = None
+
+    for value, tag in tuples_list:
+        if tag != current_tag:
+            if current_tag:
+                combined_list.append((current_value, current_tag))
+            current_value, current_tag = value, tag
+        else:
+            current_value = " ".join(i for i in [current_value, value] if i)
+
+    if current_tag:
+        combined_list.append((current_value, current_tag))
+
+    return combined_list
+
+
+def _manual_join(parsed: List[tuple]) -> Tuple[Dict[str, str], List[Union[str, None]]]:
+    """Remove duplicates and join remaining fields."""
+    parsed_clean = [i for i in parsed if i[1] not in toss_tags]
+    counts = Counter([i[1] for i in parsed_clean])
+    ok_tags = [tag for tag, count in counts.items() if count == 1]
+    ok_dict: Dict[str, str] = {i[1]: i[0] for i in parsed_clean if i[1] in ok_tags}
+    removed = [osm_mapping.get(field) for field, count in counts.items() if count > 1]
+
+    new_dict: Dict[str, Union[str, None]] = {}
+    if "addr:street" not in removed:
+        new_dict["addr:street"] = addr_street(ok_dict)
+    if "addr:housenumber" not in removed:
+        new_dict["addr:housenumber"] = addr_housenumber(ok_dict)
+    if "addr:unit" not in removed:
+        new_dict["addr:unit"] = ok_dict.get("OccupancyIdentifier")
+    if "addr:city" not in removed:
+        new_dict["addr:city"] = ok_dict.get("PlaceName")
+    if "addr:state" not in removed:
+        new_dict["addr:state"] = ok_dict.get("StateName")
+    if "addr:postcode" not in removed:
+        new_dict["addr:postcode"] = ok_dict.get("ZipCode")
+
+    return {k: v for k, v in new_dict.items() if v}, removed
+
+
+def collapse_list(seq: list) -> list:
+    """Remove duplicates in list while keeping order.
+
+    ```python
+    >>> collapse_list(["foo", "bar", "foo"])
+    ["foo", "bar"]
+    ```
+
+    Args:
+        seq (list): The list to collapse.
+
+    Returns:
+        list: The collapsed list.
+    """
+    seen = set()
+    seen_add = seen.add
+    return [x for x in seq if not (x in seen or seen_add(x))]
+
+
+def split_unit(address_string: str) -> Dict[str, str]:
+    """Split unit from address string, if present."""
+    address_string = address_string.strip(" ")
+    if not any(char.isalpha() for char in address_string):
+        return {"addr:housenumber": address_string}
+
+    add_dict = {}
+    number = ""
+    for char in address_string:
+        if char.isdigit():
+            number += char
+        else:
+            break
+
+    unit = remove_prefix(address_string, number).lstrip(" -,/")
+    if unit:
+        add_dict["addr:unit"] = unit
+    add_dict["addr:housenumber"] = number
+
+    return add_dict
+
+
+def remove_prefix(text: str, prefix: str) -> str:
+    """Remove prefix from string for Python 3.8."""
+    if text.startswith(prefix):
+        return text[len(prefix) :]
+    return text
+
+
+def get_address(
+    address_string: str,
+) -> Tuple[Dict[str, Union[str, int]], List[Union[str, None]]]:
+    """Process address strings.
+
+    ```python
+    >>> get_address("345 MAPLE RD, COUNTRYSIDE, PA 24680-0198")[0]
+    {"addr:housenumber": "345", "addr:street": "Maple Road",
+    "addr:city": "Countryside", "addr:state": "PA", "addr:postcode": "24680-0198"}
+    >>> get_address("777 Strawberry St.")[0]
+    {"addr:housenumber": "777", "addr:street": "Strawberry Street"}
+    >>> address = get_address("222 NW Pineapple Ave Suite A Unit B")
+    >>> address[0]
+    {"addr:housenumber": "222", "addr:street": "Northwest Pineapple Avenue"}
+    >>> address[1]
+    ["addr:unit"]
+    ```
+
+    Args:
+        address_string (str): The address string to process.
+
+    Returns:
+        Tuple[Dict[str, Union[str, int]], List[Union[str, None]]]:
+        The processed address string and the removed fields.
+    """
+    try:
+        cleaned = usaddress.tag(clean_address(address_string), tag_mapping=osm_mapping)[
+            0
+        ]
+        removed = []
+    except usaddress.RepeatedLabelError as err:
+        collapsed = collapse_list(
+            [(i[0].strip(" .,#"), i[1]) for i in err.parsed_string]
+        )
+        cleaned, removed = _manual_join(_combine_consecutive_tuples(collapsed))
+
+    for toss in toss_tags:
+        cleaned.pop(toss, None)
+
+    if "addr:housenumber" in cleaned:
+        cleaned = {**cleaned, **split_unit(cleaned["addr:housenumber"])}
+
+    if "addr:street" in cleaned:
+        street = abbrs(cleaned["addr:street"])
+        cleaned["addr:street"] = street_comp.sub(
+            "Street",
+            street,
+        ).strip(".")
+
+    if "addr:city" in cleaned:
+        cleaned["addr:city"] = abbrs(get_title(cleaned["addr:city"], single_word=True))
+
+    if "addr:state" in cleaned:
+        old = cleaned["addr:state"].replace(".", "")
+        if old.upper() in state_expand:
+            cleaned["addr:state"] = state_expand[old.upper()]
+        elif len(old) == 2 and old.upper() in list(state_expand.values()):
+            cleaned["addr:state"] = old.upper()
+
+    if "addr:unit" in cleaned:
+        cleaned["addr:unit"] = cleaned["addr:unit"].removeprefix("Space").strip(" #.")
+
+    if "addr:postcode" in cleaned:
+        # remove extraneous postcode digits
+        cleaned["addr:postcode"] = post_comp.sub(
+            r"\1", cleaned["addr:postcode"]
+        ).replace(" ", "-")
+
+    try:
+        validated: Address = Address.model_validate(dict(cleaned))
+    except ValidationError as err:
+        bad_fields: list = [each.get("loc", [])[0] for each in err.errors()]
+        cleaned_ret = dict(cleaned)
+        for each in bad_fields:
+            cleaned_ret.pop(each, None)
+
+        removed.extend(bad_fields)
+        validated: Address = Address.model_validate(cleaned_ret)
+
+    return validated.model_dump(exclude_none=True, by_alias=True), removed
+
+
+def get_phone(phone: str) -> str:
+    """Format phone numbers to the US and Canadian standard format of `+1 XXX-XXX-XXXX`.
+
+    ```python
+    >>> get_phone("2029009019")
+    "+1 202-900-9019"
+    >>> get_phone("(202) 900-9019")
+    "+1 202-900-9019"
+    >>> get_phone("202-900-901")
+    ValueError: Invalid phone number: 202-900-901
+    ```
+
+    Args:
+        phone (str): The phone number to format.
+
+    Returns:
+        str: The formatted phone number.
+
+    Raises:
+        ValueError: If the phone number is invalid.
+    """
+    phone_valid = regex.search(
+        r"^\(?(?:\+? ?1?[ -.]*)?(?:\(?(\d{3})\)?[ -.]*)(\d{3})[ -.]*(\d{4})$",
+        phone,
+    )
+    if phone_valid:
+        return (
+            f"+1 {phone_valid.group(1)}-{phone_valid.group(2)}-{phone_valid.group(3)}"
+        )
+    raise ValueError(f"Invalid phone number: {phone}")

atlus/objects.py

@@ -0,0 +1,47 @@
+"""Define objects for parsing fields."""
+
+from typing import Union, Optional
+from pydantic import BaseModel, Field
+
+
+class Address(BaseModel):
+    """Define address parsing fields."""
+
+    addr_housenumber: Optional[Union[int, str]] = Field(
+        alias="addr:housenumber",
+        description="The house number that is included in the address.",
+        examples=[200, "1200-29"],
+        default=None,
+    )
+    addr_street: Optional[str] = Field(
+        alias="addr:street",
+        description="The street that the address is located on.",
+        examples=["North Spring Street"],
+        default=None,
+    )
+    addr_unit: Optional[str] = Field(
+        alias="addr:unit",
+        description="The unit number or letter that is included in the address.",
+        examples=["B"],
+        default=None,
+    )
+    addr_city: Optional[str] = Field(
+        alias="addr:city",
+        description="The city that the address is located in.",
+        examples=["Los Angeles"],
+        default=None,
+    )
+    addr_state: Optional[str] = Field(
+        alias="addr:state",
+        pattern=r"^[A-Z]{2}$",
+        description="The state or territory of the address.",
+        examples=["CA"],
+        default=None,
+    )
+    addr_postcode: Optional[str] = Field(
+        alias="addr:postcode",
+        pattern=r"^\d{5}(?:\-\d{4})?$",
+        description="The postal code of the address.",
+        examples=["90012", "90012-4801"],
+        default=None,
+    )

atlus/resources.py

@@ -0,0 +1,522 @@
+"""Hold info for the processing script."""
+
+import regex
+
+direction_expand = {
+    "NE": "Northeast",
+    "SE": "Southeast",
+    "NW": "Northwest",
+    "SW": "Southwest",
+    "N": "North",
+    "E": "East",
+    "S": "South",
+    "W": "West",
+}
+"""Compass direction abbreviations."""
+
+name_expand = {
+    "ARPT": "airport",
+    "BLDG": "building",
+    "CONF": "conference",
+    "CONV": "convention",
+    "CNTR": "center",
+    "CTR": "center",
+    "DWTN": "downtown",
+    "INTL": "international",
+    "FT": "fort",
+    "MT": "mount",
+    "MTN": "mountain",
+    "SHPG": "shopping",
+}
+"""Common name abbreviations."""
+
+state_expand = {
+    "ALABAMA": "AL",
+    "ALA": "AL",
+    "ALASKA": "AK",
+    "ALAS": "AK",
+    "ARIZONA": "AZ",
+    "ARIZ": "AZ",
+    "ARKANSAS": "AR",
+    "ARK": "AR",
+    "CALIFORNIA": "CA",
+    "CALIF": "CA",
+    "CAL": "CA",
+    "COLORADO": "CO",
+    "COLO": "CO",
+    "COL": "CO",
+    "CONNECTICUT": "CT",
+    "CONN": "CT",
+    "DELAWARE": "DE",
+    "DEL": "DE",
+    "DISTRICT OF COLUMBIA": "DC",
+    "FLORIDA": "FL",
+    "FLA": "FL",
+    "FLOR": "FL",
+    "GEORGIA": "GA",
+    "GA": "GA",
+    "HAWAII": "HI",
+    "IDAHO": "ID",
+    "IDA": "ID",
+    "ILLINOIS": "IL",
+    "ILL": "IL",
+    "INDIANA": "IN",
+    "IND": "IN",
+    "IOWA": "IA",
+    "KANSAS": "KS",
+    "KANS": "KS",
+    "KAN": "KS",
+    "KENTUCKY": "KY",
+    "KEN": "KY",
+    "KENT": "KY",
+    "LOUISIANA": "LA",
+    "MAINE": "ME",
+    "MARYLAND": "MD",
+    "MASSACHUSETTS": "MA",
+    "MASS": "MA",
+    "MICHIGAN": "MI",
+    "MICH": "MI",
+    "MINNESOTA": "MN",
+    "MINN": "MN",
+    "MISSISSIPPI": "MS",
+    "MISS": "MS",
+    "MISSOURI": "MO",
+    "MONTANA": "MT",
+    "MONT": "MT",
+    "NEBRASKA": "NE",
+    "NEBR": "NE",
+    "NEB": "NE",
+    "NEVADA": "NV",
+    "NEV": "NV",
+    "NEW HAMPSHIRE": "NH",
+    "NEW JERSEY": "NJ",
+    "NEW MEXICO": "NM",
+    "N MEX": "NM",
+    "NEW M": "NM",
+    "NEW YORK": "NY",
+    "NORTH CAROLINA": "NC",
+    "NORTH DAKOTA": "ND",
+    "N DAK": "ND",
+    "OHIO": "OH",
+    "OKLAHOMA": "OK",
+    "OKLA": "OK",
+    "OREGON": "OR",
+    "OREG": "OR",
+    "ORE": "OR",
+    "PENNSYLVANIA": "PA",
+    "PENN": "PA",
+    "RHODE ISLAND": "RI",
+    "SOUTH CAROLINA": "SC",
+    "SOUTH DAKOTA": "SD",
+    "S DAK": "SD",
+    "TENNESSEE": "TN",
+    "TENN": "TN",
+    "TEXAS": "TX",
+    "TEX": "TX",
+    "UTAH": "UT",
+    "VERMONT": "VT",
+    "VIRGINIA": "VA",
+    "WASHINGTON": "WA",
+    "WASH": "WA",
+    "WEST VIRGINIA": "WV",
+    "W VA": "WV",
+    "WISCONSIN": "WI",
+    "WIS": "WI",
+    "WISC": "WI",
+    "WYOMING": "WY",
+    "WYO": "WY",
+    "ONTARIO": "ON",
+    "QUEBEC": "QC",
+    "NOVA SCOTIA": "NS",
+    "NEW BRUNSWICK": "NB",
+    "MANITOBA": "MB",
+    "BRITISH COLUMBIA": "BC",
+    "PRINCE EDWARD ISLAND": "PE",
+    "PRINCE EDWARD": "PE",
+    "SASKATCHEWAN": "SK",
+    "ALBERTA": "AB",
+    "NEWFOUNDLAND AND LABRADOR": "NL",
+    "NEWFOUNDLAND & LABRADOR": "NL",
+    "NEWFOUNDLAND": "NL",
+    "YUKON": "YK",
+    "NUNAVUT": "NU",
+    "NORTHWEST TERRITORIES": "NT",
+    "NW TERRITORIES": "NT",
+}
+"""Map states to abbreviations."""
+
+street_expand = {
+    "ACC": "ACCESS",
+    "ALY": "ALLEY",
+    "ANX": "ANEX",
+    "ARC": "ARCADE",
+    "AV": "AVENUE",
+    "AVE": "AVENUE",
+    "BYU": "BAYOU",
+    "BCH": "BEACH",
+    "BND": "BEND",
+    "BLF": "BLUFF",
+    "BLFS": "BLUFFS",
+    "BTM": "BOTTOM",
+    "BLVD": "BOULEVARD",
+    "BR": "BRANCH",
+    "BRG": "BRIDGE",
+    "BRK": "BROOK",
+    "BRKS": "BROOKS",
+    "BG": "BURG",
+    "BGS": "BURGS",
+    "BYP": "BYPASS",
+    "CP": "CAMP",
+    "CY": "KEY",
+    "CYN": "CANYON",
+    "CPE": "CAPE",
+    "CTR": "CENTER",
+    "CTRS": "CENTERS",
+    "CIR": "CIRCLE",
+    "CIRS": "CIRCLES",
+    "CLF": "CLIFF",
+    "CLFS": "CLIFFS",
+    "CLB": "CLUB",
+    "CMN": "COMMON",
+    "CMNS": "COMMONS",
+    "COR": "CORNER",
+    "CORS": "CORNERS",
+    "CRSE": "COURSE",
+    "CT": "COURT",
+    "CTS": "COURTS",
+    "CV": "COVE",
+    "CVS": "COVES",
+    "CRK": "CREEK",
+    "CRES": "CRESCENT",
+    "CRST": "CREST",
+    "CSWY": "CAUSEWAY",
+    "CURV": "CURVE",
+    "DL": "DALE",
+    "DM": "DAM",
+    "DV": "DIVIDE",
+    "DR": "DRIVE",
+    "DRS": "DRIVES",
+    "EST": "ESTATE",
+    "EXPY": "EXPRESSWAY",
+    "EXPWY": "EXPRESSWAY",
+    "EXT": "EXTENSION",
+    "EXTS": "EXTENSIONS",
+    "FGR": "FORGE",
+    "FGRS": "FORGES",
+    "FLS": "FALLS",
+    "FLD": "FIELD",
+    "FLDS": "FIELDS",
+    "FLT": "FLAT",
+    "FLTS": "FLATS",
+    "FRD": "FORD",
+    "FRDS": "FORDS",
+    "FRST": "FOREST",
+    "FRG": "FORGE",
+    "FRGS": "FORGES",
+    "FRK": "FORK",
+    "FRKS": "FORKS",
+    "FRY": "FERRY",
+    "FRYS": "FERRYS",
+    "FOR": "FORD",
+    "FORS": "FORDS",
+    "FT": "FORT",
+    "FWY": "FREEWAY",
+    "GD": "GRADE",
+    "GDN": "GARDEN",
+    "GDNS": "GARDENS",
+    "GTWY": "GATEWAY",
+    "GLN": "GLEN",
+    "GLNS": "GLENS",
+    "GN": "GREEN",
+    "GNS": "GREENS",
+    "GRN": "GREEN",
+    "GRNS": "GREENS",
+    "GRV": "GROVE",
+    "GRVS": "GROVES",
+    "HBR": "HARBOR",
+    "HBRS": "HARBORS",
+    "HGWY": "HIGHWAY",
+    "HVN": "HAVEN",
+    "HTS": "HEIGHTS",
+    "HWY": "HIGHWAY",
+    "HL": "HILL",
+    "HLS": "HILLS",
+    "HOLW": "HOLLOW",
+    "INLT": "INLET",
+    "IS": "ISLAND",
+    "ISS": "ISLANDS",
+    "JCT": "JUNCTION",
+    "JCTS": "JUNCTIONS",
+    "KY": "KEY",
+    "KYS": "KEYS",
+    "KNL": "KNOLL",
+    "KNLS": "KNOLLS",
+    "LK": "LAKE",
+    "LKS": "LAKES",
+    "LNDG": "LANDING",
+    "LN": "LANE",
+    "LGT": "LIGHT",
+    "LGTS": "LIGHTS",
+    "LF": "LOAF",
+    "LCK": "LOCK",
+    "LCKS": "LOCKS",
+    "LDG": "LODGE",
+    "LP": "LOOP",
+    "MNR": "MANOR",
+    "MNRS": "MANORS",
+    "MDW": "MEADOW",
+    "MDWS": "MEADOWS",
+    "ML": "MILL",
+    "MLS": "MILLS",
+    "MSN": "MISSION",
+    "MTWY": "MOTORWAY",
+    "MT": "MOUNT",
+    "MTN": "MOUNTAIN",
+    "MTNS": "MOUNTAINS",
+    "NCK": "NECK",
+    "ORCH": "ORCHARD",
+    "OPAS": "OVERPASS",
+    "PKY": "PARKWAY",
+    "PKWY": "PARKWAY",
+    "PSGE": "PASSAGE",
+    "PNE": "PINE",
+    "PNES": "PINES",
+    "PL": "PLACE",
+    "PLN": "PLAIN",
+    "PLNS": "PLAINS",
+    "PLZ": "PLAZA",
+    "PT": "POINT",
+    "PTS": "POINTS",
+    "PRT": "PORT",
+    "PRTS": "PORTS",
+    "PR": "PRAIRIE",
+    "PVT": "PRIVATE",
+    "RADL": "RADIAL",
+    "RNCH": "RANCH",
+    "RPD": "RAPID",
+    "RPDS": "RAPIDS",
+    "RST": "REST",
+    "RDG": "RIDGE",
+    "RDGS": "RIDGES",
+    "RIV": "RIVER",
+    "RD": "ROAD",
+    "RDS": "ROADS",
+    "RT": "ROUTE",
+    "RTE": "ROUTE",
+    "SHL": "SHOAL",
+    "SHLS": "SHOALS",
+    "SHR": "SHORE",
+    "SHRS": "SHORES",
+    "SKWY": "SKYWAY",
+    "SPG": "SPRING",
+    "SPGS": "SPRINGS",
+    "SQ": "SQUARE",
+    "SQS": "SQUARES",
+    "STA": "STATION",
+    "STRA": "STRAVENUE",
+    "STRM": "STREAM",
+    "STS": "STREETS",
+    "SMT": "SUMMIT",
+    "SRVC": "SERVICE",
+    "TER": "TERRACE",
+    "TRWY": "THROUGHWAY",
+    "THFR": "THOROUGHFARE",
+    "TRCE": "TRACE",
+    "TRAK": "TRACK",
+    "TRFY": "TRAFFICWAY",
+    "TRL": "TRAIL",
+    "TRLR": "TRAILER",
+    "TUNL": "TUNNEL",
+    "TPKE": "TURNPIKE",
+    "UPAS": "UNDERPASS",
+    "UN": "UNION",
+    "UNP": "UNDERPASS",
+    "UNS": "UNIONS",
+    "VIA": "VIADUCT",
+    "VIAS": "VIADUCTS",
+    "VLY": "VALLEY",
+    "VLYS": "VALLEYS",
+    "VW": "VIEW",
+    "VWS": "VIEWS",
+    "VLG": "VILLAGE",
+    "VL": "VILLE",
+    "VIS": "VISTA",
+    "WK": "WALK",
+    "WKWY": "WALKWAY",
+    "WY": "WAY",
+    "WL": "WELL",
+    "WLS": "WELLS",
+    "XING": "CROSSING",
+    "XINGS": "CROSSINGS",
+    "XRD": "CROSSROAD",
+    "XRDS": "CROSSROADS",
+    "YU": "BAYOU",
+}
+"""Common street type abbreviations."""
+
+saints = [
+    "Abigail",
+    "Agatha",
+    "Agnes",
+    "Andrew",
+    "Anthony",
+    "Augustine",
+    "Bernadette",
+    "Brigid",
+    "Catherine",
+    "Charles",
+    "Christopher",
+    "Clare",
+    "Cloud",
+    "Dymphna",
+    "Elizabeth",
+    "Faustina",
+    "Felix",
+    "Francis",
+    "Gabriel,",
+    "George",
+    "Gerard",
+    "James",
+    "Joan",
+    "John",
+    "Joseph",
+    "Jude",
+    "Kateri",
+    "Louis",
+    "Lucie",
+    "Lucy",
+    "Luke",
+    "Maria",
+    "Mark",
+    "Martin",
+    "Mary",
+    "Maximilian",
+    "Michael",
+    "Monica",
+    "Padre",
+    "Patrick",
+    "Paul",
+    "Peter",
+    "Philomena",
+    "Raphael",
+    "Rita",
+    "Rose",
+    "Sebastian",
+    "Teresa",
+    "Therese",
+    "Thomas",
+    "Valentine",
+    "Victor",
+    "Vincent",
+]
+"""Most common saint names."""
+
+bad_zip_first_3 = [
+    "001",
+    "002",
+    "003",
+    "004",
+    "213",
+    "269",
+    "343",
+    "345",
+    "348",
+    "353",
+    "419",
+    "428",
+    "429",
+    "517",
+    "518",
+    "519",
+    "529",
+    "533",
+    "536",
+    "552",
+    "568",
+    "569",
+    "578",
+    "579",
+    "589",
+    "621",
+    "632",
+    "642",
+    "643",
+    "659",
+    "663",
+    "682",
+    "694",
+    "695",
+    "696",
+    "697",
+    "698",
+    "699",
+    "702",
+    "709",
+    "715",
+    "732",
+    "742",
+    "817",
+    "818",
+    "819",
+    "839",
+    "848",
+    "849",
+    "851",
+    "854",
+    "858",
+    "861",
+    "862",
+    "866",
+    "867",
+    "868",
+    "869",
+    "876",
+    "886",
+    "887",
+    "888",
+    "892",
+    "896",
+    "899",
+    "909",
+    "929",
+    "987",
+]
+"""Three-digit combinations that don't represent a zip code."""
+
+# pre-compile regex for speed
+ABBR_JOIN = "|".join({**name_expand, **street_expand})
+abbr_join_comp = regex.compile(
+    rf"(\b(?:{ABBR_JOIN})\b\.?)(?!')",
+    flags=regex.IGNORECASE,
+)
+
+DIR_FILL = "|".join(r"\.?".join(list(abbr)) for abbr in direction_expand)
+dir_fill_comp = regex.compile(
+    rf"(?<!(?:^(?:Avenue) |[\.']))(\b(?:{DIR_FILL})\b\.?)(?!(?:\.?[a-zA-Z]| (?:Street|Avenue)))",
+    flags=regex.IGNORECASE,
+)
+
+sr_comp = regex.compile(
+    r"(\bS\.?R\b\.?)(?= \d+)",
+    flags=regex.IGNORECASE,
+)
+
+saint_comp = regex.compile(
+    rf"^(St\.?)(?= )|(\bSt\.?)(?= (?:{'|'.join(saints)}))",
+    flags=regex.IGNORECASE,
+)
+
+street_comp = regex.compile(
+    r"St\.?(?= [NESW]\.?[EW]?\.?)|(?<=\d[thndstr]{2} )St\.?\b|St\.?$"
+)
+
+post_comp = regex.compile(r"(\d{5})-?0{4}")
+
+usa_comp = regex.compile(r",? (?:USA?|United States(?: of America)?|Canada)\b")
+
+paren_comp = regex.compile(r" ?\(.*\)")
+
+# match Wisconsin grid-style addresses: N65w25055, W249 N6620, etc.
+grid_comp = regex.compile(
+    r"\b([NnSs]\d{2,}\s*[EeWw]\d{2,}|[EeWw]\d{2,}\s*[NnSs]\d{2,})\b"
+)

atlus-0.2.2.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.3
+Name: atlus
+Version: 0.2.2
+Summary: Translate raw address strings into the OSM tagging scheme.
+Project-URL: Documentation, https://whubsch.github.io/atlus_py/index.html
+Project-URL: Issues, https://github.com/whubsch/atlus_py/issues
+Project-URL: Source, https://github.com/whubsch/atlus_py
+Author-email: Will <wahubsch@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: address,geocoding,mapping,openstreetmap,osm
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: regex
+Requires-Dist: usaddress
+Description-Content-Type: text/markdown
+
+# Atlus
+
+![GitHub License](https://img.shields.io/github/license/whubsch/atlus_py)
+![GitHub last commit](https://img.shields.io/github/last-commit/whubsch/atlus_py)
+![PyPI - Version](https://img.shields.io/pypi/v/atlus)
+![Pepy Total Downlods](https://img.shields.io/pepy/dt/atlus)
+
+This Python project translates raw address strings into the OpenStreetMap (OSM) tagging scheme. The package only supports US (and to some extent Canadian) addresses. You can try out the package without installing it at [the Atlus website](https://atlus.dev).
+
+> [!NOTE]
+> Use of this package does not absolve you from following OSM's [import guidelines](https://wiki.openstreetmap.org/wiki/Import/Guidelines).
+
+## Table of Contents
+
+- [Features](#features)
+- [Usage](#usage)
+- [Docs](#docs)
+- [License](#license)
+
+## Features
+
+- Expand common street and name abbreviations.
+- Parse address parts correctly and reliably.
+- Get rid of address junk that is not needed for OpenStreetMap tagging.
+- Parse US and Canadian phone numbers into the standard format.
+
+## Usage
+
+This package is meant to work with GeoJSON files containing raw address data, including those produced by the [All the Places](https://alltheplaces.xyz) project or [Overture maps](https://wiki.openstreetmap.org/wiki/Overture).
+
+```console
+pip install atlus
+```
+
+```python
+>>> import atlus
+>>> atlus.abbrs("St. Francis")
+"Saint Francis"
+>>> atlus.get_address("789 Oak Dr, Smallville California, 98765")
+{"addr:housenumber": "789", "addr:street": "Oak Drive", "addr:city": "Smallville", "addr:state": "CA", "addr:postcode": "98765"}
+>>> atlus.get_phone("(202) 900-9019")
+"+1 202-900-9019"
+```
+
+## Docs
+
+The documentation for our package is available online at our [documentation page](https://whubsch.github.io/atlus_py/index.html). We would greatly appreciate your contributions to help improve the auto-generated docs; please submit any updates or corrections via pull requests.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.txt) file for details.
+
+## See also
+
+- [OpenStreetMap](https://www.openstreetmap.org/)
+- [Atlus](https://wiki.openstreetmap.org/wiki/atlus)
+- [All the Places](https://wiki.openstreetmap.org/wiki/All_the_Places)

atlus-0.2.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+atlus/__about__.py,sha256=Fs7wclAtJ2v8-YvoTdAtThsw1F8Mf23FAnfN2XcN59Y,61
+atlus/__init__.py,sha256=NzltrLPGvaoFTi6a4BfgFNjnSQOl-DmtRTf5bBZ4RSQ,1001
+atlus/atlus.py,sha256=-Z0hVi5tY4ckUuKyPqfCWwfTidx3O7f1tTWItxPGZ4k,13887
+atlus/objects.py,sha256=x7OnajWqLjAO2G9soP-Ge4QvTg1OajlfO807bcUf9lQ,1458
+atlus/resources.py,sha256=rr0mfZAAUSjEwIOhHrOricr7FcevGw642YK4HCeihn0,10123
+atlus-0.2.2.dist-info/METADATA,sha256=HQhYcd3zU7MYAMytL4NPnCU95uhFBIZGIKH4gLV1E_s,3407
+atlus-0.2.2.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+atlus-0.2.2.dist-info/licenses/LICENSE.txt,sha256=b5WOl3a6Gti3d3gAPHP7TybGNScqVDGytjXwwzLIauU,1064
+atlus-0.2.2.dist-info/RECORD,,

atlus-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

atlus-0.2.2.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.