Python Squirrel库入门教程：高效数据缓存与持久化工具

一、Squirrel库核心概述

Squirrel是一款面向Python开发者的轻量级数据缓存与持久化工具库，其核心用途是帮助开发者快速实现内存数据的本地持久化、缓存管理以及跨会话数据共享，无需编写复杂的数据库操作代码。工作原理上，Squirrel基于键值对存储结构，支持将Python原生数据类型（如字典、列表、元组、数值等）序列化为字节流后存储到本地文件，读取时再反序列化为原数据类型，同时提供过期时间设置、缓存清理等功能。该库的优点是API简洁易用、零配置快速上手、支持多种存储后端（文件、内存），对技术小白友好；缺点是不支持高并发场景下的分布式缓存，大数据量存储性能略逊于专业数据库。Squirrel的开源协议为MIT License，开发者可自由用于商业和非商业项目，无授权限制。

二、Squirrel库安装步骤

作为Python的第三方库，Squirrel可以通过pip包管理工具一键安装，无论你是Windows、MacOS还是Linux系统，安装步骤完全一致，具体操作如下：

2.1 环境准备

确保你的电脑已经安装了Python环境（推荐Python 3.6及以上版本），可以通过在命令行中输入以下指令验证Python版本：

# 验证Python版本
import sys
print(sys.version)

运行代码后，如果输出类似3.9.7 (default, Sep 16 2021, 08:50:36) [MSC v.1916 64 bit (AMD64)]的内容，说明Python环境已就绪。

2.2 执行安装命令

打开命令行终端（Windows为CMD或PowerShell，MacOS和Linux为Terminal），输入以下安装指令：

pip install squirrel

等待终端输出Successfully installed squirrel-x.x.x（x.x.x为版本号），即表示安装成功。如果安装过程中出现网络超时问题，可以切换国内PyPI镜像源，例如使用阿里云镜像：

pip install squirrel -i https://mirrors.aliyun.com/pypi/simple/

三、Squirrel库核心API使用教程

Squirrel库的核心操作围绕缓存对象的创建、数据的增删改查、过期时间设置、缓存清理展开，所有API设计都遵循“简洁直观”的原则，即使是没有缓存开发经验的小白也能快速掌握。下面我们通过代码示例逐一讲解每个核心功能的使用方法。

3.1 初始化缓存对象

使用Squirrel的第一步是创建一个缓存实例，该实例可以指定存储后端（默认是文件存储，也可以选择内存存储）。文件存储会将数据保存到本地文件，程序重启后数据不丢失；内存存储则仅在程序运行期间保存数据，程序退出后数据自动清除。

# 导入Squirrel库的核心类
from squirrel import Cache

# 初始化文件存储缓存，数据会保存到本地的squirrel_cache.db文件
file_cache = Cache(backend="file", path="squirrel_cache.db")

# 初始化内存存储缓存，程序退出后数据丢失
memory_cache = Cache(backend="memory")

代码说明：

• backend参数用于指定存储后端，可选值为file和memory，默认值为file。
• path参数仅在backend="file"时生效，用于指定缓存文件的保存路径和文件名。如果不指定，默认会在当前目录下创建squirrel_cache.db文件。

3.2 数据的添加与读取

Squirrel使用set()方法添加数据，使用get()方法读取数据，支持Python所有原生数据类型，包括字符串、数值、列表、字典、元组等。

# 向文件缓存中添加数据
# 存储字符串类型
file_cache.set("username", "python_squirrel")
# 存储数值类型
file_cache.set("age", 25)
# 存储列表类型
file_cache.set("hobbies", ["coding", "reading", "hiking"])
# 存储字典类型
file_cache.set("user_info", {"id": 1001, "name": "小明", "email": "[email protected]"})

# 从文件缓存中读取数据
username = file_cache.get("username")
age = file_cache.get("age")
hobbies = file_cache.get("hobbies")
user_info = file_cache.get("user_info")

# 打印读取的数据
print(f"用户名: {username}")
print(f"年龄: {age}")
print(f"爱好: {hobbies}")
print(f"用户信息: {user_info}")

代码说明：

• set(key, value)方法接收两个参数，key为字符串类型的键名，value为需要存储的任意Python原生数据。
• get(key)方法接收一个参数key，返回该键对应的数值，如果键不存在，则返回None。
• 运行代码后，控制台会输出以下内容：

  用户名: python_squirrel
  年龄: 25
  爱好: ['coding', 'reading', 'hiking']
  用户信息: {'id': 1001, 'name': '小明', 'email': '[email protected]'}

即使关闭程序后重新运行读取代码，数据依然会存在，因为我们使用的是文件存储后端。

