# IDCard_Validate_Tools

**Repository Path**: jarvy01/IDCard_Validate_Tools

## Basic Information

- **Project Name**: IDCard_Validate_Tools
- **Description**: 通过身份证号码校验号码是否正确，提取号码归属地、性别、生日、年龄等信息。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2024-12-01
- **Last Updated**: 2024-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IDCard_verify

一个用于验证中国居民身份证号码并提取信息的Python库。

## 功能特点

- 支持15位和18位身份证号码验证
- 智能识别和验证地区编码
- 验证出生日期的合法性
- 验证18位身份证的校验码
- 提取身份证号码中包含的个人信息
- 支持省市县三级地区智能解析
- 自动处理特殊行政区和直辖市

## 安装

```bash
pip install idcard-verify
```

## 快速开始

```python
from IDCard import IdCard

# 创建IdCard实例
try:
    idcard = IdCard('身份证号码')
    
    # 获取基本信息
    print(idcard.fullarea)    # 输出: 湖北省黄冈市
    print(idcard.sex)         # 输出: male/female
    print(idcard.sex_cn)      # 输出: 男/女
    print(idcard.birthday)    # 输出: datetime对象
    print(idcard.age)         # 输出: 25
    
    # 获取所有信息
    info = idcard.info_to_dict
    print(info)  # 输出所有信息的字典
    
except ValueError as e:
    print(f'验证失败: {e}')
```

## API文档

### IdCard类

#### 属性

- `id`: str - 身份证号码
- `validate`: bool - 身份证号码是否有效
- `fullarea`: str - 完整的行政区划信息（智能组合省市县名称）
- `sex`: str - 性别(英文，'female'或'male')
- `sex_cn`: str - 性别(中文，'女'或'男')
- `birthday`: datetime - 出生日期
- `age`: int - 年龄
- `info_to_dict`: dict - 包含所有信息的字典

#### 方法

- `__init__(id_number: str)`: 初始化IdCard对象
- `checkIdcard() -> tuple`: 检查身份证号码的合法性，返回(是否合法, 错误信息)
- `get_area(code: str) -> str`: 获取行政区划代码对应的地区名称

### 地区编码解析说明

本库支持智能的地区编码解析：

1. 完整的6位地区编码解析：

```python
idcard = IdCard('420106xxxxxxxxxx')
print(idcard.fullarea)  # 输出: 湖北省武汉市武昌区
```

2. 缺失县级编码的解析：

```python
idcard = IdCard('422100xxxxxxxxxx')
print(idcard.fullarea)  # 输出: 湖北省黄冈市
```

3. 特殊行政区处理：

```python
idcard = IdCard('110100xxxxxxxxxx')
print(idcard.fullarea)  # 输出: 北京市
```

4. 自动处理重复问题：
- 直辖市不会重复显示市名
- 省直辖县会正确显示层级关系
- 特殊行政区会使用正确的名称

## 异常处理

当传入无效的身份证号码时，将抛出ValueError异常：

```python
try:
    idcard = IdCard('无效的身份证号码')
except ValueError as e:
    print(f'错误: {e}')
```

可能的错误包括：
- 身份证号码格式错误
- 地区编码不存在
- 出生日期无效
- 校验码错误

## 开发说明

### 环境要求

- Python 3.6+
- 无其他外部依赖

### 本地开发

1. 克隆仓库

```bash
git clone https://github.com/yourusername/IDCard_verify.git
```

2. 安装依赖（如果有）

```bash
pip install -r requirements.txt
```

### 数据更新

行政区划数据存储在压缩的JSON文件中，如需更新：

1. 编辑 `IDCard/area_codes.json`
2. 运行更新工具：

```bash
python tools/export_area_codes.py
```

## 许可证

MIT License

## 贡献指南

欢迎提交Issue和Pull Request。在提交PR之前，请确保：

1. 更新测试用例
2. 遵循PEP 8编码规范
3. 更新相关文档

## 更新日志

### 1.1.0
- 优化了地区编码解析逻辑
- 增加了省市县三级智能解析
- 改进了特殊行政区处理
- 优化了数据存储方式

### 1.0.0
- 初始发布
- 基本的身份证验证功能
- 信息提取功能