fiftyone-code-style

用途

FiftyOne Code Style 用于编写符合 FiftyOne 官方约定的 Python 代码。适用于向 FiftyOne 贡献代码、开发插件，或编写与 FiftyOne 集成的代码。

主要能力

模块模板

技能提供以下模块结构模板：文档字符串 → 导入 → logger → 公共函数 → 私有函数。示例中包含模块描述文档字符串、版权声明、导入语句、logger = logging.getLogger(__name__)，以及 public_function 调用 _helper 的写法。

导入组织

导入分为四组，每组内部按字母排序，组间以空行分隔：

组	示例
1. 标准库	import logging、import os
2. 第三方	import numpy as np
3. eta 包	import eta.core.utils as etau
4. FiftyOne	import fiftyone.core.labels as fol

FiftyOne 导入别名

模块	别名
fiftyone	fo
fiftyone.core.labels	fol
fiftyone.core.fields	fof
fiftyone.core.media	fom
fiftyone.core.storage	fos
fiftyone.core.utils	fou
fiftyone.utils.image	foui
fiftyone.utils.video	fouv

文档字符串（Google 风格）

参数带默认值时写作 param (default): description；多行描述需缩进续行；交叉引用使用 :class:fiftyone.module.Class。文档字符串包含 Args、Returns、Raises 部分，例如 `get_operator` 的示例中包含 `operator_uri`、`enabled (True)` 参数，返回 `:class:`fiftyone.operators.Operator，并在未找到时抛出 ValueError。

惰性导入

对可选或重型依赖使用 fou.lazy_import()：

o3d = fou.lazy_import("open3d", callback=lambda: fou.ensure_package("open3d"))

mask_utils = fou.lazy_import(
    "pycocotools.mask", callback=lambda: fou.ensure_import("pycocotools")
)

守卫模式

使用 hasattr() 检查可选属性：

if hasattr(label, "confidence"):
    if label.confidence is None or label.confidence < threshold:
        label = label.__class__()

错误处理

非致命错误使用 logger.warning()：

try:
    result = process_data(data)
except Exception as e:
    logger.warning("Failed to process data: %s", e)

避免冗余代码

编写新函数前先搜索已有实现：本地搜索环境中的 FiftyOne 源码；远程搜索 https://github.com/voxel51/fiftyone；优先检查 fiftyone/core/utils.py 和 fiftyone/utils/*。

常用工具函数

模块	函数
fou	lazy_import()、ensure_package()、extract_kwargs_for_class()
etau	guess_mime_type()、ensure_dir()、make_temp_dir()

速查参考

模式	约定
模块结构	文档字符串 → 导入 → logger → 公共 → 私有
私有函数	前缀 _
文档字符串	Google 风格，含 Args/Returns/Raises
错误处理	非致命错误使用 logger.warning()
惰性导入	可选依赖使用 fou.lazy_import()
守卫模式	使用 hasattr() 检查
导入别名	fo、fol、fof、fom、fos、fou

适用场景

适合参与 FiftyOne 项目开发、编写 FiftyOne 插件，或开发需要与 FiftyOne 集成的代码。

限制

技能的具体安装命令未提供；许可证信息暂未提供；支持的操作系统或运行环境暂未提供。