ssdlab-region-parser 0.1.0__tar.gz

ssdlab_region_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SSDLab
+
+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.

ssdlab_region_parser-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.1
+Name: ssdlab-region-parser
+Version: 0.1.0
+Summary: Chinese administrative region parser, not include Honkong, Macau and Taiwan yet.
+Author: ChufanHe
+Author-email: sthechufan@gmail.com
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: jieba>=0.42.1
+Requires-Dist: openpyxl>=3.1.0
+
+# region_parser
+Chinese administrative region parser, not include Honkong, Macau and Taiwan yet.

ssdlab_region_parser-0.1.0/README.md

@@ -0,0 +1,2 @@
+# region_parser
+Chinese administrative region parser, not include Honkong, Macau and Taiwan yet.

ssdlab_region_parser-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ssdlab-region-parser"
+version = "0.1.0"
+description = "Chinese administrative region parser, not include Honkong, Macau and Taiwan yet."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "pandas>=2.0",
+  "jieba>=0.42.1",
+  "openpyxl>=3.1.0"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"region_parser.data" = ["*.xlsx"]

ssdlab_region_parser-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ssdlab_region_parser-0.1.0/setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="ssdlab-region-parser",
+    version="0.1.0",
+    author="ChufanHe",
+    author_email="sthechufan@gmail.com",
+    description="Chinese administrative region parser, not include Hong Kong, Macau and Taiwan yet.",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
+    python_requires=">=3.10",
+    install_requires=[
+        "pandas>=2.0",
+        "jieba>=0.42.1",
+        "openpyxl>=3.1.0",
+    ],
+    package_data={
+        "region_parser.data": ["*.xlsx"],
+    },
+    include_package_data=True,
+)

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser/__init__.py

@@ -0,0 +1,3 @@
+from .parser import CN_RegionParser
+
+__all__ = ["CN_RegionParser"]

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser/models.py

@@ -0,0 +1,75 @@
+from dataclasses import dataclass, field
+import pandas as pd
+
+
+@dataclass
+class CN_RegionParseResult:
+    province_name: object = pd.NA
+    province_code: object = pd.NA
+    city_name: object = pd.NA
+    city_code: object = pd.NA
+    county_name: object = pd.NA
+    county_code: object = pd.NA
+
+    matched_words: list[str] = field(default_factory=list)
+    kept_words: list[str] = field(default_factory=list)
+    dropped_words: list[str] = field(default_factory=list)
+    best_match: object = pd.NA
+
+    def to_dict(self) -> dict:
+        return {
+            "省级名称": self.province_name,
+            "省级代码": self.province_code,
+            "城市名称": self.city_name,
+            "城市代码": self.city_code,
+            "区县名称": self.county_name,
+            "区县代码": self.county_code,
+            # "matched_words": self.matched_words,
+            # "kept_words": self.kept_words,
+            # "dropped_words": self.dropped_words,
+            # "best_match": self.best_match,
+        }
+    
+    # series
+    def to_series(self) -> pd.Series:
+        return pd.Series(self.to_dict())
+
+    # tuple
+    def to_tuple(self) -> tuple:
+        return (
+            self.province_name, self.province_code,
+            self.city_name, self.city_code,
+            self.county_name, self.county_code
+        )
+
+    # list
+    def to_list(self) -> list:
+        return [
+            self.province_name, self.province_code,
+            self.city_name, self.city_code,
+            self.county_name, self.county_code,
+        ]
+
+    # str
+    def to_str(self) -> str:
+        return (
+            f"省级名称：{self.province_name}    省份代码：{self.province_code} | "
+            f"城市名称：{self.city_name}    城市代码：{self.city_code} | "
+            f"区县名称：{self.county_name}    区县代码：{self.county_code}"
+        )
+
+
+@dataclass
+class CN_RegionResources:
+    df_region_code: pd.DataFrame
+    province_keywords: list[str]
+    city_keywords: list[str]
+    county_keywords: list[str]
+    region_keywords: list[str]
+    word_set: set[str]
+    province_dict: dict
+    city_dict: dict
+    county_dict: dict
+    region_mapping_dict: dict
+    df_paths: pd.DataFrame
+    word_to_paths: dict

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser/parser.py

