当前位置：首页 > news >正文

Python 中的 typing.ClassVar 详解

news 来源：原创 2025/6/21 1:08:30

一、ClassVar 的定义和基本用途

ClassVar 是 typing 模块中提供的一种特殊类型，用于在类型注解中标记类变量（静态变量）。根据官方文档，使用 ClassVar[…] 注释的属性表示该属性只在类层面使用，不应在实例上赋值
例如：

from typing import ClassVarclass Starship:stats: ClassVar[dict[str, int]] = {}  # 类变量damage: int = 10                     # 实例变量

上例中，stats 被标注为 ClassVar，表示它是一个共享的类级别变量；damage 则是普通的实例变量。需要注意的是，ClassVar 只是类型提示，不改变运行时行为；它本身不是类，也不能用于 isinstance() 或 issubclass() 检查。

二、ClassVar 与实例变量的区别

在 Python 中，类中定义并赋值的变量默认属于类属性，所有实例共享同一份数据。使用 ClassVar 注解后，静态类型检查器会将该属性视为“类变量”，并禁止通过实例来赋值。相反，实例变量通常在 init 方法中初始化，或者在类体中仅使用类型注解而不赋默认值。例如，下面的写法会导致混淆，不建议这样写：

class A:x: ClassVar[int] = 1  # 类变量y: int = 2            # 实际上，这里 y 是在类体中赋值，运行时也是类变量def __init__(self):self.y = 2        # 将 y 定义为实例变量

如上所示，不要在类体中给期望的实例变量赋值，否则该变量既被注解为实例属性，又被赋予了类属性的默认值，导致类型检查和逻辑上的混淆。正确做法是：在类体中仅使用注解不赋值（y: int），并在 init 中给实例属性赋值；或者如果需要类级别配置，则显式使用 ClassVar 注解。类型检查器（如 mypy）会识别 ClassVar 注释的属性，并在不当使用时发出警告或错误。

PEP 526 背景： ClassVar 的引入源自 PEP 526（2016 年提出），该 PEP 为变量注解提供了语法。PEP 526 明确指出，通过 ClassVar[…] 注解的变量标识为类变量，不应在实例上被赋值。在 PEP 526 的示例中，有如下类：

class Starship:captain: str = 'Picard'               # 实例属性（默认值）damage: int                           # 实例属性（无默认值）stats: ClassVar[dict[str, int]] = {}  # 类属性

这里 stats 是真正意义上的类变量（比如记录游戏统计数据），而 captain 只是为实例提供了一个默认值。PEP 526 解释说，区分类变量和实例变量对静态类型检查器很有帮助，例如下面代码中，如果不使用 ClassVar：

enterprise = Starship(3000)
enterprise.stats = {}   # 如果 stats 是类变量，这里将被标记为错误
Starship.stats = {}     # 正确，直接修改类的属性

使用 ClassVar 让类型检查器能够在类似 enterprise.stats = {} 这种赋值操作上报错。

三、适用场景

ClassVar 主要用于需要共享或静态存储的类属性场景，例如：

3.1 共享配置或常量

类中定义的配置信息、常量或缓存（如超时、默认值等），需要被所有实例共享。通过 ClassVar 标记后，这些属性被视为类级别常量
例如：

class Config:DEFAULTS: ClassVar[dict] = {'timeout': 5, 'verbose': False}

3.2 dataclass 中排除实例字段

在使用 @dataclass 时，可以用 ClassVar 标记那些不应出现在 init 中的类属性。ClassVar 注释的字段不会被视为实例字段，因此不会成为构造参数。
例如：

@dataclass
class Point:x: inty: intcount: ClassVar[int] = 0  # 类级计数器，不作为实例字段

在上例中，count 不会出现在自动生成的 init 方法参数中。

3.3 类型协议

在使用结构化子类型（PEP 544 的 Protocol）时，可以用 ClassVar 区分类属性和实例属性，帮助类型检查器理解协议的成员性质。RealPython 的示例也指出：“应该使用 ClassVar 来区分类属性和实例属性”。

3.4 其他静态用途

