cpca-linch 0.4.4__tar.gz

cpca_linch-0.4.4/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 QinYuan Du
+
+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.

cpca_linch-0.4.4/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+exclude .gitignore
+

cpca_linch-0.4.4/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: cpca-linch
+Version: 0.4.4
+Summary: Chinese Province, City and Area Recognition Utilities (Updated 2025)
+Home-page: https://github.com/laofahai/cpca-linch
+Author: laofahai
+Author-email: 
+License: MIT
+Keywords: Simplified Chinese,Chinese geographic information,Chinese province city area recognition
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Chinese (Simplified)
+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: Topic :: Text Processing
+Classifier: Topic :: Text Processing :: Indexing
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: jieba
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+cpca-linch
+==========
+
+A Python module for extracting Chinese province, city, and district information from address strings.
+
+Fork from `DQinYuan/chinese_province_city_area_mapper <https://github.com/DQinYuan/chinese_province_city_area_mapper>`_ with updated 2025 administrative division data.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install cpca-linch
+
+Usage
+-----
+
+.. code-block:: python
+
+    import cpca
+
+    df = cpca.transform(["徐汇区虹漕路461号58号楼5楼", "广东省中山市沙溪镇云汉轻纺城"])
+    print(df)
+
+Output::
+
+         省    市    区              地址
+    0  上海市  上海市  徐汇区  虹漕路461号58号楼5楼
+    1  广东省  中山市  沙溪镇       云汉轻纺城
+
+Key Improvements
+----------------
+
+1. Updated administrative division data to 2025 (from `xiangyuecn/AreaCity-JsSpider-StatsGov <https://github.com/xiangyuecn/AreaCity-JsSpider-StatsGov>`_)
+2. Support for towns in prefecture-level cities without districts (Dongguan, Zhongshan, Danzhou, Jiayuguan)
+3. Removed latitude/longitude data for smaller package size
+
+Full documentation: `https://github.com/laofahai/cpca-linch <https://github.com/laofahai/cpca-linch>`_
+
+License
+-------
+
+MIT

cpca_linch-0.4.4/README.rst

@@ -0,0 +1,43 @@
+cpca-linch
+==========
+
+A Python module for extracting Chinese province, city, and district information from address strings.
+
+Fork from `DQinYuan/chinese_province_city_area_mapper <https://github.com/DQinYuan/chinese_province_city_area_mapper>`_ with updated 2025 administrative division data.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install cpca-linch
+
+Usage
+-----
+
+.. code-block:: python
+
+    import cpca
+
+    df = cpca.transform(["徐汇区虹漕路461号58号楼5楼", "广东省中山市沙溪镇云汉轻纺城"])
+    print(df)
+
+Output::
+
+         省    市    区              地址
+    0  上海市  上海市  徐汇区  虹漕路461号58号楼5楼
+    1  广东省  中山市  沙溪镇       云汉轻纺城
+
+Key Improvements
+----------------
+
+1. Updated administrative division data to 2025 (from `xiangyuecn/AreaCity-JsSpider-StatsGov <https://github.com/xiangyuecn/AreaCity-JsSpider-StatsGov>`_)
+2. Support for towns in prefecture-level cities without districts (Dongguan, Zhongshan, Danzhou, Jiayuguan)
+3. Removed latitude/longitude data for smaller package size
+
+Full documentation: `https://github.com/laofahai/cpca-linch <https://github.com/laofahai/cpca-linch>`_
+
+License
+-------
+
+MIT

cpca_linch-0.4.4/cpca/__init__.py