3.3 设置数据的过期时间

在很多场景下，我们需要缓存的数据在一段时间后自动失效（例如验证码、临时会话信息），Squirrel的set()方法支持通过expire参数设置过期时间，单位为秒。

# 存储一个有效期为60秒的验证码
file_cache.set("verify_code", "852369", expire=60)

# 立即读取，此时数据未过期
verify_code = file_cache.get("verify_code")
print(f"未过期的验证码: {verify_code}")  # 输出：未过期的验证码: 852369

# 等待60秒后再次读取，数据已过期，返回None
import time
time.sleep(60)
expired_code = file_cache.get("verify_code")
print(f"过期后的验证码: {expired_code}")  # 输出：过期后的验证码: None

代码说明：

• expire参数为可选参数，默认值为None，表示数据永久有效。当指定数值时，数据会在对应的秒数后自动失效。
• 过期的数据会在下次调用get()方法时被检测并清理，不会占用存储空间。

3.4 数据的修改与删除

修改缓存数据的方法依然是set()，只需要对同一个键名重新赋值即可；删除数据则使用delete()方法，指定需要删除的键名即可。

# 修改已存在的数据
file_cache.set("username", "squirrel_python")
updated_username = file_cache.get("username")
print(f"修改后的用户名: {updated_username}")  # 输出：修改后的用户名: squirrel_python

# 删除指定键的数据
file_cache.delete("age")
deleted_age = file_cache.get("age")
print(f"删除后的age值: {deleted_age}")  # 输出：删除后的age值: None

# 批量删除多个键的数据
file_cache.delete_many(["hobbies", "user_info"])
hobbies_after_delete = file_cache.get("hobbies")
user_info_after_delete = file_cache.get("user_info")
print(f"删除后的hobbies值: {hobbies_after_delete}")  # 输出：删除后的hobbies值: None
print(f"删除后的user_info值: {user_info_after_delete}")  # 输出：删除后的user_info值: None

代码说明：

• delete(key)方法用于删除单个键值对，delete_many(keys)方法用于批量删除多个键值对，keys参数为一个包含多个键名的列表。
• 被删除的数据会立即从存储后端中移除，无论是文件存储还是内存存储。

3.5 缓存数据的批量操作

除了单个数据的增删改查，Squirrel还支持批量添加和批量读取数据，这在需要一次性处理大量数据时可以显著提高效率。

# 批量添加数据
batch_data = {
    "key1": "value1",
    "key2": 100,
    "key3": [1, 2, 3],
    "key4": {"a": 1, "b": 2}
}
file_cache.set_many(batch_data)

# 批量读取数据
keys_to_get = ["key1", "key2", "key3", "key4"]
batch_result = file_cache.get_many(keys_to_get)

# 打印批量读取的结果
for key, value in batch_result.items():
    print(f"{key}: {value}")

代码说明：

• set_many(data)方法接收一个字典类型的参数data，字典中的每个键值对都会被添加到缓存中。
• get_many(keys)方法接收一个列表类型的参数keys，返回一个包含所有键值对的字典，对于不存在的键，其对应的数值为None。

3.6 缓存的清空与状态查询

如果需要清空所有缓存数据，可以使用clear()方法；如果需要查询缓存中当前的键数量，可以使用count()方法。

# 查询当前缓存中的键数量
key_count = file_cache.count()
print(f"缓存中的键数量: {key_count}")

# 清空所有缓存数据
file_cache.clear()

# 再次查询键数量，此时为0
empty_count = file_cache.count()
print(f"清空后的键数量: {empty_count}")

代码说明：

• count()方法返回缓存中有效键的数量，不包含已过期的键。
• clear()方法会删除缓存中的所有数据，操作不可逆，使用时需要谨慎。

四、Squirrel库实际应用案例

为了帮助开发者更好地理解Squirrel库在实际项目中的使用场景，下面我们以用户登录状态缓存和API接口数据缓存两个常见场景为例，编写完整的代码案例，展示如何将Squirrel库集成到Python项目中。

4.1 案例一：用户登录状态缓存

在Web开发或桌面应用开发中，用户登录后需要保持登录状态，避免每次操作都重新输入用户名和密码。使用Squirrel可以将用户的登录信息缓存到本地，程序重启后依然可以保持登录状态，直到用户主动退出登录。

from squirrel import Cache
import time

# 初始化文件缓存，存储用户登录信息
login_cache = Cache(backend="file", path="login_status.db")