如实现单例模式、缓存计算结果、计数器等场合，ClassVar 都可用于标识那些跨实例共享的数据。

四、代码示例

from typing import ClassVarclass Starship:stats: ClassVar[dict[str, int]] = {}  # 类变量damage: int = 10                      # 实例变量enterprise = Starship()
print(Starship.stats)  # 输出 {}
print(enterprise.stats)  # 同样输出 {}（实例读取的是类属性）
enterprise.stats = {'hits': 1}  # 通过实例赋值：会创建实例属性，不推荐
print(Starship.stats)  # 仍输出 {}，说明类属性未被改变
print(enterprise.stats)  # 输出 {'hits': 1}，实例属性覆盖了类属性

在上述示例中，stats 被标记为 ClassVar，表明它应作为类属性共享使用。从运行结果可以看到，通过实例 enterprise.stats = {…} 赋值实际上会新建一个实例属性，不影响原有的类属性；类型检查器会将这种通过实例修改 ClassVar 的行为视为错误。

另一个示例演示了 dataclass 中的 ClassVar 用法：

from dataclasses import dataclass
from typing import ClassVar@dataclass
class Counter:x: inty: inttotal: ClassVar[int] = 0  # 类级计数器# 创建实例时，__init__ 只接收 x, y 两个参数，total 不在其中
c1 = Counter(1, 2)
c2 = Counter(3, 4)
print(Counter.total, c1.total, c2.total)  # 输出 0 0 0
Counter.total = 5
print(c1.total, c2.total)  # 输出 5 5（所有实例共享类属性）

在这个例子中，total 使用了 ClassVar 注解，所以在 dataclass 自动生成的构造函数中不会包含它。所有实例都共享同一个 total 值，且修改 Counter.total 会影响所有实例的读值。

五、 ClassVar 与 @classmethod、@staticmethod 的关系

ClassVar、@classmethod 和 @staticmethod 属于不同的概念，它们之间没有直接关联：
ClassVar 用于标记类属性（变量），仅影响类型提示；它不会改变对象的绑定行为。
@classmethod 是一个装饰器，用于定义类方法，使方法第一个参数接收类本身（通常命名为 cls），可用于访问或修改类状态。
@staticmethod 也是装饰器，将方法转为静态方法，不接收类或实例的隐式参数，类似普通函数。
简而言之，ClassVar 关注的是数据（属性）级别的静态标记，而 @classmethod/@staticmethod 是对方法的绑定方式的修饰，两者作用域不同、互不干扰。

六、常见误用及陷阱

误以为运行时生效： ClassVar 只是类型标记，对程序运行时无任何影响。不要指望它在运行时阻止属性被修改；它不会生成新的行为或存储方式。

在实例上赋值： 尽管运行时允许 instance.var = …，但类型检查器会认为这是错误的。mypy 示例中指出，将类变量通过实例赋值会报错（但代码运行时依然会新建实例属性）。正确的操作应修改类属性：ClassName.var = …。

省略类型参数： 如果在 ClassVar 中省略类型（例如写成 x: ClassVar = 0），这会导致该属性被视为隐式 Any 类型。这一行为可能与预期不符，应始终提供具体类型：ClassVar[int]。

ClassVar 不是类： ClassVar 不能用于 isinstance() 或 issubclass() 等检查；它本身也不是可实例化的类。

类型变量（TypeVar）不可用： ClassVar 的类型参数必须是具体类型，不能使用类型变量。例如 ClassVar[T]（其中 T 是 TypeVar）是非法的，会被静态检查器视为错误。

与 Final 一起使用： PEP 591 建议不要同时将 ClassVar 和 Final 注解标记在同一个属性上。Python 3.12 及更早版本中，两者同时使用会导致错误；正确的做法是仅使用 Final 注解即可表示类级常量。在 Python 3.13 及以后版本中，文档已允许 ClassVar 与 Final 嵌套使用。

滥用概念： 不要将 ClassVar 当成 Java/C++ 中那种“静态变量”语义上的特殊对象；在 Python 中，它仅是一个类型提示工具，不会自动创建或隐藏实例属性。

