# pylint 介绍

Pylint 是一个用于 Python的静态代码分析器。它会检查错误、强制执行编码标准、寻找代码异味，并可以就如何重构代码提出建议。





## python代码检查配合

 pylint 一起使用的项目包括
 
- ruff（非常快速，内置自动修复功能，并从流行的 linter 中提取大量检查，但实现方式为 rust ）
- flake8（一个使用 ast 直接实现你自己的检查的框架）
- mypy
- pyright / pylance 或 pyre（类型检查）
- bandit（安全导向的检查）
- black 和 isort（自动格式化）
- autoflake（自动移除未使用的导入或变量）
- pyupgrade（自动升级到更新的 Python 语法）
- pydocstringformatter（自动 pep257 格式化）

## 版本说明

开发环境中应该使用指定的pylint版本，保证效果统一

- 在主要版本发布（ 1.0.0 ）中，会改变其他所有内容（pylint 选项、json 输出、开发 API 等），同时仍然尽量减少干扰。
- 在次要版本（ 1.2.0 ）中，添加检查、移除检查、移除已结束生命周期的 Python 解释器、升级 astroid 的次要/主要版本，并修复误报。
- 在补丁版本（ 1.2.3 ）中，仅修复误报和崩溃。

## 在markdown中使用pylint 徽章

效果如下