def user_login(username: str, password: str) -> bool:
    """
    用户登录函数，模拟验证用户名和密码
    :param username: 用户名
    :param password: 密码
    :return: 登录成功返回True，失败返回False
    """
    # 模拟数据库中的用户信息
    db_users = {
        "admin": "admin123",
        "user1": "user123",
        "user2": "user234"
    }
    # 验证用户名和密码
    if username in db_users and db_users[username] == password:
        # 登录成功，缓存用户信息，有效期2小时（7200秒）
        login_cache.set(f"login_{username}", True, expire=7200)
        login_cache.set(f"user_{username}", {"username": username, "login_time": time.time()})
        print(f"用户 {username} 登录成功！")
        return True
    else:
        print("用户名或密码错误，登录失败！")
        return False

def check_login_status(username: str) -> bool:
    """
    检查用户是否处于登录状态
    :param username: 用户名
    :return: 已登录返回True，未登录返回False
    """
    login_status = login_cache.get(f"login_{username}")
    return login_status is not None and login_status

def user_logout(username: str) -> None:
    """
    用户退出登录，清除缓存中的登录状态
    :param username: 用户名
    """
    login_cache.delete(f"login_{username}")
    login_cache.delete(f"user_{username}")
    print(f"用户 {username} 已退出登录！")

# 测试登录功能
user_login("admin", "admin123")

# 检查登录状态
if check_login_status("admin"):
    user_info = login_cache.get(f"user_admin")
    login_time = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(user_info["login_time"]))
    print(f"用户 {user_info['username']} 于 {login_time} 登录，当前处于登录状态。")

# 退出登录
user_logout("admin")

# 再次检查登录状态
if not check_login_status("admin"):
    print(f"用户 admin 已退出登录。")

代码说明：

• user_login()函数模拟用户登录验证，验证通过后将登录状态和用户信息缓存到本地，有效期为2小时。
• check_login_status()函数通过读取缓存中的登录状态键，判断用户是否处于登录状态。
• user_logout()函数通过删除缓存中的登录状态键，实现用户退出登录功能。
• 该案例适用于桌面应用、CLI工具等需要保持用户登录状态的场景，无需依赖数据库即可实现状态持久化。

4.2 案例二：API接口数据缓存

在调用第三方API接口时，频繁请求会导致接口限流、响应速度慢等问题。使用Squirrel可以将API返回的数据缓存到本地，在有效期内重复请求时直接读取缓存数据，从而提高程序的响应速度，减少对API接口的请求次数。

from squirrel import Cache
import requests
import time

# 初始化文件缓存，存储API接口数据
api_cache = Cache(backend="file", path="api_cache.db")

def get_weather_data(city: str) -> dict:
    """
    获取城市天气数据，优先读取缓存，缓存失效后调用API接口
    :param city: 城市名称
    :return: 天气数据字典
    """
    # 定义缓存键名
    cache_key = f"weather_{city}"
    # 尝试从缓存中读取数据
    cached_data = api_cache.get(cache_key)
    if cached_data is not None:
        print(f"从缓存中读取{city}的天气数据...")
        return cached_data

    # 缓存失效，调用API接口获取数据（这里使用模拟API）
    print(f"调用API获取{city}的天气数据...")
    # 模拟API请求延迟
    time.sleep(2)
    # 模拟API返回的数据
    api_data = {
        "city": city,
        "temperature": 22,
        "weather": "sunny",
        "humidity": 45,
        "update_time": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime())
    }

    # 将API返回的数据缓存到本地，有效期10分钟（600秒）
    api_cache.set(cache_key, api_data, expire=600)
    return api_data

# 第一次调用，缓存未命中，调用API
weather_beijing = get_weather_data("北京")
print(f"北京天气: {weather_beijing}")

# 第二次调用，缓存命中，直接读取缓存
weather_beijing_cached = get_weather_data("北京")
print(f"北京天气（缓存）: {weather_beijing_cached}")

代码说明：

• get_weather_data()函数实现了“缓存优先”的逻辑，首先尝试从缓存中读取数据，如果缓存存在且未过期，则直接返回缓存数据；如果缓存不存在或已过期，则调用API获取数据，并将数据缓存到本地。
• 该案例中设置的缓存有效期为10分钟，意味着10分钟内重复调用该函数获取同一城市的天气数据，不会触发API请求，从而减少了API调用次数，提高了程序响应速度。
• 实际项目中，可以将模拟API替换为真实的天气API接口，例如高德地图天气API、和风天气API等。

五、Squirrel库相关资源链接

• Pypi地址：https://pypi.org/project/Squirrel
• Github地址：https://github.com/xxxxx/xxxxxx
• 官方文档地址：https://www.xxxxx.com/xxxxxx

关注我，每天分享一个实用的Python自动化工具。