Python 中的 typing.ClassVar 详解

一、ClassVar 的定义和基本用途 ClassVar 是 typing 模块中提供的一种特殊类型，用于在类型注解中标记类变量（静态变量）。根据官方文档，使用 ClassVar[…] 注释的属性表示该属性只在类层面使用，不应在实例上赋值例如&…...

编程日记 2025/6/21 1:08:30

主流数据库运维故障排查卡片式速查表与视觉图谱

主流数据库运维故障排查卡片式速查表与视觉图谱本文件将主文档内容转化为模块化卡片结构，并补充数据库结构图、排查路径图、锁机制对比等视觉图谱，以便在演示、教学或现场排障中快速引用。 📌 故障卡片速查：连接失败数据库检查…...

编程日记 2025/6/21 0:26:40

Unity：延迟执行函数：Invoke()

目录 Unity 中的 Invoke() 方法详解什么是 Invoke()？ 基本使用方法使用要点延伸功能 ❗️Invoke 的局限与注意事项在Unity中，延迟执行函数是游戏逻辑中常见的需求，比如： 延迟切换场景延迟播放音效或动画给玩家时间…...

编程日记 2025/5/29 21:12:45

医学影像系统性能优化与调试技术：深度剖析与实践指南

🧑 博主简介：CSDN博客专家、CSDN平台优质创作者，高级开发工程师，数学专业，10年以上C/C, C#, Java等多种编程语言开发经验，拥有高级工程师证书；擅长C/C、C#等开发语言，熟悉Java常用开…...

编程日记 2025/5/26 10:00:38

【HTML5学习笔记1】html标签（上）

web标准（重点） w3c 构成：结构、表现、行为，结构样式行为相分离结构：网页元素整理分类 html 表现：外观css 行为：交互 javascript html标签 1.html语法规范 1） 所有标签都在…...

编程日记 2025/5/29 16:59:24

SearchIndexablesProvider

实现的 provider 根据索引添加文档可知，该 provider 需要继承自 frameworks/base/core/java/android/provider/SearchIndexablesProvider.java 类，并且添加权限 android.permission.READ_SEARCH_INDEXABLES。过滤 Settings 代码，可以轻易找到…...

编程日记 2025/5/26 10:42:29

《k-means 散点图可视化》实验报告

一，实验目的本次实验旨在通过Python编程实现k - means算法的散点图可视化。学习者将编写代码，深入理解聚类分析基本原理与k - means算法实现流程，掌握数据聚类及可视化方法，以直观展示聚类结果。二，实验原理 k-mea…...

编程日记 2025/5/29 15:24:09

数学复习笔记 12

前言现在做一下例题和练习题。矩阵的秩和线性相关。另外还要复盘前面高数的部分的内容。奥，之前矩阵的例题和练习题，也没有做完，行列式的例题和练习题也没有做完。累加起来了。以后还是得学一个知识点就做一个部分的内容，日拱一…...

编程日记 2025/5/24 16:28:43

Web-CSS入门

WEB前端，三部分：HTML部分、CSS部分、Javascript部分。 1.HTML部分：主要负责网页的结构层 2.CSS部分：主要负责网页的样式层 3.JS部分：主要负责网页的行为层 **基本概念** 层叠样式表，Cascading Style Sh…...

编程日记 2025/5/28 15:17:16

Qt/C++编写音视频实时通话程序/画中画/设备热插拔/支持本地摄像头和桌面

一、前言近期有客户提需求，需要在嵌入式板子上和电脑之间音视频通话，要求用Qt开发，可以用第三方的编解码组件，能少用就尽量少用，以便后期移植起来方便。如果换成5年前的知识储备，估计会采用纯网络通信收发…...

编程日记 2025/5/29 20:12:00

Ubuntu快速安装Python3.11及多版本管理

之前文章和大家分享过，将会出一篇专栏（从电脑装ubuntu系统，到安装ubuntu的常用基础软件：jdk、python、node、nginx、maven、supervisor、minio、docker、git、mysql、redis、postgresql、mq、ollama等），目前…...