@@ -0,0 +1,330 @@
+import jieba
+jieba.setLogLevel(jieba.logging.WARN)
+import pandas as pd
+
+from .resources import build_region_resources, load_keywords_into_jieba
+from .models import CN_RegionParseResult
+
+
+class CN_RegionParser:
+    def __init__(self):
+        self.resources = build_region_resources()
+        load_keywords_into_jieba(self.resources.region_keywords)
+
+    @staticmethod
+    def _deduplicate_keep_order(words: list[str]) -> list[str]:
+        seen = set()
+        result = []
+        for word in words:
+            if pd.isna(word):
+                continue
+            word = str(word).strip()
+            if not word:
+                continue
+            if word not in seen:
+                seen.add(word)
+                result.append(word)
+        return result
+
+    def extract_region(self, text: str) -> str:
+        if pd.isna(text):
+            return pd.NA
+        text = str(text).strip()
+        if not text:
+            return pd.NA
+
+        words = jieba.lcut(text)
+        matched = [w for w in words if w in self.resources.word_set]
+        matched = self._deduplicate_keep_order(matched)
+        return " ".join(matched) if matched else pd.NA
+
+    def extract_region_lcut_all(self, text: str) -> str:
+        if pd.isna(text):
+            return pd.NA
+        text = str(text).strip()
+        if not text:
+            return pd.NA
+
+        words = jieba.lcut(text, cut_all=True)
+        matched = [w for w in words if w in self.resources.word_set]
+        matched = self._deduplicate_keep_order(matched)
+        return " ".join(matched) if matched else pd.NA
+
+    def extract_region_lcut_for_search(self, text: str) -> str:
+        if pd.isna(text):
+            return pd.NA
+        text = str(text).strip()
+        if not text:
+            return pd.NA
+
+        words = jieba.lcut_for_search(text)
+        matched = [w for w in words if w in self.resources.word_set]
+        matched = self._deduplicate_keep_order(matched)
+        return " ".join(matched) if matched else pd.NA
+
+    def extract_candidates(self, text: str) -> dict:
+        a1 = self.extract_region(text)
+        a2 = self.extract_region_lcut_all(text)
+        a3 = self.extract_region_lcut_for_search(text)
+
+        a1_list = a1.split() if pd.notna(a1) else []
+        a2_list = a2.split() if pd.notna(a2) else []
+        a3_list = a3.split() if pd.notna(a3) else []
+
+        merged = self._deduplicate_keep_order(a1_list + a2_list + a3_list)
+
+        return {
+            "extract_region": a1,
+            "extract_region_lcut_all": a2,
+            "extract_region_lcut_for_search": a3,
+            "merged_words": merged,
+        }
+
+    def can_coexist_in_same_path(self, w1: str, w2: str) -> bool:
+        paths1 = self.resources.word_to_paths.get(w1, set())
+        paths2 = self.resources.word_to_paths.get(w2, set())
+        return len(paths1 & paths2) > 0
+
+    def keep_words_by_chain(self, words: list[str]) -> dict:
+        if not words:
+            return {
+                "kept_words": [],
+                "dropped_words": [],
+                "common_paths": set(),
+            }
+
+        kept = []
+        dropped = []
+
+        current_paths = None
+
+        for word in words:
+            word_paths = self.resources.word_to_paths.get(word, set())
+
+            if not word_paths:
+                dropped.append(word)
+                continue
+
+            if current_paths is None:
+                kept.append(word)
+                current_paths = set(word_paths)
+                continue
+
+            overlap = current_paths & word_paths
+            if overlap:
+                kept.append(word)
+                current_paths = overlap
+            else:
+                dropped.append(word)
+
+        return {
+            "kept_words": kept,
+            "dropped_words": dropped,
+            "common_paths": current_paths if current_paths is not None else set(),
+        }
+
+    def parse(self, text: str):
+        candidates = self.extract_candidates(text)
+        filtered = self.keep_words_by_chain(candidates["merged_words"])
+
+        best = self.find_best_match(
+            kept_words=filtered["kept_words"],
+            common_paths=filtered["common_paths"],
+        )
+
+        # matched_words = self.map_words_to_standard_names(filtered["kept_words"])
+
+        prov, city, county = self.fill_region_by_best(
+            best=best,
+            context_list=filtered["kept_words"],
+        )
+
+        region_info = self.expand_region_codes(prov, city, county)
+
+        return CN_RegionParseResult(
+            province_name = region_info["省级名称"],
+            province_code = region_info["省级代码"],
+            city_name = region_info["城市名称"],
+            city_code = region_info["城市代码"],
+            county_name = region_info["区县名称"],
+            county_code = region_info["区县代码"],
+            # matched_words = matched_words,
+            # kept_words = filtered["kept_words"],
+            # dropped_words = filtered["dropped_words"],
+            # best_match = best,
+        )
+    
+    def map_words_to_standard_names(self, words: list[str]) -> list[str]:
+        mapped = []
+        for word in words:
+            std = self.resources.region_mapping_dict.get(word, word)
+            if std not in mapped:
+                mapped.append(std)
+        return mapped
+    
+    @staticmethod
+    def _split_path(path: str) -> tuple[str, str, str]:
+        parts = str(path).split("|")
+        parts = parts + [""] * (3 - len(parts))
+        return parts[0], parts[1], parts[2]
+
+    def find_best_match(self, kept_words: list[str], common_paths: set) -> object:
+        if not kept_words:
+            return pd.NA
+
+        std_words = self.map_words_to_standard_names(kept_words)
+
+        province_names = set(self.resources.df_region_code["省级名称"].dropna().astype(str))
+        city_names = set(self.resources.df_region_code["城市名称"].dropna().astype(str))
+        county_names = set(self.resources.df_region_code["区县名称"].dropna().astype(str))
+
+        provs = [w for w in std_words if w in province_names]
+        cities = [w for w in std_words if w in city_names]
+        counties = [w for w in std_words if w in county_names]
+
+        # 情况1：唯一合法路径，优先返回最细层级
+        if len(common_paths) == 1:
+            path = next(iter(common_paths))
+            prov, city, county = self._split_path(path)
+            if county:
+                return county
+            if city:
+                return city
+            if prov:
+                return prov
+
+        # 情况2：如果明确命中了区县，优先区县
+        if len(counties) == 1:
+            return counties[0]
+
+        # 情况3：如果明确命中了城市，返回城市
+        if len(cities) == 1:
+            return cities[0]
+
+        # 情况4：如果只明确到省
+        if len(provs) == 1:
+            return provs[0]
+
+        # 情况5：多个候选时，从 kept_words 末尾往前找最细层级
+        for w in reversed(std_words):
+            if w in county_names:
+                return w
+        for w in reversed(std_words):
+            if w in city_names:
+                return w
+        for w in reversed(std_words):
+            if w in province_names:
+                return w
+
+        return pd.NA
+    
+    def fill_region_by_best(self, best: object, context_list: list[str]) -> tuple[object, object, object]:
+        if pd.isna(best):
+            return pd.NA, pd.NA, pd.NA
+
+        df = self.resources.df_region_code
+        std_context = self.map_words_to_standard_names(context_list)
+
+        province_names = set(df["省级名称"].dropna().astype(str))
+        city_names = set(df["城市名称"].dropna().astype(str))
+        county_names = set(df["区县名称"].dropna().astype(str))
+
+        # 1) best 是省级：只返回省
+        if best in province_names:
+            return best, pd.NA, pd.NA
+
+        # 2) best 是市级：返回省、市；区县留空
+        if best in city_names:
+            rows = df[df["城市名称"] == best].copy()
+            if rows.empty:
+                return pd.NA, best, pd.NA
+
+            best_score = -1
+            best_row = None
+
+            for _, row in rows.iterrows():
+                score = 0
+                if row["省级名称"] in std_context:
+                    score += 1
+                if row["城市名称"] in std_context:
+                    score += 1
+
+                if score > best_score:
+                    best_score = score
+                    best_row = row
+
+            if best_row is None:
+                best_row = rows.iloc[0]
+
+            return best_row["省级名称"], best_row["城市名称"], pd.NA
+
+        # 3) best 是区县级：返回完整省、市、县
+        if best in county_names:
+            rows = df[df["区县名称"] == best].copy()
+            if rows.empty:
+                return pd.NA, pd.NA, best
+
+            best_score = -1
+            best_row = None
+
+            for _, row in rows.iterrows():
+                score = 0
+                if row["省级名称"] in std_context:
+                    score += 1
+                if row["城市名称"] in std_context:
+                    score += 1
+                if row["区县名称"] in std_context:
+                    score += 1
+
+                if score > best_score:
+                    best_score = score
+                    best_row = row
+
+            if best_row is None:
+                best_row = rows.iloc[0]
+
+            return best_row["省级名称"], best_row["城市名称"], best_row["区县名称"]
+
+        return pd.NA, pd.NA, pd.NA
+    def expand_region_codes(self, prov: object, city: object, county: object) -> dict:
+        df = self.resources.df_region_code
+
+        result = {
+            "省级名称": prov,
+            "省级代码": pd.NA,
+            "城市名称": city,
+            "城市代码": pd.NA,
+            "区县名称": county,
+            "区县代码": pd.NA,
+        }
+
+        if pd.notna(prov) and pd.notna(city) and pd.notna(county):
+            row = df[
+                (df["省级名称"] == prov) &
+                (df["城市名称"] == city) &
+                (df["区县名称"] == county)
+            ]
+            if not row.empty:
+                row = row.iloc[0]
+                result["省级代码"] = row.get("省份代码", pd.NA)
+                result["城市代码"] = row.get("城市代码", pd.NA)
+                result["区县代码"] = row.get("区县代码", pd.NA)
+                return result
+
+        if pd.notna(prov) and pd.notna(city):
+            row = df[
+                (df["省级名称"] == prov) &
+                (df["城市名称"] == city)
+            ]
+            if not row.empty:
+                row = row.iloc[0]
+                result["省级代码"] = row.get("省份代码", pd.NA)
+                result["城市代码"] = row.get("城市代码", pd.NA)
+
+        if pd.notna(prov):
+            row = df[df["省级名称"] == prov]
+            if not row.empty:
+                row = row.iloc[0]
+                result["省级代码"] = row.get("省份代码", pd.NA)
+
+        return result

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser/resources.py