@@ -0,0 +1,321 @@
+# -*- coding: utf-8 -*-
+# __init__.py
+
+
+from .structures import AddrMap, Pca
+from .structures import P,C,A
+
+VERSION = (0, 4, 4)
+
+__version__ = ".".join([str(x) for x in VERSION])
+
+
+def _data_from_csv() -> (AddrMap, AddrMap, AddrMap, dict, dict):
+    # 区名及其简写 -> 相关pca元组
+    area_map = AddrMap()
+    # 城市名及其简写 -> 相关pca元组
+    city_map = AddrMap()
+    # (省名全称, 区名全称) -> 相关pca元组
+    province_area_map = AddrMap()
+    # 省名 -> 省全名
+    province_map = {}
+    # (省名, 市名, 区名) -> (纬度,经度)
+    latlng = {}
+    # 数据约定:国家直辖市的sheng字段为直辖市名称, 省直辖县的city字段为空
+    from pkg_resources import resource_stream
+
+    with resource_stream('cpca.resources', 'pca.csv') as pca_stream:
+        from io import TextIOWrapper
+        import csv
+        text = TextIOWrapper(pca_stream, encoding='utf8')
+        pca_csv = csv.DictReader(text)
+        for record_dict in pca_csv:
+            # 经纬度为可选字段
+            lat = record_dict.get('lat', '')
+            lng = record_dict.get('lng', '')
+            if lat and lng:
+                latlng[(record_dict['sheng'], record_dict['shi'], record_dict['qu'])] = (lat, lng)
+
+            _fill_province_map(province_map, record_dict)
+            _fill_area_map(area_map, record_dict)
+            _fill_city_map(city_map, record_dict)
+            _fill_province_area_map(province_area_map, record_dict)
+
+    return area_map, city_map, province_area_map, province_map, latlng
+
+
+def _fill_province_area_map(province_area_map: AddrMap, record_dict):
+    pca_tuple = (record_dict['sheng'], record_dict['shi'], record_dict['qu'])
+    key = (record_dict['sheng'], record_dict['qu'])
+    # 第三个参数在此处没有意义, 随便给的
+    province_area_map.append_relational_addr(key, pca_tuple, P)
+
+
+def _fill_area_map(area_map: AddrMap, record_dict):
+    area_name = record_dict['qu']
+    pca_tuple = (record_dict['sheng'], record_dict['shi'], record_dict['qu'])
+    area_map.append_relational_addr(area_name, pca_tuple, A)
+    # 处理区名简写
+    if area_name.endswith('市'):
+        area_map.append_relational_addr(area_name[:-1], pca_tuple, A)
+    elif area_name.endswith('区'):
+        area_map.append_relational_addr(area_name[:-1], pca_tuple, A)
+    elif area_name.endswith('县'):
+        area_map.append_relational_addr(area_name[:-1], pca_tuple, A)
+    elif area_name.endswith('镇'):
+        area_map.append_relational_addr(area_name[:-1], pca_tuple, A)
+    elif area_name.endswith('街道'):
+        area_map.append_relational_addr(area_name[:-2], pca_tuple, A)
+
+
+def _fill_city_map(city_map: AddrMap, record_dict):
+    city_name = record_dict['shi']
+    pca_tuple = (record_dict['sheng'], record_dict['shi'], record_dict['qu'])
+    city_map.append_relational_addr(city_name, pca_tuple, C)
+    if city_name.endswith('市'):
+        city_map.append_relational_addr(city_name[:-1], pca_tuple, C)
+    # 特别行政区
+    elif city_name == '香港特别行政区':
+        city_map.append_relational_addr('香港', pca_tuple, C)
+    elif city_name == '澳门特别行政区':
+        city_map.append_relational_addr('澳门', pca_tuple, C)
+    
+
+def _fill_province_map(province_map, record_dict):
+    sheng = record_dict['sheng']
+    if sheng not in province_map:
+        province_map[sheng] = sheng
+        # 处理省的简写情况
+        # 普通省分 和 直辖市
+        if sheng.endswith('省') or sheng.endswith('市'):
+            province_map[sheng[:-1]] = sheng
+        # 自治区
+        elif sheng == '新疆维吾尔自治区':
+            province_map['新疆'] = sheng
+        elif sheng == '内蒙古自治区':
+            province_map['内蒙古'] = sheng
+        elif sheng == '广西壮族自治区':
+            province_map['广西'] = sheng
+            province_map['广西省'] = sheng
+        elif sheng == '西藏自治区':
+            province_map['西藏'] = sheng
+        elif sheng == '宁夏回族自治区':
+            province_map['宁夏'] = sheng
+        # 特别行政区
+        elif sheng == '香港特别行政区':
+            province_map['香港'] = sheng
+        elif sheng == '澳门特别行政区':
+            province_map['澳门'] = sheng
+
+
+area_map, city_map, province_area_map, province_map, latlng = _data_from_csv()
+
+# 直辖市
+munis = {'北京市', '天津市', '上海市', '重庆市'}
+
+
+def is_munis(city_full_name):
+    return city_full_name in munis
+
+
+myumap = {
+    '南关区': '长春市',
+    '南山区': '深圳市',
+    '宝山区': '上海市',
+    '市辖区': '东莞市',
+    '普陀区': '上海市',
+    '朝阳区': '北京市',
+    '河东区': '天津市',
+    '白云区': '广州市',
+    '西湖区': '杭州市',
+    '铁西区': '沈阳市'
+}
+
+
+def transform(location_strs, umap=myumap, index=[], cut=True, lookahead=8, pos_sensitive=False, open_warning=True):
+    """将地址描述字符串转换以"省","市","区"信息为列的DataFrame表格
+        Args:
+            locations:地址描述字符集合,可以是list, Series等任意可以进行for in循环的集合
+                      比如:["徐汇区虹漕路461号58号楼5楼", "泉州市洛江区万安塘西工业区"]
+            umap:自定义的区级到市级的映射,主要用于解决区重名问题,如果定义的映射在模块中已经存在，则会覆盖模块中自带的映射
+            index:可以通过这个参数指定输出的DataFrame的index,默认情况下是range(len(data))
+            cut:是否使用分词，默认使用，分词模式速度较快，但是准确率可能会有所下降
+            lookahead:只有在cut为false的时候有效，表示最多允许向前看的字符的数量
+                      默认值为8是为了能够发现"新疆维吾尔族自治区"这样的长地名
+                      如果你的样本中都是短地名的话，可以考虑把这个数字调小一点以提高性能
+            pos_sensitive:如果为True则会多返回三列，分别提取出的省市区在字符串中的位置，如果字符串中不存在的话则显示-1
+            open_warning: 是否打开umap警告, 默认打开
+        Returns:
+            一个Pandas的DataFrame类型的表格，如下：
+               |省    |市   |区    |地址                 |
+               |上海市|上海市|徐汇区|虹漕路461号58号楼5楼  |
+               |福建省|泉州市|洛江区|万安塘西工业区        |
+    """
+
+    from collections.abc import Iterable
+
+    if not isinstance(location_strs, Iterable):
+        from .exceptions import InputTypeNotSuportException
+        raise InputTypeNotSuportException(
+            'location_strs参数必须为可迭代的类型(比如list, Series等实现了__iter__方法的对象)')
+
+    import pandas as pd
+
+    result = pd.DataFrame([_handle_one_record(addr, umap, cut, lookahead, pos_sensitive, open_warning) for addr in location_strs], index=index) \
+             if index else pd.DataFrame([_handle_one_record(addr, umap, cut, lookahead, pos_sensitive, open_warning) for addr in location_strs])
+    # 这句的唯一作用是让列的顺序好看一些
+    if pos_sensitive:
+        return result.loc[:, ('省', '市', '区', '地址', '省_pos', '市_pos', '区_pos')]
+    else:
+        return result.loc[:, ('省', '市', '区', '地址')]
+
+
+def _handle_one_record(addr, umap, cut, lookahead, pos_sensitive, open_warning):
+    """处理一条记录"""
+
+    # 空记录
+    if not isinstance(addr, str) or addr == '' or addr is None:
+        empty = {'省': '', '市': '', '区': ''}
+        if pos_sensitive:
+            empty['省_pos'] = -1
+            empty['市_pos'] = -1
+            empty['区_pos'] = -1
+        return empty
+
+    # 地名提取
+    pca, addr = _extract_addr(addr, cut, lookahead)
+
+    _fill_city(pca, umap, open_warning)
+
+    _fill_province(pca)
+
+    result = pca.propertys_dict(pos_sensitive)
+    result["地址"] = addr
+
+    return result
+
+
+def _fill_province(pca):
+    """填充省"""
+    if (not pca.province) and pca.city and (pca.city in city_map):
+        pca.province = city_map.get_value(pca.city, P)
+
+
+def _fill_city(pca, umap, open_warning):
+    """填充市"""
+    if not pca.city:
+        # 从 区 映射
+        if pca.area:
+            # 从umap中映射
+            if umap.get(pca.area):
+                pca.city = umap.get(pca.area)
+                return
+            if pca.area in area_map and area_map.is_unique_value(pca.area):
+                pca.city = area_map.get_value(pca.area, C)
+                return
+
+        # 从 省,区 映射
+        if pca.area and pca.province:
+            newKey = (pca.province, pca.area)
+            if newKey in province_area_map and province_area_map.is_unique_value(newKey):
+                pca.city = province_area_map.get_value(newKey, C)
+                return
+
+        if open_warning:
+            import logging
+            logging.warning("%s 无法映射, 建议添加进umap中", pca.area)
+
+
+def _extract_addr(addr, cut, lookahead):
+    """提取地址中的省,市,区名称
+       Args:
+           addr:原始地址字符串
+           cut: 是否分词
+       Returns:
+           [sheng, shi, qu, (sheng_pos, shi_pos, qu_pos)], addr
+    """
+    return _jieba_extract(addr) if cut else _full_text_extract(addr, lookahead)
+
+
+def _jieba_extract(addr):
+    """基于结巴分词进行提取"""
+    import jieba
+
+    result = Pca()
+
+    pos = 0
+    truncate = 0
+
+    def _set_pca(pca_property, name, full_name):
+        """pca_property: 'province', 'city' or 'area'"""
+        if not getattr(result, pca_property):
+            setattr(result, pca_property, full_name)
+            setattr(result, pca_property + "_pos", pos)
+            if is_munis(full_name):
+                setattr(result, "province_pos", pos)
+            nonlocal truncate
+            if pos == truncate:
+                truncate += len(name)
+
+    for word in jieba.cut(addr):
+        # 优先提取低级别行政区 (主要是为直辖市和特别行政区考虑)
+        if word in area_map:
+            _set_pca('area', word, area_map.get_full_name(word))
+        elif word in city_map:
+            _set_pca('city', word, city_map.get_full_name(word))
+        elif word in province_map:
+            _set_pca('province', word, province_map[word])
+        
+        pos += len(word)
+
+    return result, addr[truncate:]
+
+
+def _full_text_extract(addr, lookahead):
+    """全文匹配进行提取"""
+
+    result = Pca()
+
+    truncate = 0
+
+    def _set_pca(pca_property, pos, name, full_name):
+        """pca_property: 'province', 'city' or 'area'"""
+        def _defer_set():
+            if not getattr(result, pca_property):
+                setattr(result, pca_property, full_name)
+                setattr(result, pca_property + "_pos", pos)
+                if is_munis(full_name):
+                    setattr(result, "province_pos", pos)
+                nonlocal truncate
+                if pos == truncate:
+                    truncate += len(name)
+            return len(name)
+        return _defer_set
+
+    # i为起始位置
+    i = 0
+    while i < len(addr):
+        # 用于设置pca属性的函数
+        defer_fun = None
+        # l为从起始位置开始的长度,从中提取出最长的地址
+        for length in range(1, lookahead + 1):
+            if i + length > len(addr):
+                break
+            word = addr[i:i + length]
+            # 优先提取低级别的行政区 (主要是为直辖市和特别行政区考虑)
+            if word in area_map:
+                defer_fun = _set_pca('area', i, word, area_map.get_full_name(word))
+                continue
+            elif word in city_map:
+                defer_fun = _set_pca('city', i, word, city_map.get_full_name(word))
+                continue
+            elif word in province_map:
+                defer_fun = _set_pca('province', i, word, province_map[word])
+                continue
+
+        if defer_fun:
+            i += defer_fun()
+        else:
+            i += 1
+
+    return result, addr[truncate:]