编程日记 2025/6/1 8:10:21

Qt功能区：Ribbon使用

Ribbon使用 1. Ribbon功能区介绍1.1 样式 2. 基本功能区设置2.1 安装动态库（推荐）2.2 在MainWindow中使用Ribbon2.3 在QWidget中使用SARibbonBar2.4 创建Category和Pannel2.5 ContextCategory 上下文标签创建 2.6 ApplicationButton2.7 QuickAccessBar和…...

编程日记 2025/5/29 14:43:34

【学习心得】Jupyter 如何在conda的base环境中其他虚拟环境内核

如果你在conda的base环境运行了jupyter lab打开了一个ipynb文本，此时选择的内核是base虚拟环境的Python内核，如果我想切换成其他conda虚拟环境来运行这个文件该怎么办？下面我们试着还原一下问题，并且解决问题。【注】这个问题出…...

编程日记 2025/5/26 10:43:16

在微创手术中使用Kinova轻型机械臂进行多视图图像采集和3D重建

在微创手术中，Kinova轻型机械臂通过其灵活的运动控制和高精度的操作能力，支持多视图图像采集和3D重建。这种技术通过机械臂搭载的光学系统实现精准的多角度扫描，为医疗团队提供清晰且详细的解剖结构模型。其核心在于结合先进的传感器配置与重…...

编程日记 2025/5/29 22:50:00

[Java][Leetcode middle] 238. 除自身以外数组的乘积

第一个想法是： 想求出所有元素乘积，然后除以i对应的元素本书；这个想法是完全错误的： nums[I] 可能有0题目要求了不能用除法第二个想法是： 其实写之前就知道会超时，但是我什么都做不到啊！ 双…...

编程日记 2025/5/27 7:02:18

【leetcode】144. 二叉树的前序遍历

给你二叉树的根节点 root ，返回它节点值的前序遍历。示例 1： 输入：root [1,null,2,3] 输出：[1,2,3] 解释： 示例 2： 输入：root [1,2,3,4,5,null,8,null,null,6,7,9] 输出&#xff1a…...

编程日记 2025/5/29 11:33:21

SpringBoot常用注解详解

文章目录 1. 前言2. 核心注解2.1 SpringBootApplication2.2 Configuration2.3 EnableAutoConfiguration2.4 ComponentScan2.5 Bean2.6 Autowired2.7 Qualifier2.8 Primary2.9 Value2.10 PropertySource2.11 ConfigurationProperties2.12 Profile 3. Web开发相关注解3.1 Control…...

编程日记 2025/5/26 11:36:08

中文分词与数据可视化02

jieba 库简介 jieba（结巴分词）是一个高效的中文分词工具，广泛用于中文自然语言处理（NLP）任务。它支持以下功能： 分词：将句子切分为独立的词语。自定义词典：添加专业词汇或新词&am…...

编程日记 2025/5/27 15:22:02

SSH主机密钥验证失败：全面解决方案与技术手册

一、问题本质与安全机制解析 SSH(Secure Shell)的主机密钥验证是安全通信的核心机制，当出现"Host key verification failed"错误时，表明客户端检测到服务器身份异常。这种设计可有效防范中间人攻击(Man-in-the-Middle)，其工作原理…...

编程日记 2025/5/29 0:42:28

buuctf Crypto-鸡藕椒盐味1

1.题目： 公司食堂最新出了一种小吃，叫鸡藕椒盐味汉堡，售价八块钱，为了促销，上面有一个验证码，输入后可以再换取一个汉堡。但是问题是每个验证码几乎都有错误,而且打印的时候倒了一下。小明买到了一个汉堡&a…...

编程日记 2025/5/29 10:20:52

真题卷001——算法备赛

蓝桥杯2024年C/CB组国赛卷 1.合法密码问题描述小蓝正在开发自己的OJ网站。他要求用户的密码必须符合一下条件： 长度大于等于8小于等于16必须包含至少一个数字字符和至少一个符号字符请计算一下字符串，有多少个子串可以当作合法密码。字符串为&am…...

