Provide pyecharts with 138,398 cities of the world with a population of at least 1000 inhabitants (pyecharts#663)

* ✨ OPEN / CLOSE principle - open for extension but closed for modification. Allow the extension of city coordinates so that echarts-cities-pypkg can be installed, hence 138,398 city coordinations is added covering all countries in the world

* 🐛 what if no country data is returned

* 🔥 remove lazy object test

* 🎨 last resort, have to introduce country as a parameter to geo.add() function. no way to search for the coordinates without the country name.

* 📚 documentation update

* 📚 fix typos and add missing docstrings

* 🔬 more unit tests

* 💚 make unit test pass

* 🐛 without unicode_literals but with utf-8, all Chinese strings are utf-8 encoded, hence requires decoding.

* 🎨 🔨 code refacotring and 📚 update documentation

* 🎨 finalized version

* 🔥 remove un-used function

* 🔨 change function parameter name: map_country -> coordinate_country

* 🔨 country -> region

* 🔨 country -> region

* 🚜 rename db file

* 🔨 whitening with black

* 📖 update dataset

* 📖 update data set country

Author: chfw

MANIFEST.in

@@ -1,4 +1,5 @@
 include pyecharts/datasets/city_coordinates.json
+include pyecharts/datasets/countries_regions_db.json
 include pyecharts/templates/*.html
 include README.md
 include changelog.md

README.md

@@ -56,6 +56,16 @@ $ python setup.py install
 
 Please note: since version 0.3.2, **NO LONGER** pyecharts comes with any map files. Please read next section for more informations.
 
+### Geo Data extensions (0.5.7+)
+
+1. From geonames.org, [138,398 cities of the world with a population of at least 1000 inhabitants](https://github.com/echarts-maps/echarts-cities-js): [echarts-cities-pypkg](https://github.com/pyecharts/echarts-cities-pypkg)
+
+In order to install them, you can try one or all of them below:
+
+```shell
+$ pip install echarts-cities-pypkg
+```
+
 ### Map extensions
 
 Here is a list of map extensions from pyecharts dev team:

docs/zh-cn/changelog.md

@@ -6,6 +6,7 @@
     * [issue#651](https://github.com/pyecharts/pyecharts/issues/651) Scatter 图新增 `extra_name` 参数，额外的数据项的名称，可以为每个数据点指定一个名称。
     * [issue#657](https://github.com/pyecharts/pyecharts/issues/657) 基本图形新增 `extra_html_text_label` 参数用于显示额外的文本标签，仅限于在单图形或者 Page 时使用。
     * [issue#660](https://github.com/pyecharts/pyecharts/issues/660) 为 X/Y 坐标轴新增 `xaxis_line_color`, `xaxis_line_width`, `yaxis_line_color`, `yaxis_line_width` 四个参数，用于控制其坐标轴线线的颜色以及宽度。
+    * 新增 echarts-cities-pypkg 为可选的地理数据扩展。引入来自 geonames.org 的 138,398 个城市坐标
 
 
 * ### version 0.5.6 - 2018.7.28（current）

docs/zh-cn/charts.md

@@ -1161,6 +1161,7 @@ Geo.add() 方法签名
 add(name, attr, value,
     type="scatter",
     maptype='china',
+    coordinate_region='中国',
     symbol_size=12,
     border_color="#111",
     geo_normal_color="#323c48",
@@ -1178,6 +1179,8 @@ add(name, attr, value,
     图例类型，有'scatter', 'effectScatter', 'heatmap'可选。默认为 'scatter'
 * maptype -> str  
     地图类型。 从 v0.3.2+ 起，地图已经变为扩展包，支持全国省份，全国城市，全国区县，全球国家等地图，具体请参考 [地图自定义篇](zh-cn/customize_map)
+* coordinate_region -> str
+    城市坐标所属国家。从 v0.5.7 引入，针对国际城市的地理位置的查找。
 * symbol_size -> int  
     标记图形大小。默认为 12
 * border_color -> str  

docs/zh-cn/datasets.md

@@ -27,9 +27,9 @@ pyecharts 内置了一些常用的城市地理坐标数据，这些数据保存
 }
 ```
 
-### 检索地理坐标
+### 检索中国地理坐标
 
-`get_coordinate(name)` 返回城市名称的地理坐标，如果未定义将返回 None 。
+`get_coordinate(name, region="中国")` 返回城市名称的地理坐标，如果未定义将返回 None 。
 
 ```python
 from pyecharts.datasets.coordinates import get_coordinate
@@ -59,12 +59,12 @@ print(result) # {'北京':[116.46, 39.92], '北京市': [116.4, 39.9]}
 ```python
 from pyecharts.datasets.coordinates import search_coordinates_by_keyword
 result = search_coordinates_by_keyword('福州', '杭州')
-print(result) # {'福州市': [119.3, 26.08], '杭州市': [120.15, 30.28] ...} 
+print(result) # {'福州市': [119.3, 26.08], '杭州市': [120.15, 30.28] ...}
 ```
 
 ### 按过滤函数搜索地理坐标
 
-`search_coordinates_by_filter(func)` 根据过滤函数，返回一个匹配的字典对象。
+`search_coordinates_by_filter(func, region="中国")` 根据过滤函数，返回一个匹配的字典对象。
 用法（结果同上）
 
 ```python
@@ -113,6 +113,64 @@ geo.add(
 geo.render()
 ```
 
+## 国际城市地理坐标
+
+自 v0.5.7 之后，[echarts-cities-pypkg](https://github.com/pyecharts/echarts-cities-pypkg) 给 pyecharts 补充了 [138,398 个城市地理坐标](https://github.com/echarts-maps/echarts-cities-js)，覆盖了200 多个国家。你可以配合 echarts-countries-pypkg 画地理散点图。
+
+### 安装方法
+
+```
+pip install echarts-cities-pypkg
+```
+
+### 使用方法
+
+```python
+from pyecharts.datasets.coordinates import get_coordinate
+
+coordinate = get_coordinate('Oxford', region="英国")
+print(coordinate) # [-1.25596, 51.75222]
+```
+
+### 按关键字搜索地理坐标
+
+`search_coordinates_by_region_and_keyword(*args)` 根据一个或多个关键字，返回一个匹配的字典对象。
+
+用法 1：单个关键字模糊搜索
+
+```python
+from pyecharts.datasets.coordinates import search_coordinates_by_region_and_keyword
+
+result = search_coordinates_by_region_and_keyword("英国", 'London')
+print(result)
+#{
+#    "Londonderry County Borough": [-7.30917, 54.99721],
+#    "City of London": [-0.09184, 51.51279],
+#    "London": [-0.12574, 51.50853],
+#}
+```
+
+用法 2：多个关键字模糊搜索
+
+```python
+from pyecharts.datasets.coordinates import search_coordinates_by_region_and_keyword
+result = search_coordinates_by_region_and_keyword('中国香港', 'Central', 'Hong Kong')
+print(result) # { "Hong Kong": [114.15769, 22.28552], "Central": [114.15846, 22.28299]}
+```
+
+### 按过滤函数搜索地理坐标
+
+```python
+from pyecharts.datasets.coordinates import search_coordinates_by_filter
+
+result = search_coordinates_by_filter(
+    func=lambda name: "Central" in name or "Hong Kong" in name,
+    region="中国香港",
+
+)
+print(result) # { "Hong Kong": [114.15769, 22.28552], "Central": [114.15846, 22.28299]}
+```
+
 ## 地图数据
 
 以下是 pyecharts 开发组托管的地图扩展（map extension）:

pyecharts/charts/geo.py

@@ -1,4 +1,5 @@
 # coding=utf-8
+from __future__ import unicode_literals
 
 from pyecharts.chart import Chart
 from pyecharts.datasets.coordinates import get_coordinate
@@ -29,7 +30,7 @@ def add_coordinate(self, name, longitude, latitude):
         """
         self._coordinates.update({name: [longitude, latitude]})
 
-    def get_coordinate(self, name, raise_exception=False):
+    def get_coordinate(self, name, region="中国", raise_exception=False):
         """
         Return coordinate for the city name.
 
@@ -40,7 +41,7 @@ def get_coordinate(self, name, raise_exception=False):
         if name in self._coordinates:
             return self._coordinates[name]
 
-        coordinate = get_coordinate(name)
+        coordinate = get_coordinate(name, region=region)
         if coordinate is None and raise_exception:
             raise ValueError("No coordinate is specified for {}".format(name))
 
@@ -56,6 +57,7 @@ def __add(
         value,
         type="scatter",
         maptype="china",
+        coordinate_region="中国",
         symbol_size=12,
         border_color="#111",
         geo_normal_color="#323c48",
@@ -77,6 +79,8 @@ def __add(
         :param maptype:
             地图类型。 从 v0.3.2+ 起，地图已经变为扩展包，支持全国省份，全国城市，全国区县，
             全球国家等地图，具体请参考 [地图自定义篇](zh-cn/customize_map)
+        :param coordinate_region:
+            城市坐标所属国家。从 v0.5.7 引入，针对国际城市的地理位置的查找。
         :param symbol_size:
             标记图形大小。
         :param border_color:
@@ -105,7 +109,9 @@ def __add(
 
         _data = []
         for _name, _value in zip(attr, value):
-            _coordinate = self.get_coordinate(_name, raise_exception=True)
+            _coordinate = self.get_coordinate(
+                _name, coordinate_region, raise_exception=True
+            )
             _data_value = [_coordinate[0], _coordinate[1], _value]
             _data.append({"name": _name, "value": _data_value})
         self._option.update(

pyecharts/charts/geolines.py

@@ -1,4 +1,5 @@
 # coding=utf-8
+from __future__ import unicode_literals
 
 from pyecharts.charts.geo import Geo
 from pyecharts.constants import SYMBOL
@@ -20,6 +21,7 @@ def add(
         name,
         data,
         maptype="china",
+        coordinate_region="中国",
         symbol=None,
         symbol_size=12,
         border_color="#111",
@@ -46,6 +48,8 @@ def add(
         :param maptype:
             地图类型。 从 v0.3.2+ 起，地图已经变为扩展包，支持全国省份，全国城市，全国区县，
             全球国家等地图，具体请参考 [地图自定义篇](zh-cn/customize_map)
+        :param coordinate_region:
+            城市坐标所属国家。从 v0.5.7 引入，针对国际城市的地理位置的查找。
         :param symbol:
             线两端的标记类型，可以是一个数组分别指定两端，也可以是单个统一指定。
         :param symbol_size:
@@ -99,7 +103,7 @@ def add(
                 _from_name, _to_name, _line_value = element
 
             _from_coordinate = self.get_coordinate(
-                _from_name, raise_exception=True
+                _from_name, coordinate_region, raise_exception=True
             )
             _to_coordinate = self.get_coordinate(
                 _to_name, raise_exception=True

pyecharts/constants.py

@@ -15,6 +15,7 @@
 JUPYTER_PRESENTATIONS = [SVG, PNG, JPEG, DEFAULT_HTML, NTERACT]
 ENVIRONMENT_PLUGIN_TYPE = "pyecharts_environment"
 JS_EXTENSION_PLUGIN_TYPE = "pyecharts_js_extension"
+GEO_DATA_PLUGIN_TYPE = "pyecharts_geo_data_bank"
 
 # themes
 LIGHT_THEME = "light"