cpca_linch-0.4.4/cpca/drawer.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+from . import latlng
+
+
+def _base_input_check(locations):
+    import pandas as pd
+    from .exceptions import InputTypeNotSuportException
+    if not isinstance(locations, pd.DataFrame):
+        raise InputTypeNotSuportException(InputTypeNotSuportException.input_type)
+    if "省" not in locations.columns or "市" not in locations.columns \
+         or "区" not in locations.columns:
+        raise InputTypeNotSuportException(InputTypeNotSuportException.input_type)
+
+
+_lnglat = dict([(item[0], tuple(reversed(item[1]))) for item in latlng.items()])
+
+
+def _geo_update(geo):
+    geo._coordinates = _lnglat
+
+
+def draw_locations(locations, file_path):
+    """
+    基于folium生成地域分布的热力图的html文件.
+    :param locations: 样本的省市区, pandas的dataframe类型.
+    :param file_path: 生成的html文件的路径.
+    """
+    _base_input_check(locations)
+    import folium
+    from folium.plugins import HeatMap
+    # 注意判断key是否存在
+    heatData = []
+    for map_key in zip(locations["省"], locations["市"], locations["区"]):
+        if latlng.get(map_key):
+            lat_lon = latlng.get(map_key)
+            heatData.append([float(lat_lon[0]), float(lat_lon[1]), 1])
+    # 绘制Map，开始缩放程度是5倍
+    map_osm = folium.Map(location=[35, 110], zoom_start=5)
+    # 将热力图添加到前面建立的map里
+    HeatMap(heatData).add_to(map_osm)
+    # 保存为html文件
+    map_osm.save(file_path)
+
+
+def echarts_draw(locations, file_path, title="地域分布图"
+                 , subtitle="location distribute"):
+    """
+    生成地域分布的echarts热力图的html文件.
+    :param locations: 样本的省市区, pandas的dataframe类型.
+    :param file_path: 生成的html文件路径.
+    :param title: 图表的标题
+    :param subtitle: 图表的子标题
+    """
+    from pyecharts import Geo
+
+    _base_input_check(locations)
+    count_map = {}
+    for map_key in zip(locations["省"], locations["市"], locations["区"]):
+        if latlng.get(map_key):
+            count_map[map_key] = count_map.get(map_key, 0) + 1
+
+    geo = Geo(title, subtitle, title_color="#fff",
+          title_pos="center", width=1200,
+          height=600, background_color='#404a59')
+    _geo_update(geo)
+    attr, value = geo.cast(count_map)
+    geo.add("", attr, value, type="heatmap", is_visualmap=True,
+        visual_text_color='#fff',
+        is_piecewise=True, visual_split_number=10)
+    geo.render(file_path)
+
+
+def echarts_cate_draw(locations, labels, file_path, title="地域分布图", subtitle="location distribute",
+                      point_size=7):
+    """
+    依据分类生成地域分布的echarts散点图的html文件.
+    :param locations: 样本的省市区, pandas的dataframe类型.
+    :param labels: 长度必须和locations相等, 代表每个样本所属的分类.
+    :param file_path: 生成的html文件路径.
+    :param title: 图表的标题
+    :param subtitle: 图表的子标题
+    :param point_size: 每个散点的大小
+    """
+    _base_input_check(locations)
+    
+    if len(locations) != len(labels):
+        from .exceptions import CPCAException
+        raise CPCAException("locations的长度与labels长度必须相等")
+
+    from pyecharts import Geo
+    
+    geo = Geo(title, subtitle, title_color="#000000",
+          title_pos="center", width=1200,
+          height=600, background_color='#fff')
+    _geo_update(geo)
+    
+    uniques = set(list(labels))
+    
+
+    def _data_add(_geo, _cate_keys, _category):
+        real_keys = []
+        for cate_key in _cate_keys:
+            if latlng.get(cate_key):
+                real_keys.append(cate_key)
+        
+        attr = real_keys
+        value = [1] * len(real_keys)
+        geo.add(_category, attr, value, symbol_size=point_size,
+                legend_pos="left", legend_top="bottom", 
+                geo_normal_color="#fff",
+                geo_emphasis_color =" #f0f0f5")
+    
+    for category in uniques:
+        cate_locations = locations[labels == category]
+        _data_add(geo, zip(cate_locations["省"], cate_locations["市"],
+                           cate_locations["区"]), category)
+        
+    geo.render(file_path)

cpca_linch-0.4.4/cpca/exceptions.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""
+Created on Wed Feb 28 18:55:58 2018
+自定义的一些异常类
+@author: 燃烧杯
+"""
+
+class CPCAException(Exception):
+    pass
+
+class PlaceTypeNotExistException(CPCAException):
+    pass
+
+class InputTypeNotSuportException(CPCAException):
+    input_type = \
+"""
+输入应该为
+|省     |市    |区     |
+|江苏省 |扬州市 |邗江区 |
+格式的pandas.core.frame.DateFrame
+"""
+    pass

cpca_linch-0.4.4/cpca/resources/__init__.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+
+
+
+