编程日记 2025/5/27 8:22:44

基于MCP的桥梁设计规范智能解析与校审系统构建实践

引言在腾讯云开发者社区中，有多种MCP工具可以用于本系统的开发和优化中，以下是一些潜在的应用场景： ‌PDF解析工具‌：如pdfplumber等，可以用于规范文件的预处理，提取文本和图像信息。‌自然语言处理工具…...

编程日记 2025/5/22 2:16:27

matlab与python问题解析

Python requests乱码的五种解决办法 Python requests乱码的五种解决办法_requests.get乱码-CSDN博客 requests库post请求参数data、json和files的使用 requests库post请求参数data、json和files的使用_requests post data-CSDN博客如何在浏览器中查看POST请求提交的数据内…...

编程日记 2025/5/29 16:59:09

【分布式锁通关指南 10】源码剖析redisson之MultiLock的实现

引言本期我们将把目光聚焦在 Redisson 中另一个颇具代表性的分布式锁实现——MultiLock。它的核心思想是：一次性对多个独立的 RLock 进行加锁或解锁操作，只有当多个锁都成功加锁时才算真正完成锁的获取，一旦有任何一个失败，整体操…...

编程日记 2025/5/29 13:11:49

MySQL 8.0 OCP 1Z0-908 131-140题

Q131.You have upgraded the MySQL binaries from 5.7.28 to 8.0.18 by using an in-place upgrade. Examine the message sequence generated during the first start of MySQL 8.0.18: 。。。[System]。。。/usx/sbin/mysqld (mysqld 8.0.18-commercial) starting as process…...

编程日记 2025/5/29 13:38:04

实战解析MCP-使用本地的Qwen-2.5模型-AI协议的未来？

文章目录目录文章目录前言一、MCP是什么？ 1.1MCP定义 1.2工作原理二、为什么要MCP？ 2.1 打破碎片化的困局 2.2 实时双向通信，提升交互效率 2.3 提高安全性与数据隐私保护三、MCP 与 LangChain 的区别 3.1 目标定位不同 3.…...

编程日记 2025/5/29 12:00:03

从零开始学习three.js（20）：three.js实现天气与时间动态效果（白天，黑夜，下雨，下雪）

基于Three.js的天气与时间动态效果实现本文将通过代码解析，介绍如何使用Three.js实现动态天气（下雨、下雪）和时间（白天、黑夜）切换效果。完整代码基于一个交互式天气模拟项目，支持粒子密度、速度和环境亮…...

编程日记 2025/5/17 5:58:50

sqli-labs靶场23-28a关（过滤）

目录 less23（--过滤） less24（二次注入） less25（or过滤） less25a（or过滤） less26（--和空格过滤报错） less26a（--空格过滤盲注） …...

编程日记 2025/5/22 0:30:54

Sigmoid与Softmax：从二分类到多分类的深度解析

Sigmoid与Softmax：从二分类到多分类的深度解析联系函数性质：二者都是非线性函数，也都是指数归一化函数，可将输入值映射为0到1之间的实数，都能把输出转化成概率分布的形式，在神经网络中常作为激活函数使用。Softmax是Sigmoid的推广：从功能角度看，Softmax函数可视为…...

编程日记 2025/5/29 16:52:55

uni-app x正式支持鸿蒙原生应用开发

DCloud发布的HBuilderX 4.64正式版，支持编译uni-app x项目到鸿蒙平台，实现跨平台开发鸿蒙原生应用。至此，uni-app x 已经完成Android、iOS、鸿蒙、Web、微信小程序等主流平台全覆盖。 uni-app x，是下一代 uni-app，是一…...

编程日记 2025/5/28 22:40:30

【软件推荐——pdf2docx】

pdf2docx Open source Python library for converting PDF to DOCX. https://github.com/ArtifexSoftware/pdf2docx Install pip install pdf2docx使用 from pdf2docx import Converterpdf_file D:\my\c4611_sample_explain.pdf docx_file D:\my\c4611_sample_explain.d…...

编程日记 2025/5/27 0:13:48