[![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint)


在任何 Markdown 文件中添加该行即可
```
[![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint)

```


# pylint 安装与配置

## pylint 安装

Pylint 可以通过包管理器进行安装

```
pip install pylint
```

如果需要使用pylint提供的拼写检查需要额外安装

```
pip install pylint[spelling]
```


## pylint的使用

```
pylint 需要检查的文件夹或文件路径
```


![image.png](https://oss.silon.vip/img/b838aa2dbeaa6c736a2356817c5d3c11.image.webp)

## pylint 配置

### 生成配置文件

Pylint 支持多种配置文件格式

- .pylintrc（RC 文件）
    - .pylintrc 文件通常是独立存在的，专门用于 Pylint 的配置
    - 项目已经使用 .pylintrc 并且配置较为简单，建议使用
- TOML 的配置（通常集成在 pyproject.toml 中）
    - Python 工具配置的标准（如 Poetry、Black 等）一般都写在该文件中
    - 希望将所有工具的配置集中管理，且项目配置较为复杂，建议使用

可以使用 --generate-toml-config 或 --generate-rcfile 生成一个示例配置文件。

```
# 生成 rc 文件在当前目录
pylint --generate-rcfile > .pylintrc

# 生成 toml 文件在当前目录
pylint --generate-toml-config > pyproject.toml
```

创建时可以预设一些选项
```
pylint --disable=bare-except,invalid-name --class-rgx='[A-Z][a-z]+' --generate-toml-config
```



### 各部分常用配置说明及参考


#### 基本配置

```
[tool.pylint.main]
# 启用持久化缓存
persistent = true

# 根据机器的CPU核心数设置, 0 为自动检查核心数
jobs = 0 

# 用于版本依赖性检查的最低 python 版本
py-version = "3.11"
```

#### 命名规范

```
[tool.pylint.basic]
# 命名风格
variable-naming-style = "snake_case"
function-naming-style = "snake_case"
class-naming-style = "PascalCase"
const-naming-style = "UPPER_CASE"

# 禁止使用的变量名
bad-names = ["a", "tmp", "temp", "test"]

# 允许的好变量名
good-names = ["i", "j", "k", "ex", "Run", "_"]

# 函数、方法至少多少行需要写docling注释，-1为必写，0为不写
docstring-min-length = 5

# 允许在名称中使用的正则表达式（覆盖命名风格）
# 比如允许变量名以“_”开头
variable-rgx = "^_?[a-z][a-z0-9_]{2,29}$"
```

#### 代码复杂度的限制

```
[tool.pylint.design]

# 哪些class不计入父类数量计算
ignored-parents = "object,abc.ABC"

# 最大函数参数数
max-args = 5

# class字段数量上限，Model/Serializer/Forms 可能有较多字段
max-attributes = 15

# if 语句中的布尔表达式数量
max-bool-expr = 5

# 函数/方法中的分支数量
max-branches = 10

# 局部变量数量
max-locals = 15

# class多重继承数量
max-parents = 5

# 与 max-args 同步
max-positional-arguments = 5

# public方法数量
max-public-methods = 20

# return 数量限制
max-returns = 6

# 一个函数最大行数
max-statements = 60

# class 至少应该有几个public方法
min-public-methods = 1
```

#### 代码格式

```
# 预期的行尾格式，可根据团队环境选择。对于跨平台开发，推荐使用 LF。
expected-line-ending-format = "LF"

# 允许行长度超过限制的正则表达式
ignore-long-lines = "^\\s*(# )?<?https?://\\S+>?$"

# 括号内要求的缩进空格数
indent-after-paren = 4

# 缩进使用的字符串，推荐使用4个空格
indent-string = "    "

# 单行最大字符数
max-line-length = 120

# 模块的最大行数
max-module-lines = 1000

# 允许类体只有单一语句时与声明在同一行
# class Configuration: setting = True
single-line-class-stmt = false

# 允许if体只有单一语句且无else时与测试条件在同一行
# if is_active: status = "Active"
single-line-if-stmt = flase
```

#### import 检查

```
[tool.pylint.imports]
# 允许在任何级别导入的模块列表，一般放内置和第三方库
allow-any-import-level = ["os", "sys", "django"]

# 分类明确标准库
known-standard-library = [
    "os",
    "sys",
    "math",
    "json",
    "logging",
]

# 分类明确第三方库
known-third-party = [
    "django",
    "rest_framework",
    "enchant",
    "requests",
]
```

#### pylint检查警告配置

``` 
[tool.pylint."messages control"]

# 仅显示以下置信度级别的警告
confidence = [
  "HIGH",
  "CONTROL_FLOW",
  "INFERENCE",
  "INFERENCE_FAILURE",
  "UNDEFINED",
]

# 禁用不相关或不必要的消息
disable = [
  "raw-checker-failed",
  "bad-inline-option",
  "locally-disabled",
  "file-ignored",
  "suppressed-message",
  "useless-suppression",
  "deprecated-pragma",
  "use-symbolic-message-instead",
  "use-implicit-booleaness-not-comparison-to-string",
  "use-implicit-booleaness-not-comparison-to-zero",
  "C0103",  # 变量命名长度过短或过长（根据需要调整）
  "W0511",  # TODO和FIXME注释（根据团队规范决定是否禁用）
]
```

#### 注释检查

常见的注释标签在检查范围内可帮助团队及时发现和处理潜在问题
```
[tool.pylint.miscellaneous]

# 要考虑的注释标签列表
notes = ["FIXME", "XXX", "TODO"]

# 注释标签的正则表达式
notes-rgx = "^(FIXME|XXX|TODO)\b"
```

#### 代码重构提示

```
[tool.pylint.refactoring]

# 函数/方法体中嵌套块的最大数量
max-nested-blocks = 5

# 永不返回的函数的完整名称
never-returning-functions = ["sys.exit", "argparse.parse_error"]

# 使用非空分隔符连接字符串列表时，Pylint会建议使用str.join方法
suggest-join-with-non-empty-separator = true
```

#### pylint 检查报告

```
[tool.pylint.reports]

# 全局评估报告的评价公式
evaluation = "max(0, 0 if fatal else 10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10))"

# 消息模板
msg-template = "{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}"

# 输出格式，用颜色区分不同类型的消息，提升可读性
output-format = "colorized"

# 是否显示完整报告
reports = false

# 启用评估分数
score = true

```


#### 代码相似度计算

一般不进行修改

```
[tool.pylint.similarities]

# 在相似度计算中忽略注释
ignore-comments = true

# 在相似度计算中忽略文档字符串
ignore-docstrings = true

# 在相似度计算中忽略导入语句
ignore-imports = true

# 在相似度计算中忽略函数签名
ignore-signatures = true

# 相似度的最小行数
min-similarity-lines = 4
```


#### 拼写检查

该功能需要安装pylint 的spell检查包

```
[tool.pylint.spelling]

# 限制拼写错误建议的数量
max-spelling-suggestions = 4

# 拼写词典名称（保持为空，使用默认词典）
spelling-dict = ""

# 忽略拼写检查的注释指令
spelling-ignore-comment-directives = "fmt: on,fmt: off,noqa:,noqa,nosec,isort:skip,mypy:"

# 不进行拼写检查的单词列表（根据项目需求添加）
spelling-ignore-words = "POST,GET,PUT,PATCH,DELETE,URL,HTTP"

# 私有词典文件路径（如有需要）
spelling-private-dict-file = ""

# 将未知单词存储到私有词典
spelling-store-unknown-words = false
```

#### 类型检查

```
[tool.pylint.typecheck]

# 上下文管理器装饰器列表
contextmanager-decorators = ["contextlib.contextmanager"]

# 动态设置的成员列表（根据项目需要添加）
generated-members = ["objects", "manager", "verbose_name"]

# 忽略mixin类中缺失的成员
ignore-none = true

# 对不透明推断的对象忽略成员检查
ignore-on-opaque-inference = true

# 忽略mixin成员的检查
ignored-checks-for-mixins = [
  "no-member",
  "not-async-context-manager",
  "not-context-manager",
  "attribute-defined-outside-init",
]

# 忽略成员检查的类名
ignored-classes = [
  "optparse.Values",
  "thread._local",
  "_thread._local",
  "argparse.Namespace",
]

# 缺失成员时显示提示
missing-member-hint = true

# 缺失成员提示的最小编辑距离
missing-member-hint-distance = 1

# 缺失成员提示的最大选项数
missing-member-max-choices = 1

# 定义mixin类的正则模式
mixin-class-rgx = ".*[Mm]ixin"

# 改变被装饰函数签名的装饰器列表（根据项目需要添加）
signature-mutators = ["functools.wraps"]
```

#### 变量使用

```
[tool.pylint.variables]
# 允许的全局未使用变量
allow-global-unused-variables = true

# 允许覆盖内置名称的变量列表
allowed-redefined-builtins = ["len", "id"]

# 允许作为回调函数标识的名称前缀或后缀
callbacks = ["cb_", "_cb"]

# 匹配虚拟变量名称的正则表达式
dummy-variables-rgx = "_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_"

# 忽略的参数名称正则表达式
ignored-argument-names = "_.*|^ignored_|^unused_"

# 允许重新定义内置函数的模块列表
redefining-builtins-modules = [
  "six.moves",
  "past.builtins",
  "future.builtins",
  "builtins",
  "io",
]
```


# 开发环境配置

## 编辑器集成

https://pylint.readthedocs.io/en/latest/user_guide/installation/ide_integration/index.html

## 代码pre-commit 检查

https://pylint.readthedocs.io/en/latest/user_guide/installation/pre-commit-integration.html

pylint 代码检查 

## 场景介绍

在一个团队中，成员可能使用不同的操作系统进行开发。例如，Windows 用户的文件系统对文件名不区分大小写，而 Linux 用户的文件系统则是区分大小写的。这种差异可能导致以下问题：

- **文件冲突**：同一目录下存在 `README.md` 和 `readme.md`，在大小写不敏感的系统上会被视为同一个文件，导致版本控制中的混乱。
- **部署问题**：某些文件在大小写敏感的服务器上可能找不到，从而导致应用程序运行错误。
- **代码引用错误**：代码中引用的文件名大小写不一致，可能在某些环境下无法正确加载资源。

为了避免这些问题，确保 Git 能够追踪文件名的大小写变化是至关重要的。


## 方案概述

Git 提供了一个配置选项 `core.ignorecase`，用于控制文件名的大小写敏感性。默认情况下，该选项会根据操作系统的文件系统自动设置：

- 在大小写不敏感的文件系统上（如 Windows 和 macOS），`core.ignorecase` 默认为 `true`。
- 在大小写敏感的文件系统上（如大多数 Linux 文件系统），`core.ignorecase` 默认为 `false`。

要在 Git 中开启文件名的大小写敏感追踪，需要将 `core.ignorecase` 设置为 `false`。这样，Git 会区分文件名的大小写变化，确保在版本控制中准确追踪文件的重命名和修改。





## 原理解析

### `core.ignorecase` 的作用

- **`core.ignorecase = true`**：Git 将忽略文件名的大小写变化。例如，`README.md` 和 `readme.md` 被视为同一个文件。这在大小写不敏感的操作系统上有助于避免不必要的文件冲突。
  
- **`core.ignorecase = false`**：Git 将区分文件名的大小写变化。`README.md` 和 `readme.md` 被视为不同的文件。这在大小写敏感的文件系统上确保了文件名的唯一性和准确性。

### 为什么需要手动设置

尽管 Git 会根据操作系统默认设置 `core.ignorecase`，但在某些情况下，你可能需要手动调整。例如：

- 在大小写不敏感的系统上开发，但需要部署到大小写敏感的服务器。
- 遇到文件名大小写冲突但不容易解决的情况。

手动设置 `core.ignorecase` 为 `false` 可以强制 Git 开启大小写敏感追踪，确保版本库的准确性。

## 使用示例

### 1. 查看当前配置

在修改配置之前，建议先查看当前 `core.ignorecase` 的设置：

```bash
git config core.ignorecase
```

### 2. 设置 `core.ignorecase` 为 `false`

在 Git 仓库中执行以下命令，将 `core.ignorecase` 设置为 `false`：

```bash
git config core.ignorecase false
```

如果你希望全局应用此设置（对所有仓库生效），可以添加 `--global` 选项：

```bash
git config --global core.ignorecase false
```

### 3. 验证配置

再次查看配置，确保设置已生效：

```bash
git config core.ignorecase
# 输出应为: false
```

### 4. 重命名文件以测试大小写敏感性

假设当前仓库中有一个文件 `example.txt`，我们将其重命名为 `Example.txt`：

```bash
git mv example.txt Example.txt
git commit -m "Rename example.txt to Example.txt to test case sensitivity"
```

由于 `core.ignorecase` 被设置为 `false`，Git 会将 `example.txt` 和 `Example.txt` 视为不同的文件，并正确跟踪重命名操作。

### 5. 处理现有的大小写冲突

如果你的仓库中已经存在大小写冲突的文件，可以按照以下步骤解决：

1. **暂存所有更改**：

    ```bash
    git add .
    ```

2. **提交或暂存当前更改**。

3. **设置 `core.ignorecase` 为 `false`**。

    ```bash
    git config core.ignorecase false
    ```

4. **重命名其中一个文件**，确保文件名的大小写有变化。

    ```bash
    git mv conflictingFile.txt ConflictingFile.txt
    git commit -m "Resolve case sensitivity conflicts"
    ```


# 参考资料

- [Git 官方文档 - core.ignorecase](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreignoreCase)

git 开启文件名大小写追踪

# 使用 GitHub 的 Deploy Key 进行项目部署

在现代软件开发中，自动化部署已成为保障项目高效上线的关键环节。GitHub 的 Deploy Key 提供了一种安全、简便的方式，使服务器能够安全地访问 GitHub 仓库，从而实现代码的自动部署。本篇博客将详细介绍如何使用 GitHub 的 Deploy Key 进行项目部署，涵盖其概念、对比分析、准备工作以及具体实施步骤。

## 目录

1. [Deploy Key 介绍](#deploy-key-介绍)
2. [相似方案对比，优缺点整理](#相似方案对比优缺点整理)
3. [服务器所需准备](#服务器所需准备)
4. [GitHub 所需准备](#github-所需准备)
5. [详细的实践指南](#详细的实践指南)
6. [总结](#总结)





## Deploy Key 介绍

**Deploy Key** 是 GitHub 提供的一种 SSH 公钥，用于授权服务器访问特定的 GitHub 仓库。与个人 SSH 密钥不同，Deploy Key 绑定到单个仓库，具有更细粒度的权限控制。这使得 Deploy Key 成为在持续集成和部署流程中，从服务器安全地拉取代码的理想选择。

**主要特点：**

- **安全性高**：每个 Deploy Key 只能访问指定的仓库，避免了权限过大的风险。
- **独立管理**：Deploy Key 独立于个人账户，便于团队协作和管理。
- **简便性**：配置简单，适用于各种自动化部署场景。

## 相似方案对比，优缺点整理

在使用 Deploy Key 进行项目部署之前，了解其他常见的授权方式有助于做出更明智的选择。以下是几种常见方案的对比：

### 1. **Personal Access Token (PAT)**

**优点：**

- **灵活性高**：可以为不同的操作设置不同的权限。
- **适用范围广**：不仅限于 Git 操作，还可以用于 GitHub API 访问。

**缺点：**

- **安全性较低**：PAT 通常与个人账户关联，权限较大，一旦泄露风险较高。
- **管理复杂**：需要定期更新和管理权限，尤其在团队协作中更为繁琐。

### 2. **OAuth 应用**

**优点：**

- **集成性强**：适用于需要与第三方服务集成的场景。
- **细粒度权限控制**：可以精确控制应用的访问权限。

**缺点：**

- **实现复杂**：配置和管理较为复杂，适合中大型项目。
- **依赖外部服务**：需要依赖 OAuth 提供方的服务稳定性。

### 3. **Deploy Key**

**优点：**

- **安全性高**：仅限于特定仓库，权限可控。
- **易于管理**：独立于个人账户，便于在团队中共享和管理。
- **简便性**：配置简单，适用于自动化部署场景。

**缺点：**

- **作用范围有限**：每个 Deploy Key 只能绑定一个仓库，不适用于需要访问多个仓库的场景。

### 总结

对于需要安全、简便地从服务器拉取代码进行部署的场景，Deploy Key 是一个理想的选择。相比于 PAT，Deploy Key 提供了更细粒度的权限控制，降低了安全风险。而与 OAuth 应用相比，Deploy Key 的配置和管理更为简单，适合中小型项目的自动化部署需求。

## 服务器所需准备

在配置 Deploy Key 之前，需要确保服务器具备以下条件：

1. **操作系统**：本指南以 Linux 服务器为例，其他操作系统的步骤类似。
2. **SSH 客户端**：确保服务器已安装 SSH 客户端，以便与 GitHub 进行通信。
3. **Git 安装**：确保服务器上已安装 Git，便于拉取代码库。

### 检查 SSH 客户端和 Git 是否安装

```bash
# 检查 SSH 客户端
ssh -V

# 检查 Git 是否安装
git --version
```

如果未安装，可以使用以下命令进行安装：

```bash
# 对于 Debian/Ubuntu 系统
sudo apt update
sudo apt install -y git openssh-client

# 对于 CentOS/RHEL 系统
sudo yum install -y git openssh-clients
```

## GitHub 所需准备

在 GitHub 上配置 Deploy Key 涉及生成 SSH 密钥，并将公钥添加到仓库的 Deploy Keys 中。具体步骤如下：

1. **生成 SSH 密钥对**
2. **添加公钥到 GitHub 仓库**
3. **配置服务器上的私钥**

### 1. 生成 SSH 密钥对

在服务器上生成一个新的 SSH 密钥对，用于与 GitHub 进行安全通信。

```bash
ssh-keygen -t ed25519 -C "deploy-key-for-my-project"
```

**命令解释：**

- `-t ed25519`：指定密钥类型为 ED25519，更安全且推荐。
- `-C "deploy-key-for-my-project"`：添加注释，便于识别。

当提示输入保存路径时，建议使用默认路径或指定一个用于部署的路径，例如 `~/.ssh/deploy_key`。

这里一般不设置密码，以便自动化部署时无需手动输入。

```bash
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519): /home/user/.ssh/deploy_key
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```

### 2. 添加公钥到 GitHub 仓库

将生成的公钥添加到 GitHub 的目标仓库中，步骤如下：

1. **复制公钥内容**

   ```bash
   cat ~/.ssh/deploy_key.pub
   ```

   复制输出的公钥内容。

2. **登录 GitHub 并导航到目标仓库**

3. **进入仓库的设置**

   点击仓库页面右上角的 **Settings**。

4. **添加 Deploy Key**

   在左侧菜单中选择 **Deploy keys**，然后点击 **Add deploy key**。

5. **填写 Deploy Key 信息**

   - **Title**：为 Deploy Key 命名，例如 `Server Deploy Key`
   - **Key**：粘贴复制的公钥内容。
   - **Allow write access**：根据需要选择是否允许写权限。对于只需拉取代码的部署场景，保持默认的只读权限即可。

6. **确认添加**

   点击 **Add key** 完成添加。

### 3. 配置服务器上的私钥

确保服务器能够使用私钥进行 SSH 认证，不需要输入密码。

1. **创建 SSH 目录（如果尚未存在）**

   ```bash
   mkdir -p ~/.ssh
   chmod 700 ~/.ssh
   ```

2. **保存私钥并设置权限**

   将生成的私钥（如 `~/.ssh/deploy_key`）放置在合适的位置，并设置正确的权限。

   ```bash
   chmod 600 ~/.ssh/deploy_key
   ```

3. **配置 SSH 客户端**

   创建或编辑 `~/.ssh/config` 文件，添加如下配置：

   ```bash
   Host github-deploy
       HostName github.com
       User git
       IdentityFile ~/.ssh/deploy_key
       IdentitiesOnly yes
   ```

   这个配置为 GitHub 的连接指定了使用 Deploy Key，避免使用其他 SSH 密钥。

## 更新仓库

以下是使用 Deploy Key 从 GitHub 部署项目的详细步骤，包括代码拉取和部署自动化。

### 1. 克隆仓库

使用配置好的 SSH 主机别名 `github-deploy` 克隆仓库。

```bash
git clone git@github-deploy:username/repository.git
```

**示例：**

```bash
git clone git@github-deploy:silon-j/myproject.git
```

注意这里 @ 后面的内容和 github 上一键粘贴的内容是不同的。

这里就基本已经完成 deploy key 的配置和拉取的验证了。

### 2. 设置自动部署脚本

为了实现每次代码更新后自动部署，可以使用 GitHub 的 Webhooks 或者在服务器上设置定时任务（如使用 cron）。

以下以简单的 Git pull 脚本为例：

```bash
#!/bin/bash

# 定义项目目录
PROJECT_DIR=/path/to/myproject

# 进入项目目录
cd $PROJECT_DIR || exit

# 拉取最新代码
git pull origin main

# 重新启动服务（根据项目需求调整）
# 示例：使用 PM2 管理 Node.js 应用
pm2 restart myproject
```

将以上脚本保存为 `deploy.sh`，并赋予执行权限：

```bash
chmod +x deploy.sh
```


## 总结

使用 GitHub 的 Deploy Key 进行项目部署是一种安全、简便且高效的方法。通过将 SSH 公钥绑定到特定仓库，Deploy Key 能够确保服务器仅访问授权的代码库，降低了安全风险，也避免了多人协作时拉取项目的权限问题。



# 相关链接

- [GitHub Docs: About Deploy Keys](https://docs.github.com/en/developers/overview/managing-deploy-keys)
- [Webhook GitHub Integration](https://docs.github.com/en/developers/webhooks-and-events/webhooks/about-webhooks)
- [Webhook GitHub Example](https://github.com/adnanh/webhook)

```

使用 GitHub 的 Deploy Key 进行项目更新

## 变量和注释使用


### 变量解包

python 中可以对变量进行解构

```python
usernames = ['silon', 'sibine']

user_a, user_b = usernames
```


```python
# 可以对嵌套解构进行解构

attrs = [1, [66, 77]]

num1, (num2, num3) = attrs
```



同时可以对被解构的内容进行切片

```python
data = [1, 2, 3, 4, 5]

# 动态解构和切片赋值效果相同
a, *b, c = data

# 切片赋值
a, b, c = data[0], data[1:-1], data[-1]
```

### 变量类型注释

python 在 3.5 版本之后，提供了类型注释

类型注释用于标明变量的类型

需要注意的是：  
**类型注释只是一种注释，不提供任何校验功能**，如果需要校验类型，可以安装其他静态类型检查工具（mypy 等）


使用类型注释，可以配合 ide，得到更好的代码提示效果

```python
from typing import List
def remove_invalid(items: List[int]):
    """剔除 items 里面无效的元素"""
```


另外官方 也推荐使用 sphnix 格式的注释

```
def remove_invalid(items):
    """剔除 items 里面无效的元素
    
    :param items: 待剔除对象
    :type items: 包含整数的列表，[int, ...]
    """
```


### 变量命名规范

Python制定了官方的编码风格指南：PEP 8。这份风格指南里有许多详细的风格建议，比如应该用4个空格缩进，每行不超过79个字符，等等。其中，当然也包含变量的命名规范：

· 对于普通变量，使用蛇形命名法，比如max_value；  
· 对于常量，采用全大写字母，使用下划线连接，比如MAX_VALUE；  
· 如果变量标记为“仅内部使用”，为其增加下划线前缀，比如_local_var；  
· 当名字与Python关键字冲突时，在变量末尾追加下划线，比如class_。  


除了必须要遵守 pep8 标准，还需要保证以下要求，达到好的效果

- 描述性要强  
    要使用尽量精确的词语进行变量描述，避免使用 data、temp 等非常泛性的名称，容易与其他变量混淆
- 长度尽量短  
    可以结合上下文，进行变量名称的精简，例如可以把`how_many_points_needed_for_user_level3`直接删减成`level3_points`
- 匹配类型
    使用固定的命名格式，来表达该变量的类型
    常见组合例如：  
    
    | 类型 | 组合 |
    | --- | --- |
    | bool | is_super、 has_permission 、 allow_empty |
    | int和float| port、 age、 _cnt 、 _length |
    | list | 复数变量名: apples |
    | 其他  | 建议使用类型注释 |
    
    注意不要使用 复数格式，用于 int 类型变量
- 仅特定场景使用短命名
    
    | 场景 | 命名 |
    | --- | --- |
    | 数组索引 | i,j,k  |
    | 某个整数 | n |
    | 某字符串 | s |
    | 某异常  | e |
    | 文件对象 | fp |
- 同一段代码，不要出现多个相似变量，例如 name1，name2

    
### 注释使用规范

编写代码时，使用注释，有几个注意点

1. 不建议将注释作为临时屏蔽代码的工具  
    不要觉得注释掉的内容以后还要用，如果需要，可以从git 历史中寻找
2. 不要使用注释复述代码  
    注释作为代码之外的说明性文字，应该尽量提供那些读者无法从代码里读出来的信息。描述代码为什么要这么做，而不是简单复述代码本身。  
    错误示范：  
    ```python
    #调用strip()去掉空格
    input_string = input_string.strip(
    ```
    正确示范：
    ```python
    #如果直接把带空格的输入传递到后端处理，可能会造成后端服务崩溃
    # 因此使用strip() 去掉首尾空格
    input_string = input_string.strip(
    ```
3. 适当增加指引式注释  
    指引性注释的主要作用是降低代码的认知成本，让我们能更容易理解代码的意图。
    ```python
    #初始化访问服务的client对象
    token = token_service.get_token()
    service_client = ServiceClient(token=token)
    service_client.ready()
    # 调用服务获取数据，然后进行过滤
    data = service_client.fetch_full_data()
    for item in data:
        if item.value > SOME_VALUE:
        ...
    ```
    同时使用指引式注释，也能帮助自己梳理代码
    ```python
    service_client = make_client()
    data = fetch_and_filter(service_client)
    ```
4. 不要过度注释使用者不需了解的内容，例如编写代码的思路  


### 变量使用的建议

- 要保证变量的一致性
    - 名字一致性：不要把同一个事务，在一个系统里各处起不同的名称  
      例如 user_avatar_url, user_profile_url
    - 类型一致性：不要把同一个变量重复指向不同类型的值，应该创建新的变量来处理新的类型的值
      ```python
      def foo():
      users = {'data': ['piglei', 'raymond']}
      ...
      # 使用一个新名字
      user_list = []
      ...
      ```
- 变量的定义尽量靠近  
    不要一次性都在顶部把局部变量定义好，应该在即将使用到该临时变量时，再定义  
    好的例子如下
    ```python
    def generate_trip_png(trip):
    """
    根据旅途数据生成 PNG 图片
    """
    # 开始初始化 waypoints 数据
    waypoints = []
    waypoints.append(...)
    ...
    # 开始处理 photo_markers、text_markers
    photo_markers, text_markers = [], []
    photo_markers.append(...)
    ...
    # 开始计算 marker_count
    marker_count = 0
    marker_count += ..
    ```
- 为复杂处理，创建临时变量，提升可读性  
    最常见的就是，将复杂的条件判断，进行 flag 的赋值
    ```python
    #为所有性别为女或者级别大于3的活跃用户发放10000个金币
    user_is_eligible = user.is_active and (user.sex == 'female' or user.level > 3)
    if user_is_eligible:
        user.add_coins(10000)
    ```
- 同一作用域不要使用过多变量  
    要减少函数里的变量数量，最直接的方式是给这些变量分组，建立新的模型（数据类）
- 能不定义变量，就不定义  
    不需要过度优化，不必为了那些未来可能出现的变动，牺牲代码此时此刻的可读性。如果以后需要定义变量，那就以后再做
    ```python
    def get_best_trip_by_user_id(user_id):
        # 心理活动：嗯，这个值未来说不定会修改/二次使用，我们先把它定义成变量吧！
        user = get_user(user_id)
        trip = get_best_trip(user_id)
        result = {
            'user': user,
            'trip': trip
        }
        return result
    ```
    正确示例：  
    ```python
    def get_best_trip_by_user_id(user_id):
        return {
            'user': get_user(user_id),
            'trip': get_best_trip(user_id)
        }
    ```
- 不要使用 locals()  
    locals()是Python的一个内置函数，调用它会返回当前作用域中的所有局部变量  
    其他人在阅读代码时，为了搞明白模板渲染到底用了哪些变量，必须记住当前作用域里的所有变量  
    使用locals()还有一个缺点，那就是它会把一些并没有真正使用的变量也一并暴露

### 注释使用建议

- 适当使用空行区分代码块
- 尽量先写注释后写代码

Python 习惯改进- 变量和注释的使用

# GVM 安装指南

GVM（Go Version Manager）是一个用于管理 Go 语言版本的工具，可以让你方便地在多个 Go 版本之间切换。本文将介绍如何在你的系统上安装 GVM。

[官方项目地址](https://github.com/moovweb/gvm)





## 前期准备

### 在 macOS

```
xcode-select --install
brew update
brew install mercurial
```

### debian 或 ubuntu
```
sudo apt-get install curl git mercurial make binutils bison gcc build-essential
```

### 其他 linux 发行版本
[查看官方文档](https://github.com/moovweb/gvm)


## 安装 GVM

1. **打开终端**。

2. **输入以下命令下载并安装 GVM**：

```bash
bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
```

![image.png](https://oss.silon.vip/img/d80019f9f147d5bfde2898b3cb4f4876.image.webp)

3. **激活 GVM**：

   安装后，你需要将 GVM 的初始化脚本添加到你的 Shell 配置文件中。根据使用的 shell 类型，选择相应的配置文件：

    对于 **bash** 用户：
     ```bash
     source /Users/silon/.gvm/scripts/gvm
     source ~/.bashrc
     ```

    对于 **zsh** 用户：
     ```bash
     source /Users/silon/.gvm/scripts/gvm
     source ~/.zshrc
     ```
 
4. **验证安装**：

   你可以通过运行以下命令来验证 GVM 是否已正确安装：

   ```bash
   gvm version
   ```

   如果安装成功，你将看到 GVM 的版本信息。
 
![image.png](https://oss.silon.vip/img/755a82122592daeffd7674d1fc5a7ce3.image.webp)
 

# 使用 GVM 管理 Go 版本

安装后，你可以使用以下命令来管理 Go 语言版本：

1. **列出可用的 Go 版本**：

   ```bash
   gvm listall
   ```

2. **安装指定版本的 Go**：

   例如，要安装 Go 1.17：

   ```bash
   gvm install go1.17
   ```

3. **使用指定的 Go 版本**：

   使用以下命令激活已安装的 Go 版本：

   ```bash
   gvm use go1.17
   ```

4. **查看当前使用的 Go 版本**：

   可以通过以下命令查看当前激活的 Go 版本：

   ```bash
   go version
   ```

## 示例

假设你想安装并使用 Go 的最新稳定版 1.20。可以按照以下步骤操作：

1. 使用 GVM 安装 Go 1.20：

   ```bash
   gvm install go1.20
   ```

2. 使用 Go 1.20：

   ```bash
   gvm use go1.20
   ```

3. 验证当前版本：

   ```bash
   go version
   ```

以上步骤应该能顺利地让你在 macOS 上使用 Homebrew 安装和使用 GVM 以及管理 Go 版本。


![image.png](https://oss.silon.vip/img/200f1e9b66ab9e2bd3fc0d3926d60b4d.image.webp)


# 卸载 GVM

如果你需要卸载 GVM，可以使用以下命令：

```bash
rm -rf $HOME/.gvm
```

并记得从你的 shell 配置文件中删除 GVM 的初始化脚本。