@@ -0,0 +1,136 @@
+from importlib.resources import files
+import pandas as pd
+import jieba
+
+from .models import CN_RegionResources
+
+
+RESOURCE_PACKAGE = "region_parser.data"
+REGION_EXCEL_NAME = "CN_Region_Reference_Library.xlsx"
+
+
+def split_keywords(series: pd.Series) -> list[str]:
+    words = (
+        series.dropna()
+        .astype(str)
+        .str.split("|", regex=False)
+        .explode()
+        .astype(str)
+        .str.strip()
+    )
+    words = words[words != ""].unique().tolist()
+    words.sort(key=len, reverse=True)
+    return words
+
+
+def load_region_code_table() -> pd.DataFrame:
+    excel_path = files(RESOURCE_PACKAGE).joinpath(REGION_EXCEL_NAME)
+    return pd.read_excel(excel_path)
+
+
+def build_word_to_paths(df_paths: pd.DataFrame) -> dict:
+    word_to_paths = {}
+
+    for _, row in df_paths.iterrows():
+        path = row["path"]
+        for col in ["省级关键词", "市级关键词", "区县关键词"]:
+            value = row.get(col)
+            if pd.isna(value):
+                continue
+
+            for word in str(value).split("|"):
+                word = word.strip()
+                if not word:
+                    continue
+
+                if word not in word_to_paths:
+                    word_to_paths[word] = set()
+                word_to_paths[word].add(path)
+
+    return word_to_paths
+
+
+def build_region_resources() -> CN_RegionResources:
+    df_region_code = load_region_code_table()
+
+    province_keywords = split_keywords(df_region_code["省级关键词"])
+    city_keywords = split_keywords(df_region_code["市级关键词"])
+    county_keywords = split_keywords(df_region_code["区县关键词"])
+
+    region_keywords = sorted(
+        set(province_keywords + city_keywords + county_keywords),
+        key=len,
+        reverse=True,
+    )
+
+    word_set = set(region_keywords)
+
+    df_province = (
+        df_region_code[["省级名称", "省级关键词", "省份代码"]]
+        .dropna(subset=["省级关键词"])
+        .assign(省级关键词=lambda x: x["省级关键词"].str.split("|", regex=False))
+        .explode("省级关键词")
+        .assign(省级关键词=lambda x: x["省级关键词"].astype(str).str.strip())
+        .query("省级关键词 != ''")
+        .drop_duplicates()
+        .reset_index(drop=True)
+    )
+    province_dict = df_province.set_index("省级关键词")["省级名称"].to_dict()
+
+    df_city = (
+        df_region_code[["城市名称", "市级关键词", "城市代码"]]
+        .dropna(subset=["市级关键词"])
+        .assign(市级关键词=lambda x: x["市级关键词"].str.split("|", regex=False))
+        .explode("市级关键词")
+        .assign(市级关键词=lambda x: x["市级关键词"].astype(str).str.strip())
+        .query("市级关键词 != ''")
+        .drop_duplicates()
+        .reset_index(drop=True)
+    )
+    city_dict = df_city.set_index("市级关键词")["城市名称"].to_dict()
+
+    df_county = (
+        df_region_code[["区县名称", "区县关键词", "区县代码"]]
+        .dropna(subset=["区县关键词"])
+        .assign(区县关键词=lambda x: x["区县关键词"].str.split("|", regex=False))
+        .explode("区县关键词")
+        .assign(区县关键词=lambda x: x["区县关键词"].astype(str).str.strip())
+        .query("区县关键词 != ''")
+        .drop_duplicates()
+        .reset_index(drop=True)
+    )
+    county_dict = df_county.set_index("区县关键词")["区县名称"].to_dict()
+
+    region_mapping_dict = {**province_dict, **city_dict, **county_dict}
+
+    df_paths = df_region_code[
+        ["省级名称", "城市名称", "区县名称", "省级关键词", "市级关键词", "区县关键词"]
+    ].copy()
+
+    df_paths["path"] = (
+        df_paths["省级名称"].fillna("") + "|" +
+        df_paths["城市名称"].fillna("") + "|" +
+        df_paths["区县名称"].fillna("")
+    )
+
+    word_to_paths = build_word_to_paths(df_paths)
+
+    return CN_RegionResources(
+        df_region_code=df_region_code,
+        province_keywords=province_keywords,
+        city_keywords=city_keywords,
+        county_keywords=county_keywords,
+        region_keywords=region_keywords,
+        word_set=word_set,
+        province_dict=province_dict,
+        city_dict=city_dict,
+        county_dict=county_dict,
+        region_mapping_dict=region_mapping_dict,
+        df_paths=df_paths,
+        word_to_paths=word_to_paths,
+    )
+
+
+def load_keywords_into_jieba(words: list[str]) -> None:
+    for word in words:
+        jieba.add_word(word, freq=1000)

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser.egg-info/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.1
+Name: ssdlab-region-parser
+Version: 0.1.0
+Summary: Chinese administrative region parser, not include Honkong, Macau and Taiwan yet.
+Author: ChufanHe
+Author-email: sthechufan@gmail.com
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: jieba>=0.42.1
+Requires-Dist: openpyxl>=3.1.0
+
+# region_parser
+Chinese administrative region parser, not include Honkong, Macau and Taiwan yet.

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+src/SSDLab_region_parser/__init__.py
+src/SSDLab_region_parser/models.py
+src/SSDLab_region_parser/parser.py
+src/SSDLab_region_parser/resources.py
+src/SSDLab_region_parser.egg-info/PKG-INFO
+src/SSDLab_region_parser.egg-info/SOURCES.txt
+src/SSDLab_region_parser.egg-info/dependency_links.txt
+src/SSDLab_region_parser.egg-info/requires.txt
+src/SSDLab_region_parser.egg-info/top_level.txt
+src/SSDLab_region_parser/data/__init__.py
+src/ssdlab_region_parser/__init__.py
+src/ssdlab_region_parser/models.py
+src/ssdlab_region_parser/parser.py
+src/ssdlab_region_parser/resources.py
+src/ssdlab_region_parser.egg-info/PKG-INFO
+src/ssdlab_region_parser.egg-info/SOURCES.txt
+src/ssdlab_region_parser.egg-info/dependency_links.txt
+src/ssdlab_region_parser.egg-info/requires.txt
+src/ssdlab_region_parser.egg-info/top_level.txt
+src/ssdlab_region_parser/data/__init__.py

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pandas>=2.0
+jieba>=0.42.1
+openpyxl>=3.1.0

ssdlab_region_parser-0.1.0/src/SSDLab_region_parser.egg-info/top_level.txt

@@ -0,0 +1 @@
+ssdlab_region_parser