Metadata-Version: 2.3
Name: xdb_location
Version: 0.1.37
Summary: a geographic information database
Author: hongjian fang
Author-email: hongjian fang <fanghongjian@geetest.com>
License: MIT
Requires-Dist: pytest>=8.3.5
Requires-Dist: requests>=2.31.0
Requires-Dist: typer
Requires-Dist: coverage ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: ruff ; extra == 'test'
Requires-Dist: ty ; extra == 'test'
Requires-Dist: ipdb ; extra == 'test'
Maintainer: hongjian fang
Maintainer-email: hongjian fang <fanghongjian@geetest.com>
Requires-Python: >=3.8
Project-URL: bugs, https://github.com/gunhe/xdb_location/issues
Project-URL: changelog, https://github.com/gunhe/xdb_location/blob/master/HISTORY.md
Project-URL: homepage, https://github.com/gunhe/xdb_location
Provides-Extra: test
Description-Content-Type: text/markdown

# XdbLocation
是一个离线IP地址定位库和IP定位数据管理的库


* PyPI package: https://pypi.org/project/xdb_location/
* Github: https://github.com/gunhe/xdb_location

# 安装

## 稳定版本

要安装Xdb_Location，请在终端中运行以下命令：

```sh
uv add xdb_location
```

或者，如果你更喜欢使用 `pip`:

```sh
pip install xdb_location
```

## 源码安装

Xdb_Location的源文件可以从以下网址下载 [Github repo](https://github.com/gunhe/xdb_location).

您可以克隆公共存储库:

```sh
git clone git://github.com/gunhe/xdb_location
```

一旦你有了源代码的副本，你就可以用以下方式安装它：

```sh
cd xdb_location
uv pip install .
```

## 使用
```bash
from xdb_location.xdb_location import searchWithContent
target_ip_location = searchWithContent(target_ip="1.15.241.228")
print(target_ip_location)
```

## 虚拟号查询

查询手机号是否命中虚拟运营商号段库：

```python
from virtual_phone import virtual_number_searcher

result = virtual_number_searcher("17040655743")
print(result)
```

返回示例：

```python
{
    "section": "1704065",
    "area": "福建 漳州",
    "network": "联通网络",
    "provider": "天音移动",
    "company": "天音通信",
    "is_virtual_number": True,
    "phone_number": "17040655743",
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `section` | 手机号前 7 位号段 |
| `area` | 号段归属地 |
| `network` | 使用网络 |
| `provider` | 虚拟运营商品牌 |
| `company` | 虚拟运营商所属公司 |
| `is_virtual_number` | 是否命中虚拟号段库 |
| `phone_number` | 原始查询手机号 |

如果未命中虚拟号段库，`is_virtual_number` 为 `False`，其余未知字段返回 `未知`：

```python
{
    "section": "1582732",
    "area": "未知",
    "network": "未知",
    "provider": "未知",
    "company": "未知",
    "is_virtual_number": False,
    "phone_number": "15827325745",
}
```

## 最佳实践
```bash
# 程序启动前把 searchWithContent 对象缓存下来，做成一个全局对象
from xdb_location.xdb_location import searchWithContentCache

# 使用searchWithContent 对象来查询
searcher = searchWithContentCache()
target_ip_location = searcher.search("1.15.241.228")
print(target_ip_location)

# 程序结束时候释放内存空间
searcher.close()
```

# 数据生成

```bash
git clone https://github.com/gunhe/xdb_location.git
cd xdb_location
# 测试数据生成
uv run xdb_location ./src/xdb_location/data/ip.test.txt ./ip2region.test.xdb
# ipv4 数据生成
uv run xdb_location ./src/xdb_location/data/ipv4_source.txt ./ip2region.ipv4_source.xdb
# ipv6 数据生成
uv run xdb_location ./src/xdb_location/data/ipv6_source.txt ./ip2region.ipv6_source.xdb
```

## 参考

[uv](https://docs.astral.sh/uv/)

[Publishing your package](https://docs.astral.sh/uv/guides/package/)

[Using uv in GitHub Actions](https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi)

[Typer](https://typer.tiangolo.com/tutorial/)

[Cookiecutter](https://github.com/audreyfeldroy/cookiecutter)

[audreyfeldroy/cookiecutter-pypackage](https://github.com/audreyfeldroy/cookiecutter-pypackage)

[https://github.com/lionsoul2014/ip2region](https://github.com/lionsoul2014/ip2region)
