diff --git a/README.md b/README.md index 5d97276..7e7aa9c 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ For API introductions, usage documentation, and test programs, please refer to t | [Lua_c](binding/lua_c/README.md) | lua c extension xdb query client | :white_check_mark: | :white_check_mark: | | [Lua](binding/lua/README.md) | lua xdb query client | :white_check_mark: | :white_check_mark: | | [Rust](binding/rust/README.md) | rust xdb query client | :white_check_mark: | :white_check_mark: | -| [Python](binding/python) | python xdb query client | :white_check_mark: | :white_check_mark: | +| [Python](binding/python/README.md) | python xdb query client | :white_check_mark: | :white_check_mark: | | [Javascript](binding/javascript) | javascript xdb query client | :white_check_mark: | :white_check_mark: | | [Csharp](binding/csharp) | csharp xdb query client | :white_check_mark: | :white_check_mark: | | [Erlang](binding/erlang) | erlang xdb query client | :white_check_mark: | :x: | diff --git a/README_zh.md b/README_zh.md index f9d4d1f..8b67d9f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -43,7 +43,7 @@ API 介绍,使用文档和测试程序请参考对应 `searcher` 查询客户 | [Lua_c](binding/lua_c/README_zh.md) | lua c 扩展 xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Lua](binding/lua/README_zh.md) | lua xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Rust](binding/rust/README_zh.md) | rust xdb 查询客户端 | :white_check_mark: | :white_check_mark: | -| [Python](binding/python) | python xdb 查询客户端 | :white_check_mark: | :white_check_mark: | +| [Python](binding/python/README_zh.md) | python xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Javascript](binding/javascript) | javascript xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Csharp](binding/csharp) | csharp xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Erlang](binding/erlang) | erlang xdb 查询客户端 | :white_check_mark: | :x: | diff --git a/binding/python/README.md b/binding/python/README.md index 8eb9a0e..0e6ceea 100644 --- a/binding/python/README.md +++ b/binding/python/README.md @@ -1,63 +1,75 @@ -# ip2region xdb python 查询客户端实现 +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) -# 版本兼容 -该实现兼容 Python `>=` **`3.7`** +# ip2region python query client -# 使用方式 +# Version Compatibility + +This implementation is compatible with Python `>=` **`3.7`** + +# Usage + +### Install `py-ip2region` -### 安装 `py-ip2region` ```bash pip3 install py-ip2region ``` -### 关于查询 API -查询 API 的原型为: -```python -# 通过字符串 IP 或者 util.parse_ip 解析得到的二进制 IP (bytes类型) 进行查询 +### About Query API + +The prototype of the Query API is: + +```python +# Query via string IP or binary IP (bytes type) parsed by util.parse_ip search(ip: str | bytes) ``` -如果查询出错会抛异常,查询成功则会返回字符的 `region` 信息,如果指定的 IP 查询不到则会返回空字符串 `""`。 -### 关于 IPv4 和 IPv6 -该 xdb 查询客户端实现同时支持对 IPv4 和 IPv6 的查询,使用方式如下: +An exception will be thrown if the query fails. If successful, the `region` information in string format will be returned. If the specified IP cannot be found, an empty string `""` will be returned. + +### About IPv4 and IPv6 + +This xdb query client implementation supports both IPv4 and IPv6 queries. Use it as follows: + ```python import ip2region.util as util -# 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件,IP版本指定为 util.IPv4 -db_path = "../../data/ip2region_v4.xdb" # 或者你的 ipv4 xdb 的路径 +# For IPv4: Set xdb path to the v4 xdb file, and specify the IP version as util.IPv4 +db_path = "../../data/ip2region_v4.xdb" # Or your ipv4 xdb path version = util.IPv4 -# 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件,IP版本指定为 Version.IPv6 -db_path = "../../data/ip2region_v6.xdb" # 或者你的 ipv6 xdb 路径 +# For IPv6: Set xdb path to the v6 xdb file, and specify the IP version as util.IPv6 +db_path = "../../data/ip2region_v6.xdb" # Or your ipv6 xdb path version = util.IPv6 -# db_path 指定的 xdb 的 IP 版本必须和 version 指定的一致,不然查询执行的时候会报错 -# 备注:以下演示直接使用 db_path 和 version 变量 +# The IP version of the xdb specified by db_path must match the version specified by version, otherwise an error will occur during query execution +# Note: The following demonstrations directly use the db_path and version variables ``` -### 文件验证 -建议您主动去验证 xdb 文件的适用性,因为后期的一些新功能可能会导致目前的 Searcher 版本无法适用你使用的 xdb 文件,验证可以避免运行过程中的一些不可预测的错误。 你不需要每次都去验证,例如在服务启动的时候,或者手动调用命令验证确认版本匹配即可,不要在每次创建的 Searcher 的时候运行验证,这样会影响查询的响应速度,尤其是高并发的使用场景。 +### File Verification + +It is recommended that you proactively verify the applicability of the xdb file. Future new features may cause the current Searcher version to be incompatible with the xdb file you are using; verification can prevent unpredictable errors during runtime. You do not need to verify every time. For example, perform verification when the service starts or manually call the command to confirm version matching. Do not run verification every time a Searcher is created, as this will affect query response speed, especially in high-concurrency scenarios. + ```python import ip2region.util as util try: util.verify_from_file(db_path) except Exception e: - # 适用性验证失败!!! - # 当前查询客户端实现不适用于 db_path 指定的 xdb 文件的查询. - # 应该停止启动服务,使用合适的 xdb 文件或者升级到适合 db_path 的 Searcher 实现。 + # Applicability verification failed!!! + # The current query client implementation is not applicable for the xdb file specified by db_path. + # You should stop the service and use a suitable xdb file or upgrade to a Searcher implementation suitable for db_path. print(f"binding is not applicable for xdb file '{db_path}': {str(e)}") return -# 验证通过,当前使用的 Searcher 可以安全的用于对 db_path 指向的 xdb 的查询操作 +# Verification passed, the current Searcher can be safely used for query operations on the xdb pointed to by db_path ``` -### 完全基于文件的查询 +### File-Only Query ```python +import ip2region.util as util import ip2region.searcher as xdb -# 1,使用上述的 version 和 db_path 创建完全基于文件的查询对象 +# 1. Use the version and db_path mentioned above to create a file-only query object try: searcher = xdb.new_with_file_only(version, db_path) except Exception as e: @@ -65,7 +77,7 @@ except Exception as e: return -# 2、查询,IPv4 或者 IPv6 的地址都是同一个接口 +# 2. Query, it supports both IPv4 and IPv6 addresses ip = "1.2.3.4" # ip = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" // IPv6 try: @@ -74,35 +86,36 @@ try: except Exception as e: print(f"failed to search: {str(e)}") -# 3、关闭资源 +# 3. Close resources searcher.close() -# 备注:每个线程需要单独创建一个独立的 Searcher 对象 +# Note: Each thread needs to create an independent Searcher object ``` -### 缓存 `VectorIndex` 索引 +### Caching `VectorIndex` + +We can pre-load the `VectorIndex` data from the `xdb` file and cache it globally. Using the global VectorIndex cache every time a Searcher object is created can reduce a fixed IO operation, thereby accelerating queries and reducing IO pressure. -我们可以提前从 `xdb` 文件中加载出来 `VectorIndex` 数据,然后全局缓存,每次创建 Searcher 对象的时候使用全局的 VectorIndex 缓存可以减少一次固定的 IO 操作,从而加速查询,减少 IO 压力。 ```python import ip2region.util as util import ip2region.searcher as xdb -# 1、从 db_path 中预先加载 VectorIndex 缓存,并且把这个得到的数据作为全局变量,后续反复使用。 +# 1. Pre-load VectorIndex cache from db_path and use this data as a global variable for subsequent repeated use. try: v_index = util.load_vector_index_from_file(db_path) except Exception as e: print(f"failed to load vector index from {db_path}: {str(e)}") return -# 2、使用全局的 v_index 创建带 VectorIndex 缓存的查询对象。 +# 2. Use the global v_index to create a query object with VectorIndex cache. try: searcher = xdb.new_with_vector_index(version, db_path, v_index) except Exception as e: - print(f"failed to new_with_vector_index: {str(e))}") + print(f"failed to new_with_vector_index: {str(e)}") return -# 3、查询,IPv4 或者 IPv6 的地址都是同一个接口 +# 3. Query; the interface is the same for both IPv4 and IPv6 addresses ip = "1.2.3.4" # ip = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" // IPv6 try: @@ -111,34 +124,35 @@ try: except Exception as e: print(f"failed to search: {str(e)}"); -# 4、关闭资源 +# 4. Close resources searcher.close() -# 备注:每个线程需要单独创建一个独立的 Searcher 对象,但是都共享全局的只读 v_index 缓存。 +# Note: Each thread needs to create an independent Searcher object, but they all share the global read-only v_index cache. ``` -### 缓存整个 `xdb` 数据 +### Caching the Entire `xdb` File + +We can also pre-load the data of the entire xdb file into memory and create a query object based on this data to achieve fully memory-based queries, similar to the previous memory search. -我们也可以预先加载整个 xdb 文件的数据到内存,然后基于这个数据创建查询对象来实现完全基于内存的查询,类似之前的 memory search。 ```python import ip2region.util as util import ip2region.searcher as xdb -# 1、从 db_path 加载整个 xdb 到内存。 +# 1. Load the entire xdb into memory from db_path. try: c_buffer = util.load_content_from_file(db_path) except Exception as e: print(f"failed to load content from {db_path}: {str(e)}") return -# 2、使用上述的 c_buff 创建一个完全基于内存的查询对象。 +# 2. Use the c_buffer mentioned above to create a fully memory-based query object. try: searcher = xdb.new_with_buffer(version, c_buffer) except Exception e: print(f"failed to new_with_buffer: {str(e)}") return -# 3、查询,IPv4 或者 IPv6 的地址都是同一个接口 +# 3. Query; the interface is the same for both IPv4 and IPv6 addresses ip = "1.2.3.4" # ip = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" # IPv6 try: @@ -147,16 +161,16 @@ try: except Exception as e: print(f"failed to search: {str(e)}") -# 4、关闭资源 - 该 searcher 对象可以安全用于并发,等整个服务关闭的时候再关闭 searcher +# 4. Close resources - This searcher object can be safely used for concurrency; close the searcher only when the entire service is going to shut down # searcher.close() -# 备注:并发使用,用整个 xdb 数据缓存创建的查询对象可以安全的用于并发,也就是你可以把这个 searcher 对象做成全局对象去跨线程访问。 +# Note: For concurrent use, query objects created with the entire xdb data cache can be safely used for concurrency, meaning you can make this searcher object a global object for cross-thread access. ``` +# Query Test -# 查询测试 +You can test queries via the `python3 search_test.py` command: -可以通过 `python3 search_test.py` 命令来测试查询: ```bash ➜ python git:(fr_python_ipv6) ✗ python3 search_test.py usage: python search_test.py [command option] @@ -170,7 +184,8 @@ options: cache policy: file/vectorIndex/content, default: vectorIndex ``` -例如:使用默认的 data/ip2region_v4.xdb 文件进行 IPv4 的查询测试: +For example: Use the default data/ip2region_v4.xdb file for IPv4 query testing: + ```bash ➜ python git:(fr_python_ipv6) ✗ python3 search_test.py --db=../../data/ip2region_v4.xdb ip2region xdb searcher test program @@ -182,7 +197,8 @@ ip2region>> 113.118.113.77 {region: 中国|广东省|深圳市|电信|CN, ioCount: 2, took: 143 μs} ``` -例如:使用默认的 data/ip2region_v6.xdb 文件进行 IPv6 的查询测试: +For example: Use the default data/ip2region_v6.xdb file for IPv6 query testing: + ```bash ➜ python git:(fr_python_ipv6) ✗ python3 search_test.py --db=../../data/ip2region_v6.xdb ip2region xdb searcher test program @@ -196,12 +212,12 @@ ip2region>> 2604:a840:3::a04d {region: United States|California|San Jose|xTom|US, ioCount: 13, took: 240 μs} ``` -输入 ip 即可进行查询测试,也可以分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的查询效果。 +Input an IP to perform a query test. You can also set `cache-policy` to file/vectorIndex/content respectively to test the effects of the three different cache implementations. +# bench Test -# bench 测试 +Bench testing can be performed via the `python3 bench_test.py` command, which ensures the `xdb` file is error-free and allows for performance evaluation: -可以通过 `python3 bench_test.py` 命令来进行 bench 测试,一方面确保 `xdb` 文件没有错误,一方面可以评估查询性能: ```bash ➜ python git:(fr_python_ipv6) ✗ python3 bench_test.py usage: python bench_test.py [command option] @@ -216,15 +232,17 @@ options: cache policy: file/vectorIndex/content, default: vectorIndex ``` -例如:通过默认的 data/ip2region_v4.xdb 和 data/ipv4_source.txt 文件进行 IPv4 的 bench 测试: +For example: Perform IPv4 bench testing via the default data/ip2region_v4.xdb and data/ipv4_source.txt files: + ```bash python3 bench_test.py --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt ``` -例如:通过默认的 data/ip2region_v6.xdb 和 data/ipv6_source.txt 文件进行 IPv6 的 bench 测试: +For example: Perform IPv6 bench testing via the default data/ip2region_v6.xdb and data/ipv6_source.txt files: + ```bash python3 bench_test.py --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt ``` -可以通过分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的效果。 -@Note: 注意 bench 使用的 src 文件要是生成对应 xdb 文件相同的源文件。 +You can test the effects of the three different cache implementations by setting `cache-policy` to file/vectorIndex/content respectively. +@Note: Ensure the src file used for bench is the same source file used to generate the corresponding xdb file. diff --git a/binding/python/README_zh.md b/binding/python/README_zh.md new file mode 100644 index 0000000..c00981b --- /dev/null +++ b/binding/python/README_zh.md @@ -0,0 +1,233 @@ +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) + +# ip2region python 查询客户端 + +# 版本兼容 +该实现兼容 Python `>=` **`3.7`** + +# 使用方式 + +### 安装 `py-ip2region` +```bash +pip3 install py-ip2region +``` + +### 关于查询 API +查询 API 的原型为: +```python +# 通过字符串 IP 或者 util.parse_ip 解析得到的二进制 IP (bytes类型) 进行查询 +search(ip: str | bytes) +``` +如果查询出错会抛异常,查询成功则会返回字符的 `region` 信息,如果指定的 IP 查询不到则会返回空字符串 `""`。 + +### 关于 IPv4 和 IPv6 +该 xdb 查询客户端实现同时支持对 IPv4 和 IPv6 的查询,使用方式如下: +```python +import ip2region.util as util + +# 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件,IP版本指定为 util.IPv4 +db_path = "../../data/ip2region_v4.xdb" # 或者你的 ipv4 xdb 的路径 +version = util.IPv4 + +# 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件,IP版本指定为 util.IPv6 +db_path = "../../data/ip2region_v6.xdb" # 或者你的 ipv6 xdb 路径 +version = util.IPv6 + +# db_path 指定的 xdb 的 IP 版本必须和 version 指定的一致,不然查询执行的时候会报错 +# 备注:以下演示直接使用 db_path 和 version 变量 +``` + +### 文件验证 +建议您主动去验证 xdb 文件的适用性,因为后期的一些新功能可能会导致目前的 Searcher 版本无法适用你使用的 xdb 文件,验证可以避免运行过程中的一些不可预测的错误。 你不需要每次都去验证,例如在服务启动的时候,或者手动调用命令验证确认版本匹配即可,不要在每次创建的 Searcher 的时候运行验证,这样会影响查询的响应速度,尤其是高并发的使用场景。 +```python +import ip2region.util as util + +try: + util.verify_from_file(db_path) +except Exception e: + # 适用性验证失败!!! + # 当前查询客户端实现不适用于 db_path 指定的 xdb 文件的查询. + # 应该停止启动服务,使用合适的 xdb 文件或者升级到适合 db_path 的 Searcher 实现。 + print(f"binding is not applicable for xdb file '{db_path}': {str(e)}") + return + +# 验证通过,当前使用的 Searcher 可以安全的用于对 db_path 指向的 xdb 的查询操作 +``` + +### 完全基于文件的查询 + +```python +import ip2region.util as util +import ip2region.searcher as xdb + +# 1,使用上述的 version 和 db_path 创建完全基于文件的查询对象 +try: + searcher = xdb.new_with_file_only(version, db_path) +except Exception as e: + print(f"failed to new_with_file_only: {str(e)}") + return + + +# 2、查询,IPv4 或者 IPv6 的地址都是同一个接口 +ip = "1.2.3.4" +# ip = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" // IPv6 +try: + region = searcher.search(ip) + print(f"search({ip}): {{region: {region}, io_count: {searcher.get_io_count()}}}") +except Exception as e: + print(f"failed to search: {str(e)}") + +# 3、关闭资源 +searcher.close() + +# 备注:每个线程需要单独创建一个独立的 Searcher 对象 +``` + +### 缓存 `VectorIndex` 索引 + +我们可以提前从 `xdb` 文件中加载出来 `VectorIndex` 数据,然后全局缓存,每次创建 Searcher 对象的时候使用全局的 VectorIndex 缓存可以减少一次固定的 IO 操作,从而加速查询,减少 IO 压力。 +```python +import ip2region.util as util +import ip2region.searcher as xdb + +# 1、从 db_path 中预先加载 VectorIndex 缓存,并且把这个得到的数据作为全局变量,后续反复使用。 +try: + v_index = util.load_vector_index_from_file(db_path) +except Exception as e: + print(f"failed to load vector index from {db_path}: {str(e)}") + return + +# 2、使用全局的 v_index 创建带 VectorIndex 缓存的查询对象。 +try: + searcher = xdb.new_with_vector_index(version, db_path, v_index) +except Exception as e: + print(f"failed to new_with_vector_index: {str(e))}") + return + + +# 3、查询,IPv4 或者 IPv6 的地址都是同一个接口 +ip = "1.2.3.4" +# ip = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" // IPv6 +try: + region = searcher.search(ip) + print(f"search({ip}): {{region: {region}, io_count: {searcher.get_io_count()}}}") +except Exception as e: + print(f"failed to search: {str(e)}"); + +# 4、关闭资源 +searcher.close() + +# 备注:每个线程需要单独创建一个独立的 Searcher 对象,但是都共享全局的只读 v_index 缓存。 +``` + +### 缓存整个 `xdb` 文件 + +我们也可以预先加载整个 xdb 文件的数据到内存,然后基于这个数据创建查询对象来实现完全基于内存的查询,类似之前的 memory search。 +```python +import ip2region.util as util +import ip2region.searcher as xdb + +# 1、从 db_path 加载整个 xdb 到内存。 +try: + c_buffer = util.load_content_from_file(db_path) +except Exception as e: + print(f"failed to load content from {db_path}: {str(e)}") + return + +# 2、使用上述的 c_buff 创建一个完全基于内存的查询对象。 +try: + searcher = xdb.new_with_buffer(version, c_buffer) +except Exception e: + print(f"failed to new_with_buffer: {str(e)}") + return + +# 3、查询,IPv4 或者 IPv6 的地址都是同一个接口 +ip = "1.2.3.4" +# ip = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" # IPv6 +try: + region = searcher.search(ip) + print(f"search({ip}): {{region: {region}, io_count: 0}}") +except Exception as e: + print(f"failed to search: {str(e)}") + +# 4、关闭资源 - 该 searcher 对象可以安全用于并发,等整个服务关闭的时候再关闭 searcher +# searcher.close() + +# 备注:并发使用,用整个 xdb 数据缓存创建的查询对象可以安全的用于并发,也就是你可以把这个 searcher 对象做成全局对象去跨线程访问。 +``` + + +# 查询测试 + +可以通过 `python3 search_test.py` 命令来测试查询: +```bash +➜ python git:(fr_python_ipv6) ✗ python3 search_test.py +usage: python search_test.py [command option] + +ip2region search test script + +options: + -h, --help show this help message and exit + --db DB ip2region binary xdb file path + --cache-policy CACHE_POLICY + cache policy: file/vectorIndex/content, default: vectorIndex +``` + +例如:使用默认的 data/ip2region_v4.xdb 文件进行 IPv4 的查询测试: +```bash +➜ python git:(fr_python_ipv6) ✗ python3 search_test.py --db=../../data/ip2region_v4.xdb +ip2region xdb searcher test program +source xdb: ../../data/ip2region_v4.xdb (IPv4, vectorIndex) +type 'quit' to exit +ip2region>> 1.2.3.4 +{region: Australia|Queensland|Brisbane|0|AU, ioCount: 5, took: 188 μs} +ip2region>> 113.118.113.77 +{region: 中国|广东省|深圳市|电信|CN, ioCount: 2, took: 143 μs} +``` + +例如:使用默认的 data/ip2region_v6.xdb 文件进行 IPv6 的查询测试: +```bash +➜ python git:(fr_python_ipv6) ✗ python3 search_test.py --db=../../data/ip2region_v6.xdb +ip2region xdb searcher test program +source xdb: ../../data/ip2region_v6.xdb (IPv6, vectorIndex) +type 'quit' to exit +ip2region>> :: +{region: , ioCount: 1, took: 166 μs} +ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e +{region: 中国|广东省|深圳市|电信|CN, ioCount: 8, took: 197 μs} +ip2region>> 2604:a840:3::a04d +{region: United States|California|San Jose|xTom|US, ioCount: 13, took: 240 μs} +``` + +输入 ip 即可进行查询测试,也可以分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的查询效果。 + + +# bench 测试 + +可以通过 `python3 bench_test.py` 命令来进行 bench 测试,一方面确保 `xdb` 文件没有错误,一方面可以评估查询性能: +```bash +➜ python git:(fr_python_ipv6) ✗ python3 bench_test.py +usage: python bench_test.py [command option] + +ip2region bench test script + +options: + -h, --help show this help message and exit + --db DB ip2region binary xdb file path + --src SRC source ip text file path + --cache-policy CACHE_POLICY + cache policy: file/vectorIndex/content, default: vectorIndex +``` + +例如:通过默认的 data/ip2region_v4.xdb 和 data/ipv4_source.txt 文件进行 IPv4 的 bench 测试: +```bash +python3 bench_test.py --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt +``` + +例如:通过默认的 data/ip2region_v6.xdb 和 data/ipv6_source.txt 文件进行 IPv6 的 bench 测试: +```bash +python3 bench_test.py --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt +``` + +可以通过分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的效果。 +@Note: 注意 bench 使用的 src 文件要是生成对应 xdb 文件相同的源文件。